muonroi-cli 1.8.4 → 1.8.5

package/dist/packages/agent-harness-core/src/visual-quality.js

@@ -0,0 +1,141 @@
+/**
+ * visual-quality.ts — programmatic visual-quality heuristics over a VisualFrame.
+ *
+ * P1 of Harness TUI v2. Given the ground-truth rendered cell grid, compute cheap
+ * ground-truth signals a human would call "messy" — WITHOUT a vision model:
+ *   - blank / near-blank row ratios (the council "↳" + "· Skip" garbage)
+ *   - long runs of consecutive blank rows (dead space)
+ *   - whitespace density
+ *   - mojibake (U+FFFD replacement chars + misdecoded-UTF8 clusters like `💡`)
+ *
+ * These are the exact defects the semantic tree (LiveFrame) is blind to — the
+ * 2217600e1f27 export had 12 near-empty rows + mojibake that no existing
+ * self-verify check could see. A composite `score` + `issues[]` lets self-QA
+ * fail a render regression automatically.
+ *
+ * Thresholds are conservative defaults; tune per surface. This is a heuristic,
+ * not a proof — a low score flags "look closer", it does not assert a bug.
+ */
+export const DEFAULT_VISUAL_QUALITY_THRESHOLDS = {
+    nearEmptyMaxChars: 2,
+    nearEmptyRowPct: 0.5,
+    maxConsecutiveBlankRows: 4,
+    mojibakeCount: 1,
+    whitespacePct: 0.92,
+};
+// Characters that legitimately never (or almost never) appear in this TUI but
+// are produced when UTF-8 bytes are re-decoded as CP437/latin1. Presence in a
+// 2+ cluster is a strong mojibake signal (e.g. 💡 → "≡ƒÆí", em-dash → "ΓÇô").
+const MOJIBAKE_SIGNAL = new Set([
+    ..."≡ƒÆÇÃÂ’ÿÖÜúÑŒ¬".split(""),
+    "�", // replacement char
+]);
+function rowText(line) {
+    return line.spans.map((s) => s.text).join("");
+}
+function countMojibake(text) {
+    let count = 0;
+    let sample;
+    // Definitive: U+FFFD replacement chars.
+    for (const ch of text) {
+        if (ch === "�")
+            count++;
+    }
+    // Clusters of 2+ consecutive signal chars — mojibake arrives in runs, which
+    // keeps ordinary accented text (single é, ü) from tripping the heuristic.
+    const chars = [...text];
+    let run = 0;
+    for (let i = 0; i <= chars.length; i++) {
+        const isSignal = i < chars.length && MOJIBAKE_SIGNAL.has(chars[i]) && chars[i] !== "�";
+        if (isSignal) {
+            run++;
+        }
+        else {
+            if (run >= 2) {
+                count += run;
+                if (!sample)
+                    sample = chars.slice(Math.max(0, i - run - 4), i + 2).join("");
+            }
+            run = 0;
+        }
+    }
+    return { count, sample };
+}
+/**
+ * Compute visual-quality signals for a rendered frame. Pure + deterministic.
+ */
+export function computeVisualQuality(frame, thresholds = DEFAULT_VISUAL_QUALITY_THRESHOLDS) {
+    const rows = frame.lines.length;
+    const cols = frame.cols;
+    let contentChars = 0;
+    let totalCells = 0;
+    let blankRows = 0;
+    let nearEmptyRows = 0;
+    let maxConsecutiveBlankRows = 0;
+    let curBlankRun = 0;
+    let mojibakeCount = 0;
+    const mojibakeSamples = [];
+    for (const line of frame.lines) {
+        const text = rowText(line);
+        const nonSpace = [...text].filter((c) => c.trim().length > 0).length;
+        contentChars += nonSpace;
+        totalCells += Math.max(text.length, cols);
+        if (nonSpace === 0) {
+            blankRows++;
+            curBlankRun++;
+            maxConsecutiveBlankRows = Math.max(maxConsecutiveBlankRows, curBlankRun);
+        }
+        else {
+            curBlankRun = 0;
+        }
+        // "Low-content" rows = blank OR only a glyph or two (skeleton noise like the
+        // council "↳" / "· Skip" rows, and the blank separators between them). Both
+        // are visual garbage, so they count together against the total row budget.
+        if (nonSpace <= thresholds.nearEmptyMaxChars)
+            nearEmptyRows++;
+        const mj = countMojibake(text);
+        if (mj.count > 0) {
+            mojibakeCount += mj.count;
+            if (mj.sample && mojibakeSamples.length < 5)
+                mojibakeSamples.push(mj.sample);
+        }
+    }
+    // Ratio of low-content (blank or near-empty) rows over the whole frame.
+    const nearEmptyRowPct = rows > 0 ? nearEmptyRows / rows : 0;
+    const whitespacePct = totalCells > 0 ? 1 - contentChars / totalCells : 1;
+    const issues = [];
+    if (nearEmptyRowPct > thresholds.nearEmptyRowPct) {
+        issues.push(`${nearEmptyRows}/${rows} rows are blank or near-empty (<=${thresholds.nearEmptyMaxChars} chars) — skeleton/garbage rows`);
+    }
+    if (maxConsecutiveBlankRows > thresholds.maxConsecutiveBlankRows) {
+        issues.push(`${maxConsecutiveBlankRows} consecutive blank rows — large dead gap`);
+    }
+    if (mojibakeCount >= thresholds.mojibakeCount) {
+        issues.push(`${mojibakeCount} mojibake signal(s) detected (misdecoded UTF-8 / U+FFFD)${mojibakeSamples.length ? ` e.g. ${JSON.stringify(mojibakeSamples[0])}` : ""}`);
+    }
+    if (whitespacePct > thresholds.whitespacePct && contentChars > 0) {
+        issues.push(`${(whitespacePct * 100).toFixed(0)}% of the grid is whitespace — very sparse render`);
+    }
+    // Composite score: start at 100, subtract weighted penalties.
+    let score = 100;
+    score -= Math.min(40, Math.round(nearEmptyRowPct * 60));
+    score -= Math.min(25, Math.max(0, maxConsecutiveBlankRows - thresholds.maxConsecutiveBlankRows) * 4);
+    score -= Math.min(30, mojibakeCount * 6);
+    score -= whitespacePct > thresholds.whitespacePct ? 10 : 0;
+    score = Math.max(0, Math.min(100, score));
+    return {
+        rows,
+        cols,
+        contentChars,
+        blankRows,
+        nearEmptyRows,
+        nearEmptyRowPct,
+        maxConsecutiveBlankRows,
+        whitespacePct,
+        mojibakeCount,
+        mojibakeSamples,
+        score,
+        issues,
+    };
+}
+//# sourceMappingURL=visual-quality.js.map

