@greppleai/grip-tui 0.0.0-stage → 0.1.3

package/dist/stdin-buffer.js

@@ -0,0 +1,318 @@
+/**
+ * StdinBuffer buffers input and emits complete sequences.
+ *
+ * This is necessary because stdin data events can arrive in partial chunks,
+ * especially for escape sequences like mouse events. Without buffering,
+ * partial sequences can be misinterpreted as regular keypresses.
+ *
+ * For example, the mouse SGR sequence `\x1b[<35;20;5m` might arrive as:
+ * - Event 1: `\x1b`
+ * - Event 2: `[<35`
+ * - Event 3: `;20;5m`
+ *
+ * The buffer accumulates these until a complete sequence is detected.
+ * Call the `process()` method to feed input data.
+ *
+ * Based on code from OpenTUI (https://github.com/anomalyco/opentui)
+ * MIT License - Copyright (c) 2025 opentui
+ */
+import { EventEmitter } from "events";
+const ESC = "\x1b";
+const BRACKETED_PASTE_START = "\x1b[200~";
+const BRACKETED_PASTE_END = "\x1b[201~";
+const ESCAPE_SEQUENCE_PREFIXES = new Set(["[", "]", "O", "P", "_"]);
+/**
+ * Check if a string is a complete escape sequence or needs more data
+ */
+function isCompleteSequence(data) {
+    if (!data.startsWith(ESC)) {
+        return "not-escape";
+    }
+    if (data.length === 1) {
+        return "incomplete";
+    }
+    const afterEsc = data.slice(1);
+    // CSI sequences: ESC [
+    if (afterEsc.startsWith("[")) {
+        // Check for old-style mouse sequence: ESC[M + 3 bytes
+        if (afterEsc.startsWith("[M")) {
+            // Old-style mouse needs ESC[M + 3 bytes = 6 total
+            return data.length >= 6 ? "complete" : "incomplete";
+        }
+        return isCompleteCsiSequence(data);
+    }
+    // OSC sequences: ESC ]
+    if (afterEsc.startsWith("]")) {
+        return isCompleteOscSequence(data);
+    }
+    // DCS sequences: ESC P ... ESC \ (includes XTVersion responses)
+    if (afterEsc.startsWith("P")) {
+        return isCompleteDcsSequence(data);
+    }
+    // APC sequences: ESC _ ... ESC \ (includes Kitty graphics responses)
+    if (afterEsc.startsWith("_")) {
+        return isCompleteApcSequence(data);
+    }
+    // SS3 sequences: ESC O
+    if (afterEsc.startsWith("O")) {
+        // ESC O followed by a single character
+        return afterEsc.length >= 2 ? "complete" : "incomplete";
+    }
+    // Meta key sequences: ESC followed by a single character
+    if (afterEsc.length === 1) {
+        return "complete";
+    }
+    // Unknown escape sequence - treat as complete
+    return "complete";
+}
+/**
+ * Check if CSI sequence is complete
+ * CSI sequences: ESC [ ... followed by a final byte (0x40-0x7E)
+ */
+function getSgrMouseSequenceCompletion(payload, lastCharacter) {
+    if (/^<\d+;\d+;\d+[Mm]$/.test(payload))
+        return "complete";
+    if (lastCharacter === "M" || lastCharacter === "m") {
+        const parts = payload.slice(1, -1).split(";");
+        if (parts.length === 3 && parts.every((part) => /^\d+$/.test(part)))
+            return "complete";
+    }
+    return "incomplete";
+}
+function isCompleteCsiSequence(data) {
+    if (!data.startsWith(`${ESC}[`)) {
+        return "complete";
+    }
+    // Need at least ESC [ and one more character
+    if (data.length < 3) {
+        return "incomplete";
+    }
+    const payload = data.slice(2);
+    // CSI sequences end with a byte in the range 0x40-0x7E (@-~)
+    // This includes all letters and several special characters
+    const lastChar = payload[payload.length - 1];
+    const lastCharCode = lastChar.charCodeAt(0);
+    if (lastCharCode < 0x40 || lastCharCode > 0x7e)
+        return "incomplete";
+    // Special handling for SGR mouse sequences: ESC[<B;X;Ym or ESC[<B;X;YM
+    if (payload.startsWith("<"))
+        return getSgrMouseSequenceCompletion(payload, lastChar);
+    return "complete";
+}
+/**
+ * Check if OSC sequence is complete
+ * OSC sequences: ESC ] ... ST (where ST is ESC \ or BEL)
+ */
+function isCompleteOscSequence(data) {
+    if (!data.startsWith(`${ESC}]`)) {
+        return "complete";
+    }
+    // OSC sequences end with ST (ESC \) or BEL (\x07)
+    if (data.endsWith(`${ESC}\\`) || data.endsWith("\x07")) {
+        return "complete";
+    }
+    return "incomplete";
+}
+/**
+ * Check if DCS (Device Control String) sequence is complete
+ * DCS sequences: ESC P ... ST (where ST is ESC \)
+ * Used for XTVersion responses like ESC P >| ... ESC \
+ */
+function isCompleteDcsSequence(data) {
+    if (!data.startsWith(`${ESC}P`)) {
+        return "complete";
+    }
+    // DCS sequences end with ST (ESC \)
+    if (data.endsWith(`${ESC}\\`)) {
+        return "complete";
+    }
+    return "incomplete";
+}
+/**
+ * Check if APC (Application Program Command) sequence is complete
+ * APC sequences: ESC _ ... ST (where ST is ESC \)
+ * Used for Kitty graphics responses like ESC _ G ... ESC \
+ */
+function isCompleteApcSequence(data) {
+    if (!data.startsWith(`${ESC}_`)) {
+        return "complete";
+    }
+    // APC sequences end with ST (ESC \)
+    if (data.endsWith(`${ESC}\\`)) {
+        return "complete";
+    }
+    return "incomplete";
+}
+/**
+ * Split accumulated buffer into complete sequences
+ */
+function parseUnmodifiedKittyPrintableCodepoint(sequence) {
+    const match = sequence.match(/^\x1b\[(\d+)(?::\d*)?(?::\d+)?u$/);
+    if (!match)
+        return undefined;
+    const codepoint = parseInt(match[1], 10);
+    return codepoint >= 32 ? codepoint : undefined;
+}
+function shouldSplitAdjacentEscapeSequence(candidate, nextCharacter) {
+    return candidate === `${ESC}${ESC}` && nextCharacter !== undefined && ESCAPE_SEQUENCE_PREFIXES.has(nextCharacter);
+}
+function extractEscapeSequence(remaining) {
+    let sequenceEnd = 1;
+    while (sequenceEnd <= remaining.length) {
+        const candidate = remaining.slice(0, sequenceEnd);
+        const status = isCompleteSequence(candidate);
+        if (status === "incomplete") {
+            sequenceEnd++;
+            continue;
+        }
+        if (status === "complete" && shouldSplitAdjacentEscapeSequence(candidate, remaining[sequenceEnd])) {
+            return { completion: "complete", sequence: ESC, consumed: 1 };
+        }
+        return { completion: "complete", sequence: candidate, consumed: sequenceEnd };
+    }
+    return { completion: "incomplete", sequence: "", consumed: 0 };
+}
+function extractCompleteSequences(buffer) {
+    const sequences = [];
+    let position = 0;
+    while (position < buffer.length) {
+        const remaining = buffer.slice(position);
+        if (!remaining.startsWith(ESC)) {
+            sequences.push(remaining[0]);
+            position++;
+            continue;
+        }
+        const extraction = extractEscapeSequence(remaining);
+        if (extraction.completion === "incomplete")
+            return { sequences, remainder: remaining };
+        sequences.push(extraction.sequence);
+        position += extraction.consumed;
+    }
+    return { sequences, remainder: "" };
+}
+/**
+ * Buffers stdin input and emits complete sequences via the 'data' event.
+ * Handles partial escape sequences that arrive across multiple chunks.
+ */
+export class StdinBuffer extends EventEmitter {
+    buffer = "";
+    timeout = null;
+    timeoutMs;
+    pasteMode = false;
+    pasteBuffer = "";
+    pendingKittyPrintableCodepoint;
+    constructor(options = {}) {
+        super();
+        this.timeoutMs = options.timeout ?? 10;
+    }
+    clearPendingTimeout() {
+        if (!this.timeout)
+            return;
+        clearTimeout(this.timeout);
+        this.timeout = null;
+    }
+    decodeInputChunk(data) {
+        if (!Buffer.isBuffer(data))
+            return data;
+        if (data.length !== 1 || data[0] <= 127)
+            return data.toString();
+        return `${ESC}${String.fromCharCode(data[0] - 128)}`;
+    }
+    emitDataSequences(sequences) {
+        for (const sequence of sequences)
+            this.emitDataSequence(sequence);
+    }
+    finishBracketedPasteIfComplete() {
+        const endIndex = this.pasteBuffer.indexOf(BRACKETED_PASTE_END);
+        if (endIndex === -1)
+            return;
+        const pastedContent = this.pasteBuffer.slice(0, endIndex);
+        const remaining = this.pasteBuffer.slice(endIndex + BRACKETED_PASTE_END.length);
+        this.pasteMode = false;
+        this.pasteBuffer = "";
+        this.pendingKittyPrintableCodepoint = undefined;
+        this.emit("paste", pastedContent);
+        if (remaining.length > 0)
+            this.process(remaining);
+    }
+    continueBracketedPaste() {
+        this.pasteBuffer += this.buffer;
+        this.buffer = "";
+        this.finishBracketedPasteIfComplete();
+    }
+    beginBracketedPaste(startIndex) {
+        if (startIndex > 0) {
+            const beforePaste = this.buffer.slice(0, startIndex);
+            this.emitDataSequences(extractCompleteSequences(beforePaste).sequences);
+        }
+        this.pendingKittyPrintableCodepoint = undefined;
+        this.buffer = this.buffer.slice(startIndex + BRACKETED_PASTE_START.length);
+        this.pasteMode = true;
+        this.pasteBuffer = this.buffer;
+        this.buffer = "";
+        this.finishBracketedPasteIfComplete();
+    }
+    emitCompleteBufferedSequences() {
+        const result = extractCompleteSequences(this.buffer);
+        this.buffer = result.remainder;
+        this.emitDataSequences(result.sequences);
+    }
+    scheduleIncompleteSequenceFlush() {
+        if (this.buffer.length === 0)
+            return;
+        this.timeout = setTimeout(() => this.emitDataSequences(this.flush()), this.timeoutMs);
+    }
+    process(data) {
+        this.clearPendingTimeout();
+        const chunk = this.decodeInputChunk(data);
+        if (chunk.length === 0 && this.buffer.length === 0) {
+            this.emitDataSequence("");
+            return;
+        }
+        this.buffer += chunk;
+        if (this.pasteMode) {
+            this.continueBracketedPaste();
+            return;
+        }
+        const pasteStartIndex = this.buffer.indexOf(BRACKETED_PASTE_START);
+        if (pasteStartIndex !== -1) {
+            this.beginBracketedPaste(pasteStartIndex);
+            return;
+        }
+        this.emitCompleteBufferedSequences();
+        this.scheduleIncompleteSequenceFlush();
+    }
+    emitDataSequence(sequence) {
+        const rawCodepoint = sequence.length === 1 ? sequence.codePointAt(0) : undefined;
+        if (rawCodepoint !== undefined && rawCodepoint === this.pendingKittyPrintableCodepoint) {
+            this.pendingKittyPrintableCodepoint = undefined;
+            return;
+        }
+        this.pendingKittyPrintableCodepoint = parseUnmodifiedKittyPrintableCodepoint(sequence);
+        this.emit("data", sequence);
+    }
+    flush() {
+        this.clearPendingTimeout();
+        if (this.buffer.length === 0) {
+            return [];
+        }
+        const sequences = [this.buffer];
+        this.buffer = "";
+        this.pendingKittyPrintableCodepoint = undefined;
+        return sequences;
+    }
+    clear() {
+        this.clearPendingTimeout();
+        this.buffer = "";
+        this.pasteMode = false;
+        this.pasteBuffer = "";
+        this.pendingKittyPrintableCodepoint = undefined;
+    }
+    getBuffer() {
+        return this.buffer;
+    }
+    destroy() {
+        this.clear();
+    }
+}
+//# sourceMappingURL=stdin-buffer.js.map

package/dist/stdin-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin-buffer.js","sourceRoot":"","sources":["../src/stdin-buffer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * StdinBuffer buffers input and emits complete sequences.\n *\n * This is necessary because stdin data events can arrive in partial chunks,\n * especially for escape sequences like mouse events. Without buffering,\n * partial sequences can be misinterpreted as regular keypresses.\n *\n * For example, the mouse SGR sequence `\\x1b[<35;20;5m` might arrive as:\n * - Event 1: `\\x1b`\n * - Event 2: `[<35`\n * - Event 3: `;20;5m`\n *\n * The buffer accumulates these until a complete sequence is detected.\n * Call the `process()` method to feed input data.\n *\n * Based on code from OpenTUI (https://github.com/anomalyco/opentui)\n * MIT License - Copyright (c) 2025 opentui\n */\n\nimport { EventEmitter } from \"events\";\n\nconst ESC = \"\\x1b\";\nconst BRACKETED_PASTE_START = \"\\x1b[200~\";\nconst BRACKETED_PASTE_END = \"\\x1b[201~\";\nconst ESCAPE_SEQUENCE_PREFIXES = new Set([\"[\", \"]\", \"O\", \"P\", \"_\"]);\n\ntype SequenceCompletion = \"complete\" | \"incomplete\";\ntype EscapeSequenceCompletion = SequenceCompletion | \"not-escape\";\n\n/**\n * Check if a string is a complete escape sequence or needs more data\n */\nfunction isCompleteSequence(data: string): EscapeSequenceCompletion {\n\tif (!data.startsWith(ESC)) {\n\t\treturn \"not-escape\";\n\t}\n\n\tif (data.length === 1) {\n\t\treturn \"incomplete\";\n\t}\n\n\tconst afterEsc = data.slice(1);\n\n\t// CSI sequences: ESC [\n\tif (afterEsc.startsWith(\"[\")) {\n\t\t// Check for old-style mouse sequence: ESC[M + 3 bytes\n\t\tif (afterEsc.startsWith(\"[M\")) {\n\t\t\t// Old-style mouse needs ESC[M + 3 bytes = 6 total\n\t\t\treturn data.length >= 6 ? \"complete\" : \"incomplete\";\n\t\t}\n\t\treturn isCompleteCsiSequence(data);\n\t}\n\n\t// OSC sequences: ESC ]\n\tif (afterEsc.startsWith(\"]\")) {\n\t\treturn isCompleteOscSequence(data);\n\t}\n\n\t// DCS sequences: ESC P ... ESC \\ (includes XTVersion responses)\n\tif (afterEsc.startsWith(\"P\")) {\n\t\treturn isCompleteDcsSequence(data);\n\t}\n\n\t// APC sequences: ESC _ ... ESC \\ (includes Kitty graphics responses)\n\tif (afterEsc.startsWith(\"_\")) {\n\t\treturn isCompleteApcSequence(data);\n\t}\n\n\t// SS3 sequences: ESC O\n\tif (afterEsc.startsWith(\"O\")) {\n\t\t// ESC O followed by a single character\n\t\treturn afterEsc.length >= 2 ? \"complete\" : \"incomplete\";\n\t}\n\n\t// Meta key sequences: ESC followed by a single character\n\tif (afterEsc.length === 1) {\n\t\treturn \"complete\";\n\t}\n\n\t// Unknown escape sequence - treat as complete\n\treturn \"complete\";\n}\n\n/**\n * Check if CSI sequence is complete\n * CSI sequences: ESC [ ... followed by a final byte (0x40-0x7E)\n */\nfunction getSgrMouseSequenceCompletion(payload: string, lastCharacter: string): SequenceCompletion {\n\tif (/^<\\d+;\\d+;\\d+[Mm]$/.test(payload)) return \"complete\";\n\tif (lastCharacter === \"M\" || lastCharacter === \"m\") {\n\t\tconst parts = payload.slice(1, -1).split(\";\");\n\t\tif (parts.length === 3 && parts.every((part) => /^\\d+$/.test(part))) return \"complete\";\n\t}\n\treturn \"incomplete\";\n}\n\nfunction isCompleteCsiSequence(data: string): SequenceCompletion {\n\tif (!data.startsWith(`${ESC}[`)) {\n\t\treturn \"complete\";\n\t}\n\n\t// Need at least ESC [ and one more character\n\tif (data.length < 3) {\n\t\treturn \"incomplete\";\n\t}\n\n\tconst payload = data.slice(2);\n\n\t// CSI sequences end with a byte in the range 0x40-0x7E (@-~)\n\t// This includes all letters and several special characters\n\tconst lastChar = payload[payload.length - 1];\n\tconst lastCharCode = lastChar.charCodeAt(0);\n\n\tif (lastCharCode < 0x40 || lastCharCode > 0x7e) return \"incomplete\";\n\n\t// Special handling for SGR mouse sequences: ESC[<B;X;Ym or ESC[<B;X;YM\n\tif (payload.startsWith(\"<\")) return getSgrMouseSequenceCompletion(payload, lastChar);\n\n\treturn \"complete\";\n}\n\n/**\n * Check if OSC sequence is complete\n * OSC sequences: ESC ] ... ST (where ST is ESC \\ or BEL)\n */\nfunction isCompleteOscSequence(data: string): SequenceCompletion {\n\tif (!data.startsWith(`${ESC}]`)) {\n\t\treturn \"complete\";\n\t}\n\n\t// OSC sequences end with ST (ESC \\) or BEL (\\x07)\n\tif (data.endsWith(`${ESC}\\\\`) || data.endsWith(\"\\x07\")) {\n\t\treturn \"complete\";\n\t}\n\n\treturn \"incomplete\";\n}\n\n/**\n * Check if DCS (Device Control String) sequence is complete\n * DCS sequences: ESC P ... ST (where ST is ESC \\)\n * Used for XTVersion responses like ESC P >| ... ESC \\\n */\nfunction isCompleteDcsSequence(data: string): SequenceCompletion {\n\tif (!data.startsWith(`${ESC}P`)) {\n\t\treturn \"complete\";\n\t}\n\n\t// DCS sequences end with ST (ESC \\)\n\tif (data.endsWith(`${ESC}\\\\`)) {\n\t\treturn \"complete\";\n\t}\n\n\treturn \"incomplete\";\n}\n\n/**\n * Check if APC (Application Program Command) sequence is complete\n * APC sequences: ESC _ ... ST (where ST is ESC \\)\n * Used for Kitty graphics responses like ESC _ G ... ESC \\\n */\nfunction isCompleteApcSequence(data: string): SequenceCompletion {\n\tif (!data.startsWith(`${ESC}_`)) {\n\t\treturn \"complete\";\n\t}\n\n\t// APC sequences end with ST (ESC \\)\n\tif (data.endsWith(`${ESC}\\\\`)) {\n\t\treturn \"complete\";\n\t}\n\n\treturn \"incomplete\";\n}\n\n/**\n * Split accumulated buffer into complete sequences\n */\nfunction parseUnmodifiedKittyPrintableCodepoint(sequence: string): number | undefined {\n\tconst match = sequence.match(/^\\x1b\\[(\\d+)(?::\\d*)?(?::\\d+)?u$/);\n\tif (!match) return undefined;\n\n\tconst codepoint = parseInt(match[1]!, 10);\n\treturn codepoint >= 32 ? codepoint : undefined;\n}\n\ninterface EscapeSequenceExtraction {\n\tcompletion: SequenceCompletion;\n\tsequence: string;\n\tconsumed: number;\n}\n\ninterface ExtractedSequences {\n\tsequences: string[];\n\tremainder: string;\n}\n\nfunction shouldSplitAdjacentEscapeSequence(candidate: string, nextCharacter: string | undefined): boolean {\n\treturn candidate === `${ESC}${ESC}` && nextCharacter !== undefined && ESCAPE_SEQUENCE_PREFIXES.has(nextCharacter);\n}\n\nfunction extractEscapeSequence(remaining: string): EscapeSequenceExtraction {\n\tlet sequenceEnd = 1;\n\twhile (sequenceEnd <= remaining.length) {\n\t\tconst candidate = remaining.slice(0, sequenceEnd);\n\t\tconst status = isCompleteSequence(candidate);\n\t\tif (status === \"incomplete\") {\n\t\t\tsequenceEnd++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (status === \"complete\" && shouldSplitAdjacentEscapeSequence(candidate, remaining[sequenceEnd])) {\n\t\t\treturn { completion: \"complete\", sequence: ESC, consumed: 1 };\n\t\t}\n\t\treturn { completion: \"complete\", sequence: candidate, consumed: sequenceEnd };\n\t}\n\treturn { completion: \"incomplete\", sequence: \"\", consumed: 0 };\n}\n\nfunction extractCompleteSequences(buffer: string): ExtractedSequences {\n\tconst sequences: string[] = [];\n\tlet position = 0;\n\n\twhile (position < buffer.length) {\n\t\tconst remaining = buffer.slice(position);\n\t\tif (!remaining.startsWith(ESC)) {\n\t\t\tsequences.push(remaining[0]!);\n\t\t\tposition++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst extraction = extractEscapeSequence(remaining);\n\t\tif (extraction.completion === \"incomplete\") return { sequences, remainder: remaining };\n\t\tsequences.push(extraction.sequence);\n\t\tposition += extraction.consumed;\n\t}\n\n\treturn { sequences, remainder: \"\" };\n}\n\nexport type StdinBufferOptions = {\n\t/**\n\t * Maximum time to wait for sequence completion (default: 10ms)\n\t * After this time, the buffer is flushed even if incomplete\n\t */\n\ttimeout?: number;\n};\n\nexport type StdinBufferEventMap = {\n\tdata: [string];\n\tpaste: [string];\n};\n\n/**\n * Buffers stdin input and emits complete sequences via the 'data' event.\n * Handles partial escape sequences that arrive across multiple chunks.\n */\nexport class StdinBuffer extends EventEmitter<StdinBufferEventMap> {\n\tprivate buffer: string = \"\";\n\tprivate timeout: ReturnType<typeof setTimeout> | null = null;\n\tprivate readonly timeoutMs: number;\n\tprivate pasteMode: boolean = false;\n\tprivate pasteBuffer: string = \"\";\n\tprivate pendingKittyPrintableCodepoint: number | undefined;\n\n\tconstructor(options: StdinBufferOptions = {}) {\n\t\tsuper();\n\t\tthis.timeoutMs = options.timeout ?? 10;\n\t}\n\n\tprivate clearPendingTimeout(): void {\n\t\tif (!this.timeout) return;\n\t\tclearTimeout(this.timeout);\n\t\tthis.timeout = null;\n\t}\n\n\tprivate decodeInputChunk(data: string | Buffer): string {\n\t\tif (!Buffer.isBuffer(data)) return data;\n\t\tif (data.length !== 1 || data[0]! <= 127) return data.toString();\n\t\treturn `${ESC}${String.fromCharCode(data[0]! - 128)}`;\n\t}\n\n\tprivate emitDataSequences(sequences: readonly string[]): void {\n\t\tfor (const sequence of sequences) this.emitDataSequence(sequence);\n\t}\n\n\tprivate finishBracketedPasteIfComplete(): void {\n\t\tconst endIndex = this.pasteBuffer.indexOf(BRACKETED_PASTE_END);\n\t\tif (endIndex === -1) return;\n\t\tconst pastedContent = this.pasteBuffer.slice(0, endIndex);\n\t\tconst remaining = this.pasteBuffer.slice(endIndex + BRACKETED_PASTE_END.length);\n\t\tthis.pasteMode = false;\n\t\tthis.pasteBuffer = \"\";\n\t\tthis.pendingKittyPrintableCodepoint = undefined;\n\t\tthis.emit(\"paste\", pastedContent);\n\t\tif (remaining.length > 0) this.process(remaining);\n\t}\n\n\tprivate continueBracketedPaste(): void {\n\t\tthis.pasteBuffer += this.buffer;\n\t\tthis.buffer = \"\";\n\t\tthis.finishBracketedPasteIfComplete();\n\t}\n\n\tprivate beginBracketedPaste(startIndex: number): void {\n\t\tif (startIndex > 0) {\n\t\t\tconst beforePaste = this.buffer.slice(0, startIndex);\n\t\t\tthis.emitDataSequences(extractCompleteSequences(beforePaste).sequences);\n\t\t}\n\t\tthis.pendingKittyPrintableCodepoint = undefined;\n\t\tthis.buffer = this.buffer.slice(startIndex + BRACKETED_PASTE_START.length);\n\t\tthis.pasteMode = true;\n\t\tthis.pasteBuffer = this.buffer;\n\t\tthis.buffer = \"\";\n\t\tthis.finishBracketedPasteIfComplete();\n\t}\n\n\tprivate emitCompleteBufferedSequences(): void {\n\t\tconst result = extractCompleteSequences(this.buffer);\n\t\tthis.buffer = result.remainder;\n\t\tthis.emitDataSequences(result.sequences);\n\t}\n\n\tprivate scheduleIncompleteSequenceFlush(): void {\n\t\tif (this.buffer.length === 0) return;\n\t\tthis.timeout = setTimeout(() => this.emitDataSequences(this.flush()), this.timeoutMs);\n\t}\n\n\tpublic process(data: string | Buffer): void {\n\t\tthis.clearPendingTimeout();\n\t\tconst chunk = this.decodeInputChunk(data);\n\t\tif (chunk.length === 0 && this.buffer.length === 0) {\n\t\t\tthis.emitDataSequence(\"\");\n\t\t\treturn;\n\t\t}\n\t\tthis.buffer += chunk;\n\n\t\tif (this.pasteMode) {\n\t\t\tthis.continueBracketedPaste();\n\t\t\treturn;\n\t\t}\n\t\tconst pasteStartIndex = this.buffer.indexOf(BRACKETED_PASTE_START);\n\t\tif (pasteStartIndex !== -1) {\n\t\t\tthis.beginBracketedPaste(pasteStartIndex);\n\t\t\treturn;\n\t\t}\n\n\t\tthis.emitCompleteBufferedSequences();\n\t\tthis.scheduleIncompleteSequenceFlush();\n\t}\n\n\tprivate emitDataSequence(sequence: string): void {\n\t\tconst rawCodepoint = sequence.length === 1 ? sequence.codePointAt(0) : undefined;\n\t\tif (rawCodepoint !== undefined && rawCodepoint === this.pendingKittyPrintableCodepoint) {\n\t\t\tthis.pendingKittyPrintableCodepoint = undefined;\n\t\t\treturn;\n\t\t}\n\n\t\tthis.pendingKittyPrintableCodepoint = parseUnmodifiedKittyPrintableCodepoint(sequence);\n\t\tthis.emit(\"data\", sequence);\n\t}\n\n\tflush(): string[] {\n\t\tthis.clearPendingTimeout();\n\n\t\tif (this.buffer.length === 0) {\n\t\t\treturn [];\n\t\t}\n\n\t\tconst sequences = [this.buffer];\n\t\tthis.buffer = \"\";\n\t\tthis.pendingKittyPrintableCodepoint = undefined;\n\t\treturn sequences;\n\t}\n\n\tclear(): void {\n\t\tthis.clearPendingTimeout();\n\t\tthis.buffer = \"\";\n\t\tthis.pasteMode = false;\n\t\tthis.pasteBuffer = \"\";\n\t\tthis.pendingKittyPrintableCodepoint = undefined;\n\t}\n\n\tgetBuffer(): string {\n\t\treturn this.buffer;\n\t}\n\n\tdestroy(): void {\n\t\tthis.clear();\n\t}\n}\n"]}

package/dist/terminal-control.d.ts

@@ -0,0 +1,5 @@
+/** Remove characters that can terminate or introduce terminal control strings. */
+export declare function sanitizeTerminalControlPayload(value: string): string;
+/** Preserve SGR color/style sequences while removing all other control characters. */
+export declare function sanitizeHyperlinkText(value: string): string;
+//# sourceMappingURL=terminal-control.d.ts.map

package/dist/terminal-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-control.d.ts","sourceRoot":"","sources":["../src/terminal-control.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB3D","sourcesContent":["const SGR_SEQUENCE = /^\\x1b\\[[0-9:;]*m/;\n\n/** Remove characters that can terminate or introduce terminal control strings. */\nexport function sanitizeTerminalControlPayload(value: string): string {\n\treturn value.replace(/[\\u0000-\\u001f\\u007f-\\u009f]/g, \"\");\n}\n\n/** Preserve SGR color/style sequences while removing all other control characters. */\nexport function sanitizeHyperlinkText(value: string): string {\n\tlet result = \"\";\n\tlet offset = 0;\n\twhile (offset < value.length) {\n\t\tif (value.charCodeAt(offset) === 0x1b) {\n\t\t\tconst sgr = value.slice(offset).match(SGR_SEQUENCE)?.[0];\n\t\t\tif (sgr) {\n\t\t\t\tresult += sgr;\n\t\t\t\toffset += sgr.length;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\t\tconst code = value.charCodeAt(offset);\n\t\tif (code > 0x1f && (code < 0x7f || code > 0x9f)) result += value[offset];\n\t\toffset++;\n\t}\n\treturn result;\n}\n"]}

package/dist/terminal-control.js

@@ -0,0 +1,26 @@
+const SGR_SEQUENCE = /^\x1b\[[0-9:;]*m/;
+/** Remove characters that can terminate or introduce terminal control strings. */
+export function sanitizeTerminalControlPayload(value) {
+    return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+}
+/** Preserve SGR color/style sequences while removing all other control characters. */
+export function sanitizeHyperlinkText(value) {
+    let result = "";
+    let offset = 0;
+    while (offset < value.length) {
+        if (value.charCodeAt(offset) === 0x1b) {
+            const sgr = value.slice(offset).match(SGR_SEQUENCE)?.[0];
+            if (sgr) {
+                result += sgr;
+                offset += sgr.length;
+                continue;
+            }
+        }
+        const code = value.charCodeAt(offset);
+        if (code > 0x1f && (code < 0x7f || code > 0x9f))
+            result += value[offset];
+        offset++;
+    }
+    return result;
+}
+//# sourceMappingURL=terminal-control.js.map

package/dist/terminal-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-control.js","sourceRoot":"","sources":["../src/terminal-control.ts"],"names":[],"mappings":"AAAA,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAExC,kFAAkF;AAClF,MAAM,UAAU,8BAA8B,CAAC,KAAa,EAAU;IACrE,OAAO,KAAK,CAAC,OAAO,CAAC,+BAA+B,EAAE,EAAE,CAAC,CAAC;AAAA,CAC1D;AAED,sFAAsF;AACtF,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAU;IAC5D,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OAAO,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACzD,IAAI,GAAG,EAAE,CAAC;gBACT,MAAM,IAAI,GAAG,CAAC;gBACd,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC;gBACrB,SAAS;YACV,CAAC;QACF,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;QACzE,MAAM,EAAE,CAAC;IACV,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["const SGR_SEQUENCE = /^\\x1b\\[[0-9:;]*m/;\n\n/** Remove characters that can terminate or introduce terminal control strings. */\nexport function sanitizeTerminalControlPayload(value: string): string {\n\treturn value.replace(/[\\u0000-\\u001f\\u007f-\\u009f]/g, \"\");\n}\n\n/** Preserve SGR color/style sequences while removing all other control characters. */\nexport function sanitizeHyperlinkText(value: string): string {\n\tlet result = \"\";\n\tlet offset = 0;\n\twhile (offset < value.length) {\n\t\tif (value.charCodeAt(offset) === 0x1b) {\n\t\t\tconst sgr = value.slice(offset).match(SGR_SEQUENCE)?.[0];\n\t\t\tif (sgr) {\n\t\t\t\tresult += sgr;\n\t\t\t\toffset += sgr.length;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\t\tconst code = value.charCodeAt(offset);\n\t\tif (code > 0x1f && (code < 0x7f || code > 0x9f)) result += value[offset];\n\t\toffset++;\n\t}\n\treturn result;\n}\n"]}

package/dist/terminal-image.d.ts

@@ -0,0 +1,112 @@
+export type ImageProtocol = "kitty" | "iterm2" | null;
+export interface TerminalCapabilities {
+    images: ImageProtocol;
+    trueColor: boolean;
+    hyperlinks: boolean;
+}
+export interface CellDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+export interface ImageDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+export interface ImageRenderOptions {
+    maxWidthCells?: number;
+    maxHeightCells?: number;
+    preserveAspectRatio?: boolean;
+    /** Kitty image ID. If provided, reuses/replaces existing image with this ID. */
+    imageId?: number;
+    /** Whether Kitty should apply its default cursor movement after placement. */
+    moveCursor?: boolean;
+}
+export interface KittyImageEncodeOptions {
+    columns?: number;
+    rows?: number;
+    imageId?: number;
+    /** Whether Kitty should apply its default cursor movement after placement. Default: true. */
+    moveCursor?: boolean;
+}
+export interface ITerm2ImageEncodeOptions {
+    width?: number | string;
+    height?: number | string;
+    name?: string;
+    preserveAspectRatio?: boolean;
+    inline?: boolean;
+}
+export declare function getCellDimensions(): CellDimensions;
+export declare function setCellDimensions(dims: CellDimensions): void;
+export declare function detectCapabilities(tmuxForwardsHyperlink?: () => boolean): TerminalCapabilities;
+export declare function getCapabilities(): TerminalCapabilities;
+export declare function resetCapabilitiesCache(): void;
+/** Override the cached capabilities. Useful in tests to exercise both code paths. */
+export declare function setCapabilities(caps: TerminalCapabilities): void;
+export declare function isImageLine(line: string): boolean;
+/**
+ * Generate a random image ID for Kitty graphics protocol.
+ * Uses random IDs to avoid collisions between different module instances
+ * (e.g., main app vs extensions).
+ */
+export declare function allocateImageId(): number;
+export declare function encodeKitty(base64Data: string, options?: KittyImageEncodeOptions): string;
+/**
+ * Delete a Kitty graphics image by ID.
+ * Uses uppercase 'I' to also free the image data.
+ */
+export declare function deleteKittyImage(imageId: number): string;
+/**
+ * Delete all visible Kitty graphics images.
+ * Uses uppercase 'A' to also free the image data.
+ */
+export declare function deleteAllKittyImages(): string;
+/** Delete all visible Kitty placements while retaining their uploaded image data. */
+export declare function deleteAllKittyPlacements(): string;
+export declare function encodeITerm2(base64Data: string, options?: ITerm2ImageEncodeOptions): string;
+export interface ImageCellSize {
+    columns: number;
+    rows: number;
+}
+export interface ImageRenderResult extends ImageCellSize {
+    sequence: string;
+    imageId?: number;
+}
+export interface KittyImageMetadata extends ImageCellSize {
+    imageId: number;
+    widthPx: number;
+    heightPx: number;
+}
+export interface KittyImagePlacement {
+    imageId: number;
+    transmissionGeneration: number;
+    transmissionBytes: number;
+    estimatedDecodedBytes: number;
+    sequence: string;
+    replacementLine: string;
+}
+export declare function registerKittyImageMetadata(metadata: KittyImageMetadata): void;
+export declare function getKittyImageMetadata(line: string): KittyImageMetadata | undefined;
+/** Build a placement-only command for an image line emitted by {@link renderImage}. */
+export declare function getKittyImagePlacement(line: string): KittyImagePlacement | undefined;
+export declare function cropKittyImageLine(line: string, hiddenRows: number, visibleRows: number): string;
+export declare function calculateImageCellSize(imageDimensions: ImageDimensions, maxWidthCells: number, maxHeightCells?: number, cellDimensions?: CellDimensions): ImageCellSize;
+export declare function calculateImageRows(imageDimensions: ImageDimensions, targetWidthCells: number, cellDimensions?: CellDimensions): number;
+export declare function getPngDimensions(base64Data: string): ImageDimensions | null;
+export declare function getJpegDimensions(base64Data: string): ImageDimensions | null;
+export declare function getGifDimensions(base64Data: string): ImageDimensions | null;
+export declare function getWebpDimensions(base64Data: string): ImageDimensions | null;
+export declare function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null;
+export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): ImageRenderResult | null;
+/**
+ * Wrap text in an OSC 8 hyperlink sequence.
+ * The text is rendered as a clickable hyperlink in terminals that support OSC 8
+ * (Ghostty, Kitty, WezTerm, iTerm2, VSCode, and others).
+ * In terminals that do not support OSC 8, the escape sequences are ignored
+ * and only the plain text is displayed.
+ *
+ * @param text - The visible text to display
+ * @param url - The URL to link to
+ */
+export declare function hyperlink(text: string, url: string): string;
+export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;
+//# sourceMappingURL=terminal-image.d.ts.map

package/dist/terminal-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-image.d.ts","sourceRoot":"","sources":["../src/terminal-image.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from \"node:child_process\";\nimport { sanitizeHyperlinkText, sanitizeTerminalControlPayload } from \"./terminal-control.ts\";\n\nexport type ImageProtocol = \"kitty\" | \"iterm2\" | null;\n\nexport interface TerminalCapabilities {\n\timages: ImageProtocol;\n\ttrueColor: boolean;\n\thyperlinks: boolean;\n}\n\nexport interface CellDimensions {\n\twidthPx: number;\n\theightPx: number;\n}\n\n// grip-ignore noNearIdenticalDataStructures: Bitmap dimensions and terminal-cell pixel metrics come from separate measurement sources and serve distinct rendering APIs.\nexport interface ImageDimensions {\n\twidthPx: number;\n\theightPx: number;\n}\n\nexport interface ImageRenderOptions {\n\tmaxWidthCells?: number;\n\tmaxHeightCells?: number;\n\tpreserveAspectRatio?: boolean;\n\t/** Kitty image ID. If provided, reuses/replaces existing image with this ID. */\n\timageId?: number;\n\t/** Whether Kitty should apply its default cursor movement after placement. */\n\tmoveCursor?: boolean;\n}\n\nexport interface KittyImageEncodeOptions {\n\tcolumns?: number;\n\trows?: number;\n\timageId?: number;\n\t/** Whether Kitty should apply its default cursor movement after placement. Default: true. */\n\tmoveCursor?: boolean;\n}\n\nexport interface ITerm2ImageEncodeOptions {\n\twidth?: number | string;\n\theight?: number | string;\n\tname?: string;\n\tpreserveAspectRatio?: boolean;\n\tinline?: boolean;\n}\nlet cachedCapabilities: TerminalCapabilities | null = null;\n\n// Default cell dimensions - updated by TUI when terminal responds to query\nlet cellDimensions: CellDimensions = { widthPx: 9, heightPx: 18 };\n\nexport function getCellDimensions(): CellDimensions {\n\treturn cellDimensions;\n}\n\nexport function setCellDimensions(dims: CellDimensions): void {\n\tcellDimensions = dims;\n}\n\n/**\n * Checks whether the attached tmux client forwards OSC 8 hyperlinks to the\n * outer terminal. tmux only re-emits them when its `client_termfeatures` lists\n * `hyperlinks`, and strips them otherwise. On any error fallbacks `false`.\n */\nfunction probeTmuxHyperlinks(): boolean {\n\ttry {\n\t\tconst termfeatures = execSync(\"tmux display-message -p '#{client_termfeatures}'\", {\n\t\t\tencoding: \"utf8\",\n\t\t\ttimeout: 250,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"ignore\"],\n\t\t});\n\t\treturn termfeatures\n\t\t\t.split(\",\")\n\t\t\t.map((feature) => feature.trim())\n\t\t\t.includes(\"hyperlinks\");\n\t} catch {\n\t\treturn false;\n\t}\n}\n\ninterface TerminalCapabilityDetection {\n\tmatches: () => boolean;\n\tcapabilities: TerminalCapabilities;\n}\n\nfunction detectKnownTerminalCapabilities(\n\tenv: NodeJS.ProcessEnv,\n\ttermProgram: string,\n\tterminalEmulator: string,\n\tterm: string,\n): TerminalCapabilities | undefined {\n\tconst detections: TerminalCapabilityDetection[] = [\n\t\t{\n\t\t\tmatches: () => Boolean(env.KITTY_WINDOW_ID) || termProgram === \"kitty\",\n\t\t\tcapabilities: { images: \"kitty\", trueColor: true, hyperlinks: true },\n\t\t},\n\t\t{\n\t\t\tmatches: () => termProgram === \"ghostty\" || term.includes(\"ghostty\") || Boolean(env.GHOSTTY_RESOURCES_DIR),\n\t\t\tcapabilities: { images: \"kitty\", trueColor: true, hyperlinks: true },\n\t\t},\n\t\t{\n\t\t\tmatches: () =>\n\t\t\t\ttermProgram === \"warpterminal\" || Boolean(env.WARP_SESSION_ID) || Boolean(env.WARP_TERMINAL_SESSION_UUID),\n\t\t\tcapabilities: { images: \"kitty\", trueColor: true, hyperlinks: true },\n\t\t},\n\t\t{\n\t\t\tmatches: () => Boolean(env.WEZTERM_PANE) || termProgram === \"wezterm\",\n\t\t\tcapabilities: { images: \"kitty\", trueColor: true, hyperlinks: true },\n\t\t},\n\t\t{\n\t\t\tmatches: () => Boolean(env.ITERM_SESSION_ID) || termProgram === \"iterm.app\",\n\t\t\tcapabilities: { images: \"iterm2\", trueColor: true, hyperlinks: true },\n\t\t},\n\t\t{\n\t\t\tmatches: () => Boolean(env.WT_SESSION),\n\t\t\tcapabilities: { images: null, trueColor: true, hyperlinks: true },\n\t\t},\n\t\t{\n\t\t\tmatches: () => termProgram === \"vscode\",\n\t\t\tcapabilities: { images: null, trueColor: true, hyperlinks: true },\n\t\t},\n\t\t{\n\t\t\tmatches: () => termProgram === \"alacritty\",\n\t\t\tcapabilities: { images: null, trueColor: true, hyperlinks: true },\n\t\t},\n\t\t{\n\t\t\tmatches: () => terminalEmulator === \"jetbrains-jediterm\",\n\t\t\tcapabilities: { images: null, trueColor: true, hyperlinks: false },\n\t\t},\n\t];\n\treturn detections.find((detection) => detection.matches())?.capabilities;\n}\n\nexport function detectCapabilities(tmuxForwardsHyperlink: () => boolean = probeTmuxHyperlinks): TerminalCapabilities {\n\tconst env = process.env;\n\tconst termProgram = env.TERM_PROGRAM?.toLowerCase() || \"\";\n\tconst terminalEmulator = env.TERMINAL_EMULATOR?.toLowerCase() || \"\";\n\tconst term = env.TERM?.toLowerCase() || \"\";\n\tconst colorTerm = env.COLORTERM?.toLowerCase() || \"\";\n\tconst hasTrueColorHint = colorTerm === \"truecolor\" || colorTerm === \"24bit\";\n\n\t// Emit OSC 8 hyperlinks only when tmux confirms it forwards.\n\t// Image protocols are unreliable under tmux, so leave `images: null`.\n\tif (env.TMUX || term.startsWith(\"tmux\")) {\n\t\treturn { images: null, trueColor: hasTrueColorHint, hyperlinks: tmuxForwardsHyperlink() };\n\t}\n\n\t// screen does not forward OSC 8 hyperlinks, so keep them off there.\n\tif (term.startsWith(\"screen\")) {\n\t\treturn { images: null, trueColor: hasTrueColorHint, hyperlinks: false };\n\t}\n\n\tconst knownCapabilities = detectKnownTerminalCapabilities(env, termProgram, terminalEmulator, term);\n\tif (knownCapabilities) return knownCapabilities;\n\n\t// Unknown terminal: be conservative. OSC 8 is rendered invisibly as \"just\n\t// text\" on terminals that swallow it, which means the URL disappears from\n\t// the rendered output. Default to the legacy `text (url)` behavior unless we\n\t// have positively identified a hyperlink-capable terminal above.\n\treturn { images: null, trueColor: hasTrueColorHint, hyperlinks: false };\n}\n\nexport function getCapabilities(): TerminalCapabilities {\n\tif (!cachedCapabilities) {\n\t\tcachedCapabilities = detectCapabilities();\n\t}\n\treturn cachedCapabilities;\n}\n\nexport function resetCapabilitiesCache(): void {\n\tcachedCapabilities = null;\n}\n\n/** Override the cached capabilities. Useful in tests to exercise both code paths. */\nexport function setCapabilities(caps: TerminalCapabilities): void {\n\tcachedCapabilities = caps;\n}\n\nconst KITTY_PREFIX = \"\\x1b_G\";\nconst ITERM2_PREFIX = \"\\x1b]1337;File=\";\n\nexport function isImageLine(line: string): boolean {\n\t// Fast path: sequence at line start (single-row images)\n\tif (line.startsWith(KITTY_PREFIX) || line.startsWith(ITERM2_PREFIX)) {\n\t\treturn true;\n\t}\n\t// Slow path: sequence elsewhere (multi-row images have cursor-up prefix)\n\treturn line.includes(KITTY_PREFIX) || line.includes(ITERM2_PREFIX);\n}\n\n/**\n * Generate a random image ID for Kitty graphics protocol.\n * Uses random IDs to avoid collisions between different module instances\n * (e.g., main app vs extensions).\n */\nexport function allocateImageId(): number {\n\t// Use random ID in range [1, 0xffffffff] to avoid collisions\n\treturn Math.floor(Math.random() * 0xfffffffe) + 1;\n}\n\nexport function encodeKitty(base64Data: string, options: KittyImageEncodeOptions = {}): string {\n\tconst sanitizedData = sanitizeTerminalControlPayload(base64Data);\n\tconst CHUNK_SIZE = 4096;\n\n\tconst params: string[] = [\"a=T\", \"f=100\", \"q=2\"];\n\n\tif (options.moveCursor === false) params.push(\"C=1\");\n\tif (options.columns) params.push(`c=${options.columns}`);\n\tif (options.rows) params.push(`r=${options.rows}`);\n\tif (options.imageId) params.push(`i=${options.imageId}`);\n\n\tif (sanitizedData.length <= CHUNK_SIZE) {\n\t\treturn `\\x1b_G${params.join(\",\")};${sanitizedData}\\x1b\\\\`;\n\t}\n\n\tconst chunks: string[] = [];\n\tlet offset = 0;\n\tlet isFirst = true;\n\n\twhile (offset < sanitizedData.length) {\n\t\tconst chunk = sanitizedData.slice(offset, offset + CHUNK_SIZE);\n\t\tconst isLast = offset + CHUNK_SIZE >= sanitizedData.length;\n\n\t\tif (isFirst) {\n\t\t\tchunks.push(`\\x1b_G${params.join(\",\")},m=1;${chunk}\\x1b\\\\`);\n\t\t\tisFirst = false;\n\t\t} else if (isLast) {\n\t\t\tchunks.push(`\\x1b_Gm=0;${chunk}\\x1b\\\\`);\n\t\t} else {\n\t\t\tchunks.push(`\\x1b_Gm=1;${chunk}\\x1b\\\\`);\n\t\t}\n\n\t\toffset += CHUNK_SIZE;\n\t}\n\n\treturn chunks.join(\"\");\n}\n\n/**\n * Delete a Kitty graphics image by ID.\n * Uses uppercase 'I' to also free the image data.\n */\nexport function deleteKittyImage(imageId: number): string {\n\treturn `\\x1b_Ga=d,d=I,i=${imageId},q=2\\x1b\\\\`;\n}\n\n/**\n * Delete all visible Kitty graphics images.\n * Uses uppercase 'A' to also free the image data.\n */\nexport function deleteAllKittyImages(): string {\n\treturn \"\\x1b_Ga=d,d=A,q=2\\x1b\\\\\";\n}\n\n/** Delete all visible Kitty placements while retaining their uploaded image data. */\nexport function deleteAllKittyPlacements(): string {\n\treturn \"\\x1b_Ga=d,d=a,q=2\\x1b\\\\\";\n}\n\nexport function encodeITerm2(base64Data: string, options: ITerm2ImageEncodeOptions = {}): string {\n\tconst sanitizedData = sanitizeTerminalControlPayload(base64Data);\n\tconst params: string[] = [\n\t\t`inline=${options.inline !== false ? 1 : 0}`,\n\t\t`size=${Buffer.byteLength(sanitizedData, \"base64\")}`,\n\t];\n\n\tif (options.width !== undefined) params.push(`width=${sanitizeTerminalControlPayload(String(options.width))}`);\n\tif (options.height !== undefined) params.push(`height=${sanitizeTerminalControlPayload(String(options.height))}`);\n\tif (options.name) {\n\t\tconst nameBase64 = Buffer.from(options.name).toString(\"base64\");\n\t\tparams.push(`name=${nameBase64}`);\n\t}\n\tif (options.preserveAspectRatio === false) {\n\t\tparams.push(\"preserveAspectRatio=0\");\n\t}\n\n\treturn `\\x1b]1337;File=${params.join(\";\")}:${sanitizedData}\\x07`;\n}\n\nexport interface ImageCellSize {\n\tcolumns: number;\n\trows: number;\n}\n\nexport interface ImageRenderResult extends ImageCellSize {\n\tsequence: string;\n\timageId?: number;\n}\n\nexport interface KittyImageMetadata extends ImageCellSize {\n\timageId: number;\n\twidthPx: number;\n\theightPx: number;\n}\ninterface RegisteredKittyImageMetadata extends KittyImageMetadata {\n\ttransmissionGeneration: number;\n}\n\nexport interface KittyImagePlacement {\n\timageId: number;\n\ttransmissionGeneration: number;\n\ttransmissionBytes: number;\n\testimatedDecodedBytes: number;\n\tsequence: string;\n\treplacementLine: string;\n}\n\nconst kittyImageMetadata = new Map<number, RegisteredKittyImageMetadata>();\nlet kittyTransmissionGeneration = 0;\n\nexport function registerKittyImageMetadata(metadata: KittyImageMetadata): void {\n\tkittyTransmissionGeneration += 1;\n\tkittyImageMetadata.delete(metadata.imageId);\n\tkittyImageMetadata.set(metadata.imageId, { ...metadata, transmissionGeneration: kittyTransmissionGeneration });\n\tif (kittyImageMetadata.size > 1000) {\n\t\tconst oldestImageId = kittyImageMetadata.keys().next().value;\n\t\tif (oldestImageId !== undefined) kittyImageMetadata.delete(oldestImageId);\n\t}\n}\n\nfunction getRegisteredKittyImageMetadata(line: string): RegisteredKittyImageMetadata | undefined {\n\tconst controls = /\\x1b_G([^;]*);/.exec(line)?.[1];\n\tif (!controls) return undefined;\n\tconst imageId = /(?:^|,)i=(\\d+)(?:,|$)/.exec(controls)?.[1];\n\treturn imageId === undefined ? undefined : kittyImageMetadata.get(Number.parseInt(imageId, 10));\n}\n\nexport function getKittyImageMetadata(line: string): KittyImageMetadata | undefined {\n\tconst metadata = getRegisteredKittyImageMetadata(line);\n\tif (!metadata) return undefined;\n\treturn {\n\t\timageId: metadata.imageId,\n\t\tcolumns: metadata.columns,\n\t\trows: metadata.rows,\n\t\twidthPx: metadata.widthPx,\n\t\theightPx: metadata.heightPx,\n\t};\n}\n\nconst KITTY_PLACEMENT_CONTROL_KEYS = new Set([\n\t\"i\",\n\t\"p\",\n\t\"x\",\n\t\"y\",\n\t\"w\",\n\t\"h\",\n\t\"X\",\n\t\"Y\",\n\t\"c\",\n\t\"r\",\n\t\"C\",\n\t\"U\",\n\t\"z\",\n\t\"P\",\n\t\"Q\",\n\t\"H\",\n\t\"V\",\n]);\n\n/** Build a placement-only command for an image line emitted by {@link renderImage}. */\nexport function getKittyImagePlacement(line: string): KittyImagePlacement | undefined {\n\tconst match = /\\x1b_G([^;]*);/.exec(line);\n\tconst metadata = getRegisteredKittyImageMetadata(line);\n\tif (!match || !metadata) return undefined;\n\n\tlet commandStart = match.index;\n\tlet commandControls = match[1];\n\tlet transmissionEnd: number;\n\twhile (true) {\n\t\tconst terminator = line.indexOf(\"\\x1b\\\\\", commandStart + KITTY_PREFIX.length);\n\t\tif (terminator === -1) return undefined;\n\t\ttransmissionEnd = terminator + 2;\n\t\tif (!/(?:^|,)m=1(?:,|$)/.test(commandControls)) break;\n\t\tcommandStart = transmissionEnd;\n\t\tif (!line.startsWith(KITTY_PREFIX, commandStart)) return undefined;\n\t\tconst controlsEnd = line.indexOf(\";\", commandStart + KITTY_PREFIX.length);\n\t\tif (controlsEnd === -1) return undefined;\n\t\tcommandControls = line.slice(commandStart + KITTY_PREFIX.length, controlsEnd);\n\t}\n\n\tconst controls = match[1]\n\t\t.split(\",\")\n\t\t.filter((control) => KITTY_PLACEMENT_CONTROL_KEYS.has(control.split(\"=\", 1)[0] ?? \"\"));\n\tconst sequence = `\\x1b_Ga=p,q=2,${controls.join(\",\")}\\x1b\\\\`;\n\treturn {\n\t\timageId: metadata.imageId,\n\t\ttransmissionGeneration: metadata.transmissionGeneration,\n\t\ttransmissionBytes: transmissionEnd - match.index,\n\t\testimatedDecodedBytes: metadata.widthPx * metadata.heightPx * 4,\n\t\tsequence,\n\t\treplacementLine: `${line.slice(0, match.index)}${sequence}${line.slice(transmissionEnd)}`,\n\t};\n}\n\nexport function cropKittyImageLine(line: string, hiddenRows: number, visibleRows: number): string {\n\tconst metadata = getKittyImageMetadata(line);\n\tconst match = /\\x1b_G([^;]*);/.exec(line);\n\tif (!metadata || !match || hiddenRows < 0 || hiddenRows >= metadata.rows || visibleRows <= 0) return line;\n\tconst croppedRows = Math.min(visibleRows, metadata.rows - hiddenRows);\n\tif (hiddenRows === 0 && croppedRows === metadata.rows) return line;\n\tconst sourceY = Math.floor((metadata.heightPx * hiddenRows) / metadata.rows);\n\tconst sourceEnd = Math.ceil((metadata.heightPx * (hiddenRows + croppedRows)) / metadata.rows);\n\tconst sourceHeight = Math.max(1, Math.min(metadata.heightPx, sourceEnd) - sourceY);\n\tconst controls = match[1].split(\",\").filter((control) => !/^[yhr]=/.test(control));\n\tcontrols.push(`y=${sourceY}`, `h=${sourceHeight}`, `r=${croppedRows}`);\n\treturn `${line.slice(0, match.index)}\\x1b_G${controls.join(\",\")};${line.slice(match.index + match[0].length)}`;\n}\n\nexport function calculateImageCellSize(\n\timageDimensions: ImageDimensions,\n\tmaxWidthCells: number,\n\tmaxHeightCells?: number,\n\tcellDimensions: CellDimensions = { widthPx: 9, heightPx: 18 },\n): ImageCellSize {\n\tconst maxWidth = Math.max(1, Math.floor(maxWidthCells));\n\tconst maxHeight = maxHeightCells === undefined ? undefined : Math.max(1, Math.floor(maxHeightCells));\n\tconst imageWidth = Math.max(1, imageDimensions.widthPx);\n\tconst imageHeight = Math.max(1, imageDimensions.heightPx);\n\n\tconst widthScale = (maxWidth * cellDimensions.widthPx) / imageWidth;\n\tconst heightScale = maxHeight === undefined ? widthScale : (maxHeight * cellDimensions.heightPx) / imageHeight;\n\tconst scale = Math.min(widthScale, heightScale);\n\n\tconst scaledWidthPx = imageWidth * scale;\n\tconst scaledHeightPx = imageHeight * scale;\n\tconst columns = Math.ceil(scaledWidthPx / cellDimensions.widthPx);\n\tconst rows = Math.ceil(scaledHeightPx / cellDimensions.heightPx);\n\n\treturn {\n\t\tcolumns: Math.max(1, Math.min(maxWidth, columns)),\n\t\trows: Math.max(1, maxHeight === undefined ? rows : Math.min(maxHeight, rows)),\n\t};\n}\n\nexport function calculateImageRows(\n\timageDimensions: ImageDimensions,\n\ttargetWidthCells: number,\n\tcellDimensions: CellDimensions = { widthPx: 9, heightPx: 18 },\n): number {\n\treturn calculateImageCellSize(imageDimensions, targetWidthCells, undefined, cellDimensions).rows;\n}\n\nexport function getPngDimensions(base64Data: string): ImageDimensions | null {\n\ttry {\n\t\tconst buffer = Buffer.from(base64Data, \"base64\");\n\n\t\tif (buffer.length < 24) {\n\t\t\treturn null;\n\t\t}\n\n\t\tif (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4e || buffer[3] !== 0x47) {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst width = buffer.readUInt32BE(16);\n\t\tconst height = buffer.readUInt32BE(20);\n\n\t\treturn { widthPx: width, heightPx: height };\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nexport function getJpegDimensions(base64Data: string): ImageDimensions | null {\n\ttry {\n\t\tconst buffer = Buffer.from(base64Data, \"base64\");\n\n\t\tif (buffer.length < 2) {\n\t\t\treturn null;\n\t\t}\n\n\t\tif (buffer[0] !== 0xff || buffer[1] !== 0xd8) {\n\t\t\treturn null;\n\t\t}\n\n\t\tlet offset = 2;\n\t\twhile (offset < buffer.length - 9) {\n\t\t\tif (buffer[offset] !== 0xff) {\n\t\t\t\toffset++;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tconst marker = buffer[offset + 1];\n\n\t\t\tif (marker >= 0xc0 && marker <= 0xc2) {\n\t\t\t\tconst height = buffer.readUInt16BE(offset + 5);\n\t\t\t\tconst width = buffer.readUInt16BE(offset + 7);\n\t\t\t\treturn { widthPx: width, heightPx: height };\n\t\t\t}\n\n\t\t\tif (offset + 3 >= buffer.length) {\n\t\t\t\treturn null;\n\t\t\t}\n\t\t\tconst length = buffer.readUInt16BE(offset + 2);\n\t\t\tif (length < 2) {\n\t\t\t\treturn null;\n\t\t\t}\n\t\t\toffset += 2 + length;\n\t\t}\n\n\t\treturn null;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nexport function getGifDimensions(base64Data: string): ImageDimensions | null {\n\ttry {\n\t\tconst buffer = Buffer.from(base64Data, \"base64\");\n\n\t\tif (buffer.length < 10) {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst sig = buffer.slice(0, 6).toString(\"ascii\");\n\t\tif (sig !== \"GIF87a\" && sig !== \"GIF89a\") {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst width = buffer.readUInt16LE(6);\n\t\tconst height = buffer.readUInt16LE(8);\n\n\t\treturn { widthPx: width, heightPx: height };\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nexport function getWebpDimensions(base64Data: string): ImageDimensions | null {\n\ttry {\n\t\tconst buffer = Buffer.from(base64Data, \"base64\");\n\n\t\tif (buffer.length < 30) {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst riff = buffer.slice(0, 4).toString(\"ascii\");\n\t\tconst webp = buffer.slice(8, 12).toString(\"ascii\");\n\t\tif (riff !== \"RIFF\" || webp !== \"WEBP\") {\n\t\t\treturn null;\n\t\t}\n\n\t\tconst chunk = buffer.slice(12, 16).toString(\"ascii\");\n\t\tif (chunk === \"VP8 \") {\n\t\t\tif (buffer.length < 30) return null;\n\t\t\tconst width = buffer.readUInt16LE(26) & 0x3fff;\n\t\t\tconst height = buffer.readUInt16LE(28) & 0x3fff;\n\t\t\treturn { widthPx: width, heightPx: height };\n\t\t} else if (chunk === \"VP8L\") {\n\t\t\tif (buffer.length < 25) return null;\n\t\t\tconst bits = buffer.readUInt32LE(21);\n\t\t\tconst width = (bits & 0x3fff) + 1;\n\t\t\tconst height = ((bits >> 14) & 0x3fff) + 1;\n\t\t\treturn { widthPx: width, heightPx: height };\n\t\t} else if (chunk === \"VP8X\") {\n\t\t\tif (buffer.length < 30) return null;\n\t\t\tconst width = (buffer[24] | (buffer[25] << 8) | (buffer[26] << 16)) + 1;\n\t\t\tconst height = (buffer[27] | (buffer[28] << 8) | (buffer[29] << 16)) + 1;\n\t\t\treturn { widthPx: width, heightPx: height };\n\t\t}\n\n\t\treturn null;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nexport function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null {\n\tif (mimeType === \"image/png\") {\n\t\treturn getPngDimensions(base64Data);\n\t}\n\tif (mimeType === \"image/jpeg\") {\n\t\treturn getJpegDimensions(base64Data);\n\t}\n\tif (mimeType === \"image/gif\") {\n\t\treturn getGifDimensions(base64Data);\n\t}\n\tif (mimeType === \"image/webp\") {\n\t\treturn getWebpDimensions(base64Data);\n\t}\n\treturn null;\n}\n\nexport function renderImage(\n\tbase64Data: string,\n\timageDimensions: ImageDimensions,\n\toptions: ImageRenderOptions = {},\n): ImageRenderResult | null {\n\tconst caps = getCapabilities();\n\n\tif (!caps.images) {\n\t\treturn null;\n\t}\n\n\tconst maxWidth = options.maxWidthCells ?? 80;\n\tconst size = calculateImageCellSize(imageDimensions, maxWidth, options.maxHeightCells, getCellDimensions());\n\n\tif (caps.images === \"kitty\") {\n\t\tif (options.imageId !== undefined) {\n\t\t\tregisterKittyImageMetadata({\n\t\t\t\timageId: options.imageId,\n\t\t\t\tcolumns: size.columns,\n\t\t\t\trows: size.rows,\n\t\t\t\twidthPx: imageDimensions.widthPx,\n\t\t\t\theightPx: imageDimensions.heightPx,\n\t\t\t});\n\t\t}\n\t\tconst sequence = encodeKitty(base64Data, {\n\t\t\tcolumns: size.columns,\n\t\t\trows: size.rows,\n\t\t\timageId: options.imageId,\n\t\t\tmoveCursor: options.moveCursor,\n\t\t});\n\t\treturn { sequence, columns: size.columns, rows: size.rows, imageId: options.imageId };\n\t}\n\n\tif (caps.images === \"iterm2\") {\n\t\tconst sequence = encodeITerm2(base64Data, {\n\t\t\twidth: size.columns,\n\t\t\theight: \"auto\",\n\t\t\tpreserveAspectRatio: options.preserveAspectRatio ?? true,\n\t\t});\n\t\treturn { sequence, columns: size.columns, rows: size.rows };\n\t}\n\n\treturn null;\n}\n\n/**\n * Wrap text in an OSC 8 hyperlink sequence.\n * The text is rendered as a clickable hyperlink in terminals that support OSC 8\n * (Ghostty, Kitty, WezTerm, iTerm2, VSCode, and others).\n * In terminals that do not support OSC 8, the escape sequences are ignored\n * and only the plain text is displayed.\n *\n * @param text - The visible text to display\n * @param url - The URL to link to\n */\nexport function hyperlink(text: string, url: string): string {\n\treturn `\\x1b]8;;${sanitizeTerminalControlPayload(url)}\\x1b\\\\${sanitizeHyperlinkText(text)}\\x1b]8;;\\x1b\\\\`;\n}\n\nexport function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string {\n\tconst parts: string[] = [];\n\tif (filename) parts.push(filename);\n\tparts.push(`[${mimeType}]`);\n\tif (dimensions) parts.push(`${dimensions.widthPx}x${dimensions.heightPx}`);\n\treturn `[Image: ${parts.join(\" \")}]`;\n}\n"]}