@askdkc/dsh-cli 0.11.3

package/lib/types/ink/render-to-screen.d.ts

@@ -0,0 +1,65 @@
+import type { ReactElement } from 'react';
+import { type Screen, StylePool } from './screen.js';
+/** Position of a match within a rendered message, relative to the message's
+ *  own bounding box (row 0 = message top). Stable across scroll — to
+ *  highlight on the real screen, add the message's screen-row offset. */
+export type MatchPosition = {
+    row: number;
+    col: number;
+    /** Number of CELLS the match spans (= query.length for ASCII, more
+     *  for wide chars in the query). */
+    len: number;
+};
+/** Render a React element (wrapped in all contexts the component needs —
+ *  caller's job) to an isolated Screen buffer at the given width. Returns
+ *  the Screen + natural height (from yoga). Used for search: render ONE
+ *  message, scan its Screen for the query, get exact (row, col) positions.
+ *
+ *  ~1-3ms per call (yoga alloc + calculateLayout + paint). The
+ *  flushSyncWork cross-root leak measured ~0.0003ms/call growth — fine
+ *  for on-demand single-message rendering, pathological for render-all-
+ *  8k-upfront. Cache per (msg, query, width) upstream.
+ *
+ *  Unmounts between calls. Root/container/pools persist for reuse.
+ *
+ * @param el - the React element to render.
+ * @param width - the render width in columns.
+ * @returns the painted screen buffer and the yoga-computed content height.
+ */
+export declare function renderToScreen(el: ReactElement, width: number): {
+    screen: Screen;
+    height: number;
+};
+/** Scan a Screen buffer for all occurrences of query. Returns positions
+ *  relative to the buffer (row 0 = buffer top). Same cell-skip logic as
+ *  applySearchHighlight (SpacerTail/SpacerHead/noSelect) so positions
+ *  match what the overlay highlight would find. Case-insensitive.
+ *
+ *  For the side-render use: this Screen is the FULL message (natural
+ *  height, not viewport-clipped). Positions are stable — to highlight
+ *  on the real screen, add the message's screen offset (lo).
+ *
+ * @param screen - the screen buffer to scan.
+ * @param query - the substring to search for, matched case-insensitively.
+ * @returns the match positions relative to the buffer, or an empty list.
+ */
+export declare function scanPositions(screen: Screen, query: string): MatchPosition[];
+/** Write CURRENT (yellow+bold+underline) at positions[currentIdx] +
+ *  rowOffset. OTHER positions are NOT styled here — the scan-highlight
+ *  (applySearchHighlight with null hint) does inverse for all visible
+ *  matches, including these. Two-layer: scan = 'you could go here',
+ *  position = 'you ARE here'. Writing inverse again here would be a
+ *  no-op (withInverse idempotent) but wasted work.
+ *
+ *  Positions are message-relative (row 0 = message top). rowOffset =
+ *  message's current screen-top (lo). Clips outside [0, height).
+ *
+ * @param screen - the screen buffer to style.
+ * @param stylePool - the style pool providing the current-match transform.
+ * @param positions - the message-relative match positions.
+ * @param rowOffset - the message's current screen-top row.
+ * @param currentIdx - index into positions of the match to highlight.
+ * @returns true when the highlight was written, false when out of range.
+ */
+export declare function applyPositionedHighlight(screen: Screen, stylePool: StylePool, positions: MatchPosition[], rowOffset: number, currentIdx: number): boolean;
+//# sourceMappingURL=render-to-screen.d.ts.map

package/lib/types/ink/render-to-screen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-to-screen.d.ts","sourceRoot":"","sources":["../../../src/ink/render-to-screen.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAUzC,OAAO,EAML,KAAK,MAAM,EACX,SAAS,EAEV,MAAM,aAAa,CAAA;AAEpB;;yEAEyE;AACzE,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX;wCACoC;IACpC,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,MAAM,GACZ;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA6EpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,CAoD5E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,aAAa,EAAE,EAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAaT"}

package/lib/types/ink/render-to-screen.js

