@oh-my-pi/pi-tui 18.2.4 → 18.2.5

package/src/overlays/usage-row.ts

@@ -0,0 +1,118 @@
+import type { Usage } from "@oh-my-pi/pi-ai";
+import { Container, Spacer } from "../index";
+import { formatDuration, formatNumber } from "@oh-my-pi/pi-utils";
+import { theme } from "../theme/theme";
+import { formatMetricRow, MetricRow, type MetricSpec } from "../components/metric";
+
+/** Below this the rate is nonsense (cached/instant responses yield absurd tok/s). */
+const MIN_DURATION_MS = 100;
+
+/** Local `YYYY-MM-DD HH:mm:ss` stamp for the per-turn usage row. */
+function formatUsageTimestamp(ms: number): string {
+	const d = new Date(ms);
+	const pad = (n: number): string => String(n).padStart(2, "0");
+	const date = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+	const time = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+	return `${date} ${time}`;
+}
+
+/**
+ * Prompt→yield wall time for a turn, from pure local timestamps: the user
+ * prompt's timestamp to the response's completion time (`completedAt`, stamped
+ * by the session at `message_end`). No provider-reported duration is involved —
+ * messages persisted before the stamp existed simply have no span.
+ * Undefined when either end is unknown (mid-attach or unstamped message).
+ */
+export function turnElapsedMs(
+	turnStartedAt: number | undefined,
+	message: { completedAt?: number },
+): number | undefined {
+	if (turnStartedAt === undefined || message.completedAt === undefined) return undefined;
+	const elapsed = message.completedAt - turnStartedAt;
+	return elapsed > 0 ? Math.round(elapsed) : undefined;
+}
+
+function usageRowSpecs(
+	usage: Usage,
+	durationMs?: number,
+	ttftMs?: number,
+	timestamp?: number,
+	turnElapsedMs?: number,
+): MetricSpec[] {
+	const totalInput = usage.input + usage.cacheWrite;
+	const specs: MetricSpec[] = [];
+	// Lead with the turn's local wall-clock time (down to the second), log-line style.
+	if (timestamp !== undefined && Number.isFinite(timestamp) && timestamp > 0) {
+		specs.push({ value: formatUsageTimestamp(timestamp) });
+	}
+	// The delta the operator actually waited, bare with a space so it scans
+	// apart from the TTFT figure below (which keeps the clock icon).
+	// `message.duration` comes from performance.now(), so the combined value is
+	// fractional; round before formatDuration so the label never prints a raw
+	// float (e.g. `347.28381699998863ms`).
+	if (turnElapsedMs !== undefined && turnElapsedMs > 0) {
+		specs.push({ value: `Δ ${formatDuration(Math.round(turnElapsedMs))}` });
+	}
+	specs.push({ leading: theme.icon.input, value: formatNumber(totalInput) });
+	specs.push({ leading: theme.icon.output, value: formatNumber(usage.output) });
+	if (usage.cacheRead > 0) {
+		specs.push({ leading: theme.icon.cache, value: formatNumber(usage.cacheRead) });
+	}
+	if (ttftMs && ttftMs > 0) {
+		specs.push({ leading: theme.icon.time, value: `${(ttftMs / 1000).toFixed(1)}s` });
+	}
+	if (durationMs && durationMs > MIN_DURATION_MS && usage.output > 0) {
+		// TPS over the total request duration — the post-TTFT window undercounts
+		// generation time when reasoning tokens are hidden before the first
+		// visible byte, inflating the rate.
+		const tokPerSec = (usage.output / durationMs) * 1000;
+		specs.push({ leading: theme.icon.throughput, value: `${tokPerSec.toFixed(1)}/s` });
+	}
+	return specs;
+}
+
+/** Format the metrics shared by standalone usage blocks and compact tool groups. */
+export function formatUsageRow(
+	usage: Usage,
+	durationMs?: number,
+	ttftMs?: number,
+	timestamp?: number,
+	turnElapsedMs?: number,
+): string {
+	return formatMetricRow(usageRowSpecs(usage, durationMs, ttftMs, timestamp, turnElapsedMs), {
+		separator: "  ",
+	});
+}
+
+/** Blocks minted by {@link createUsageRowBlock}, so transcript walkers can attribute them to the turn above. */
+const usageRowBlocks = new WeakSet<Container>();
+
+/** Whether `component` is a per-turn usage/metrics row from {@link createUsageRowBlock}. */
+export function isUsageRowBlock(component: object): boolean {
+	return usageRowBlocks.has(component as Container);
+}
+
+// `timestamp` and `turnElapsedMs` are optional and trail the throughput args to
+// preserve the existing (usage, durationMs, ttftMs) call contract — this
+// function is part of the package's public export surface (./modes/components/*).
+export function createUsageRowBlock(
+	usage: Usage,
+	durationMs?: number,
+	ttftMs?: number,
+	timestamp?: number,
+	turnElapsedMs?: number,
+): Container {
+	const block = new Container();
+	block.addChild(new Spacer(1));
+	block.addChild(
+		new MetricRow(usageRowSpecs(usage, durationMs, ttftMs, timestamp, turnElapsedMs), {
+			separator: "  ",
+			overflow: "wrap",
+			paddingX: 1,
+			paddingY: 0,
+			style: text => theme.fg("dim", text),
+		}),
+	);
+	usageRowBlocks.add(block);
+	return block;
+}