package/dist/packages/agent-harness-opentui/src/agent-mode.d.ts

@@ -17,6 +17,7 @@
  */
 import type { LiveEvent } from "@muonroi/agent-harness-core/protocol";
 import type { SemanticRegistry } from "./reconciler-hook.js";
+import { type RendererLike } from "./visual-capture.js";
 export type AgentModeOptions = {
     cols: number;
     rows: number;
@@ -40,6 +41,11 @@ export type AgentModeRuntime = {
     onCommand: (h: (cmd: unknown) => void) => void;
     /** Get the current timestamp (real or fake clock). */
     now: () => number;
+    /**
+     * Attach the OpenTUI renderer once it exists (constructed AFTER this runtime
+     * — see src/index.ts). Enables VisualFrame capture of the real cell grid.
+     */
+    attachRenderer: (renderer: RendererLike) => void;
     /** Tear down: close streams, dispose idle detector. */
     dispose: () => void;
 };

package/dist/packages/agent-harness-opentui/src/agent-mode.js

@@ -22,6 +22,7 @@ import { createIdleDetector } from "@muonroi/agent-harness-core/idle";
 import { createLineSplitter, createSidechannelWriter } from "@muonroi/agent-harness-core/transports/sidechannel";
 import { installOpenTUIHarness } from "./install.js";
 import { createSemanticRegistry } from "./reconciler-hook.js";
+import { createVisualCaptureHook } from "./visual-capture.js";
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -90,6 +91,11 @@ export async function startAgentMode(opts) {
     const now = () => (opts.fakeClock ? 0 : Date.now());
     // --- Semantic registry ---------------------------------------------------
     const registry = createSemanticRegistry();
+    // --- Visual capture (real rendered cell grid) ----------------------------
+    // The renderer does not exist yet — it is constructed after this runtime and
+    // handed back via attachRenderer(). The hook reads it late-bound.
+    let rendererRef;
+    const visualHook = createVisualCaptureHook(() => rendererRef);
     // --- Idle detector -------------------------------------------------------
     const idle = createIdleDetector({
         quiescenceMs: opts.idleMs,
@@ -116,6 +122,9 @@ export async function startAgentMode(opts) {
         // becomes deterministic (seq*16). Without this, ts = Date.now() and the
         // determinism spec sees timestamps differ between runs.
         fakeClock: opts.fakeClock,
+        // Emit a VisualFrame (real rendered cell grid) alongside each semantic
+        // change. No-op until attachRenderer() supplies the renderer.
+        captureVisual: (seq, ts) => visualHook.capture(seq, ts),
     });
     // --- Command channel (in stream → handlers) ------------------------------
     const commandHandlers = [];
@@ -165,6 +174,10 @@ export async function startAgentMode(opts) {
     const onCommand = (h) => {
         commandHandlers.push(h);
     };
+    const attachRenderer = (renderer) => {
+        rendererRef = renderer;
+        visualHook.resetDedup(); // force the first visual frame after attach
+    };
     const dispose = () => {
         harnessHandle.uninstall(); // stops poll interval; transport.close() ends outStream
         idle.dispose();
@@ -173,6 +186,6 @@ export async function startAgentMode(opts) {
             inStream.destroy();
         }
     };
-    return { registry, capture, emitEvent, onCommand, now, dispose };
+    return { registry, capture, emitEvent, onCommand, now, attachRenderer, dispose };
 }
 //# sourceMappingURL=agent-mode.js.map

package/dist/packages/agent-harness-opentui/src/input-bridge.d.ts

@@ -13,15 +13,7 @@
  * raw byte. We construct ParsedKey directly so we don't depend on terminal
  * escape sequence conventions.
  */
+import type { KeyEvent } from "@opentui/core";
 import type { AgentModeRuntime } from "./agent-mode.js";
-/**
- * Subscribe to agentRuntime.onCommand and inject synthetic key events into
- * OpenTUI's keyHandler. Safe no-op when agentRuntime is undefined (normal user
- * mode).
- *
- * Special key `__focus__:<id>` is intentionally NOT translated to OpenTUI input
- * here — it is a driver-level signal currently ignored at this layer. (Focus
- * routing in OpenTUI is owned by individual components; a global focus dispatch
- * is out of scope for this bridge.)
- */
+export declare function keyForNamed(key: string): KeyEvent | null;
 export declare function useAgentInputBridge(agentRuntime: AgentModeRuntime | undefined): void;

package/dist/packages/agent-harness-opentui/src/input-bridge.js

@@ -35,7 +35,54 @@ const NAMED = {
     PageUp: { name: "pageup", sequence: "\x1b[5~", raw: "\x1b[5~" },
     PageDown: { name: "pagedown", sequence: "\x1b[6~", raw: "\x1b[6~" },
 };
-function makeKey(partial) {
+// Case-insensitive view of NAMED. The map above is capitalized, but drivers
+// naturally send lowercase ("enter", "escape", "tab", "space") — those missed
+// the exact-case lookup, so keyForNamed returned null and the keystroke was a
+// SILENT no-op (Enter never submitted, Escape never dismissed a modal). Resolve
+// on the lowercased base so every casing works. Includes a couple of common
+// short aliases drivers reach for.
+const NAMED_LC = {
+    ...Object.fromEntries(Object.entries(NAMED).map(([k, v]) => [k.toLowerCase(), v])),
+    ret: NAMED.Return,
+    del: NAMED.Delete,
+    spacebar: NAMED.Space,
+    pgup: NAMED.PageUp,
+    pgdn: NAMED.PageDown,
+};
+/**
+ * Strip modifier prefixes (`C-` ctrl, `M-` meta/alt, `S-` shift) off a harness
+ * key string so combos like `C-b` or `C-o` can be driven. Prefixes may stack in
+ * any order (`C-S-tab`). The remainder is the base key (named or single char).
+ */
+function parseModifiers(key) {
+    const mods = {};
+    let base = key;
+    // Only consume a prefix when a base remains after it, so a literal "C" or a
+    // hyphen key is not mis-parsed.
+    for (;;) {
+        if (base.length > 2 && base[1] === "-") {
+            const p = base[0];
+            if (p === "C" || p === "c") {
+                mods.ctrl = true;
+                base = base.slice(2);
+                continue;
+            }
+            if (p === "M" || p === "m") {
+                mods.meta = true;
+                base = base.slice(2);
+                continue;
+            }
+            if (p === "S") {
+                mods.shift = true;
+                base = base.slice(2);
+                continue;
+            }
+        }
+        break;
+    }
+    return { mods, base };
+}
+function makeKey(partial, mods = {}) {
     // Some app key-handlers conditionally call key.preventDefault()/stopPropagation()
     // (typed `?.()` so they tolerate undefined). When the host's keypress arrives
     // through a terminal, OpenTUI attaches these methods; in agent-mode we
@@ -48,9 +95,9 @@ function makeKey(partial) {
     let _propagationStopped = false;
     const ev = {
         name: partial.name,
-        ctrl: false,
-        meta: false,
-        shift: false,
+        ctrl: mods.ctrl ?? false,
+        meta: mods.meta ?? false,
+        shift: mods.shift ?? false,
         option: false,
         sequence: partial.sequence,
         number: false,
@@ -72,18 +119,22 @@ function makeKey(partial) {
     };
     return ev;
 }
-function keyForChar(ch) {
-    return makeKey({ name: ch, sequence: ch, raw: ch });
+function keyForChar(ch, mods = {}) {
+    return makeKey({ name: ch, sequence: ch, raw: ch }, mods);
 }
-function keyForNamed(key) {
-    const m = NAMED[key];
+export function keyForNamed(key) {
+    const { mods, base } = parseModifiers(key);
+    // Exact case first (fast path), then case-insensitive so "enter"/"Enter"/
+    // "ENTER"/"return" all resolve. Single-letter bases never collide with a
+    // NAMED word, so they still fall through to the literal-char path below.
+    const m = NAMED[base] ?? NAMED_LC[base.toLowerCase()];
     if (!m) {
         // Unknown named key — fall back to treating it as a literal character if it's 1 char.
-        if (key.length === 1)
-            return keyForChar(key);
+        if (base.length === 1)
+            return keyForChar(base, mods);
         return null;
     }
-    return makeKey(m);
+    return makeKey(m, mods);
 }
 /**
  * Subscribe to agentRuntime.onCommand and inject synthetic key events into
@@ -95,15 +146,51 @@ function keyForNamed(key) {
  * routing in OpenTUI is owned by individual components; a global focus dispatch
  * is out of scope for this bridge.)
  */
+// Runtimes that already have the input bridge wired — module-level so the guard
+// survives App remounts (a per-component ref would reset and re-register).
+const mountedRuntimes = new WeakSet();
 export function useAgentInputBridge(agentRuntime) {
-    const { keyHandler } = useAppContext();
+    const ctx = useAppContext();
+    const keyHandler = ctx.keyHandler;
+    // Focused renderables (the composer textarea) subscribe to keypresses via
+    // renderer._internalKeyInput.onInternal("keypress"), NOT via the public
+    // keyHandler (useAppContext().keyHandler === renderer.keyInput). On the real
+    // TTY renderer both are the SAME InternalKeyHandler, but under the agent-mode
+    // headless renderer they are DISTINCT objects — so emitting only on keyHandler
+    // reached app-level useKeyboard shortcuts yet never the textarea, and typed
+    // text silently vanished (the tier-2 harness-drive bug). Prefer
+    // _internalKeyInput: its emitWithPriority dispatches to BOTH the focused
+    // renderable AND global listeners registered on it.
+    const internal = ctx.renderer?._internalKeyInput;
     useEffect(() => {
-        if (!agentRuntime || !keyHandler)
+        if (!agentRuntime)
+            return;
+        // onCommand has no unsubscribe (it only pushes to a handler array), so
+        // registering twice doubles every keystroke (observed: a typed prompt
+        // arrived duplicated). A per-component ref is not enough — the App can
+        // remount (e.g. hero → chat transition) giving a fresh ref while the prior
+        // handler stays registered on the same long-lived runtime. Track mounted
+        // runtimes in a module-level WeakSet so registration is once-per-runtime
+        // across remounts.
+        if (mountedRuntimes.has(agentRuntime))
+            return;
+        const target = internal ?? keyHandler;
+        if (!target)
             return;
         // Toast-only stub in normal interactive mode provides emitEvent but not
         // onCommand. Guard so the bridge no-ops cleanly instead of crashing the TUI.
         if (typeof agentRuntime.onCommand !== "function")
             return;
+        mountedRuntimes.add(agentRuntime);
+        // Emit to the renderable channel (the focused textarea), and also to the
+        // public keyHandler when it is a distinct object so global shortcuts still
+        // fire. The `!== target` guard avoids double-dispatch on the real renderer
+        // where the two are identical.
+        const emitKey = (k) => {
+            target.emit("keypress", k);
+            if (keyHandler && keyHandler !== target)
+                keyHandler.emit("keypress", k);
+        };
         agentRuntime.onCommand((cmd) => {
             if (!cmd || typeof cmd !== "object")
                 return;
@@ -113,14 +200,14 @@ export function useAgentInputBridge(agentRuntime) {
                     return;
                 const k = keyForNamed(c.key);
                 if (k)
-                    keyHandler.emit("keypress", k);
+                    emitKey(k);
             }
             else if (c.op === "type" && typeof c.text === "string") {
                 for (const ch of c.text) {
-                    keyHandler.emit("keypress", keyForChar(ch));
+                    emitKey(keyForChar(ch));
                 }
             }
         });
-    }, [agentRuntime, keyHandler]);
+    }, [agentRuntime, internal, keyHandler]);
 }
 //# sourceMappingURL=input-bridge.js.map

package/dist/packages/agent-harness-opentui/src/install.d.ts

@@ -41,6 +41,14 @@ export interface InstallOpenTUIHarnessOptions {
      * the `--agent-fake-clock` CLI flag.
      */
     fakeClock?: boolean;
+    /**
+     * Optional visual-frame capture. When provided, a VisualFrame (the actual
+     * rendered cell grid — colors + attributes) is captured and sent right after
+     * each SEMANTIC frame change. Piggybacking on semantic changes bounds the
+     * per-frame `getSpanLines()` allocation to real UI updates instead of every
+     * poll tick. Returns null on dedup / unavailable renderer.
+     */
+    captureVisual?: (seq: number, ts: number) => object | null;
 }
 export interface OpenTUIHarnessHandle {
     /**

package/dist/packages/agent-harness-opentui/src/install.js

@@ -28,6 +28,7 @@ export function installOpenTUIHarness(opts) {
     const fps = opts.fps ?? 60;
     const intervalMs = Math.max(1, Math.round(1000 / fps));
     let seq = 0;
+    let vseq = 0;
     const fakeClock = opts.fakeClock ?? false;
     const hook = createReconcilerHook({
         registry: opts.registry,
@@ -43,6 +44,15 @@ export function installOpenTUIHarness(opts) {
         try {
             opts.transport.send(`${JSON.stringify(frame)}\n`);
             opts.onFrame?.(frame);
+            // Piggyback the visual (rendered cell-grid) frame on semantic changes so
+            // getSpanLines() only runs when the UI actually changed, not every tick.
+            if (opts.captureVisual) {
+                const vframe = opts.captureVisual(vseq, fakeClock ? vseq * 16 : Date.now());
+                if (vframe !== null) {
+                    vseq++;
+                    opts.transport.send(`${JSON.stringify(vframe)}\n`);
+                }
+            }
         }
         catch {
             // Drop frame on transport error — survivor of next tick will retry.

package/dist/packages/agent-harness-opentui/src/semantic.js

@@ -31,22 +31,24 @@ export function Semantic(props) {
         const unregister = registry.register({ ...nodeRef.current, parentId });
         return unregister;
     }, [registry, parentId, node.id]);
-    // Updates: re-register on prop change. This calls register() with the new
-    // node fields; Map.set on an existing key preserves insertion order.
-    // biome-ignore lint/correctness/useExhaustiveDependencies: nodeKey is the intentional cache-bust for node fields
+    // Updates: patch fields on prop change via registry.update(). nodeKey is the
+    // intentional cache-bust dep — it serializes the node fields so this effect
+    // re-runs whenever any field changes; Map.set on an existing key preserves
+    // insertion order.
     React.useEffect(() => {
         if (!registry)
             return;
         if (!nodeKey)
             return;
         // Skip the very first run — the mount effect above already registered.
-        // We detect "subsequent run" by checking if the entry exists in the
-        // registry. On mount, the order is: this effect runs after the mount
-        // effect, so the entry IS present. We then call register() again with
-        // the same node — that's a no-op write that updates fields without
-        // changing position. On subsequent renders with different nodeKey,
-        // register() updates the fields in place.
-        registry.register({ ...nodeRef.current, parentId });
+        // On mount this effect runs after the mount effect, so the entry IS
+        // present; update() patches fields in place (Map.set on an existing key
+        // preserves insertion order). On subsequent renders with a different
+        // nodeKey it patches the changed fields. Using update() (not register())
+        // is the cheaper intended path — it merges instead of rebuilding the
+        // entry, and it is a no-op if the entry was already unmounted.
+        const { id: _id, ...patch } = nodeRef.current;
+        registry.update(nodeRef.current.id, patch);
         // No cleanup — the mount effect's cleanup is the single source of
         // truth for unmounting. If we returned a cleanup here, it would race
         // with re-renders and re-delete the entry.

package/dist/packages/agent-harness-opentui/src/visual-capture.d.ts

@@ -0,0 +1,56 @@
+/**
+ * visual-capture.ts — read OpenTUI's ACTUAL rendered cell grid.
+ *
+ * The semantic harness (reconciler-hook) reports STRUCTURE (id/role/name/props)
+ * but is blind to what a human SEES — colors, bold/italic, alignment, blank
+ * rows, mojibake. This module snapshots the ground-truth render buffer instead:
+ * OpenTUI's `CliRenderer.currentRenderBuffer` is a cell grid it already paints,
+ * and `OptimizedBuffer.getSpanLines()` returns per-cell char + RGBA fg/bg +
+ * attribute bits (verified against @opentui/core@0.1.107 buffer.d.ts:43 +
+ * lib/RGBA.d.ts). No OCR — the buffer is authoritative and in-process.
+ *
+ * Consumers get a `VisualFrame` (protocol) they can query per-cell, render to
+ * annotated text, or (P2) rasterize to PNG for a vision model.
+ */
+import { type VisualFrame } from "@muonroi/agent-harness-core/protocol";
+interface RgbaLike {
+    toInts?: () => [number, number, number, number];
+    r?: number;
+    g?: number;
+    b?: number;
+    a?: number;
+}
+interface CapturedSpanLike {
+    text: string;
+    fg: RgbaLike;
+    bg: RgbaLike;
+    attributes: number;
+    width: number;
+}
+interface CapturedLineLike {
+    spans: CapturedSpanLike[];
+}
+interface OptimizedBufferLike {
+    width: number;
+    height: number;
+    getSpanLines: () => CapturedLineLike[];
+}
+export interface RendererLike {
+    currentRenderBuffer?: OptimizedBufferLike;
+    nextRenderBuffer?: OptimizedBufferLike;
+}
+export interface VisualCaptureHook {
+    /** Build a VisualFrame from the renderer's current buffer. Returns null when
+     *  no renderer is attached, the buffer is unreadable, or content is unchanged
+     *  (content-hash dedup — same contract as the semantic reconciler hook). */
+    capture(seq: number, ts: number): VisualFrame | null;
+    /** Reset dedup state so the next capture always emits. */
+    resetDedup(): void;
+}
+/**
+ * Create a visual-capture hook. `getRenderer` is a late-bound accessor because
+ * the OpenTUI renderer is constructed AFTER the agent-mode runtime (which owns
+ * this hook) — see src/index.ts attachRenderer wiring.
+ */
+export declare function createVisualCaptureHook(getRenderer: () => RendererLike | undefined): VisualCaptureHook;
+export {};

package/dist/packages/agent-harness-opentui/src/visual-capture.js

@@ -0,0 +1,103 @@
+/**
+ * visual-capture.ts — read OpenTUI's ACTUAL rendered cell grid.
+ *
+ * The semantic harness (reconciler-hook) reports STRUCTURE (id/role/name/props)
+ * but is blind to what a human SEES — colors, bold/italic, alignment, blank
+ * rows, mojibake. This module snapshots the ground-truth render buffer instead:
+ * OpenTUI's `CliRenderer.currentRenderBuffer` is a cell grid it already paints,
+ * and `OptimizedBuffer.getSpanLines()` returns per-cell char + RGBA fg/bg +
+ * attribute bits (verified against @opentui/core@0.1.107 buffer.d.ts:43 +
+ * lib/RGBA.d.ts). No OCR — the buffer is authoritative and in-process.
+ *
+ * Consumers get a `VisualFrame` (protocol) they can query per-cell, render to
+ * annotated text, or (P2) rasterize to PNG for a vision model.
+ */
+import { createHash } from "node:crypto";
+import { PROTOCOL_VERSION, } from "@muonroi/agent-harness-core/protocol";
+/** Low byte of OpenTUI's TextAttributes (ATTRIBUTE_BASE_MASK = 255). */
+const ATTR_MASK = 255;
+function clampByte(n) {
+    return Math.max(0, Math.min(255, Math.round(n)));
+}
+/**
+ * Convert an OpenTUI RGBA to a "#rrggbb" (or "#rrggbbaa" when translucent) hex
+ * string. Prefers `toInts()` (0-255 ints); falls back to component getters,
+ * scaling 0-1 floats up to 0-255 when the renderer exposes normalized channels.
+ */
+function toHex(c) {
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    let a = 255;
+    if (c && typeof c.toInts === "function") {
+        const ints = c.toInts();
+        r = ints[0];
+        g = ints[1];
+        b = ints[2];
+        a = ints[3];
+    }
+    else if (c) {
+        const scale = (v) => (v === undefined ? 0 : v <= 1 ? v * 255 : v);
+        r = scale(c.r);
+        g = scale(c.g);
+        b = scale(c.b);
+        a = c.a === undefined ? 255 : c.a <= 1 ? c.a * 255 : c.a;
+    }
+    const h = (n) => clampByte(n).toString(16).padStart(2, "0");
+    return a < 255 ? `#${h(r)}${h(g)}${h(b)}${h(a)}` : `#${h(r)}${h(g)}${h(b)}`;
+}
+/**
+ * Create a visual-capture hook. `getRenderer` is a late-bound accessor because
+ * the OpenTUI renderer is constructed AFTER the agent-mode runtime (which owns
+ * this hook) — see src/index.ts attachRenderer wiring.
+ */
+export function createVisualCaptureHook(getRenderer) {
+    let lastHash;
+    function capture(seq, ts) {
+        const renderer = getRenderer();
+        const buffer = renderer?.currentRenderBuffer ?? renderer?.nextRenderBuffer;
+        if (!buffer || typeof buffer.getSpanLines !== "function")
+            return null;
+        let captured;
+        try {
+            captured = buffer.getSpanLines();
+        }
+        catch (err) {
+            // getSpanLines allocates + decodes native Zig memory; a mid-resize/destroy
+            // race can throw. Skip this frame (the next tick retries). Debug-gated log
+            // only — unconditional logging here would spam the render loop.
+            if (process.env.MUONROI_DEBUG_VISUAL) {
+                console.error(`[visual-capture] getSpanLines failed: ${err?.message}`);
+            }
+            return null;
+        }
+        const lines = captured.map((ln) => ({
+            spans: (ln.spans ?? []).map((s) => ({
+                text: s.text,
+                fg: toHex(s.fg),
+                bg: toHex(s.bg),
+                attrs: (s.attributes ?? 0) & ATTR_MASK,
+                width: s.width,
+            })),
+        }));
+        const hash = createHash("sha1").update(JSON.stringify(lines)).digest("hex");
+        if (lastHash === hash)
+            return null;
+        lastHash = hash;
+        return {
+            mode: "visual",
+            version: PROTOCOL_VERSION,
+            seq,
+            ts,
+            cols: buffer.width,
+            rows: buffer.height,
+            cursor: null,
+            lines,
+        };
+    }
+    function resetDedup() {
+        lastHash = undefined;
+    }
+    return { capture, resetDedup };
+}
+//# sourceMappingURL=visual-capture.js.map