@@ -0,0 +1,189 @@
+import noop from 'lodash-es/noop.js';
+import { LegacyRoot } from 'react-reconciler/constants.js';
+import { logForDebugging } from '../utils/debug.js';
+import { createNode } from './dom.js';
+import { FocusManager } from './focus.js';
+import Output from './output.js';
+import reconciler from './reconciler.js';
+import renderNodeToOutput, { resetLayoutShifted, } from './render-node-to-output.js';
+import { CharPool, cellAtIndex, createScreen, HyperlinkPool, StylePool, setCellStyleId, } from './screen.js';
+// Shared across calls. Pools accumulate style/char interns — reusing them
+// means later calls hit cache more. Root/container reuse saves the
+// createContainer cost (~1ms). LegacyRoot: all work sync, no scheduling —
+// ConcurrentRoot's scheduler backlog leaks across roots via flushSyncWork.
+let root;
+let container;
+let stylePool;
+let charPool;
+let hyperlinkPool;
+let output;
+const timing = { reconcile: 0, yoga: 0, paint: 0, scan: 0, calls: 0 };
+const LOG_EVERY = 20;
+/** Render a React element (wrapped in all contexts the component needs —
+ *  caller's job) to an isolated Screen buffer at the given width. Returns
+ *  the Screen + natural height (from yoga). Used for search: render ONE
+ *  message, scan its Screen for the query, get exact (row, col) positions.
+ *
+ *  ~1-3ms per call (yoga alloc + calculateLayout + paint). The
+ *  flushSyncWork cross-root leak measured ~0.0003ms/call growth — fine
+ *  for on-demand single-message rendering, pathological for render-all-
+ *  8k-upfront. Cache per (msg, query, width) upstream.
+ *
+ *  Unmounts between calls. Root/container/pools persist for reuse.
+ *
+ * @param el - the React element to render.
+ * @param width - the render width in columns.
+ * @returns the painted screen buffer and the yoga-computed content height.
+ */
+export function renderToScreen(el, width) {
+    if (!root) {
+        root = createNode('ink-root');
+        root.focusManager = new FocusManager(() => false);
+        stylePool = new StylePool();
+        charPool = new CharPool();
+        hyperlinkPool = new HyperlinkPool();
+        // @ts-ignore -- runtime/type-definition mismatch: react-reconciler 0.33 takes 10 args; @types says 11
+        container = reconciler.createContainer(root, LegacyRoot, null, false, null, 'search-render', noop, noop, noop, noop);
+    }
+    const t0 = performance.now();
+    // @ts-ignore -- runtime/type-definition mismatch: updateContainerSync exists but not in @types
+    reconciler.updateContainerSync(el, container, null, noop);
+    // @ts-ignore -- runtime/type-definition mismatch: flushSyncWork exists but not in @types
+    reconciler.flushSyncWork();
+    const t1 = performance.now();
+    // Yoga layout. Root might not have a yogaNode if the tree is empty.
+    root.yogaNode?.setWidth(width);
+    root.yogaNode?.calculateLayout(width);
+    const height = Math.ceil(root.yogaNode?.getComputedHeight() ?? 0);
+    const t2 = performance.now();
+    // Paint to a fresh Screen. Width = given, height = yoga's natural.
+    // No alt-screen, no prevScreen (every call is fresh).
+    const screen = createScreen(width, Math.max(1, height), // avoid 0-height Screen (createScreen may choke)
+    stylePool, charPool, hyperlinkPool);
+    if (!output) {
+        output = new Output({ width, height, stylePool: stylePool, screen });
+    }
+    else {
+        output.reset(width, height, screen);
+    }
+    resetLayoutShifted();
+    renderNodeToOutput(root, output, { prevScreen: undefined });
+    // renderNodeToOutput queues writes into Output; .get() flushes the
+    // queue into the Screen's cell arrays. Without this the screen is
+    // blank (constructor-zero).
+    const rendered = output.get();
+    const t3 = performance.now();
+    // Unmount so next call gets a fresh tree. Leaves root/container/pools.
+    // @ts-ignore -- runtime/type-definition mismatch: updateContainerSync exists but not in @types
+    reconciler.updateContainerSync(null, container, null, noop);
+    // @ts-ignore -- runtime/type-definition mismatch: flushSyncWork exists but not in @types
+    reconciler.flushSyncWork();
+    timing.reconcile += t1 - t0;
+    timing.yoga += t2 - t1;
+    timing.paint += t3 - t2;
+    if (++timing.calls % LOG_EVERY === 0) {
+        const total = timing.reconcile + timing.yoga + timing.paint + timing.scan;
+        logForDebugging(`renderToScreen: ${timing.calls} calls · ` +
+            `reconcile=${timing.reconcile.toFixed(1)}ms yoga=${timing.yoga.toFixed(1)}ms ` +
+            `paint=${timing.paint.toFixed(1)}ms scan=${timing.scan.toFixed(1)}ms · ` +
+            `total=${total.toFixed(1)}ms · avg ${(total / timing.calls).toFixed(2)}ms/call`);
+    }
+    return { screen: rendered, height };
+}
+/** Scan a Screen buffer for all occurrences of query. Returns positions
+ *  relative to the buffer (row 0 = buffer top). Same cell-skip logic as
+ *  applySearchHighlight (SpacerTail/SpacerHead/noSelect) so positions
+ *  match what the overlay highlight would find. Case-insensitive.
+ *
+ *  For the side-render use: this Screen is the FULL message (natural
+ *  height, not viewport-clipped). Positions are stable — to highlight
+ *  on the real screen, add the message's screen offset (lo).
+ *
+ * @param screen - the screen buffer to scan.
+ * @param query - the substring to search for, matched case-insensitively.
+ * @returns the match positions relative to the buffer, or an empty list.
+ */
+export function scanPositions(screen, query) {
+    const lq = query.toLowerCase();
+    if (!lq)
+        return [];
+    const qlen = lq.length;
+    const w = screen.width;
+    const h = screen.height;
+    const noSelect = screen.noSelect;
+    const positions = [];
+    const t0 = performance.now();
+    for (let row = 0; row < h; row++) {
+        const rowOff = row * w;
+        // Same text-build as applySearchHighlight. Keep in sync — or extract
+        // to a shared helper (TODO once both are stable). codeUnitToCell
+        // maps indexOf positions (code units in the LOWERCASED text) to cell
+        // indices in colOf — surrogate pairs (emoji) and multi-unit lowercase
+        // (Turkish İ → i + U+0307) make text.length > colOf.length.
+        let text = '';
+        const colOf = [];
+        const codeUnitToCell = [];
+        for (let col = 0; col < w; col++) {
+            const idx = rowOff + col;
+            const cell = cellAtIndex(screen, idx);
+            if (cell.width === 2 /* CellWidth.SpacerTail */ ||
+                cell.width === 3 /* CellWidth.SpacerHead */ ||
+                noSelect[idx] === 1) {
+                continue;
+            }
+            const lc = cell.char.toLowerCase();
+            const cellIdx = colOf.length;
+            for (let i = 0; i < lc.length; i++) {
+                codeUnitToCell.push(cellIdx);
+            }
+            text += lc;
+            colOf.push(col);
+        }
+        // Non-overlapping — same advance as applySearchHighlight.
+        let pos = text.indexOf(lq);
+        while (pos >= 0) {
+            const startCi = codeUnitToCell[pos];
+            const endCi = codeUnitToCell[pos + qlen - 1];
+            const col = colOf[startCi];
+            const endCol = colOf[endCi] + 1;
+            positions.push({ row, col, len: endCol - col });
+            pos = text.indexOf(lq, pos + qlen);
+        }
+    }
+    timing.scan += performance.now() - t0;
+    return positions;
+}
+/** Write CURRENT (yellow+bold+underline) at positions[currentIdx] +
+ *  rowOffset. OTHER positions are NOT styled here — the scan-highlight
+ *  (applySearchHighlight with null hint) does inverse for all visible
+ *  matches, including these. Two-layer: scan = 'you could go here',
+ *  position = 'you ARE here'. Writing inverse again here would be a
+ *  no-op (withInverse idempotent) but wasted work.
+ *
+ *  Positions are message-relative (row 0 = message top). rowOffset =
+ *  message's current screen-top (lo). Clips outside [0, height).
+ *
+ * @param screen - the screen buffer to style.
+ * @param stylePool - the style pool providing the current-match transform.
+ * @param positions - the message-relative match positions.
+ * @param rowOffset - the message's current screen-top row.
+ * @param currentIdx - index into positions of the match to highlight.
+ * @returns true when the highlight was written, false when out of range.
+ */
+export function applyPositionedHighlight(screen, stylePool, positions, rowOffset, currentIdx) {
+    if (currentIdx < 0 || currentIdx >= positions.length)
+        return false;
+    const p = positions[currentIdx];
+    const row = p.row + rowOffset;
+    if (row < 0 || row >= screen.height)
+        return false;
+    const transform = (id) => stylePool.withCurrentMatch(id);
+    const rowOff = row * screen.width;
+    for (let col = p.col; col < p.col + p.len; col++) {
+        if (col < 0 || col >= screen.width)
+            continue;
+        const cell = cellAtIndex(screen, rowOff + col);
+        setCellStyleId(screen, col, row, transform(cell.styleId));
+    }
+    return true;
+}

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