package/src/prompt/attachment-chips.ts

@@ -0,0 +1,201 @@
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+import {
+	type Component,
+	getImageDimensions,
+	getKittyGraphics,
+	type ImageBudget,
+	ImageProtocol,
+	renderImage,
+	replaceTabs,
+	TERMINAL,
+	truncateToWidth,
+	visibleWidth,
+} from "../index";
+import { fileHyperlink } from "../render/hyperlink";
+import { convertImageToPng } from "../chat/image-loading";
+import { attachmentSgr } from "./composer-attachments";
+import { cachedImageDimensions, setCachedImageDimensions } from "./image-references";
+import { theme } from "../theme/theme";
+import type { ComposerChipDescriptor, CustomEditor, TextAttachment } from "./custom-editor";
+
+/** Chip card geometry (mirrors omp2): a 12x4 content area inside a 1-cell rounded border. */
+const INNER_COLS = 12;
+const INNER_ROWS = 4;
+const CARD_COLS = INNER_COLS + 2;
+const CARD_GAP = 2;
+const RESET_FG = "\x1b[39m";
+/** Symbol-keyed PNG conversion cache on the draft image (same pattern as the dimension
+ *  probe cache): Kitty's `f=100` transmit accepts only PNG, so non-PNG attachments
+ *  (pastes are usually re-encoded JPEG/WebP) convert before transmit — the same pipeline
+ *  the transcript uses. `null` = conversion in flight or failed. */
+const kImagePng = Symbol("omp.imagePng");
+
+interface ImageContentWithPng extends ImageContent {
+	[kImagePng]?: ImageContent | null;
+}
+
+/**
+ * The composer attachment band: one rounded card per staged attachment, rendered directly above
+ * the prompt box. Image and video cards show a live thumbnail (Kitty Unicode placeholders — the only
+ * protocol whose output is plain text cells and therefore composable inside a border row) with
+ * the pixel dimensions as the bottom caption; text-paste cards show the leading snippet with a
+ * `+N lines` / `N chars` caption. The top caption is the same `<icon> #N` token that sits in
+ * the editor buffer, in the same identity color. Cards that no longer fit the terminal width
+ * are omitted rather than wrapped. Renders to nothing while no attachment is staged.
+ */
+export class AttachmentChipsBand implements Component {
+	constructor(
+		private readonly editor: CustomEditor,
+		private readonly budget: ImageBudget,
+		private readonly requestRender: () => void,
+	) {}
+
+	render(width: number): readonly string[] {
+		const chips = this.editor.composerChips();
+		if (chips.length === 0) return [];
+		const rows = ["", "", "", "", "", ""];
+		const gap = " ".repeat(CARD_GAP);
+		let x = 0;
+		for (const chip of chips) {
+			if (x + CARD_COLS > width) break;
+			const card = this.#card(chip);
+			for (let r = 0; r < rows.length; r++) rows[r] += (x > 0 ? gap : "") + card[r];
+			x += (x > 0 ? CARD_GAP : 0) + CARD_COLS;
+		}
+		return rows;
+	}
+
+	#card(chip: ComposerChipDescriptor): string[] {
+		const sgr = attachmentSgr(chip.kind, chip.n);
+		const icon = theme.symbol(
+			chip.kind === "paste" ? "chip.paste" : chip.kind === "video" ? "chip.video" : "chip.image",
+		);
+		let bottomCaption: string;
+		let interior: string[];
+		if (chip.kind !== "paste") {
+			const dims = this.#imageDims(chip.image);
+			bottomCaption = dims ? `${dims.width}x${dims.height}` : "";
+			interior = this.#imageInterior(chip.image, dims, chip.kind);
+		} else {
+			bottomCaption = chip.text.lineCount > 1 ? `+${chip.text.lineCount} lines` : `${chip.text.charCount} chars`;
+			interior = this.#textInterior(chip.text);
+		}
+		const vertical = `${sgr}${theme.symbol("boxRound.vertical")}${RESET_FG}`;
+		const title =
+			chip.kind === "paste" || !chip.link ? `${icon} #${chip.n}` : fileHyperlink(chip.link, `${icon} #${chip.n}`);
+		return [
+			this.#borderRow(sgr, title, "top"),
+			...interior.map(row => vertical + row + vertical),
+			this.#borderRow(sgr, bottomCaption, "bottom"),
+		];
+	}
+
+	/** Horizontal border with an optional centered, bold caption padded by one space per side. */
+	#borderRow(sgr: string, caption: string, edge: "top" | "bottom"): string {
+		const left = theme.symbol(edge === "top" ? "boxRound.topLeft" : "boxRound.bottomLeft");
+		const right = theme.symbol(edge === "top" ? "boxRound.topRight" : "boxRound.bottomRight");
+		const horizontal = theme.symbol("boxRound.horizontal");
+		if (!caption) return `${sgr}${left}${horizontal.repeat(INNER_COLS)}${right}${RESET_FG}`;
+		const cut = truncateToWidth(caption, INNER_COLS - 2);
+		const fill = INNER_COLS - visibleWidth(cut) - 2;
+		const leftFill = Math.max(0, Math.floor(fill / 2));
+		const rightFill = Math.max(0, fill - leftFill);
+		return `${sgr}${left}${horizontal.repeat(leftFill)} \x1b[1m${cut}\x1b[22m ${horizontal.repeat(rightFill)}${right}${RESET_FG}`;
+	}
+
+	/** Pixel dimensions for the caption/thumbnail fit, probed once from the header bytes and
+	 *  cached on the image object (`null` = undecodable header, never re-probed). */
+	#imageDims(image: ImageContent): { width: number; height: number } | null {
+		let dims = cachedImageDimensions(image);
+		if (dims === undefined) {
+			const probed = getImageDimensions(image.data, image.mimeType);
+			dims = probed ? { width: probed.widthPx, height: probed.heightPx } : null;
+			setCachedImageDimensions(image, dims);
+		}
+		return dims;
+	}
+
+	/** 12x4 thumbnail as Kitty Unicode-placeholder cell rows, centered; any other protocol (or a
+	 *  budget-suppressed image) falls back to a centered icon — direct placements, SIXEL, and
+	 *  iTerm2 output cursor-addressed sequences that cannot be composed into a border row. */
+	#imageInterior(
+		image: ImageContent,
+		dims: { width: number; height: number } | null,
+		kind: "image" | "video",
+	): string[] {
+		if (dims && TERMINAL.imageProtocol === ImageProtocol.Kitty && getKittyGraphics().unicodePlaceholders) {
+			const display = this.#kittyDisplayImage(image);
+			if (display) {
+				const budget = this.budget;
+				const imageId = budget.acquireId(
+					`chip:${display.mimeType}:${display.data.length}:${display.data.slice(0, 32)}`,
+				);
+				// observe() keeps chip thumbnails inside the shared live-graphics budget so a
+				// paste-heavy session cannot pile up placements the way unbudgeted images would.
+				if (!budget.observe(imageId)) {
+					const result = renderImage(
+						display.data,
+						{ widthPx: dims.width, heightPx: dims.height },
+						{
+							maxWidthCells: INNER_COLS,
+							maxHeightCells: INNER_ROWS,
+							imageId,
+							includeTransmit: budget.shouldTransmit(imageId),
+						},
+					);
+					if (result?.transmit) budget.enqueueTransmit(imageId, result.transmit);
+					if (result?.lines) return this.#centerGrid(result.lines);
+				}
+			}
+		}
+		const icon = theme.symbol(kind === "video" ? "chip.video" : "chip.image");
+		const pad = INNER_COLS - visibleWidth(icon);
+		const iconRow = " ".repeat(Math.floor(pad / 2)) + theme.fg("muted", icon) + " ".repeat(Math.ceil(pad / 2));
+		return [" ".repeat(INNER_COLS), iconRow, " ".repeat(INNER_COLS), " ".repeat(INNER_COLS)];
+	}
+
+	/** PNG form of `image` for the Kitty transmit; non-PNG sources convert asynchronously.
+	 *  Returns undefined while the conversion is pending (or after it failed), letting the
+	 *  caller fall back to the icon; a finished conversion triggers a repaint. */
+	#kittyDisplayImage(image: ImageContent): ImageContent | undefined {
+		if (image.mimeType === "image/png") return image;
+		const cached = (image as ImageContentWithPng)[kImagePng];
+		if (cached !== undefined) return cached ?? undefined;
+		(image as ImageContentWithPng)[kImagePng] = null;
+		convertImageToPng(image)
+			.then(converted => {
+				(image as ImageContentWithPng)[kImagePng] = converted;
+				this.requestRender();
+			})
+			.catch(() => {});
+		return undefined;
+	}
+
+	/** Center a placeholder cell grid (≤ 12 columns, ≤ 4 rows) inside the content area. */
+	#centerGrid(lines: string[]): string[] {
+		const rows: string[] = [];
+		const topPad = Math.floor((INNER_ROWS - lines.length) / 2);
+		for (let r = 0; r < INNER_ROWS; r++) {
+			const line = lines[r - topPad];
+			if (line === undefined) {
+				rows.push(" ".repeat(INNER_COLS));
+				continue;
+			}
+			const pad = Math.max(0, INNER_COLS - visibleWidth(line));
+			rows.push(" ".repeat(Math.floor(pad / 2)) + line + " ".repeat(Math.ceil(pad / 2)));
+		}
+		return rows;
+	}
+
+	/** Leading 4 rows x 12 cols of the pasted text, muted. */
+	#textInterior(entry: TextAttachment): string[] {
+		const lines = entry.content.split("\n");
+		const rows: string[] = [];
+		for (let r = 0; r < INNER_ROWS; r++) {
+			const cut = truncateToWidth(replaceTabs(lines[r] ?? ""), INNER_COLS);
+			const pad = INNER_COLS - visibleWidth(cut);
+			rows.push(theme.fg("muted", cut) + " ".repeat(Math.max(0, pad)));
+		}
+		return rows;
+	}
+}

