tmux-ide 2.9.4 → 2.9.5

package/packages/daemon/dist/tui/mirror/reference-performance-trace.js

@@ -154,13 +154,13 @@ export function createReferenceTraceWriter(stream, options = {}) {
             firstDroppedRecord ??= droppedRecordKind(value);
             return;
         }
-        const line = `${JSON.stringify(value)}\n`;
-        const bytes = Buffer.byteLength(line);
-        if (bytes > MAX_TRACE_RECORD_BYTES) {
-            oversizedRecords += 1;
-            return;
-        }
         try {
+            const line = `${JSON.stringify(value)}\n`;
+            const bytes = Buffer.byteLength(line);
+            if (bytes > MAX_TRACE_RECORD_BYTES) {
+                oversizedRecords += 1;
+                return;
+            }
             if (!saturated && pendingCount() === 0) {
                 writeLine(line);
                 return;
@@ -233,7 +233,15 @@ export function createReferenceTraceWriter(stream, options = {}) {
     return Object.freeze({ append, appendCritical, snapshot, close });
 }
 function droppedRecordKind(value) {
-    const field = (key) => typeof value[key] === "string" ? value[key].slice(0, 64) : null;
+    const field = (key) => {
+        try {
+            const result = value[key];
+            return typeof result === "string" ? result.slice(0, 64) : null;
+        }
+        catch {
+            return null;
+        }
+    };
     return Object.freeze({
         type: field("type"),
         stage: field("stage"),
@@ -258,7 +266,12 @@ export function createReferencePerformanceTraceSink(options) {
     const inputs = new Map();
     let droppedInputs = 0;
     let closed = false;
-    const snapshot = () => Object.freeze({ pendingInputs: inputs.size, droppedInputs });
+    const attempts = { begun: 0, completed: 0, superseded: 0, expired: 0, cancelled: 0 };
+    const snapshot = () => Object.freeze({
+        pendingInputs: inputs.size,
+        droppedInputs,
+        inputAttempts: Object.freeze({ ...attempts, pending: inputs.size }),
+    });
     return Object.freeze({
         detailedWindowPresentationFrames: detailed ? true : undefined,
         frame: (intervalMs, window) => {
@@ -464,67 +477,79 @@ export function createReferencePerformanceTraceSink(options) {
             }
             : {}),
         beginTerminalInput: (origin) => {
-            const startedAtMicros = nowMicros();
-            expireInputs(inputs, startedAtMicros);
-            // The transport carries one latest-only performance trace id. Once a
-            // newer input is admitted, an older probe can no longer be attributed to
-            // the exact changed-cell paint without lying. Retire it as superseded;
-            // `droppedInputs` is reserved for actual capacity loss.
-            inputs.clear();
-            while (inputs.size >= MAX_PENDING_INPUTS) {
-                inputs.delete(inputs.keys().next().value);
-                droppedInputs += 1;
+            if (closed)
+                return Object.freeze({ traceId: "", finish: () => { }, cancel: () => { } });
+            attempts.begun += 1;
+            let traceId;
+            try {
+                const startedAtMicros = nowMicros();
+                attempts.expired += expireInputs(inputs, startedAtMicros);
+                // The transport carries one latest-only performance trace id. Once a
+                // newer input is admitted, an older probe can no longer be attributed to
+                // the exact changed-cell paint without lying. Retire it as superseded;
+                // `droppedInputs` is reserved for actual capacity loss.
+                attempts.superseded += inputs.size;
+                inputs.clear();
+                while (inputs.size >= MAX_PENDING_INPUTS) {
+                    inputs.delete(inputs.keys().next().value);
+                    droppedInputs += 1;
+                    attempts.cancelled += 1;
+                }
+                traceId = createTraceId();
+                if ((detailed || options.inputOrigin) &&
+                    origin &&
+                    !closed &&
+                    typeof options.inputFingerprintKey === "string" &&
+                    options.inputFingerprintKey.length >= 32) {
+                    const payload = Buffer.from(origin.payload);
+                    const event = {
+                        processId,
+                        clockId: "opentui-performance-now",
+                        clockKind: "performance-now",
+                        atMicros: Number.isSafeInteger(origin.ingressAtMicros) &&
+                            origin.ingressAtMicros <= startedAtMicros
+                            ? origin.ingressAtMicros
+                            : startedAtMicros,
+                        origin: origin.origin,
+                        payloadByteCount: payload.byteLength,
+                        payloadFingerprint: createHmac("sha256", options.inputFingerprintKey)
+                            .update(traceId)
+                            .update("\0")
+                            .update(payload)
+                            .digest("hex"),
+                        parserConsumption: origin.origin === "keyboard"
+                            ? "keyboard-event"
+                            : origin.origin === "bracketed-paste"
+                                ? "paste-event"
+                                : "pointer-event",
+                        ...(origin.gestureId ? { gestureId: origin.gestureId } : {}),
+                        ...(origin.pointerAction ? { pointerAction: origin.pointerAction } : {}),
+                        ...(Number.isSafeInteger(origin.pointerColumn)
+                            ? { pointerColumn: origin.pointerColumn }
+                            : {}),
+                        ...(Number.isSafeInteger(origin.pointerRow) ? { pointerRow: origin.pointerRow } : {}),
+                        ...(origin.pointerButton === null || Number.isSafeInteger(origin.pointerButton)
+                            ? { pointerButton: origin.pointerButton }
+                            : {}),
+                        traceId,
+                        semanticPaneId: origin.semanticPaneId,
+                        generation: origin.generation,
+                        incarnation: origin.incarnation,
+                        revision: origin.revision,
+                        stateHash: origin.stateHash,
+                    };
+                    options.append({ version: 1, type: "performance.input-origin", ...event });
+                }
+                inputs.set(traceId, {
+                    startedAtMicros,
+                    expiresAtMicros: startedAtMicros + INPUT_EXPIRY_MICROS,
+                    endedAtMicros: null,
+                });
             }
-            const traceId = createTraceId();
-            if ((detailed || options.inputOrigin) &&
-                origin &&
-                !closed &&
-                typeof options.inputFingerprintKey === "string" &&
-                options.inputFingerprintKey.length >= 32) {
-                const payload = Buffer.from(origin.payload);
-                const event = {
-                    processId,
-                    clockId: "opentui-performance-now",
-                    clockKind: "performance-now",
-                    atMicros: Number.isSafeInteger(origin.ingressAtMicros) &&
-                        origin.ingressAtMicros <= startedAtMicros
-                        ? origin.ingressAtMicros
-                        : startedAtMicros,
-                    origin: origin.origin,
-                    payloadByteCount: payload.byteLength,
-                    payloadFingerprint: createHmac("sha256", options.inputFingerprintKey)
-                        .update(traceId)
-                        .update("\0")
-                        .update(payload)
-                        .digest("hex"),
-                    parserConsumption: origin.origin === "keyboard"
-                        ? "keyboard-event"
-                        : origin.origin === "bracketed-paste"
-                            ? "paste-event"
-                            : "pointer-event",
-                    ...(origin.gestureId ? { gestureId: origin.gestureId } : {}),
-                    ...(origin.pointerAction ? { pointerAction: origin.pointerAction } : {}),
-                    ...(Number.isSafeInteger(origin.pointerColumn)
-                        ? { pointerColumn: origin.pointerColumn }
-                        : {}),
-                    ...(Number.isSafeInteger(origin.pointerRow) ? { pointerRow: origin.pointerRow } : {}),
-                    ...(origin.pointerButton === null || Number.isSafeInteger(origin.pointerButton)
-                        ? { pointerButton: origin.pointerButton }
-                        : {}),
-                    traceId,
-                    semanticPaneId: origin.semanticPaneId,
-                    generation: origin.generation,
-                    incarnation: origin.incarnation,
-                    revision: origin.revision,
-                    stateHash: origin.stateHash,
-                };
-                options.append({ version: 1, type: "performance.input-origin", ...event });
+            catch (error) {
+                attempts.cancelled += 1;
+                throw error;
             }
-            inputs.set(traceId, {
-                startedAtMicros,
-                expiresAtMicros: startedAtMicros + INPUT_EXPIRY_MICROS,
-                endedAtMicros: null,
-            });
             let finished = false;
             return Object.freeze({
                 traceId,
@@ -536,10 +561,19 @@ export function createReferencePerformanceTraceSink(options) {
                     if (input)
                         input.endedAtMicros = nowMicros();
                 },
-                cancel: () => inputs.delete(traceId),
+                cancel: () => {
+                    if (inputs.delete(traceId))
+                        attempts.cancelled += 1;
+                },
             });
         },
-        terminalTraceSpan: (paint) => recordCompletedTrace(inputs, paint, options.append),
+        terminalTraceSpan: (paint) => {
+            if (closed || paint.processId !== processId)
+                return;
+            const outcome = recordCompletedTrace(inputs, paint, options.append);
+            if (outcome)
+                attempts[outcome] += 1;
+        },
         terminalTraceStage: (event) => {
             if ((detailed || options.inputDetail) && !closed)
                 options.append({ version: 1, type: "performance.stage", ...event });
@@ -560,6 +594,7 @@ export function createReferencePerformanceTraceSink(options) {
             // Shutdown cancels probes that can no longer observe a future paint.
             // They are not backpressure loss and must not survive as phantom work in
             // a closed collector summary.
+            attempts.cancelled += inputs.size;
             inputs.clear();
             return snapshot();
         },
@@ -568,10 +603,17 @@ export function createReferencePerformanceTraceSink(options) {
 function recordCompletedTrace(inputs, paint, appendRecord) {
     const input = inputs.get(paint.traceId);
     if (!input || input.endedAtMicros === null)
-        return;
+        return null;
+    if (paint.clockId !== "opentui-performance-now" ||
+        paint.clockKind !== "performance-now" ||
+        !Number.isFinite(paint.startedAtMicros) ||
+        !Number.isFinite(paint.endedAtMicros) ||
+        paint.startedAtMicros < input.endedAtMicros ||
+        paint.endedAtMicros < paint.startedAtMicros)
+        return null;
     if (paint.startedAtMicros > input.expiresAtMicros) {
         inputs.delete(paint.traceId);
-        return;
+        return "expired";
     }
     inputs.delete(paint.traceId);
     appendRecord({
@@ -588,11 +630,15 @@ function recordCompletedTrace(inputs, paint, appendRecord) {
         authority: { generation: paint.generation, incarnation: paint.incarnation },
     });
     appendRecord({ version: 1, type: "performance.stage", ...paint });
+    return "completed";
 }
 function expireInputs(inputs, nowMicros) {
+    let expired = 0;
     for (const [traceId, input] of inputs) {
         if (input.expiresAtMicros > nowMicros)
             break;
         inputs.delete(traceId);
+        expired += 1;
     }
+    return expired;
 }

package/packages/daemon/dist/tui/mirror/runtime/application-terminal-input-ingress.js

@@ -48,6 +48,19 @@ export function createApplicationTerminalInputIngress(interaction, generation, s
         left.clientGeneration === right.clientGeneration &&
         left.session === right.session &&
         left.pane === right.pane;
+    // Rejection is an outcome for this exact terminal scope, not queue occupancy.
+    // Successful delivery of the admitted prefix must not hide lost input.
+    let rejectedRecoveryScope = null;
+    const rejectedRecoveryNote = "some terminal input was not sent during recovery";
+    const rejectedRecoveryAdmissionNote = `terminal input queue full · ${rejectedRecoveryNote}`;
+    const clearRejectedRecovery = () => {
+        if (!rejectedRecoveryScope)
+            return;
+        rejectedRecoveryScope = null;
+        setNote((current) => current === rejectedRecoveryNote || current === rejectedRecoveryAdmissionNote
+            ? null
+            : current);
+    };
     let recoveryVersion = 0;
     const cancelRecovery = () => {
         recoveryVersion++;
@@ -62,6 +75,8 @@ export function createApplicationTerminalInputIngress(interaction, generation, s
         const target = scope();
         if (!target)
             return false;
+        if (rejectedRecoveryScope && !sameScope(rejectedRecoveryScope, target))
+            clearRejectedRecovery();
         if (recovery && !sameScope(recovery.scope, target))
             cancelRecovery();
         if (!recovery) {
@@ -74,7 +89,8 @@ export function createApplicationTerminalInputIngress(interaction, generation, s
         }
         const weight = bytes.byteLength;
         if (recovery.admitted >= 64 || recovery.weight + weight > 1024 * 1024) {
-            setNote("terminal input queue full · wait for the session to connect");
+            rejectedRecoveryScope = target;
+            setNote(rejectedRecoveryAdmissionNote);
             return true;
         }
         recovery.weight += weight;
@@ -96,7 +112,8 @@ export function createApplicationTerminalInputIngress(interaction, generation, s
             }
             return true;
         });
-        setNote(`${target.session} · terminal ${kind} queued`);
+        if (!rejectedRecoveryScope)
+            setNote(`${target.session} · terminal ${kind} queued`);
         return true;
     };
     const flushRecovery = () => {
@@ -130,7 +147,11 @@ export function createApplicationTerminalInputIngress(interaction, generation, s
             }
             if (version === recoveryVersion) {
                 cancelRecovery();
-                setNote(null);
+                if (rejectedRecoveryScope) {
+                    setNote((current) => current === rejectedRecoveryAdmissionNote ? rejectedRecoveryNote : current);
+                }
+                else
+                    setNote(null);
             }
         })();
     };
@@ -165,6 +186,7 @@ export function createApplicationTerminalInputIngress(interaction, generation, s
     };
     const cancelInteractionInput = () => {
         cancelRecovery();
+        clearRejectedRecovery();
         interaction.cancelPendingInput();
     };
     return {
@@ -191,6 +213,8 @@ export function createApplicationTerminalInputIngress(interaction, generation, s
             });
         },
         adopt(terminalsActive = true) {
+            if (rejectedRecoveryScope && !sameScope(rejectedRecoveryScope, scope()))
+                clearRejectedRecovery();
             if (!terminalsActive)
                 cancelInteractionInput();
             flush();

package/packages/daemon/dist/tui/mirror/runtime/pane-scoped-terminal-surface.jsx

@@ -1,14 +1,19 @@
 /* @jsxImportSource @opentui/solid */
-import { createRenderEffect, onCleanup, untrack } from "solid-js";
+import { createRenderEffect, createSignal, Show, onCleanup, untrack, } from "solid-js";
 /** One Solid owner per terminal pane; terminal output never wakes the root shell. */
 export function PaneScopedTerminalSurface(props) {
     let surface;
+    const [unavailable, setUnavailable] = createSignal(null);
     let activationEpoch = 0;
     let wasActive = false;
     let hadCanonicalSnapshot = false;
     const isActive = () => typeof props.active === "function" ? props.active() : props.active !== false;
     const currentPresentationGeneration = () => `${props.presentationGeneration ?? "stable"}:activation-${activationEpoch}`;
     const ensureRetainedCanonicalState = (adapter, paneId) => {
+        const message = adapter.paneUnavailable?.(paneId) ?? null;
+        setUnavailable(message);
+        if (message)
+            return;
         const identity = adapter.renderSource.paneCanonicalIdentity?.(paneId) ?? null;
         if (identity) {
             hadCanonicalSnapshot = true;
@@ -56,12 +61,20 @@ export function PaneScopedTerminalSurface(props) {
         surface.sourceEpoch = props.sourceEpoch + props.adapter.paneSourceEpoch();
         ensureRetainedCanonicalState(props.adapter, props.paneId);
     });
-    return (<pane_surface ref={(renderable) => {
+    return (<box width={props.width} height={props.height}>
+      <pane_surface ref={(renderable) => {
             surface = renderable;
             renderable.contentVersion = props.adapter.paneVersion(props.paneId);
-            renderable.presentationVersion = props.adapter.panePresentationVersion?.(props.paneId) ?? 0;
+            renderable.presentationVersion =
+                props.adapter.panePresentationVersion?.(props.paneId) ?? 0;
             renderable.sourceEpoch = props.sourceEpoch + props.adapter.paneSourceEpoch();
             renderable.presentationGeneration = currentPresentationGeneration();
             ensureRetainedCanonicalState(props.adapter, props.paneId);
-        }} width={props.width} height={props.height} mirror={props.adapter.renderSource} paneId={props.paneId} defaultFg={props.defaultFg} defaultBg={props.defaultBg} terminalPalette={props.terminalPalette} searchHl={props.searchHl} searchCur={props.searchCur} scrollOffset={props.scrollOffset} viewportOrigin={props.viewportOrigin} paneFocused={props.paneFocused} contentVersion={props.adapter.paneVersion(props.paneId)} presentationVersion={props.adapter.panePresentationVersion?.(props.paneId) ?? 0} sourceEpoch={props.sourceEpoch + props.adapter.paneSourceEpoch()} rendererEpoch={props.sourceEpoch} hostFocusTransitionOwner={props.hostFocusTransitionOwner} selRange={props.selRange} copyCursor={props.copyCursor} search={props.search}/>);
+        }} width={props.width} height={props.height} mirror={props.adapter.renderSource} paneId={props.paneId} defaultFg={props.defaultFg} defaultBg={props.defaultBg} terminalPalette={props.terminalPalette} searchHl={props.searchHl} searchCur={props.searchCur} scrollOffset={props.scrollOffset} viewportOrigin={props.viewportOrigin} paneFocused={props.paneFocused} contentVersion={props.adapter.paneVersion(props.paneId)} presentationVersion={props.adapter.panePresentationVersion?.(props.paneId) ?? 0} sourceEpoch={props.sourceEpoch + props.adapter.paneSourceEpoch()} rendererEpoch={props.sourceEpoch} hostFocusTransitionOwner={props.hostFocusTransitionOwner} selRange={props.selRange} copyCursor={props.copyCursor} search={props.search}/>
+      <Show when={unavailable()}>
+        {(message) => (<box position="absolute" left={0} top={0} width={props.width} height={props.height} backgroundColor={`#${props.defaultBg.toString(16).padStart(6, "0")}`} padding={1}>
+            <text fg={`#${props.defaultFg.toString(16).padStart(6, "0")}`}>{message()}</text>
+          </box>)}
+      </Show>
+    </box>);
 }

package/packages/daemon/dist/tui/mirror/runtime/terminal-fast-lane-renderer-adapter.js

@@ -63,6 +63,9 @@ export class TerminalFastLaneRendererAdapter {
         this.#causalCellLedger = causalCellLedger;
         this.#resourceSampler = resourceSampler;
     }
+    paneUnavailable(paneId) {
+        return this.#lane.paneUnavailable(paneId);
+    }
     paneVersion(paneId) {
         return this.#panes.get(paneId)?.version ?? 0;
     }
@@ -295,6 +298,22 @@ export class TerminalFastLaneRendererAdapter {
         if (!interest.release) {
             interest.release = this.#lane.subscribePane(paneId, (publication) => {
                 this.#publish(interest, publication);
+            }, () => {
+                interest.retainedView?.capture?.abort();
+                interest.retainedView = undefined;
+                interest.state = null;
+                interest.pendingTrace = null;
+                interest.pendingHostFrame = null;
+                interest.rowProjectionCache?.clear();
+                interest.version++;
+                for (const listener of [...interest.listeners]) {
+                    try {
+                        listener(interest.version, this.#sourceEpoch, interest.presentationVersion, "content");
+                    }
+                    catch {
+                        /* Availability observers cannot interrupt sibling delivery. */
+                    }
+                }
             });
         }
         // The lane owns a generation-scoped canonical replica even while a pane is

package/packages/daemon/dist/tui/mirror/runtime/terminal-input-adapter.js

@@ -40,11 +40,19 @@ export function terminalInputsForPaste(text) {
         throw new TypeError("terminal paste must not contain NUL");
     const framed = `\u001b[200~${text}\u001b[201~`;
     const inputs = [];
-    for (let offset = 0; offset < framed.length; offset += SESSION_RUNTIME_MAX_TERMINAL_INPUT_TEXT_CHARS) {
+    for (let offset = 0; offset < framed.length;) {
+        let end = Math.min(offset + SESSION_RUNTIME_MAX_TERMINAL_INPUT_TEXT_CHARS, framed.length);
+        // Messages can be encoded independently. Keep a supplementary code point
+        // intact instead of relying on the receiver to rejoin its UTF-16 halves.
+        const last = framed.charCodeAt(end - 1);
+        const next = framed.charCodeAt(end);
+        if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff)
+            end -= 1;
         inputs.push(SessionRuntimeTerminalInputSchemaZ.parse({
             kind: "text",
-            data: framed.slice(offset, offset + SESSION_RUNTIME_MAX_TERMINAL_INPUT_TEXT_CHARS),
+            data: framed.slice(offset, end),
         }));
+        offset = end;
     }
     return Object.freeze(inputs);
 }

package/packages/daemon/dist/tui/mirror/testing/styled-frame-oracle.js

@@ -0,0 +1,156 @@
+function check(condition, message) {
+    if (!condition)
+        throw Error(message);
+}
+const blank = () => ({ text: "", width: 1, fg: "ffffff", bg: "000000", bold: false });
+export function literalStyledFrame(marker, cols = 40) {
+    check(cols === 24 || cols === 40, "literal geometry");
+    check(marker.length <= cols, "marker width");
+    const cells = Array.from({ length: 8 }, () => Array.from({ length: cols }, blank));
+    [...marker].forEach((text, x) => (cells[0][x] = { ...blank(), text }));
+    const initial = marker === "BEFORE_SSH";
+    const glyphs = initial ? ["X", "界", "", "é", "Z"] : ["Y", "q", "", "é", "R"];
+    glyphs.forEach((text, x) => (cells[1][x] = {
+        text,
+        width: initial ? (x === 1 ? 2 : x === 2 ? 0 : 1) : 1,
+        fg: text ? "123456" : "ffffff",
+        bg: "214365",
+        bold: !!text,
+    }));
+    for (let x = 0; x < cols; x++)
+        cells[3][x] = { ...blank(), text: x < 2 ? String(x + 1) : "", bg: "445566" };
+    return { cells, cursor: { x: 4, y: 2, visible: true } };
+}
+export function styledBytes(marker) {
+    return `\x1b[0m\x1b[2J\x1b[H${marker}\x1b[2;1H\x1b[1;38;2;18;52;86;48;2;33;67;101m${marker === "BEFORE_SSH" ? "X界éZ" : "Yq éR"}\x1b[0m\x1b[4;1H\x1b[48;2;68;85;102m123456\x1b[4;3H\x1b[K\x1b[0m\x1b[3;5H\x1b]2;${marker}\x07`;
+}
+export function readCompletedFrame(raw) {
+    check((raw.cols === 24 || raw.cols === 40) && raw.rows === 8, "geometry");
+    const size = raw.cols * raw.rows;
+    check(raw.char.length === size &&
+        raw.attributes.length === size &&
+        raw.fg.length === size * 4 &&
+        raw.bg.length === size * 4, "buffer lengths");
+    const lines = raw.text.replace(/\n$/u, "").split("\n");
+    check(lines.length === 8, "line count");
+    const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+    const rgb = (a, i) => {
+        const c = a.slice(i * 4, i * 4 + 4);
+        check(c.length === 4 && c.every((v) => Number.isInteger(v) && v >= 0 && v <= 255) && c[3] === 255, "RGBA");
+        return c
+            .slice(0, 3)
+            .map((v) => v.toString(16).padStart(2, "0"))
+            .join("");
+    };
+    const continuation = (n) => n === 0 || n >>> 30 === 3;
+    const cells = lines.map((line, y) => {
+        const text = [...segmenter.segment(line)].map((s) => s.segment);
+        let pos = 0;
+        const row = Array.from({ length: raw.cols }, (_, x) => {
+            const i = y * raw.cols + x, cp = raw.char[i];
+            const cont = continuation(cp) && x > 0 && !continuation(raw.char[i - 1]) && raw.char[i - 1] !== 32;
+            let glyph = "";
+            if (cont) {
+                if (cp === 0) {
+                    check(text[pos] === " ", "direct continuation text");
+                    pos++;
+                }
+            }
+            else {
+                glyph = text[pos++] ?? "";
+                check(/^(?:[\x20-\x7e]|界|é)$/u.test(glyph), "unsupported grapheme");
+            }
+            const width = cont ? 0 : x < raw.cols - 1 && continuation(raw.char[i + 1]) ? 2 : 1;
+            const kind = cp >>> 30;
+            if (cont) {
+                const prev = raw.char[i - 1];
+                check(prev === 0x754c || (prev >>> 30 === 2 && ((prev >>> 28) & 3) === 1), "continuation owner");
+                if (kind === 3)
+                    check(((cp >>> 26) & 3) === 1 &&
+                        ((cp >>> 28) & 3) === 0 &&
+                        (cp & 0x03ffffff) === (prev & 0x03ffffff), "interned continuation");
+            }
+            else if (kind === 0) {
+                check(cp !== 0 && glyph.codePointAt(0) === cp && [...glyph].length === 1, "direct codepoint mismatch");
+                check(width === (glyph === "界" ? 2 : 1), "direct width");
+            }
+            else if (kind === 2) {
+                check(glyph === "é" && ((cp >>> 26) & 3) === 0 && ((cp >>> 28) & 3) === 0 && width === 1, "interned grapheme shape");
+            }
+            else
+                check(false, "unsupported raw char flags");
+            const visible = glyph !== " " && glyph !== "";
+            check((raw.attributes[i] & ~1) === 0, "unsupported attributes");
+            return {
+                text: visible ? glyph : "",
+                width,
+                fg: visible ? rgb(raw.fg, i) : "ffffff",
+                bg: rgb(raw.bg, i),
+                bold: visible && (raw.attributes[i] & 1) !== 0,
+            };
+        });
+        check(pos === text.length, "unconsumed text");
+        return row;
+    });
+    return {
+        cells,
+        cursor: { x: raw.cursor.x - 1, y: raw.cursor.y - 1, visible: raw.cursor.visible },
+    };
+}
+export function compareVisual(actual, expected) {
+    check(JSON.stringify(actual.cursor) === JSON.stringify(expected.cursor), "cursor mismatch");
+    check(actual.cells.length === expected.cells.length, "rows mismatch");
+    actual.cells.forEach((row, y) => {
+        check(row.length === expected.cells[y].length, "cols mismatch");
+        row.forEach((cell, x) => {
+            for (const key of ["text", "width", "fg", "bg", "bold"])
+                check(cell[key] === expected.cells[y][x][key], `${y}:${x}.${key} mismatch`);
+        });
+    });
+}
+export function nativeVisualFrame(frame) {
+    check((frame.cols === 24 || frame.cols === 40) && frame.rows === 8, "native geometry");
+    const color = (value, defaultValue) => {
+        if (value === "default")
+            return defaultValue;
+        check(/^rgb:[0-9a-f]{6}$/u.test(value), "native color vocabulary");
+        return value.slice(4);
+    };
+    return {
+        cells: frame.cells.map((row) => row.map((c) => {
+            const visible = c.text !== "" && c.text !== " ";
+            check(c.attributes.every((a) => a === "bold"), "native attribute vocabulary");
+            return {
+                text: visible ? c.text : "",
+                width: c.width,
+                fg: visible ? color(c.foreground, "ffffff") : "ffffff",
+                bg: color(c.background, "000000"),
+                bold: visible && c.attributes.includes("bold"),
+            };
+        })),
+        cursor: { x: frame.cursor[0], y: frame.cursor[1], visible: true },
+    };
+}
+/** Declared workspace chrome: one tab row plus one title row, then eight native rows. */
+export function cropWorkspaceCompletedFrame(raw) {
+    check((raw.cols === 24 || raw.cols === 40) && raw.rows === 10, "workspace geometry");
+    const size = raw.cols * raw.rows;
+    check(raw.char.length === size &&
+        raw.attributes.length === size &&
+        raw.fg.length === size * 4 &&
+        raw.bg.length === size * 4, "workspace buffer lengths");
+    const lines = raw.text.replace(/\n$/u, "").split("\n");
+    check(lines.length === 10, "workspace line count");
+    check(raw.cursor.y >= 3 && raw.cursor.y <= 10, "workspace cursor outside content");
+    const offset = 2 * raw.cols;
+    return {
+        cols: raw.cols,
+        rows: 8,
+        char: raw.char.slice(offset),
+        attributes: raw.attributes.slice(offset),
+        fg: raw.fg.slice(offset * 4),
+        bg: raw.bg.slice(offset * 4),
+        text: lines.slice(2).join("\n"),
+        cursor: { ...raw.cursor, y: raw.cursor.y - 2 },
+    };
+}