@@ -0,0 +1,34 @@
+import { type DOMElement } from './dom.js';
+import type { Frame } from './frame.js';
+import type { TerminalImagePlacement } from './terminal-image.js';
+import { type StylePool } from './screen.js';
+/** Options controlling one renderer pass over the DOM tree. */
+export type RenderOptions = {
+    frontFrame: Frame;
+    backFrame: Frame;
+    isTTY: boolean;
+    terminalWidth: number;
+    terminalRows: number;
+    altScreen: boolean;
+    /** Whether terminal graphics are active for this paint pass. */
+    terminalImages?: boolean;
+    imageReady?: (placement: TerminalImagePlacement) => boolean;
+    /**
+     * True when rasters paint over the cell grid (Sixel): image-owned cells
+     * carry the surface background instead of terminal-default blanks. See
+     * Output's `opaqueImageBacking`.
+     */
+    opaqueImageBacking?: boolean;
+    prevFrameContaminated: boolean;
+};
+/** Renders the DOM tree into a frame for the given options. */
+export type Renderer = (options: RenderOptions) => Frame;
+/**
+ * Create the renderer function for a root DOM node. The returned renderer
+ * reuses an Output across frames so its character cache persists.
+ * @param node - the root DOM node to render.
+ * @param stylePool - the style pool used for all frames.
+ * @returns a function that renders one frame from the given options.
+ */
+export default function createRenderer(node: DOMElement, stylePool: StylePool): Renderer;
+//# sourceMappingURL=renderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/ink/renderer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAiC,MAAM,UAAU,CAAA;AACzE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAIvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAUjE,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAE1D,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,KAAK,CAAA;IACjB,SAAS,EAAE,KAAK,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,sBAAsB,KAAK,OAAO,CAAA;IAC3D;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAK5B,qBAAqB,EAAE,OAAO,CAAA;CAC/B,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,KAAK,CAAA;AAExD;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,SAAS,GACnB,QAAQ,CAqMV"}

