@xynogen/pix-ask 0.2.14 → 0.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-ask",
-	"version": "0.2.14",
+	"version": "0.2.15",
 	"description": "Pi tool — structured questionnaire UI (ask_user)",
 	"type": "module",
 	"main": "src/index.ts",

package/src/chip-editor.ts

@@ -0,0 +1,271 @@
+/**
+ * chip-editor — a freeform Editor for the questionnaire that renders paste
+ * chips like the main Pi prompt does.
+ *
+ *   long pasted text            →  buffer:  [paste #1 +42 lines]
+ *                                  display: 󰉿 text 42 lines
+ *   pasted image path           →  buffer:  [paste #2 58 chars]
+ *                                  display: 󰋩 image #2
+ *
+ * The base `pi-tui` Editor already collapses large text pastes (>10 lines or
+ * >1000 chars) into `[paste #N …]` markers and expands them back to their full
+ * content on submit. This subclass adds two things on top:
+ *
+ *   1. Image-path detection — a pasted/typed image path becomes its own paste
+ *      marker so it deletes atomically and shows an image chip. On submit it
+ *      expands back to the raw path (a reference the model can read), matching
+ *      pix-display's clipboard-image behavior.
+ *   2. Display restyle — every `[paste #N …]` marker is re-rendered as a
+ *      colored icon chip. Purely visual; the buffer is untouched.
+ *
+ * This duplicates the small helpers from pix-display's ChipEditor rather than
+ * adding a cross-package dependency (repo policy prefers duplication).
+ */
+
+import {
+	Editor,
+	type EditorTheme,
+	type KeybindingsManager,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import { BOLD, FG_BLUE, FG_DIM, FG_GREEN, RST } from "@xynogen/pix-pretty/ansi";
+import { icon } from "@xynogen/pix-pretty/icon-catalog";
+import { readClipboardImageToFile } from "./clipboard-image.js";
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+// Boundary wrapper injected around each expanded paste so the model sees an
+// explicit start/end per blob instead of adjacent pastes merged into one wall.
+// Applies to text and image pastes alike.
+const PASTE_OPEN = "<paste>";
+const PASTE_CLOSE = "</paste>";
+
+const IMAGE_EXTS = new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".bmp",
+	".tif",
+	".tiff",
+	".heic",
+	".heif",
+]);
+
+// Group 1 = prefix char (or empty at start), Group 2 = path.
+const PATH_RE = /(^|[^\w/])((?:~|\/)[^\s,;'"(){}[\]]+)/g;
+
+// Pi's marker grammar — must match exactly for atomic segmentation.
+const MARKER_RE = /\[paste #(\d+)( (\+(\d+) lines|(\d+) chars))?\]/g;
+// Cursor inversion codes the Editor embeds when the cursor intersects a marker.
+const CURSOR_RE = /\x1b\[[0-9;]*m/g;
+// A `[…]` span that starts with `paste #` and may carry interleaved cursor SGR.
+const MARKER_SPAN_RE =
+	/(?:\x1b\[[0-9;]*m)*\[(?:\x1b\[[0-9;]*m)*paste #(?:[^\]]|\x1b\[[0-9;]*m)*\]/g;
+
+// ─── Helpers (duplicated from pix-display/paste-chips) ───────────────────────
+
+function extOf(p: string): string {
+	const dot = p.lastIndexOf(".");
+	return dot >= 0 ? p.slice(dot).toLowerCase() : "";
+}
+
+function isImagePath(p: string): boolean {
+	return IMAGE_EXTS.has(extOf(p));
+}
+
+function makeMarker(id: number, charCount: number): string {
+	return `[paste #${id} ${charCount} chars]`;
+}
+
+/** True when `text` ends with a Pi paste marker (chip). */
+export function endsWithMarker(text: string): boolean {
+	return /\[paste #\d+[^\]]*\]$/.test(text);
+}
+
+/** Mirror of the base Editor's paste-marker grammar, scoped to one id. */
+function markerReFor(pasteId: number): RegExp {
+	// pasteId is a numeric Map key; coerce to an integer literal so the pattern
+	// is provably digits-only (no injection / ReDoS surface).
+	const id = Math.trunc(pasteId);
+	return new RegExp(`\\[paste #${id}( (\\+\\d+ lines|\\d+ chars))?\\]`, "g");
+}
+
+/**
+ * Expand every paste marker in `text` to its content wrapped in
+ * `<paste>…</paste>`. Mirrors the base Editor's expansion loop but adds a
+ * boundary per blob (text and image alike) so adjacent pastes can't merge into
+ * one indistinguishable wall in the model-facing text.
+ */
+export function expandPasteMarkers(text: string, pastes: Map<number, string>): string {
+	let result = text;
+	for (const [pasteId, pasteContent] of pastes) {
+		result = result.replace(
+			markerReFor(pasteId),
+			() => `${PASTE_OPEN}${pasteContent}${PASTE_CLOSE}`,
+		);
+	}
+	return result;
+}
+
+function compactNumber(raw: string): string {
+	const n = Number.parseInt(raw, 10);
+	if (!Number.isFinite(n)) return raw;
+	if (n < 1_000) return `${n}`;
+	if (n < 1_000_000) return `${(n / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
+	return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, "")}m`;
+}
+
+type EditorInternals = {
+	pastes: Map<number, string>;
+	pasteCounter: number;
+};
+
+/**
+ * Walk `text`; for each image path allocate a new paste ID, register the real
+ * path in editor.pastes, remember the ID as an image, and emit a Pi-format
+ * marker so deletion is atomic and the display shows an image chip.
+ */
+export function replaceImagePaths(
+	text: string,
+	internals: EditorInternals,
+	imageIds: Set<number>,
+): string {
+	return text.replace(PATH_RE, (_, prefix: string, rawPath: string) => {
+		if (!isImagePath(rawPath)) return prefix + rawPath;
+		internals.pasteCounter += 1;
+		const id = internals.pasteCounter;
+		internals.pastes.set(id, rawPath);
+		imageIds.add(id);
+		return prefix + makeMarker(id, rawPath.length);
+	});
+}
+
+/**
+ * Re-style every paste marker in a rendered line:
+ *   image → `󰋩 image #N` (blue), text → `󰉿 text N lines/chars` (green).
+ * Width-preserving is not required — the Editor re-wraps each render call.
+ */
+export function restyleMarkers(line: string, imageIds: Set<number>): string {
+	return line.replace(MARKER_SPAN_RE, (span) => {
+		const clean = span.includes("\x1b") ? span.replace(CURSOR_RE, "") : span;
+		MARKER_RE.lastIndex = 0;
+		const m = MARKER_RE.exec(clean);
+		if (!m?.[1]) return span;
+		const [, idStr, , , linesStr, charsStr] = m;
+		const id = Number.parseInt(idStr, 10);
+		if (imageIds.has(id)) {
+			return chip(FG_BLUE, icon("paste.image"), "image", `#${id}`);
+		}
+		if (linesStr) {
+			return chip(FG_GREEN, icon("paste.text"), "text", `${linesStr} lines`);
+		}
+		if (charsStr) {
+			return chip(FG_GREEN, icon("paste.text"), "text", `${compactNumber(charsStr)} chars`);
+		}
+		return chip(FG_GREEN, icon("paste.text"), "text", `#${id}`);
+	});
+}
+
+function chip(color: string, glyph: string, label: string, meta: string): string {
+	return `${color}${BOLD}${glyph} ${label}${RST}${FG_DIM} ${meta}${RST}`;
+}
+
+// ─── ChipEditor ──────────────────────────────────────────────────────────────
+
+/**
+ * Editor subclass for the questionnaire freeform row. Text pastes are collapsed
+ * to badges by the base class; image paths become image chips here. Both expand
+ * to their real content/path on submit via the base `submitValue`.
+ */
+export class ChipEditor extends Editor {
+	private readonly imageIds = new Set<number>();
+	private readonly keybindings?: KeybindingsManager;
+
+	constructor(tui: TUI, theme: EditorTheme, keybindings?: KeybindingsManager) {
+		super(tui, theme);
+		this.keybindings = keybindings;
+		this.patchHandlePaste();
+		this.patchExpandPasteMarkers();
+		this.patchSubmitValue();
+	}
+
+	/**
+	 * Patch `expandPasteMarkers` (TS-private on the base Editor, runtime-public
+	 * JS) so every paste expands to its content wrapped in `<paste>…</paste>`.
+	 * The base inlines content raw, letting adjacent pastes merge into one
+	 * indistinguishable wall; the boundary gives the model an explicit start/end
+	 * per blob — text and image path alike.
+	 */
+	private patchExpandPasteMarkers(): void {
+		const internals = this as unknown as EditorInternals;
+		const self = this as unknown as { expandPasteMarkers(text: string): string };
+		self.expandPasteMarkers = (text: string): string => expandPasteMarkers(text, internals.pastes);
+	}
+
+	override insertTextAtCursor(text: string): void {
+		const internals = this as unknown as EditorInternals;
+		const replaced = replaceImagePaths(text, internals, this.imageIds);
+		// Land the cursor after the chip, not inside it.
+		super.insertTextAtCursor(endsWithMarker(replaced) ? `${replaced} ` : replaced);
+	}
+
+	private patchHandlePaste(): void {
+		const self = this as unknown as { handlePaste(text: string): void };
+		const base = self.handlePaste.bind(self);
+		self.handlePaste = (pastedText: string) => {
+			const before = this.getText();
+			base(pastedText);
+			const after = this.getText();
+			if (endsWithMarker(after) && after !== before) {
+				super.insertTextAtCursor(" ");
+			}
+		};
+	}
+
+	private patchSubmitValue(): void {
+		const self = this as unknown as { submitValue(): void };
+		const base = self.submitValue.bind(self);
+		self.submitValue = () => {
+			// The base resets pasteCounter to zero in submitValue; clear the
+			// parallel image-ID registry in the same operation before reuse.
+			this.imageIds.clear();
+			base();
+		};
+	}
+
+	/**
+	 * Intercept the paste-image key for clipboard-image capture before the base
+	 * Editor sees it. The questionnaire runs as an overlay, so Pi's app-level
+	 * paste-image handler never fires here; we replicate it. The key is resolved
+	 * through the app KeybindingsManager (honoring user remaps and Kitty
+	 * encoding) rather than a raw byte compare. On an image hit we spill the
+	 * bytes to a temp file and insert its path, which `insertTextAtCursor` turns
+	 * into an image chip. No image (or no keybindings/tool) → fall through so the
+	 * base Editor handles the key as ordinary input / text paste.
+	 */
+	override handleInput(data: string): void {
+		if (this.keybindings?.matches(data, "app.clipboard.pasteImage")) {
+			const filePath = readClipboardImageToFile();
+			if (filePath) {
+				this.insertTextAtCursor(filePath);
+				return;
+			}
+		}
+		super.handleInput(data);
+	}
+
+	override render(width: number): string[] {
+		const raw = super.render(width);
+		return raw.map((line) => {
+			const restyled = restyleMarkers(line, this.imageIds);
+			if (visibleWidth(restyled) > width) {
+				return truncateToWidth(restyled, width, "");
+			}
+			return restyled;
+		});
+	}
+}

package/src/clipboard-image.ts

@@ -0,0 +1,177 @@
+/**
+ * clipboard-image.ts — read an image off the system clipboard and spill it to a
+ * temp file, returning the path.
+ *
+ * The questionnaire runs as an overlay, so Pi's app-level "paste image" handler
+ * (Ctrl+V) never reaches it, and Pi's own `readClipboardImage` is not importable
+ * (its package exports map exposes only `.` and `./rpc-entry`). This is a small,
+ * provider-neutral reimplementation of the same probe order Pi uses:
+ *
+ *   Wayland / WSL → wl-paste, then xclip
+ *   WSL (fallback) → powershell.exe (Windows clipboard)
+ *   X11           → xclip
+ *
+ * Only the reachable, dependency-free path is implemented — spawning the same
+ * CLI tools Pi relies on. No clipboard, no image → null (caller falls back to
+ * text paste).
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const LIST_TIMEOUT_MS = 1000;
+const READ_TIMEOUT_MS = 3000;
+const POWERSHELL_TIMEOUT_MS = 5000;
+const MAX_BUFFER_BYTES = 50 * 1024 * 1024;
+
+// Preference order mirrors Pi: PNG first, then other lossless/animated formats.
+const SUPPORTED_MIME = ["image/png", "image/jpeg", "image/webp", "image/gif"];
+
+type ClipImage = { bytes: Buffer; mimeType: string };
+
+function baseMime(mimeType: string): string {
+	return mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
+}
+
+export function extForMime(mimeType: string): string {
+	switch (baseMime(mimeType)) {
+		case "image/png":
+			return "png";
+		case "image/jpeg":
+			return "jpg";
+		case "image/webp":
+			return "webp";
+		case "image/gif":
+			return "gif";
+		default:
+			return "png";
+	}
+}
+
+function pickPreferredMime(types: string[]): string | null {
+	const normalized = types
+		.map((t) => t.trim())
+		.filter(Boolean)
+		.map((t) => ({ raw: t, base: baseMime(t) }));
+	for (const preferred of SUPPORTED_MIME) {
+		const match = normalized.find((t) => t.base === preferred);
+		if (match) return match.raw;
+	}
+	return normalized.find((t) => t.base.startsWith("image/"))?.raw ?? null;
+}
+
+function run(command: string, args: string[], timeoutMs = READ_TIMEOUT_MS): Buffer | null {
+	const result = spawnSync(command, args, { timeout: timeoutMs, maxBuffer: MAX_BUFFER_BYTES });
+	if (result.error || result.status !== 0) return null;
+	const out = result.stdout;
+	return Buffer.isBuffer(out) ? out : Buffer.from(out ?? "");
+}
+
+export function isWaylandSession(env: NodeJS.ProcessEnv = process.env): boolean {
+	return Boolean(env.WAYLAND_DISPLAY) || env.XDG_SESSION_TYPE === "wayland";
+}
+
+function isWSL(env: NodeJS.ProcessEnv = process.env): boolean {
+	if (env.WSL_DISTRO_NAME || env.WSLENV) return true;
+	try {
+		return /microsoft|wsl/i.test(readFileSync("/proc/version", "utf-8"));
+	} catch {
+		return false;
+	}
+}
+
+function readViaWlPaste(): ClipImage | null {
+	const list = run("wl-paste", ["--list-types"], LIST_TIMEOUT_MS);
+	if (!list) return null;
+	const types = list
+		.toString("utf-8")
+		.split(/\r?\n/)
+		.map((t) => t.trim())
+		.filter(Boolean);
+	const selected = pickPreferredMime(types);
+	if (!selected) return null;
+	const data = run("wl-paste", ["--type", selected, "--no-newline"]);
+	if (!data || data.length === 0) return null;
+	return { bytes: data, mimeType: baseMime(selected) };
+}
+
+function readViaXclip(): ClipImage | null {
+	const targets = run("xclip", ["-selection", "clipboard", "-t", "TARGETS", "-o"], LIST_TIMEOUT_MS);
+	const candidates = targets
+		? targets
+				.toString("utf-8")
+				.split(/\r?\n/)
+				.map((t) => t.trim())
+				.filter(Boolean)
+		: [];
+	const preferred = candidates.length > 0 ? pickPreferredMime(candidates) : null;
+	const tryTypes = preferred ? [preferred, ...SUPPORTED_MIME] : [...SUPPORTED_MIME];
+	for (const mimeType of tryTypes) {
+		const data = run("xclip", ["-selection", "clipboard", "-t", mimeType, "-o"]);
+		if (data && data.length > 0) return { bytes: data, mimeType: baseMime(mimeType) };
+	}
+	return null;
+}
+
+function readViaPowerShell(): ClipImage | null {
+	const tmpFile = join(tmpdir(), `pix-wsl-clip-${randomUUID()}.png`);
+	try {
+		const winPathBuf = run("wslpath", ["-w", tmpFile], LIST_TIMEOUT_MS);
+		const winPath = winPathBuf?.toString("utf-8").trim();
+		if (!winPath) return null;
+		const psQuoted = winPath.split("'").join("''");
+		const psScript = [
+			"Add-Type -AssemblyName System.Windows.Forms",
+			"Add-Type -AssemblyName System.Drawing",
+			`$path = '${psQuoted}'`,
+			"$img = [System.Windows.Forms.Clipboard]::GetImage()",
+			"if ($img) { $img.Save($path, [System.Drawing.Imaging.ImageFormat]::Png); Write-Output 'ok' } else { Write-Output 'empty' }",
+		].join("; ");
+		const out = run("powershell.exe", ["-NoProfile", "-Command", psScript], POWERSHELL_TIMEOUT_MS);
+		if (out?.toString("utf-8").trim() !== "ok") return null;
+		const bytes = readFileSync(tmpFile);
+		if (bytes.length === 0) return null;
+		return { bytes, mimeType: "image/png" };
+	} catch {
+		return null;
+	} finally {
+		try {
+			unlinkSync(tmpFile);
+		} catch {
+			// best-effort cleanup
+		}
+	}
+}
+
+/**
+ * Read a clipboard image and spill it to a temp file. Returns the file path, or
+ * null when there is no image (or no clipboard tool). Linux-only probing; other
+ * platforms return null (overlay can't reach a native clipboard bridge).
+ */
+export function readClipboardImageToFile(
+	env: NodeJS.ProcessEnv = process.env,
+	platform: NodeJS.Platform = process.platform,
+): string | null {
+	if (env.TERMUX_VERSION || platform !== "linux") return null;
+
+	const wsl = isWSL(env);
+	const wayland = isWaylandSession(env);
+
+	let image: ClipImage | null = null;
+	if (wayland || wsl) image = readViaWlPaste() ?? readViaXclip();
+	if (!image && wsl) image = readViaPowerShell();
+	if (!image && !wayland) image = readViaXclip();
+	if (!image) return null;
+
+	const ext = extForMime(image.mimeType);
+	const filePath = join(tmpdir(), `pix-clipboard-${randomUUID()}.${ext}`);
+	try {
+		writeFileSync(filePath, image.bytes);
+	} catch {
+		return null;
+	}
+	return filePath;
+}

package/src/helpers.ts

@@ -23,13 +23,18 @@ export function hasAnyPreview(q: QuestionData): boolean {
 	return q.options.some((o) => typeof o.preview === "string" && o.preview.length > 0);
 }
 
-/** Which sentinel rows are auto-appended for a question. */
+/**
+ * Which sentinel rows are auto-appended for a question.
+ *
+ * Freeform ("Type something.") is ALWAYS offered so the user can reject every
+ * option and answer in their own words — regardless of preview or multi-select.
+ * Multi-select additionally gets a "Confirm" row to commit the checked options.
+ */
 export function sentinelsFor(q: QuestionData): Array<{ kind: string; label: string }> {
 	const out: Array<{ kind: string; label: string }> = [];
+	out.push({ kind: "other", label: SENTINEL_FREEFORM });
 	if (q.multiSelect) {
 		out.push({ kind: "next", label: SENTINEL_NEXT });
-	} else if (!hasAnyPreview(q)) {
-		out.push({ kind: "other", label: SENTINEL_FREEFORM });
 	}
 	return out;
 }

package/src/questionnaire.ts

@@ -2,7 +2,6 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import {
 	Container,
 	decodeKittyPrintable,
-	Editor,
 	fuzzyFilter,
 	Key,
 	type KeybindingsManager,
@@ -19,6 +18,7 @@ import {
 	modalWidth,
 	terminalModalHeight,
 } from "@xynogen/pix-pretty/modal-frame";
+import { ChipEditor } from "./chip-editor.js";
 import { dim } from "./components.js";
 import { checkboxGlyphs, selectionGlyph } from "./glyphs.js";
 import { safeMarkdownTheme, sentinelsFor } from "./helpers.js";
@@ -57,7 +57,7 @@ export class AskQuestionnaire extends Container {
 	private selectedOptionIndex = 0;
 	private multiChecked = new Set<number>();
 	private inputMode = false;
-	private editor?: Editor;
+	private editor?: ChipEditor;
 	private mdTheme = safeMarkdownTheme();
 	private pager = new ModalPager();
 	private selectedOptionRows: { start: number; end: number } | undefined;
@@ -119,18 +119,22 @@ export class AskQuestionnaire extends Container {
 
 	// ── Layout ─────────────────────────────────────────────────────────
 
-	private ensureEditor(): Editor {
+	private ensureEditor(): ChipEditor {
 		if (this.editor) return this.editor;
-		const editor = new Editor(this.tui, {
-			borderColor: (s: string) => this.theme.fg("accent", s),
-			selectList: {
-				selectedPrefix: (s: string) => this.theme.fg("accent", s),
-				selectedText: (s: string) => this.theme.fg("accent", s),
-				description: (s: string) => this.theme.fg("muted", s),
-				scrollInfo: (s: string) => this.theme.fg("dim", s),
-				noMatch: (s: string) => this.theme.fg("warning", s),
+		const editor = new ChipEditor(
+			this.tui,
+			{
+				borderColor: (s: string) => this.theme.fg("accent", s),
+				selectList: {
+					selectedPrefix: (s: string) => this.theme.fg("accent", s),
+					selectedText: (s: string) => this.theme.fg("accent", s),
+					description: (s: string) => this.theme.fg("muted", s),
+					scrollInfo: (s: string) => this.theme.fg("dim", s),
+					noMatch: (s: string) => this.theme.fg("warning", s),
+				},
 			},
-		});
+			this.keybindings,
+		);
 		editor.disableSubmit = false;
 		editor.onSubmit = (text: string) => this.handleFreeformSubmit(text);
 		editor.focused = true;
@@ -450,6 +454,9 @@ export class AskQuestionnaire extends Container {
 			const sel = i === this.selectedOptionIndex;
 			const ptr = sel ? t.fg("accent", "→") : " ";
 
+			// Visually separate the "Confirm" commit row from the choices above it.
+			if (item.kind === "next" && lines.length > 0) lines.push("");
+
 			const itemStart = lines.length;
 			if (item.kind === "option" && item.option) {
 				const optIdx = this.filteredOptions.indexOf(item.option);

package/src/schema.ts

@@ -10,7 +10,7 @@ export const MAX_LABEL_LENGTH = 60;
 
 export const SENTINEL_FREEFORM = "Type something.";
 export const SENTINEL_CHAT = "Chat about this";
-export const SENTINEL_NEXT = "Next";
+export const SENTINEL_NEXT = "Confirm";
 
 export const SPLIT_PANE_MIN_WIDTH = 84;
 export const SEPARATOR = " │ ";