@quandev104/pi-style 0.2.1 → 0.2.3

package/extension-src/pi-style/app/command-service.ts

@@ -49,6 +49,9 @@ const allowedPaths = new Set([
 	"messages.specialBlocks",
 	"messages.hideThinkingLabel",
 	"messages.hideInterimText",
+	"messages.showImagePreviews",
+	"messages.clipboardImages",
+	"messages.previewMaxWidth",
 	"tools.enabled",
 	"tools.style",
 	"tools.maxCollapsedLines",
@@ -82,6 +85,9 @@ function validatePathValue(path: string, value: unknown): boolean {
 			"messages.specialBlocks",
 			"messages.hideThinkingLabel",
 			"messages.hideInterimText",
+			"messages.showImagePreviews",
+			"messages.clipboardImages",
+			"messages.previewMaxWidth",
 			"tools.enabled",
 			"tools.showElapsed",
 			"tools.dimOutput",
@@ -105,6 +111,8 @@ function validatePathValue(path: string, value: unknown): boolean {
 		return typeof value === "string";
 	if (path === "tools.maxCollapsedLines" || path === "tools.maxExpandedLines")
 		return typeof value === "number" && Number.isFinite(value) && value >= 0;
+	if (path === "messages.previewMaxWidth")
+		return typeof value === "number" && Number.isFinite(value) && value >= 8 && value <= 60;
 	if (path === "statusLine.bottomMargin" || path === "statusLine.contextBarWidth")
 		return typeof value === "number" && Number.isFinite(value) && value >= 0;
 	if (path.endsWith(".colors") || path.endsWith(".glyphs"))

package/extension-src/pi-style/app/runtime.ts

@@ -5,6 +5,7 @@ import type { GitCommandRunner } from "../domain/providers.js";
 import type { ContextSnapshot, StatusSnapshot } from "../domain/status.js";
 import { normalizeThinkingLevel } from "../domain/status.js";
 import { installEditor } from "../features/editor/index.js";
+import { createClipboardImagePasteSurface } from "../features/messages/image-input.js";
 import {
 	installStartup,
 	type StartupHost,
@@ -18,6 +19,9 @@ import { CachedGitProvider, InMemoryContextProvider, InMemoryUsageProvider } fro
 import { RenderScheduler } from "./render-scheduler.js";
 import { createSnapshot, replaceSnapshot, type UiSnapshot } from "./snapshot.js";
 
+/** Debounce window for coalescing git refresh spawns after invalidateGit(). */
+const GIT_INVALIDATE_DEBOUNCE_MS = 250;
+
 export interface RuntimeInstallationState {
 	readonly status: "installed" | "disabled" | "failed";
 	readonly editor: "installed" | "preserved" | "disabled" | "failed";
@@ -94,6 +98,11 @@ export function createPiStyleRuntime(
 	const disposables = new DisposableStore();
 	const scheduler = new RenderScheduler({ requestRender }, generation, () => !disposed);
 	const git = new CachedGitProvider(host.gitRunner);
+	// Debounced git refresh (invalidateGit): tool-result bursts fire one
+	// invalidateGit per write/edit/bash, each of which would otherwise spawn a
+	// `git status` process. Only one refresh may be pending at a time; the
+	// handle is unreffed so it can never keep the process alive.
+	let pendingGitRefresh: ReturnType<typeof setTimeout> | undefined;
 	const contextProvider = new InMemoryContextProvider();
 	const usageProvider = new InMemoryUsageProvider();
 	const initialContext = contextSnapshot();
@@ -190,6 +199,9 @@ export function createPiStyleRuntime(
 				generation,
 				initialSnapshot: currentSnapshot,
 				isCurrent: () => !disposed,
+				// Clipboard image paste surface (ADR 0009): instant `[Image #N] `
+				// markers at keystroke time, artifact fallback, atomic backspace.
+				clipboardImagePaste: createClipboardImagePasteSurface(),
 			});
 			if (editor) {
 				disposables.add(editor);
@@ -345,11 +357,24 @@ export function createPiStyleRuntime(
 		},
 		invalidateGit() {
 			if (disposed || !host.cwd || !currentConfig.enabled || !currentConfig.statusLine.enabled) return;
-			git.invalidate(host.cwd);
-			void git.get(host.cwd).then((value) => {
+			const cwd = host.cwd;
+			// Mark the cache stale immediately (cheap, no spawn); the actual
+			// `git status` process spawn is coalesced behind a short debounce so
+			// bursts of tool results trigger ONE refresh, not one per event.
+			// CachedGitProvider serializes concurrent gets via entry.promise and
+			// honors invalidate-during-flight (needsRefresh re-runs the fetch),
+			// so this debounce only reduces spawn count and never loses a signal.
+			git.invalidate(cwd);
+			if (pendingGitRefresh !== undefined) return;
+			pendingGitRefresh = setTimeout(() => {
+				pendingGitRefresh = undefined;
 				if (disposed) return;
-				if (updateSnapshot(withSnapshotPatch({ git: value }))) requestRender();
-			});
+				void git.get(cwd).then((value) => {
+					if (disposed) return;
+					if (updateSnapshot(withSnapshotPatch({ git: value }))) requestRender();
+				});
+			}, GIT_INVALIDATE_DEBOUNCE_MS);
+			pendingGitRefresh.unref?.();
 		},
 		get disposed() {
 			return disposed;
@@ -357,6 +382,10 @@ export function createPiStyleRuntime(
 		dispose() {
 			if (disposed) return;
 			disposed = true;
+			if (pendingGitRefresh !== undefined) {
+				clearTimeout(pendingGitRefresh);
+				pendingGitRefresh = undefined;
+			}
 			scheduler.cancel();
 			// UI surfaces are restored synchronously so teardown is deterministic;
 			// the store then disposes the (already disposed) feature instances idempotently.

package/extension-src/pi-style/domain/config-normalization.ts

@@ -16,7 +16,7 @@ export const DEFAULT_CONFIG: NormalizedPiStyleConfig = Object.freeze({
 	startup: Object.freeze({ mode: "compact", showResources: false, alwaysExpanded: false }),
 	statusLine: Object.freeze({
 		enabled: true,
-		separator: "powerline-thin",
+		separator: "|",
 		layout: Object.freeze({
 			left: ["path", "git", "context_bar", "cost"],
 			right: ["model_effort"],
@@ -34,6 +34,9 @@ export const DEFAULT_CONFIG: NormalizedPiStyleConfig = Object.freeze({
 		specialBlocks: true,
 		hideThinkingLabel: true,
 		hideInterimText: true,
+		showImagePreviews: true,
+		clipboardImages: true,
+		previewMaxWidth: 30,
 	}),
 	tools: Object.freeze({
 		enabled: true,
@@ -178,6 +181,9 @@ export function normalizeConfig(
 			specialBlocks: bool(messages.specialBlocks, defaults.messages.specialBlocks),
 			hideThinkingLabel: bool(messages.hideThinkingLabel, defaults.messages.hideThinkingLabel),
 			hideInterimText: bool(messages.hideInterimText, defaults.messages.hideInterimText),
+			showImagePreviews: bool(messages.showImagePreviews, defaults.messages.showImagePreviews),
+			clipboardImages: bool(messages.clipboardImages, defaults.messages.clipboardImages),
+			previewMaxWidth: boundedInt(messages.previewMaxWidth, defaults.messages.previewMaxWidth, 8, 60),
 		}),
 		tools: Object.freeze({
 			enabled: bool(tools.enabled, defaults.tools.enabled),
@@ -239,6 +245,8 @@ const BOOL_PATHS = new Set([
 	"messages.specialBlocks",
 	"messages.hideThinkingLabel",
 	"messages.hideInterimText",
+	"messages.showImagePreviews",
+	"messages.clipboardImages",
 	"tools.enabled",
 	"tools.showElapsed",
 	"tools.dimOutput",
@@ -289,6 +297,8 @@ function validLeaf(path: string, value: unknown): boolean {
 		return typeof value === "string";
 	if (path === "tools.maxCollapsedLines" || path === "tools.maxExpandedLines")
 		return typeof value === "number" && Number.isFinite(value) && value >= 0;
+	if (path === "messages.previewMaxWidth")
+		return typeof value === "number" && Number.isFinite(value) && value >= 8 && value <= 60;
 	if (path === "statusLine.bottomMargin" || path === "statusLine.contextBarWidth")
 		return typeof value === "number" && Number.isFinite(value) && value >= 0;
 	if (STRING_ARRAY_PATHS.has(path)) return Array.isArray(value) && value.every((item) => typeof item === "string");

package/extension-src/pi-style/domain/config-types.ts

@@ -38,6 +38,12 @@ export interface PiStyleConfig {
 		specialBlocks?: boolean;
 		hideThinkingLabel?: boolean;
 		hideInterimText?: boolean;
+		/** Inline previews for user-prompt images (ADR 0008); gates append and render. */
+		showImagePreviews?: boolean;
+		/** Clipboard image input (ADR 0009): upgrade built-in paste temp paths to attachments. */
+		clipboardImages?: boolean;
+		/** Max cell width per user-prompt image preview (ADR 0008); default 30. */
+		previewMaxWidth?: number;
 	};
 	tools?: {
 		enabled?: boolean;
@@ -97,6 +103,12 @@ export interface NormalizedPiStyleConfig {
 		specialBlocks: boolean;
 		hideThinkingLabel: boolean;
 		hideInterimText: boolean;
+		/** Inline previews for user-prompt images (ADR 0008); gates append and render. */
+		showImagePreviews: boolean;
+		/** Clipboard image input (ADR 0009): upgrade built-in paste temp paths to attachments. */
+		clipboardImages: boolean;
+		/** Max cell width per user-prompt image preview (ADR 0008); default 30. */
+		previewMaxWidth: number;
 	};
 	readonly tools: {
 		enabled: boolean;

package/extension-src/pi-style/domain/status-renderer.ts

@@ -25,6 +25,8 @@ interface Candidate {
 	readonly segment: StatusSegment;
 	readonly result: SegmentRenderResult;
 	content: string;
+	/** Visible width of `content`; updated when the compact form is swapped in. */
+	contentWidth: number;
 	compact: boolean;
 	moved: boolean;
 }
@@ -47,10 +49,6 @@ function renderGroup(items: readonly Candidate[], separator: string, padding: st
 		.join(`${padding}${separator}${padding}`);
 }
 
-function widthOf(items: readonly Candidate[], separator: string, padding: string): number {
-	return visibleWidth(renderGroup(items, separator, padding));
-}
-
 export function renderStatus(
 	layout: StatusLayout,
 	snapshot: StatusSnapshot,
@@ -58,7 +56,7 @@ export function renderStatus(
 	options: StatusRendererOptions,
 ): StatusRenderResult {
 	if (width <= 0) return { primary: "", lines: [], visibleSegments: [] };
-	const separator = options.separator ?? "│";
+	const separator = options.separator ?? "|";
 	const padding = options.padding ?? " ";
 	const normalized = uniqueLayout(layout);
 	const context: SegmentContext = { snapshot, theme: options.theme, options: options.options ?? {}, width };
@@ -70,7 +68,15 @@ export function renderStatus(
 		try {
 			const result = segment.render(context);
 			if (!result.visible || !result.content) continue;
-			candidates.set(id, { id, segment, result, content: result.content, compact: false, moved: false });
+			candidates.set(id, {
+				id,
+				segment,
+				result,
+				content: result.content,
+				contentWidth: visibleWidth(result.content),
+				compact: false,
+				moved: false,
+			});
 		} catch {
 			// A broken optional segment must not break the status row.
 		}
@@ -88,13 +94,34 @@ export function renderStatus(
 		.filter((candidate): candidate is Candidate => candidate !== undefined);
 	const visible: Candidate[] = [];
 	const overflow: Candidate[] = [];
+	// Incremental fit tracking: the rendered width of a group is the sum of the
+	// member content widths plus one separator gap between consecutive members
+	// (every join boundary is broken by the separator string, so visible widths
+	// add up). This replaces re-joining and re-measuring the whole group after
+	// every push, which made the overflow loop quadratic in segment count.
+	const gapWidth = visibleWidth(`${padding}${separator}${padding}`);
+	let groupWidth = 0;
+	let groupCount = 0;
+	const widthAfter = (baseWidth: number, count: number, candidate: Candidate): number =>
+		count === 0 ? candidate.contentWidth : baseWidth + gapWidth + candidate.contentWidth;
 	for (const candidate of primary) {
 		visible.push(candidate);
-		if (widthOf(visible, separator, padding) <= width) continue;
+		const pushedWidth = widthAfter(groupWidth, groupCount, candidate);
+		if (pushedWidth <= width) {
+			groupWidth = pushedWidth;
+			groupCount++;
+			continue;
+		}
 		if (candidate.result.compactContent && !candidate.compact) {
 			candidate.content = candidate.result.compactContent;
 			candidate.compact = true;
-			if (widthOf(visible, separator, padding) <= width) continue;
+			candidate.contentWidth = visibleWidth(candidate.content);
+			const compactedWidth = widthAfter(groupWidth, groupCount, candidate);
+			if (compactedWidth <= width) {
+				groupWidth = compactedWidth;
+				groupCount++;
+				continue;
+			}
 		}
 		visible.pop();
 		if (candidate.segment.overflow !== "drop" && candidate.segment.overflow !== "primary") {
@@ -127,9 +154,14 @@ export function renderStatus(
 	}
 	if (visibleWidth(primaryText) > width) primaryText = truncateAnsi(primaryText, width);
 	const secondaryVisible: Candidate[] = [];
+	let secondaryWidth = 0;
+	let secondaryCount = 0;
 	for (const candidate of [...secondary].sort((a, b) => b.segment.defaultPriority - a.segment.defaultPriority)) {
+		const pushedWidth = widthAfter(secondaryWidth, secondaryCount, candidate);
+		if (pushedWidth > width) continue;
 		secondaryVisible.push(candidate);
-		if (widthOf(secondaryVisible, separator, padding) > width) secondaryVisible.pop();
+		secondaryWidth = pushedWidth;
+		secondaryCount++;
 	}
 	const secondaryText = renderGroup(secondaryVisible, separator, padding);
 	const lines = secondaryText ? [primaryText, secondaryText] : primaryText ? [primaryText] : [];

package/extension-src/pi-style/domain/status.ts

@@ -252,12 +252,21 @@ export function createBuiltinSegments(): ReadonlyMap<StatusSegmentId, StatusSegm
 			const percent = contextPercent(snapshot.context ?? {});
 			if (percent === undefined) return { visible: false, content: "" };
 			const token = contextBarToken(percent);
-			const window = snapshot.context?.windowTokens;
-			const label = `ctx${window !== undefined ? ` (${formatTokens(window)})` : ""}:`;
 			const width = (options.context_bar?.width as number | undefined) ?? CONTEXT_BAR_WIDTH;
+			// Pipe-delimited context block: `[█████░░░░░] | 47% used | 235K/1.0M`.
+			// Uses plain `|` (not the tall `│`) so the inline block stays visually short.
+			// No boundary pipes: the status renderer's segment separator already
+			// delimits the block, and extra pipes would double it up.
+			const pipe = theme.apply("separator", "|");
+			const bar = `${theme.apply("muted", "[")}${theme.apply(token, contextBar(percent, width))}${theme.apply("muted", "]")}`;
+			const parts = [bar, `${theme.apply(token, `${Math.round(percent)}%`)}${theme.apply("muted", " used")}`];
+			const current = snapshot.context?.currentTokens;
+			const window = snapshot.context?.windowTokens;
+			if (current !== undefined && window !== undefined)
+				parts.push(theme.apply("muted", `${formatTokens(current)}/${formatTokens(window)}`));
 			return {
 				visible: true,
-				content: `${theme.apply("muted", label)} ${theme.apply(token, contextBar(percent, width))} ${theme.apply(token, `${Math.round(percent)}%`)}`,
+				content: parts.join(` ${pipe} `),
 				compactContent: theme.apply(token, `${Math.round(percent)}%`),
 			};
 		}),
@@ -308,11 +317,10 @@ export function createBuiltinSegments(): ReadonlyMap<StatusSegmentId, StatusSegm
 					? ""
 					: theme.apply("time", formatElapsed(Date.now() - snapshot.sessionStartedAt)),
 		})),
-		segment("time", 20, ({ theme }) => ({
-			visible: true,
-			content: theme.apply("time", new Date().toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })),
-			compactContent: theme.apply("time", new Date().toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })),
-		})),
+		segment("time", 20, ({ theme }) => {
+			const text = theme.apply("time", clockTime());
+			return { visible: true, content: text, compactContent: text };
+		}),
 		segment("hostname", 20, ({ snapshot, theme }) => ({
 			visible: Boolean(snapshot.hostname),
 			content: theme.apply("muted", snapshot.hostname ?? ""),
@@ -337,6 +345,17 @@ export function createBuiltinSegments(): ReadonlyMap<StatusSegmentId, StatusSegm
 	return new Map(segments.map((item) => [item.id, item]));
 }
 
+/** Cached clock text: the minute-precision string only changes once per minute. */
+let clockCache: { minuteKey: number; value: string } | undefined;
+function clockTime(): string {
+	const now = new Date();
+	const minuteKey = now.getHours() * 60 + now.getMinutes();
+	if (clockCache?.minuteKey !== minuteKey) {
+		clockCache = { minuteKey, value: now.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }) };
+	}
+	return clockCache.value;
+}
+
 const CONTEXT_BAR_WIDTH = 10;
 
 function contextBar(percent: number, width = CONTEXT_BAR_WIDTH): string {
@@ -352,10 +371,7 @@ function contextBarToken(percent: number): SemanticToken {
 }
 
 function formatTokens(value: number): string {
-	if (value >= 1_000_000) {
-		const millions = value / 1_000_000;
-		return `${Number.isInteger(millions) ? millions : millions.toFixed(1)}M`;
-	}
+	if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
 	if (value >= 1_000) {
 		const thousands = value / 1_000;
 		return `${Number.isInteger(thousands) ? thousands : thousands.toFixed(1)}K`;

package/extension-src/pi-style/domain/theme.ts

@@ -200,10 +200,32 @@ function colorPrefixFor(
 	return "";
 }
 
+function envKeyFor(env: Record<string, string | undefined>): string {
+	return `${env.PI_STYLE_NERD_FONTS ?? ""}\u0000${env.GHOSTTY_RESOURCES_DIR ? "1" : "0"}\u0000${env.TERM_PROGRAM ?? ""}`;
+}
+
+const glyphModeCache = new WeakMap<object, Map<string, GlyphMode>>();
+
 export function detectGlyphMode(
 	config: NormalizedPiStyleConfig,
 	env: Record<string, string | undefined> = {},
 ): GlyphMode {
+	// Memoized per config object; the env-derived key keeps the result correct
+	// when the same config is resolved against different environments.
+	let byEnv = glyphModeCache.get(config);
+	if (!byEnv) {
+		byEnv = new Map();
+		glyphModeCache.set(config, byEnv);
+	}
+	const envKey = envKeyFor(env);
+	const cached = byEnv.get(envKey);
+	if (cached !== undefined) return cached;
+	const mode = computeGlyphMode(config, env);
+	byEnv.set(envKey, mode);
+	return mode;
+}
+
+function computeGlyphMode(config: NormalizedPiStyleConfig, env: Record<string, string | undefined>): GlyphMode {
 	if (env.PI_STYLE_NERD_FONTS === "1") return "nerd";
 	if (env.PI_STYLE_NERD_FONTS === "0") return "unicode";
 	if (config.theme.nerdFonts === "on") return "nerd";
@@ -224,7 +246,16 @@ export function resolveTheme(
 ): ResolvedTheme {
 	const noColor = Object.hasOwn(env, "NO_COLOR") && env.NO_COLOR !== "" && config.theme.colors.colorOverride !== "on";
 	const mode = config.preset === "ascii" ? "ascii" : detectGlyphMode(config, env);
-	const color = (token: SemanticToken) => colorPrefixFor(active, config, noColor, token);
+	// Lazy per-instance prefix memo: repeated apply(token, ...) calls stop
+	// re-running colorPrefixFor (and Pi's active.fg()) for the same token.
+	const prefixes = new Map<SemanticToken, string>();
+	const color = (token: SemanticToken): string => {
+		const cached = prefixes.get(token);
+		if (cached !== undefined) return cached;
+		const prefix = colorPrefixFor(active, config, noColor, token);
+		prefixes.set(token, prefix);
+		return prefix;
+	};
 	return {
 		mode,
 		noColor,

package/extension-src/pi-style/features/editor/index.ts

@@ -6,6 +6,7 @@ import { contextPercent, type StatusSnapshot, type ThinkingLevel } from "../../d
 import type { ResolvedTheme } from "../../domain/theme.js";
 import { resolveTheme } from "../../domain/theme.js";
 import { stripAnsi, truncateAnsi } from "../../shared/ansi.js";
+import { clipboardMarkerAtEnd, isSingleClipboardImagePath } from "../../shared/clipboard-path.js";
 
 export const EDITOR_DIAGNOSTIC_KEY = "pi-style.editor";
 type SetEditorComponent = NonNullable<ExtensionUIContext["setEditorComponent"]>;
@@ -30,6 +31,18 @@ export interface EditorInstallation {
 	dispose(): void;
 }
 
+/** Structural clipboard-image paste surface (ADR 0009) consumed by the
+ *  editor. Structural so this feature needs no cross-feature import; the
+ *  app layer passes the instance built in features/messages. */
+interface ClipboardImagePasteSurface {
+	enabled(): boolean;
+	clipboardHasImage(): boolean | null;
+	markerFromClipboard(): string;
+	markerFromArtifact(path: string): Promise<string>;
+	isMarkerIndexRegistered(index: number): boolean;
+	discardMarkerIndex(index: number): void;
+}
+
 interface EditorOptions {
 	config: NormalizedPiStyleConfig;
 	snapshot: StatusSnapshot;
@@ -37,6 +50,22 @@ interface EditorOptions {
 	/** Full Pi theme for thinking-level border colors (optional; falls back to borderColor). */
 	fullTheme?: { getThinkingBorderColor?: (level: ThinkingLevel) => (str: string) => string };
 	onSnapshot: (snapshot: StatusSnapshot) => void;
+	/** Clipboard image paste surface (ADR 0009): instant `[Image #N] ` markers
+	 *  at keystroke time, artifact-path fallback, atomic marker backspace.
+	 *  Undefined keeps native behavior entirely. */
+	clipboardImagePaste?: ClipboardImagePasteSurface;
+}
+
+/** Pi-tui Editor internals mirrored for O(1) atomic marker surgery. All are
+ *  runtime-present on the Editor prototype chain but TS-private; the typed
+ *  cast follows the autocompleteState-access pattern used in render(). */
+interface EditorInternals {
+	readonly state: { lines: string[]; cursorLine: number; cursorCol: number };
+	lastAction: string | null;
+	readonly onChange?: (text: string) => void;
+	exitHistoryBrowsing(): void;
+	setCursorCol(col: number): void;
+	cancelAutocomplete(): void;
 }
 
 interface RenderPlan {
@@ -56,9 +85,13 @@ const widthOf = visibleWidth;
 
 function widthSafe(value: string, width: number): string {
 	if (width <= 0) return "";
-	const fitted = widthOf(value) > width ? truncateAnsi(value, width, "") : value;
-	const current = widthOf(fitted);
-	return current < width ? fitted + " ".repeat(width - current) : fitted;
+	const measured = widthOf(value);
+	if (measured > width) {
+		const fitted = truncateAnsi(value, width, "");
+		const current = widthOf(fitted);
+		return current < width ? fitted + " ".repeat(width - current) : fitted;
+	}
+	return measured < width ? value + " ".repeat(width - measured) : value;
 }
 
 function isNativeBorderLine(line: string): boolean {
@@ -142,8 +175,14 @@ export class StyledEditor extends CustomEditor implements EditorComponent {
 	private readonly fullTheme: EditorOptions["fullTheme"];
 	private readonly onSnapshot: (snapshot: StatusSnapshot) => void;
 	private semantic: ResolvedTheme;
+	/** Set when config changes; invalidate() then rebuilds the (otherwise stable) semantic theme. */
+	private semanticDirty = false;
 	private disposed = false;
 	private renderPlanCache: { key: string; plan: RenderPlan } | undefined;
+	private readonly clipboardImagePaste: ClipboardImagePasteSurface | undefined;
+	/** Keybinding matcher (the factory's KeybindingsManager) for keystroke-level
+	 *  interception: the paste keybinding and backspace checks below. */
+	private readonly editorKeybindings: { matches(data: string, keybinding: string): boolean };
 
 	constructor(tui: Tui, theme: PiEditorTheme, keybindings: Keybindings, options: EditorOptions) {
 		super(tui, theme, keybindings);
@@ -152,6 +191,8 @@ export class StyledEditor extends CustomEditor implements EditorComponent {
 		this.piTheme = theme;
 		this.fullTheme = options.fullTheme;
 		this.onSnapshot = options.onSnapshot;
+		this.clipboardImagePaste = options.clipboardImagePaste;
+		this.editorKeybindings = keybindings as unknown as { matches(data: string, keybinding: string): boolean };
 		this.semantic = semanticTheme(theme, options.config);
 		this.setPaddingX(0);
 	}
@@ -165,19 +206,115 @@ export class StyledEditor extends CustomEditor implements EditorComponent {
 	configure(config: NormalizedPiStyleConfig): void {
 		if (this.disposed) return;
 		this.config = config;
-		this.semantic = semanticTheme(this.piTheme, config);
+		this.semanticDirty = true;
 		this.invalidate();
 	}
 
 	override handleInput(data: string): void {
 		if (this.disposed) return;
+		if (this.handleClipboardImagePasteKeystroke(data)) return;
+		if (this.handleAtomicMarkerBackspace(data)) return;
 		super.handleInput(data);
 		this.onSnapshot({ ...this.snapshot });
 	}
 
+	/**
+	 * Instant marker (ADR 0009): when the built-in paste keybinding fires, the
+	 * clipboard holds an image (sync native probe), and the surface is enabled,
+	 * the keystroke is owned here — an `[Image #N] ` marker is inserted
+	 * immediately (zero-latency feedback) and the bytes fill the registry
+	 * entry asynchronously. Pi's own paste handler never runs for this
+	 * keystroke, so no temp artifact is written. Text pastes (no image) and
+	 * probe-unavailable hosts fall through to the native path untouched.
+	 */
+	private handleClipboardImagePasteKeystroke(data: string): boolean {
+		const surface = this.clipboardImagePaste;
+		if (!surface?.enabled()) return false;
+		if (!this.editorKeybindings.matches(data, "app.clipboard.pasteImage")) return false;
+		if (surface.clipboardHasImage() !== true) return false;
+		super.insertTextAtCursor(surface.markerFromClipboard());
+		this.onSnapshot({ ...this.snapshot });
+		return true;
+	}
+
+	/**
+	 * Atomic marker backspace (ADR 0009): backspacing directly after a
+	 * registered `[Image #N] ` marker deletes the whole marker as one unit —
+	 * the image is discarded (image-paste semantics). Direct state surgery
+	 * (O(1)) mirroring pi-tui's handleBackspace mutation protocol: no setText
+	 * round-trip (it clears the pastes registry, and undo snapshots store that
+	 * Map by reference — silently breaking `[paste #N]` atomicity on undo) and
+	 * no per-column left-arrow inputs (O(K·L) through the keybinding chain and
+	 * visual line maps). No undo snapshot is pushed: the discarded image
+	 * cannot be restored, so the deletion is intentionally non-undoable.
+	 */
+	private handleAtomicMarkerBackspace(data: string): boolean {
+		const surface = this.clipboardImagePaste;
+		if (!surface?.enabled()) return false;
+		const isBackspace = this.editorKeybindings.matches(data, "tui.editor.deleteCharBackward") || data === "\x7f";
+		if (!isBackspace) return false;
+		const lines = this.getLines();
+		const cursor = this.getCursor();
+		const current = lines[cursor.line];
+		if (current === undefined) return false;
+		const before = current.slice(0, cursor.col);
+		const hit = clipboardMarkerAtEnd(before);
+		if (!hit || !surface.isMarkerIndexRegistered(hit.index)) return false;
+		const editor = this as unknown as EditorInternals;
+		const targetCol = cursor.col - hit.length;
+		editor.exitHistoryBrowsing();
+		editor.lastAction = null;
+		editor.cancelAutocomplete();
+		// Splice the marker out of its line in place (deletion never removes a
+		// line, so cursorLine is unchanged). setCursorCol also clears
+		// preferredVisualCol/snappedFromCursorCol. scrollOffset is left alone;
+		// render() re-clamps it to keep the cursor visible.
+		editor.state.lines[cursor.line] = current.slice(0, targetCol) + current.slice(cursor.col);
+		editor.setCursorCol(targetCol);
+		editor.onChange?.(this.getText());
+		surface.discardMarkerIndex(hit.index);
+		this.invalidate();
+		this.onSnapshot({ ...this.snapshot });
+		return true;
+	}
+
+	/**
+	 * Artifact-path fallback (ADR 0009): when the keystroke was not owned
+	 * (probe unavailable, native editor path, config toggled) Pi's built-in
+	 * paste still inserts a `<tmpdir>/pi-clipboard-<uuid>.<ext>` path through
+	 * this method. Convert it to a marker when the artifact reads successfully;
+	 * every failure inserts the original text verbatim (exact native behavior).
+	 */
+	override insertTextAtCursor(text: string): void {
+		const surface = this.clipboardImagePaste;
+		if (!surface?.enabled() || !isSingleClipboardImagePath(text)) {
+			super.insertTextAtCursor(text);
+			return;
+		}
+		void (async () => {
+			let replacement = text;
+			try {
+				replacement = await surface.markerFromArtifact(text);
+			} catch {
+				// Unreadable artifact or surface failure: keep native behavior.
+			}
+			super.insertTextAtCursor(replacement);
+			// The caller (Pi's handleClipboardPaste) requested its render before
+			// this async insert completed — without a repaint the marker stays
+			// invisible until the next keystroke. Request one now.
+			this.tui.requestRender();
+		})();
+	}
+
 	override invalidate(): void {
 		super.invalidate();
-		this.semantic = semanticTheme(this.piTheme, this.config);
+		// The semantic theme is derived from (piTheme, config); piTheme is fixed per
+		// instance and config changes go through configure(), so keystroke-driven
+		// invalidations reuse the cached instance instead of rebuilding it.
+		if (this.semanticDirty) {
+			this.semantic = semanticTheme(this.piTheme, this.config);
+			this.semanticDirty = false;
+		}
 		this.renderPlanCache = undefined;
 		this.tui.requestRender();
 	}
@@ -400,6 +537,7 @@ export function installEditor(options: {
 	generation: number;
 	initialSnapshot: StatusSnapshot;
 	isCurrent?: () => boolean;
+	clipboardImagePaste?: EditorOptions["clipboardImagePaste"];
 }): EditorInstallation | undefined {
 	if (!options.host.setEditorComponent) return undefined;
 	const previous = options.host.getEditorComponent?.();
@@ -424,6 +562,7 @@ export function installEditor(options: {
 			snapshot,
 			theme,
 			...(options.host.theme ? { fullTheme: options.host.theme } : {}),
+			...(options.clipboardImagePaste ? { clipboardImagePaste: options.clipboardImagePaste } : {}),
 			onSnapshot: (next) => {
 				if (!disposed && options.isCurrent?.() !== false) snapshot = next;
 			},