package/lib/types/ink/renderer.js

@@ -0,0 +1,181 @@
+import { logForDebugging } from '../utils/debug.js';
+import { markDirty, scheduleRenderFrom } from './dom.js';
+import { invalidateNoInterestRect } from './hit-test.js';
+import { consumeAbsoluteRemovedFlag } from './node-cache.js';
+import Output from './output.js';
+import renderNodeToOutput, { getOcclusionMismatchNodes, getScrollDrainNode, getScrollHint, hasOverlayVacatedCells, resetLayoutShifted, resetScrollDrainNode, resetScrollHint, } from './render-node-to-output.js';
+import { createScreen } from './screen.js';
+/**
+ * Create the renderer function for a root DOM node. The returned renderer
+ * reuses an Output across frames so its character cache persists.
+ * @param node - the root DOM node to render.
+ * @param stylePool - the style pool used for all frames.
+ * @returns a function that renders one frame from the given options.
+ */
+export default function createRenderer(node, stylePool) {
+    // Reuse Output across frames so charCache (tokenize + grapheme clustering)
+    // persists — most lines don't change between renders.
+    let output;
+    return options => {
+        const { frontFrame, backFrame, isTTY, terminalWidth, terminalRows } = options;
+        // The no-interest hover rect (hit-test.ts) is strictly per-frame: drop
+        // it at the top of EVERY render pass so scroll drains, blits and any
+        // other geometry change without a React commit re-arm the hit-test.
+        // Placed before the invalid-dimension early return below so even
+        // empty frames cannot serve a stale rect.
+        invalidateNoInterestRect();
+        const prevScreen = frontFrame.screen;
+        const backScreen = backFrame.screen;
+        // Read pools from the back buffer's screen — pools may be replaced
+        // between frames (generational reset), so we can't capture them in the closure
+        const charPool = backScreen.charPool;
+        const hyperlinkPool = backScreen.hyperlinkPool;
+        // Return empty frame if yoga node doesn't exist or layout hasn't been computed yet.
+        // getComputedHeight() returns NaN before calculateLayout() is called.
+        // Also check for invalid dimensions (negative, Infinity) that would cause RangeError
+        // when creating arrays.
+        const computedHeight = node.yogaNode?.getComputedHeight();
+        const computedWidth = node.yogaNode?.getComputedWidth();
+        const hasInvalidHeight = computedHeight === undefined ||
+            !Number.isFinite(computedHeight) ||
+            computedHeight < 0;
+        const hasInvalidWidth = computedWidth === undefined ||
+            !Number.isFinite(computedWidth) ||
+            computedWidth < 0;
+        if (!node.yogaNode || hasInvalidHeight || hasInvalidWidth) {
+            // Log to help diagnose root cause (visible with --debug flag)
+            if (node.yogaNode && (hasInvalidHeight || hasInvalidWidth)) {
+                logForDebugging(`Invalid yoga dimensions: width=${computedWidth}, height=${computedHeight}, ` +
+                    `childNodes=${node.childNodes.length}, terminalWidth=${terminalWidth}, terminalRows=${terminalRows}`);
+            }
+            return {
+                screen: createScreen(terminalWidth, 0, stylePool, charPool, hyperlinkPool),
+                viewport: { width: terminalWidth, height: terminalRows },
+                cursor: { x: 0, y: 0, visible: true },
+            };
+        }
+        const width = Math.floor(node.yogaNode.getComputedWidth());
+        const yogaHeight = Math.floor(node.yogaNode.getComputedHeight());
+        // Alt-screen: the screen buffer IS the alt buffer — always exactly
+        // terminalRows tall. <AlternateScreen> wraps children in <Box
+        // height={rows} flexShrink={0}>, so yogaHeight should equal
+        // terminalRows. But if something renders as a SIBLING of that Box
+        // (bug: MessageSelector was outside <FullscreenLayout>), yogaHeight
+        // exceeds rows and every assumption below (viewport +1 hack, cursor.y
+        // clamp, log-update's heightDelta===0 fast path) breaks, desyncing
+        // virtual/physical cursors. Clamping here enforces the invariant:
+        // overflow writes land at y >= screen.height and setCellAt drops
+        // them. The sibling is invisible (obvious, easy to find) instead of
+        // corrupting the whole terminal.
+        const height = options.altScreen ? terminalRows : yogaHeight;
+        if (options.altScreen && yogaHeight > terminalRows) {
+            logForDebugging(`alt-screen: yoga height ${yogaHeight} > terminalRows ${terminalRows} — ` +
+                `something is rendering outside <AlternateScreen>. Overflow clipped.`, { level: 'warn' });
+        }
+        const screen = backScreen ??
+            createScreen(width, height, stylePool, charPool, hyperlinkPool);
+        if (output) {
+            output.reset(width, height, screen, options.terminalImages, frontFrame.images, options.imageReady, options.opaqueImageBacking ?? false);
+        }
+        else {
+            output = new Output({
+                width,
+                height,
+                stylePool,
+                screen,
+                terminalImages: options.terminalImages,
+                previousImages: frontFrame.images,
+                imageReady: options.imageReady,
+                opaqueImageBacking: options.opaqueImageBacking ?? false,
+            });
+        }
+        resetLayoutShifted();
+        resetScrollHint();
+        resetScrollDrainNode();
+        // prevFrameContaminated: selection overlay mutated the returned screen
+        // buffer post-render (in ink.tsx), resetFramesForAltScreen() replaced it
+        // with blanks, or forceRedraw() reset it to 0×0. Blit on the NEXT frame
+        // would copy stale inverted cells / blanks / nothing. When clean, blit
+        // restores the O(unchanged) fast path for steady-state frames (spinner
+        // tick, text stream).
+        // Removing an absolute-positioned node poisons prevScreen: it may
+        // have painted over non-siblings (e.g. an overlay over a ScrollBox
+        // earlier in tree order), so their blits would restore the removed
+        // node's pixels. hasRemovedChild only shields direct siblings.
+        // Normal-flow removals don't paint cross-subtree and are fine.
+        const absoluteRemoved = consumeAbsoluteRemovedFlag();
+        renderNodeToOutput(node, output, {
+            prevScreen: absoluteRemoved || options.prevFrameContaminated
+                ? undefined
+                : prevScreen,
+        });
+        const renderedScreen = output.get();
+        // An absolute overlay shrank/moved this frame: its vacated cells were
+        // blitted from prevScreen (stale overlay pixels) because the underlying
+        // clean subtree never re-rendered. Flag the NEXT frame as contaminated
+        // so it renders without prevScreen and re-derives those cells from the
+        // tree (see hasOverlayVacatedCells). The current frame's diff is a
+        // no-op at those cells (output == prevScreen there), so nothing stale
+        // reaches the terminal; the poisoned frame writes the correction.
+        const overlayVacated = hasOverlayVacatedCells();
+        // Drain continuation: render cleared scrollbox.dirty, so next frame's
+        // root blit would skip the subtree. markDirty walks ancestors so the
+        // next frame descends. Done AFTER render so the clear-dirty at the end
+        // of renderNodeToOutput doesn't overwrite this.
+        const drainNode = getScrollDrainNode();
+        if (drainNode)
+            markDirty(drainNode);
+        // Occlusion surfaces (occlusionColor) whose recorded cover decision is
+        // stale against this frame's image placements — the surface painted
+        // before a later-in-order image registered, or a clean-subtree blit
+        // skipped it while an image behind appeared, moved, or was removed.
+        // Re-walk the surface and schedule the frame now: the cover must follow
+        // image changes even when no React commit is pending (see
+        // getOcclusionMismatchNodes).
+        const occlusionStale = getOcclusionMismatchNodes(output);
+        for (const surface of occlusionStale)
+            markDirty(surface);
+        if (occlusionStale.length > 0)
+            scheduleRenderFrom(occlusionStale[0]);
+        return {
+            // An invalid previous frame is unsafe for both blit and hardware
+            // scroll: DECSTBM would shift selection-overlay cells or pixels from
+            // an absolute node that was just removed.
+            scrollHint: options.altScreen &&
+                !absoluteRemoved &&
+                !options.prevFrameContaminated
+                ? getScrollHint()
+                : null,
+            scrollDrainPending: drainNode !== null,
+            poisonNextFrame: overlayVacated,
+            images: output.getImages(),
+            screen: renderedScreen,
+            viewport: {
+                width: terminalWidth,
+                // Alt screen: fake viewport.height = rows + 1 so that
+                // shouldClearScreen()'s `screen.height >= viewport.height` check
+                // (which treats exactly-filling content as "overflows" for
+                // scrollback purposes) never fires. Alt-screen content is always
+                // exactly `rows` tall (via <Box height={rows}>) but never
+                // scrolls — the cursor.y clamp below keeps the cursor-restore
+                // from emitting an LF. With the standard diff path, every frame
+                // is incremental; no fullResetSequence_CAUSES_FLICKER.
+                height: options.altScreen ? terminalRows + 1 : terminalRows,
+            },
+            cursor: {
+                x: 0,
+                // In the alt screen, keep the cursor inside the viewport. When
+                // screen.height === terminalRows exactly (content fills the alt
+                // screen), cursor.y = screen.height would trigger log-update's
+                // cursor-restore LF at the last row, scrolling one row off the top
+                // of the alt buffer and desyncing the diff's cursor model. The
+                // cursor is hidden so its position only matters for diff coords.
+                y: options.altScreen
+                    ? Math.max(0, Math.min(screen.height, terminalRows) - 1)
+                    : screen.height,
+                // Hide cursor when there's dynamic output to render (only in TTY mode)
+                visible: !isTTY || screen.height === 0,
+            },
+        };
+    };
+}

