@deepseek-harness-tui/dsh-tui 0.11.1 → 0.12.0

package/lib/types/ink/terminal-querier.js

@@ -32,6 +32,7 @@ export function decrqm(mode) {
     return {
         request: csi(`?${mode}$p`),
         match: (r) => r.type === 'decrpm' && r.mode === mode,
+        responseType: 'decrpm',
     };
 }
 /**
@@ -44,6 +45,7 @@ export function da1() {
     return {
         request: csi('c'),
         match: (r) => r.type === 'da1',
+        responseType: 'da1',
     };
 }
 /**
@@ -54,6 +56,7 @@ export function da2() {
     return {
         request: csi('>c'),
         match: (r) => r.type === 'da2',
+        responseType: 'da2',
     };
 }
 /**
@@ -65,6 +68,7 @@ export function kittyKeyboard() {
     return {
         request: csi('?u'),
         match: (r) => r.type === 'kittyKeyboard',
+        responseType: 'kittyKeyboard',
     };
 }
 /**
@@ -78,6 +82,7 @@ export function kittyGraphics(imageId) {
         // same direct-data + compression path used by real renderer uploads.
         request: `\u001b_Gi=${id},s=1,v=1,a=q,t=d,f=32,o=z;eAFjYGBgAAAABAAB\u001b\\`,
         match: (r) => r.type === 'kittyGraphics' && r.imageId === id,
+        responseType: 'kittyGraphics',
     };
 }
 /** XTWINOPS: query the physical pixel dimensions of one terminal cell. */
@@ -85,6 +90,7 @@ export function terminalCellSizePixels() {
     return {
         request: csi('16t'),
         match: (r) => r.type === 'terminalPixelSize' && r.scope === 'cell',
+        responseType: 'terminalPixelSize',
     };
 }
 /** XTWINOPS: query the terminal text area's physical pixel dimensions. */