package/src/prompt/composer-attachments.ts

@@ -0,0 +1,280 @@
+import { allowsModelMentions, allowsSkillTokens, SKILL_TOKEN_RE } from "./skill-tokens";
+import { MODEL_MENTION_RE, modelMentionToken } from "./model-mention-syntax";
+import { SYMBOL_PRESETS } from "../theme/symbols";
+import { type ThemeColor, theme } from "../theme/theme";
+
+/** Attachment chip kinds staged in the composer: images, video previews, and large text pastes. */
+export type ChipKind = "image" | "video" | "paste";
+
+/** Compact atomic composer token for an invoked skill in the active symbol preset. */
+export function skillChipLabel(name: string): string {
+	const icon =
+		typeof theme === "undefined"
+			? SYMBOL_PRESETS.unicode["icon.extensionSkill"]
+			: theme.symbol("icon.extensionSkill");
+	return `${icon} ${name}`;
+}
+
+/** Compact atomic composer token for a model mention in the active symbol preset. */
+export function modelMentionChipLabel(name: string): string {
+	const icon = typeof theme === "undefined" ? SYMBOL_PRESETS.unicode["icon.model"] : theme.symbol("icon.model");
+	return `${icon} ${name}`;
+}
+
+/** Canonical `/skill:<name>` token a skill chip expands to on submit. */
+export function skillToken(name: string): string {
+	return `/skill:${name}`;
+}
+
+function chipPillStyle(label: string, color: ThemeColor, restore: string): string {
+	if (typeof theme === "undefined") return label;
+	return `${theme.getBgAnsi("customMessageBg")}${theme.getFgAnsi(color)}\x1b[1m${label}\x1b[22m${restore}`;
+}
+
+/**
+ * Soft-pill styling for a skill chip: bold skill label color over the custom-message
+ * tint. `restore` re-arms the surrounding foreground/background after the chip.
+ */
+export function skillChipStyle(label: string, restore = "\x1b[39m\x1b[49m"): string {
+	return chipPillStyle(label, "customMessageLabel", restore);
+}
+
+/** Soft-pill styling for a model mention, restoring the surrounding colors afterward. */
+export function modelChipStyle(label: string, restore = "\x1b[39m\x1b[49m"): string {
+	return chipPillStyle(label, "statusLineModel", restore);
+}
+
+/** Every glyph a skill chip may start with, across all symbol presets. */
+const SKILL_ICONS = [...new Set(Object.values(SYMBOL_PRESETS).map(m => m["icon.extensionSkill"]))];
+
+/** Skill names as they appear in chips: word characters and dashes, dots only between segments. */
+const SKILL_NAME_SOURCE = "[\\w-]+(?:\\.[\\w-]+)*";
+
+const SKILL_CHIP_SOURCE = `(?:${SKILL_ICONS.map(icon =>
+	/^[a-z]+$/i.test(icon) ? `(?<![A-Za-z])${RegExp.escape(icon)}` : RegExp.escape(icon),
+).join("|")}) (${SKILL_NAME_SOURCE})(?![\\w-])`;
+
+/**
+ * Replaces `/skill:<name>` tokens for known skills with compact chip labels and
+ * registers each label's token as its atomic editor expansion. Leaves the text
+ * untouched when skill tokens are not invocations in this draft (see
+ * {@link allowsSkillTokens}).
+ */
+export function collapseSkillTokens(
+	text: string,
+	isKnown: (name: string) => boolean,
+	register: (label: string, expansion: string) => void,
+): string {
+	if (!text.includes("/skill:") || !allowsSkillTokens(text)) return text;
+	SKILL_TOKEN_RE.lastIndex = 0;
+	return text.replace(SKILL_TOKEN_RE, (match, delimiter: string, name: string) => {
+		if (!isKnown(name)) return match;
+		const label = skillChipLabel(name);
+		register(label, skillToken(name));
+		return `${delimiter}${label}`;
+	});
+}
+
+/**
+ * Replaces mentionable model selectors with their display chips and registers
+ * each chip's canonical selector as its atomic editor expansion.
+ */
+export function collapseModelMentions(
+	text: string,
+	labelFor: (selector: string) => string | undefined,
+	register: (label: string, expansion: string) => void,
+): string {
+	if (!text.includes("^") || !allowsModelMentions(text)) return text;
+	MODEL_MENTION_RE.lastIndex = 0;
+	return text.replace(MODEL_MENTION_RE, (match, delimiter: string, selector: string) => {
+		const label = labelFor(selector);
+		if (label === undefined) return match;
+		register(label, modelMentionToken(selector));
+		return `${delimiter}${label}`;
+	});
+}
+
+const CHIP_ICON_KEY = { image: "chip.image", video: "chip.video", paste: "chip.paste" } as const;
+
+/** Compact atomic composer token for attachment `n` in the active symbol preset. */
+export function chipLabel(kind: ChipKind, n: number): string {
+	const icon =
+		typeof theme === "undefined" ? SYMBOL_PRESETS.unicode[CHIP_ICON_KEY[kind]] : theme.symbol(CHIP_ICON_KEY[kind]);
+	return `${icon} #${n}`;
+}
+
+/** Every glyph a chip token may start with, across all symbol presets. */
+const CHIP_ICONS: Record<ChipKind, readonly string[]> = {
+	image: [...new Set(Object.values(SYMBOL_PRESETS).map(m => m[CHIP_ICON_KEY.image]))],
+	video: [...new Set(Object.values(SYMBOL_PRESETS).map(m => m[CHIP_ICON_KEY.video]))],
+	paste: [...new Set(Object.values(SYMBOL_PRESETS).map(m => m[CHIP_ICON_KEY.paste]))],
+};
+
+const CHIP_TOKEN_SOURCE = `(?:${[...CHIP_ICONS.image, ...CHIP_ICONS.video, ...CHIP_ICONS.paste]
+	.map(icon => (/^[a-z]+$/i.test(icon) ? `(?<![A-Za-z])${RegExp.escape(icon)}` : RegExp.escape(icon)))
+	.join("|")}) #[1-9]\\d*`;
+
+/** Infers an attachment kind from a chip label emitted by any configured symbol preset. */
+export function chipLabelKind(label: string): ChipKind {
+	if (CHIP_ICONS.image.some(icon => label.startsWith(icon))) return "image";
+	if (CHIP_ICONS.video.some(icon => label.startsWith(icon))) return "video";
+	return "paste";
+}
+
+const ATTACHMENT_PALETTE: readonly [number, number, number][] = [
+	[255, 179, 102],
+	[125, 207, 255],
+	[189, 147, 249],
+	[105, 220, 158],
+	[255, 141, 188],
+	[240, 223, 120],
+];
+
+/** Stable RGB color assigned to attachment `n`; each attachment type uses a distinct palette offset. */
+export function attachmentRgb(kind: ChipKind, n: number): readonly [number, number, number] {
+	const index =
+		kind === "image"
+			? (n - 1) % ATTACHMENT_PALETTE.length
+			: kind === "video"
+				? (n + 1) % ATTACHMENT_PALETTE.length
+				: (n + 2) % ATTACHMENT_PALETTE.length;
+	return ATTACHMENT_PALETTE[index];
+}
+
+/** ANSI truecolor foreground sequence for the color assigned by {@link attachmentRgb}. */
+export function attachmentSgr(kind: ChipKind, n: number): string {
+	const [r, g, b] = attachmentRgb(kind, n);
+	return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+/** Matches expanded image, video, and paste markers, including optional marker metadata. */
+export const PLACEHOLDER_REGEX = /\[(Image|Video|Paste) #([1-9]\d*)(?:,[^\]\n]*)?\]/g;
+/** Matches an expanded attachment marker, a compact attachment chip, or a skill chip. */
+export const COMPOSER_TOKEN_REGEX = new RegExp(
+	`${PLACEHOLDER_REGEX.source}|${CHIP_TOKEN_SOURCE}|${SKILL_CHIP_SOURCE}`,
+	"gu",
+);
+
+/** Add the registered model-chip labels to the composer placeholder matcher. */
+export function composerTokenRegex(mentionLabels: Iterable<string>): RegExp {
+	const labels = [...new Set(mentionLabels)].sort((a, b) => b.length - a.length);
+	if (labels.length === 0) return COMPOSER_TOKEN_REGEX;
+	return new RegExp(
+		`${COMPOSER_TOKEN_REGEX.source}|(?<mention>${labels.map(label => RegExp.escape(label)).join("|")})`,
+		"gu",
+	);
+}
+
+const VISION_MARKER_REGEX = /\[(Image|Video) #([1-9]\d*)((?:,[^\]\n]*)?)\](?: attachment:\/\/(\2))?/g;
+
+/** Offsets image marker indices, including matching `attachment://` references. */
+export function shiftImageMarkers(text: string, offset: number): string {
+	if (offset === 0) return text;
+	return text.replace(
+		VISION_MARKER_REGEX,
+		(_match, kind: string, idx: string, tail: string, attachmentIdx: string | undefined) => {
+			const marker = `[${kind} #${Number(idx) + offset}${tail}]`;
+			return attachmentIdx === undefined ? marker : `${marker} attachment://${Number(attachmentIdx) + offset}`;
+		},
+	);
+}
+
+/**
+ * Replaces valid expanded image markers with compact tokens and registers each
+ * token's original marker as its atomic editor expansion.
+ */
+export function collapseImageMarkers(
+	text: string,
+	imageCount: number,
+	register: (label: string, expansion: string) => void,
+): string {
+	if (imageCount === 0) return text;
+	return text.replace(VISION_MARKER_REGEX, (match, kind: string, idx: string, tail: string) => {
+		const n = Number(idx);
+		if (n > imageCount) return match;
+		const chipKind = kind === "Video" ? "video" : "image";
+		const label = chipLabel(chipKind, n);
+		register(label, `[${kind} #${n}${tail}]`);
+		return label;
+	});
+}
+
+/**
+ * Drops unreferenced vision attachments from a submission and densely remaps
+ * retained image/video markers. Returns `null` when no compaction is needed.
+ */
+export function compactImageMarkers(text: string, imageCount: number): { text: string; keep: number[] } | null {
+	if (imageCount === 0) return null;
+	const referenced = new Set<number>();
+	const scanner = new RegExp(VISION_MARKER_REGEX.source, "g");
+	for (;;) {
+		const match = scanner.exec(text);
+		if (match === null) break;
+		const n = Number(match[2]);
+		if (n <= imageCount) referenced.add(n);
+	}
+	if (referenced.size === imageCount) return null;
+	const keep = [...referenced].sort((a, b) => a - b);
+	const remap = new Map<number, number>(keep.map((n, i) => [n, i + 1]));
+	const rewritten = text.replace(
+		VISION_MARKER_REGEX,
+		(match, kind: string, idx: string, tail: string, attachmentIdx: string | undefined) => {
+			const mapped = remap.get(Number(idx));
+			if (mapped === undefined) return match;
+			const marker = `[${kind} #${mapped}${tail}]`;
+			return attachmentIdx === undefined ? marker : `${marker} attachment://${mapped}`;
+		},
+	);
+	return { text: rewritten, keep: keep.map(n => n - 1) };
+}
+
+/** Attachment kinds understood by placeholder renderers. */
+export type PlaceholderKind = "image" | "video" | "paste";
+
+/** Rendering callbacks for plain text and parsed attachment references. */
+export interface PlaceholderRenderers {
+	/** Renders text outside attachment references. */
+	renderText: (text: string) => string;
+	/** Renders one parsed marker or compact chip token. */
+	renderReference: (label: string, kind: PlaceholderKind, index: number, form: "marker" | "chip") => string;
+	/** Renders one skill chip (`<icon> <name>`). */
+	renderSkill: (label: string, name: string) => string;
+	/** Renders one registered model mention chip. */
+	renderMention: (label: string) => string;
+}
+
+/** Renders text while treating expanded markers, attachment chips, skill chips, and model mentions as distinct references. */
+export function renderPlaceholders(
+	text: string,
+	renderers: PlaceholderRenderers,
+	tokenRegex: RegExp = COMPOSER_TOKEN_REGEX,
+): string {
+	tokenRegex.lastIndex = 0;
+	let result = "";
+	let last = 0;
+	let matched = false;
+
+	for (;;) {
+		const match = tokenRegex.exec(text);
+		if (match === null) break;
+		matched = true;
+		if (match.index > last) result += renderers.renderText(text.slice(last, match.index));
+		const label = match[0];
+		if (match.groups?.mention !== undefined) {
+			result += renderers.renderMention(label);
+		} else if (label.startsWith("[")) {
+			const kind: PlaceholderKind = match[1] === "Paste" ? "paste" : match[1] === "Video" ? "video" : "image";
+			result += renderers.renderReference(label, kind, Number(match[2]), "marker");
+		} else if (match[3] !== undefined) {
+			result += renderers.renderSkill(label, match[3]);
+		} else {
+			const index = Number(label.slice(label.lastIndexOf("#") + 1));
+			result += renderers.renderReference(label, chipLabelKind(label), index, "chip");
+		}
+		last = match.index + match[0].length;
+	}
+
+	if (!matched) return renderers.renderText(text);
+	if (last < text.length) result += renderers.renderText(text.slice(last));
+	return result;
+}