package/lib/types/ink/root.d.ts

@@ -0,0 +1,109 @@
+import type { ReactNode } from 'react';
+import type { FrameEvent } from './frame.js';
+import Ink from './ink.js';
+/** Options for mounting an Ink app. */
+export type RenderOptions = {
+    /**
+     * Output stream where app will be rendered.
+     *
+     * @default process.stdout
+     */
+    stdout?: NodeJS.WriteStream;
+    /**
+     * Input stream where app will listen for input.
+     *
+     * @default process.stdin
+     */
+    stdin?: NodeJS.ReadStream;
+    /**
+     * Error stream.
+     * @default process.stderr
+     */
+    stderr?: NodeJS.WriteStream;
+    /**
+     * Configure whether Ink should listen to Ctrl+C keyboard input and exit the app. This is needed in case `process.stdin` is in raw mode, because then Ctrl+C is ignored by default and process is expected to handle it manually.
+     *
+     * @default true
+     */
+    exitOnCtrlC?: boolean;
+    /**
+     * Patch console methods to ensure console output doesn't mix with Ink output.
+     *
+     * @default true
+     */
+    patchConsole?: boolean;
+    /** Allow image probing and rendering. Fixed for this root's lifetime; defaults to true. */
+    terminalImages?: boolean;
+    /**
+     * Called after each frame render with timing and flicker information.
+     */
+    onFrame?: (event: FrameEvent) => void;
+};
+/**
+ * The handle returned by renderSync for an actively rendering Ink app.
+ */
+export type Instance = {
+    /**
+     * Replace previous root node with a new one or update props of the current root node.
+     */
+    rerender: Ink['render'];
+    /**
+     * Manually unmount the whole Ink app.
+     */
+    unmount: Ink['unmount'];
+    /**
+     * Returns a promise, which resolves when app is unmounted.
+     */
+    waitUntilExit: Ink['waitUntilExit'];
+    /**
+     * Detach the Ink runtime for process-level shutdown: latches isUnmounted
+     * (gating every mouse/alt-screen re-assert), cancels pending renders,
+     * releases TTY handlers and stdin raw mode, and disposes the querier.
+     * Exposed on the handle so shutdown code can latch the runtime even when
+     * the global instances map lookup misses (stdout identity drift, issue
+     * #522) — without it, the cleanup-vs-self-heal window re-enables mouse
+     * tracking after DISABLE_MOUSE_TRACKING has already been written.
+     */
+    detachForShutdown: Ink['detachForShutdown'];
+    /**
+     * Fully detach stdin before handing the terminal to a child process that
+     * inherits it (the /update and /restart handoffs). See Ink's own method
+     * for the listener/pump semantics.
+     */
+    detachStdinForHandoff: Ink['detachStdinForHandoff'];
+    cleanup: () => void;
+};
+/**
+ * A managed Ink root, similar to react-dom's createRoot API.
+ * Separates instance creation from rendering so the same root
+ * can be reused for multiple sequential screens.
+ */
+export type Root = {
+    render: (node: ReactNode) => void;
+    unmount: () => void;
+    waitUntilExit: () => Promise<void>;
+};
+/**
+ * Mount a component and render the output.
+ * @param node - the React element to render.
+ * @param options - the output stream or render options.
+ * @returns an instance handle for the running app.
+ */
+export declare const renderSync: (node: ReactNode, options?: NodeJS.WriteStream | RenderOptions) => Instance;
+/**
+ * Asynchronous render entry point that preserves a microtask boundary
+ * before the first synchronous render, letting async startup work settle.
+ * @param node - the React element to render.
+ * @param options - the output stream or render options.
+ * @returns a promise resolving to the instance handle once mounted.
+ */
+declare const wrappedRender: (node: ReactNode, options?: NodeJS.WriteStream | RenderOptions) => Promise<Instance>;
+export default wrappedRender;
+/**
+ * Create an Ink root without rendering anything yet.
+ * Like react-dom's createRoot — call root.render() to mount a tree.
+ * @param options - the render options; defaults match renderSync defaults.
+ * @returns a promise resolving to the managed root.
+ */
+export declare function createRoot(options?: RenderOptions): Promise<Root>;
+//# sourceMappingURL=root.d.ts.map