@@ -92,6 +98,7 @@ export function terminalWindowSizePixels() {
     return {
         request: csi('14t'),
         match: (r) => r.type === 'terminalPixelSize' && r.scope === 'window',
+        responseType: 'terminalPixelSize',
     };
 }
 /**
@@ -105,6 +112,7 @@ export function cursorPosition() {
     return {
         request: csi('?6n'),
         match: (r) => r.type === 'cursorPosition',
+        responseType: 'cursorPosition',
     };
 }
 /**
@@ -117,6 +125,7 @@ export function oscColor(code) {
     return {
         request: osc(code, '?'),
         match: (r) => r.type === 'osc' && r.code === code,
+        responseType: 'osc',
     };
 }
 /**
@@ -131,6 +140,7 @@ export function xtversion() {
     return {
         request: csi('>0q'),
         match: (r) => r.type === 'xtversion',
+        responseType: 'xtversion',
     };
 }
 // -- Querier --
@@ -166,6 +176,37 @@ export class TerminalQuerier {
     get isSuspended() {
         return this.suspended;
     }
+    /**
+     * In-flight evidence for the input parser (read-only observation): true
+     * while at least one query or flush sentinel is still waiting for its
+     * reply. Purely observational — queue semantics are untouched.
+     */
+    get hasPending() {
+        return this.queue.length > 0;
+    }
+    /**
+     * In-flight evidence for the input parser (read-only observation): the
+     * response types of the queries still awaiting a reply, plus `da1` when a
+     * flush() sentinel is still open (DA1 is the reply that resolves it).
+     *
+     * This is bound to the query lifecycle on purpose. A boolean "something
+     * was sent recently" lets any recent query authorize a claim for bytes
+     * that may belong to no query at all, so the parser receives the expected
+     * types instead: a reply tail is only claimed when its shape can complete
+     * into one of them, and a query resolved by a sentinel stops counting the
+     * moment its promise settles. Purely observational — queue semantics are
+     * untouched.
+     */
+    get pendingResponseTypes() {
+        const types = new Set();
+        for (const pending of this.queue) {
+            if (pending.kind === 'query')
+                types.add(pending.responseType);
+            else
+                types.add('da1');
+        }
+        return types;
+    }
     holdRawMode() {
         this.setRawMode?.(true);
         return () => this.setRawMode?.(false);
@@ -190,6 +231,7 @@ export class TerminalQuerier {
             this.queue.push({
                 kind: 'query',
                 match: query.match,
+                responseType: query.responseType,
                 resolve: r => resolve(r),
                 releaseRawMode: this.holdRawMode(),
             });
@@ -214,6 +256,11 @@ export class TerminalQuerier {
         this.suspended = true;
         this.drainPending();
     }
+    /**
+     * Receives responses that answer no pending query — e.g. a Kitty graphics
+     * error for a placement command sent without suppressing failures.
+     */
+    onUnsolicited = undefined;
     /**
      * Dispatch a response parsed from stdin. Called by App.tsx's
      * processKeysInBatch for every `kind: 'response'` item.
@@ -230,7 +277,8 @@ export class TerminalQuerier {
      *   and signal its flush() completion. Only draining up to the first
      *   sentinel keeps later batches intact when multiple callers have
      *   concurrent queries in flight.
-     * - Unsolicited responses (no match, no sentinel) are silently dropped.
+     * - Unsolicited responses (no match, no sentinel) go to
+     *   {@link onUnsolicited} when set, and are dropped otherwise.
      * @param r - the response parsed from stdin.
      */
     onResponse(r) {
@@ -247,8 +295,10 @@ export class TerminalQuerier {
         }
         if (r.type === 'da1') {
             const s = this.queue.findIndex(p => p.kind === 'sentinel');
-            if (s === -1)
+            if (s === -1) {
+                this.onUnsolicited?.(r);
                 return;
+            }
             for (const p of this.queue.splice(0, s + 1)) {
                 if (p.kind === 'query')
                     p.resolve(undefined);
@@ -256,7 +306,9 @@ export class TerminalQuerier {
                     p.resolve(r);
                 p.releaseRawMode();
             }
+            return;
         }
+        this.onUnsolicited?.(r);
     }
     /**
      * Resolve outstanding queries before stdin is handed to another process.

package/lib/types/ink/timeline-rail.d.ts

@@ -63,6 +63,11 @@ export interface TimelineSnapshot {
     /** Turn owning the viewport top row; first turn while pre-turn content
      *  owns the top; null only when there are no turns. */
     activeId: number | null;
+    /** Turn the sticky header names: the active turn once its prompt has
+     *  scrolled out above the viewport top (or is folded away); null while
+     *  that prompt, or pre-turn content such as the logo, is still on the
+     *  top row, where naming it would repeat text already on screen. */
+    pinnedId: number | null;
     /** ▲ target (strictly above the top), null at the first turn. */
     upId: number | null;
     /** ▼ target (below the top and reachable), null at the end. */

package/lib/types/ink/timeline-rail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeline-rail.d.ts","sourceRoot":"","sources":["../../../src/ink/timeline-rail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,qDAAqD;AACrD,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC,mDAAmD;AACnD,eAAO,MAAM,cAAc,IAAI,CAAA;AAE/B,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC;uEACuE;AACvE,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAA;IACV;6BACyB;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;iEACiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IAClC;2DACuD;IACvD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,0BAA0B;AAC1B,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnC;0CAC0C;AAC1C,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB;;qBAEiB;IACjB,UAAU,EAAE,OAAO,CAAA;CACpB,GAAG,OAAO,CAOV;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,QAAQ,EAAE,OAAO,GAChB,YAAY,GAAG,IAAI,CAuBrB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAUtE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAoB,GAAG,MAAM,CAkB9E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CA+B5E"}
+{"version":3,"file":"timeline-rail.d.ts","sourceRoot":"","sources":["../../../src/ink/timeline-rail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,qDAAqD;AACrD,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC,mDAAmD;AACnD,eAAO,MAAM,cAAc,IAAI,CAAA;AAE/B,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC;uEACuE;AACvE,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAA;IACV;6BACyB;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;iEACiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IAClC;2DACuD;IACvD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;wEAGoE;IACpE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,0BAA0B;AAC1B,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnC;0CAC0C;AAC1C,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB;;qBAEiB;IACjB,UAAU,EAAE,OAAO,CAAA;CACpB,GAAG,OAAO,CAOV;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,QAAQ,EAAE,OAAO,GAChB,YAAY,GAAG,IAAI,CAuBrB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAUtE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAoB,GAAG,MAAM,CAkB9E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CA+B5E"}

package/lib/types/ink/update-overflow-guard.d.ts

@@ -58,5 +58,29 @@ export declare function swallowNestedUpdateOverflow(error: unknown, source: stri
  * @param onChange - The subscriber callback about to run.
  */
 export declare function callWithUpdateOverflowGuard(source: string, onChange: () => void): void;
+/**
+ * Origin of a process-level fatal error, as reported to the sink.
+ */
+export type ProcessGuardOrigin = 'uncaughtException' | 'unhandledRejection';
+/**
+ * Fatal-error sink installed by the process owner (the dsh-tui runtime, which
+ * routes it into the TUI's single exit funnel). Returning true means the sink
+ * took ownership of the process — it runs the teardown (resume marker,
+ * terminal restore, `dsh-tui crashed: …`) and exits non-zero. Returning false
+ * leaves the error to Node's default crash, which keeps "fail loud, non-zero"
+ * true when no sink is registered or the tree is being torn down.
+ */
+export type ProcessGuardFatalSink = (error: unknown, origin: ProcessGuardOrigin) => boolean;
+/** Register (or clear, with undefined) the fatal-error sink. */
+export declare function registerProcessGuardFatalSink(sink: ProcessGuardFatalSink | undefined): void;
+/**
+ * Normalize the reason handed to a fatal sink so the exit funnel can never
+ * mistake a fatal error for a clean user exit. `Promise.reject()` and
+ * `throw undefined` deliver `undefined`, and the funnel selects its crash path
+ * with `error !== undefined` — passing the raw reason through would run the
+ * zero-exit path while the sink reported that it owned the process. Defined
+ * reasons (including non-Error values) are returned unchanged.
+ */
+export declare function fatalReasonForExit(error: unknown, origin: ProcessGuardOrigin): unknown;
 export declare function installNestedUpdateOverflowProcessGuard(): void;
 //# sourceMappingURL=update-overflow-guard.d.ts.map

package/lib/types/ink/update-overflow-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-overflow-guard.d.ts","sourceRoot":"","sources":["../../../src/ink/update-overflow-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAoBH,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;AAOjD,+CAA+C;AAC/C,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAEnF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAmDnF;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAOtF;AAeD,wBAAgB,uCAAuC,IAAI,IAAI,CAc9D"}
+{"version":3,"file":"update-overflow-guard.d.ts","sourceRoot":"","sources":["../../../src/ink/update-overflow-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAoBH,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;AAOjD,+CAA+C;AAC/C,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAEnF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAmDnF;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAOtF;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG,oBAAoB,CAAA;AAE3E;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAA;AAG3F,gEAAgE;AAChE,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,CAE3F;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAEtF;AAiBD,wBAAgB,uCAAuC,IAAI,IAAI,CAgB9D"}

package/lib/types/ink/update-overflow-guard.js

@@ -130,6 +130,22 @@ export function callWithUpdateOverflowGuard(source, onChange) {
         throw error;
     }
 }
+let fatalSink;
+/** Register (or clear, with undefined) the fatal-error sink. */
+export function registerProcessGuardFatalSink(sink) {
+    fatalSink = sink;
+}
+/**
+ * Normalize the reason handed to a fatal sink so the exit funnel can never
+ * mistake a fatal error for a clean user exit. `Promise.reject()` and
+ * `throw undefined` deliver `undefined`, and the funnel selects its crash path
+ * with `error !== undefined` — passing the raw reason through would run the
+ * zero-exit path while the sink reported that it owned the process. Defined
+ * reasons (including non-Error values) are returned unchanged.
+ */
+export function fatalReasonForExit(error, origin) {
+    return error === undefined ? new Error(`${origin} with undefined reason`) : error;
+}
 /**
  * Process-level backstop for the overflow error. The hotspot guards above
  * cover the known enqueue sites (clock tick, reveal tick, channel emit,
@@ -138,9 +154,11 @@ export function callWithUpdateOverflowGuard(source, onChange) {
  * feeder, a future timer, a plugin's store) would still kill the process.
  * This installs uncaughtException/unhandledRejection handlers that absorb
  * exactly the overflow error class (same self-healing contract: React
- * already reset the counter before throwing) and rethrow everything else
- * unchanged. Idempotent; opt out with DSH_TUI_NO_185_PROCESS_GUARD=1 when a
- * host owns process error policy.
+ * already reset the counter before throwing) and hand everything else to the
+ * registered fatal sink — or rethrow it unchanged when there is none, so the
+ * process still fails loud with a non-zero exit rather than continuing in an
+ * unknown state. Idempotent; opt out with DSH_TUI_NO_185_PROCESS_GUARD=1 when
+ * a host owns process error policy.
  */
 let processGuardInstalled = false;
 export function installNestedUpdateOverflowProcessGuard() {
@@ -152,6 +170,8 @@ export function installNestedUpdateOverflowProcessGuard() {
     process.on('uncaughtException', error => {
         if (swallowNestedUpdateOverflow(error, 'process.uncaught'))
             return;
+        if (fatalSink?.(error, 'uncaughtException') === true)
+            return;
         // Unknown errors keep Node's default semantics: rethrowing from a
         // listener crashes the process with the original error.
         throw error;
@@ -159,6 +179,8 @@ export function installNestedUpdateOverflowProcessGuard() {
     process.on('unhandledRejection', error => {
         if (swallowNestedUpdateOverflow(error, 'process.rejection'))
             return;
+        if (fatalSink?.(error, 'unhandledRejection') === true)
+            return;
         throw error;
     });
 }

package/lib/types/math/inline-layout.d.ts

@@ -0,0 +1,29 @@
+/** Formulas one paragraph may lay out as images; the rest keep Unicode. */
+export declare const INLINE_MEDIA_MAX = 4096;
+export type InlinePiece = {
+    readonly kind: 'text';
+    readonly text: string;
+    readonly width: number;
+} | {
+    readonly kind: 'media';
+    readonly index: number;
+    readonly columns: number;
+};
+export type InlineRow = {
+    readonly pieces: readonly InlinePiece[];
+    /** Columns the row's content spans. */
+    readonly width: number;
+    /** The row continues the previous one (a wrap, not a source newline). */
+    readonly continuation: boolean;
+};
+/** The placeholder run standing in for formula `index`, `columns` cells wide. */
+export declare function inlineMediaPlaceholder(index: number, columns: number): string;
+/**
+ * Wrap `formatted` (ANSI text containing placeholder runs for `columns.length`
+ * formulas) to `width` and split every row into text and media pieces.
+ * Returns undefined when a formula could not be kept whole on one row — its
+ * run was split by a hard wrap (wider than the row) or appears more than once
+ * — so the caller keeps the plain text rendering instead.
+ */
+export declare function layoutInlineMedia(formatted: string, width: number, columns: readonly number[]): InlineRow[] | undefined;
+//# sourceMappingURL=inline-layout.d.ts.map

package/lib/types/math/inline-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-layout.d.ts","sourceRoot":"","sources":["../../../src/math/inline-layout.ts"],"names":[],"mappings":"AAoBA,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,OAAS,CAAA;AAItC,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhF,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IACvC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CAC/B,CAAA;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAK7E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,SAAS,EAAE,GAAG,SAAS,CA2CzB"}

package/lib/types/math/inline-layout.js

@@ -0,0 +1,106 @@
+/**
+ * Line layout for a paragraph whose inline formulas are terminal images.
+ *
+ * Each formula is stood in for by a run of placeholder characters as wide as
+ * its image (one private-use code point per formula, so neighbouring
+ * formulas stay distinguishable), and the formatted paragraph is wrapped by
+ * the same `wrapText` that <Text> uses. A run holds no spaces, so it wraps
+ * as one unbreakable word: a formula never splits across rows, and a
+ * paragraph with no formulas lays out exactly as it does in <Text>. Each
+ * wrapped row is then cut into ANSI-balanced text pieces (sliceAnsi re-opens
+ * the styles and links a cut crosses) and the image slots between them.
+ * Pure: no React, no terminal.
+ */
+import stripAnsi from 'strip-ansi';
+import { stringWidth } from '../ink/stringWidth.js';
+import wrapText from '../ink/wrap-text.js';
+import sliceAnsi from '../utils/sliceAnsi.js';
+/** First placeholder code point (Private Use Area, width 1). */
+const PLACEHOLDER_BASE = 0xe000;
+/** Formulas one paragraph may lay out as images; the rest keep Unicode. */
+export const INLINE_MEDIA_MAX = 0x1000;
+const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/** The placeholder run standing in for formula `index`, `columns` cells wide. */
+export function inlineMediaPlaceholder(index, columns) {
+    if (!Number.isInteger(index) || index < 0 || index >= INLINE_MEDIA_MAX) {
+        throw new RangeError(`inline media index out of range: ${index}`);
+    }
+    return String.fromCodePoint(PLACEHOLDER_BASE + index).repeat(Math.max(1, columns));
+}
+/**
+ * Wrap `formatted` (ANSI text containing placeholder runs for `columns.length`
+ * formulas) to `width` and split every row into text and media pieces.
+ * Returns undefined when a formula could not be kept whole on one row — its
+ * run was split by a hard wrap (wider than the row) or appears more than once
+ * — so the caller keeps the plain text rendering instead.
+ */
+export function layoutInlineMedia(formatted, width, columns) {
+    if (width < 1)
+        return undefined;
+    const seen = new Set();
+    const rows = [];
+    const wrapped = wrapText(formatted, width, 'wrap');
+    const continuations = wrapContinuations(stripAnsi(formatted), stripAnsi(wrapped));
+    for (const [lineIndex, line] of wrapped.split('\n').entries()) {
+        const pieces = [];
+        const plain = stripAnsi(line);
+        let column = 0;
+        let textStart = 0;
+        let run;
+        const flushText = (end) => {
+            if (end <= textStart)
+                return;
+            const text = sliceAnsi(line, textStart, end);
+            pieces.push({ kind: 'text', text, width: end - textStart });
+        };
+        const closeRun = () => {
+            if (run === undefined)
+                return true;
+            const length = column - run.start;
+            if (seen.has(run.index) || length !== columns[run.index])
+                return false;
+            seen.add(run.index);
+            pieces.push({ kind: 'media', index: run.index, columns: length });
+            textStart = column;
+            run = undefined;
+            return true;
+        };
+        for (const { segment: char } of graphemes.segment(plain)) {
+            const code = char.codePointAt(0);
+            const index = code - PLACEHOLDER_BASE;
+            const isMedia = index >= 0 && index < columns.length;
+            if (run !== undefined && (!isMedia || index !== run.index) && !closeRun())
+                return undefined;
+            if (isMedia && run === undefined) {
+                flushText(column);
+                run = { index, start: column };
+            }
+            column += isMedia ? 1 : stringWidth(char);
+        }
+        if (!closeRun())
+            return undefined;
+        flushText(column);
+        rows.push({ pieces, width: column, continuation: continuations[lineIndex] === true });
+    }
+    return seen.size === columns.length ? rows : undefined;
+}
+/**
+ * For each line of `wrapped`, whether the newline before it was inserted by
+ * wrapping (true) or was in `source` (false). wrapAnsi (trim off) only
+ * inserts newlines, so walking both plain strings in step finds them.
+ */
+function wrapContinuations(source, wrapped) {
+    const result = [false];
+    let at = 0;
+    for (const char of wrapped) {
+        if (char === '\n') {
+            const inSource = source[at] === '\n';
+            result.push(!inSource);
+            if (inSource)
+                at += 1;
+            continue;
+        }
+        at += char.length;
+    }
+    return result;
+}

package/lib/types/math/layout.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Terminal-cell geometry for a typeset formula. Pure: no rasterization.
+ *
+ * MathJax reports a formula's size in ex. A formula starts at one base scale
+ * tied to the terminal's physical cell height (so every formula reads at the
+ * same size, like text), shrinks uniformly only when it would exceed the
+ * width or height it may occupy, and is never enlarged. The canvas is padded,
+ * never stretched, to a whole number of cells.
+ */
+import type { TerminalCellSize } from '../ink/terminal-image.js';
+/** Pixels per ex at the base scale, as a fraction of the cell height. */
+export declare const BASE_EX_TO_CELL_HEIGHT = 0.5;
+/**
+ * Display formulas set larger than the body text, like LaTeX (settings
+ * `mathImageScale`): at one ex per 0.72 cell heights the glyph strokes get
+ * roughly 45% more device pixels, which is what a terminal-drawn ink mask
+ * needs to read as clean rather than thin. Inline formulas keep the base
+ * scale — their single row of cells clamps the resolution anyway.
+ */
+export declare const LARGE_DISPLAY_EX_TO_CELL_HEIGHT = 0.72;
+/** The next step up: about 80% more pixels than the base scale. */
+export declare const XLARGE_DISPLAY_EX_TO_CELL_HEIGHT = 0.9;
+/**
+ * Below this fraction of the base scale the formula is unreadable as an
+ * image; the caller keeps the Unicode rendering instead of shrinking further.
+ */
+export declare const MIN_SCALE_FRACTION = 0.5;
+export interface FormulaSize {
+    readonly widthEx: number;
+    readonly heightEx: number;
+}
+export interface FormulaConstraints {
+    readonly cellSize: TerminalCellSize;
+    /** Pixels per ex as a fraction of the cell height; defaults to the base scale. */
+    readonly baseExToCellHeight?: number;
+    readonly maxColumns: number;
+    readonly maxRows: number;
+    /** Transparent margin around the ink, in device-independent pixels. */
+    readonly bleed: number;
+    /** Largest canvas edge and RGBA byte size the raster may use. */
+    readonly maxEdge: number;
+    readonly maxBytes: number;
+}
+export interface FormulaLayoutPlan {
+    readonly columns: number;
+    readonly rows: number;
+    /** Canvas size in device pixels (cells × cell size × deviceScale). */
+    readonly canvasWidth: number;
+    readonly canvasHeight: number;
+    /** Ink box size in device pixels, centered in the canvas. */
+    readonly contentWidth: number;
+    readonly contentHeight: number;
+    readonly pixelsPerEx: number;
+    readonly deviceScale: 1 | 2;
+}
+export type FormulaLayoutFailure = 'invalid-dimensions' | 'too-small' | 'raster-limit';
+export declare function planFormulaLayout(size: FormulaSize, constraints: FormulaConstraints): FormulaLayoutPlan | FormulaLayoutFailure;
+//# sourceMappingURL=layout.d.ts.map

package/lib/types/math/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/math/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAEhE,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,MAAM,CAAA;AACzC;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,OAAO,CAAA;AACnD,mEAAmE;AACnE,eAAO,MAAM,gCAAgC,MAAM,CAAA;AACnD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,kFAAkF;IAClF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAA;CAC5B;AAED,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,GAAG,WAAW,GAAG,cAAc,CAAA;AAEtF,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,kBAAkB,GAC9B,iBAAiB,GAAG,oBAAoB,CA6C1C"}

package/lib/types/math/layout.js

@@ -0,0 +1,59 @@
+/** Pixels per ex at the base scale, as a fraction of the cell height. */
+export const BASE_EX_TO_CELL_HEIGHT = 0.5;
+/**
+ * Display formulas set larger than the body text, like LaTeX (settings
+ * `mathImageScale`): at one ex per 0.72 cell heights the glyph strokes get
+ * roughly 45% more device pixels, which is what a terminal-drawn ink mask
+ * needs to read as clean rather than thin. Inline formulas keep the base
+ * scale — their single row of cells clamps the resolution anyway.
+ */
+export const LARGE_DISPLAY_EX_TO_CELL_HEIGHT = 0.72;
+/** The next step up: about 80% more pixels than the base scale. */
+export const XLARGE_DISPLAY_EX_TO_CELL_HEIGHT = 0.9;
+/**
+ * Below this fraction of the base scale the formula is unreadable as an
+ * image; the caller keeps the Unicode rendering instead of shrinking further.
+ */
+export const MIN_SCALE_FRACTION = 0.5;
+export function planFormulaLayout(size, constraints) {
+    const { cellSize, maxColumns, maxRows, bleed } = constraints;
+    if (!(size.widthEx > 0) || !(size.heightEx > 0) ||
+        !Number.isFinite(size.widthEx) || !Number.isFinite(size.heightEx) ||
+        maxColumns < 1 || maxRows < 1) {
+        return 'invalid-dimensions';
+    }
+    const basePixelsPerEx = cellSize.height * (constraints.baseExToCellHeight ?? BASE_EX_TO_CELL_HEIGHT);
+    const availableWidth = maxColumns * cellSize.width - bleed * 2;
+    const availableHeight = maxRows * cellSize.height - bleed * 2;
+    if (availableWidth <= 0 || availableHeight <= 0)
+        return 'too-small';
+    const pixelsPerEx = Math.min(basePixelsPerEx, availableWidth / size.widthEx, availableHeight / size.heightEx);
+    // Legibility is absolute, not relative to what the caller asked for: the
+    // floor stays on the base scale so a larger display request shrinks back to
+    // a readable size instead of flipping formulas to the Unicode fallback.
+    if (pixelsPerEx < cellSize.height * BASE_EX_TO_CELL_HEIGHT * MIN_SCALE_FRACTION)
+        return 'too-small';
+    const contentWidth = size.widthEx * pixelsPerEx;
+    const contentHeight = size.heightEx * pixelsPerEx;
+    const columns = Math.min(maxColumns, Math.ceil((contentWidth + bleed * 2) / cellSize.width));
+    const rows = Math.min(maxRows, Math.ceil((contentHeight + bleed * 2) / cellSize.height));
+    const fits = (scale) => {
+        const width = columns * cellSize.width * scale;
+        const height = rows * cellSize.height * scale;
+        return width <= constraints.maxEdge && height <= constraints.maxEdge &&
+            width * height * 4 <= constraints.maxBytes;
+    };
+    const deviceScale = fits(2) ? 2 : fits(1) ? 1 : undefined;
+    if (deviceScale === undefined)
+        return 'raster-limit';
+    return {
+        columns,
+        rows,
+        canvasWidth: columns * cellSize.width * deviceScale,
+        canvasHeight: rows * cellSize.height * deviceScale,
+        contentWidth: contentWidth * deviceScale,
+        contentHeight: contentHeight * deviceScale,
+        pixelsPerEx: pixelsPerEx * deviceScale,
+        deviceScale,
+    };
+}

package/lib/types/math/renderer.d.ts

@@ -0,0 +1,64 @@
+import { type TerminalCellSize, type TerminalImageSource } from '../ink/terminal-image.js';
+/** Same budget as the Unicode renderer: longer input is a paste, not math. */
+export declare const MATH_SOURCE_LIMIT = 4096;
+export type MathFailureCode = 'empty' | 'input-too-long' | 'tex-error' | 'invalid-dimensions' | 'too-small' | 'raster-limit' | 'empty-raster' | 'clipped-raster' | 'backend-unavailable';
+export interface MathRenderRequest {
+    /** TeX without delimiters. */
+    readonly tex: string;
+    readonly display: boolean;
+    /** Ink color as `#rrggbb` (the theme's text color). */
+    readonly color: string;
+    readonly cellSize: TerminalCellSize;
+    /** Largest cell box the formula may occupy; it shrinks to fit, never grows. */
+    readonly maxColumns: number;
+    readonly maxRows: number;
+    /**
+     * Pixels per ex as a fraction of the cell height. Display formulas pass
+     * {@link DISPLAY_EX_TO_CELL_HEIGHT} so they are set larger than the body
+     * text; inline formulas keep the base scale.
+     */
+    readonly baseExToCellHeight?: number;
+}
+export interface MathRaster {
+    /** Stable identity of this raster (formula, color, geometry). */
+    readonly key: string;
+    readonly source: TerminalImageSource;
+    readonly columns: number;
+    readonly rows: number;
+    /** Half-open pixel box of visible ink inside the canvas. */
+    readonly inkBounds: {
+        readonly left: number;
+        readonly top: number;
+        readonly right: number;
+        readonly bottom: number;
+    };
+}
+export type MathRenderResult = {
+    readonly ok: true;
+    readonly raster: MathRaster;
+} | {
+    readonly ok: false;
+    readonly failure: MathFailureCode;
+};
+/** Cache counters, for tests and debug output. */
+export declare const mathRenderStats: {
+    vectorHits: number;
+    vectorMisses: number;
+    rasterHits: number;
+    rasterMisses: number;
+};
+/**
+ * The settled result for this request if one is cached, without rendering.
+ * Lets a remounted view (scrolled back into the viewport) paint its image on
+ * the first frame instead of flashing the Unicode fallback.
+ */
+export declare function peekMathRaster(request: MathRenderRequest): MathRenderResult | undefined;
+/**
+ * Typeset and rasterize one formula. Results (including failures) are cached
+ * by formula, color and geometry; concurrent requests for the same key share
+ * one render.
+ */
+export declare function renderMathRaster(request: MathRenderRequest): Promise<MathRenderResult>;
+/** Drop every cached vector and raster (tests; a future debug command). */
+export declare function clearMathRenderCaches(): void;
+//# sourceMappingURL=renderer.d.ts.map

package/lib/types/math/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/math/renderer.ts"],"names":[],"mappings":"AAiBA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAA;AAGjC,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,OAAO,CAAA;AASrC,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,gBAAgB,GAChB,WAAW,GACX,oBAAoB,GACpB,WAAW,GACX,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,qBAAqB,CAAA;AAEzB,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CACrC;AAED,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CACrH;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAA;AAgE7D,kDAAkD;AAClD,eAAO,MAAM,eAAe;;;;;CAAqE,CAAA;AA+IjG;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,SAAS,CAIvF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyBtF;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,IAAI,IAAI,CAO5C"}