package/lib/types/ink/root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../../../src/ink/root.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,GAAmC,MAAM,UAAU,CAAA;AAG1D,uCAAuC;AACvC,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAA;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAA;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IAEtB,2FAA2F;IAC3F,cAAc,CAAC,EAAE,OAAO,CAAA;IAExB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;CACtC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB;;OAEG;IACH,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAA;IACvB;;OAEG;IACH,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,CAAA;IACvB;;OAEG;IACH,aAAa,EAAE,GAAG,CAAC,eAAe,CAAC,CAAA;IACnC;;;;;;;;OAQG;IACH,iBAAiB,EAAE,GAAG,CAAC,mBAAmB,CAAC,CAAA;IAC3C;;;;OAIG;IACH,qBAAqB,EAAE,GAAG,CAAC,uBAAuB,CAAC,CAAA;IACnD,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB,MAAM,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;IACjC,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,SAAS,EACf,UAAU,MAAM,CAAC,WAAW,GAAG,aAAa,KAC3C,QA4BF,CAAA;AAED;;;;;;GAMG;AACH,QAAA,MAAM,aAAa,GACjB,MAAM,SAAS,EACf,UAAU,MAAM,CAAC,WAAW,GAAG,aAAa,KAC3C,OAAO,CAAC,QAAQ,CAWlB,CAAA;AAED,eAAe,aAAa,CAAA;AAE5B;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA+Bf"}