@oh-my-pi/pi-tui 17.4.2 → 18.0.1

package/dist/types/tui.d.ts

@@ -18,9 +18,39 @@ export interface RenderScheduler {
 export interface TUIOptions {
     renderScheduler?: RenderScheduler;
 }
+/** Physical terminal dimensions supplied to a frame provider. */
+export interface ViewportSize {
+    readonly columns: number;
+    readonly rows: number;
+}
+/** Immutable finalized rows offered until the terminal accepts this identifier. */
+export interface HistoryBatch {
+    readonly id: number;
+    readonly rows: readonly string[];
+}
+/** One history append and the complete mutable viewport for a terminal frame. */
+export interface TerminalFramePlan {
+    readonly history?: HistoryBatch;
+    readonly viewport: readonly string[];
+}
+/** Produces bounded terminal frames and retires acknowledged history batches. */
+export interface TerminalFrameProvider {
+    renderFrame(viewport: ViewportSize): TerminalFramePlan;
+    acknowledgeHistory(id: number): void;
+    /** Full semantic viewport used only on the transient resize buffer. */
+    renderResizeFrame?(viewport: ViewportSize): readonly string[];
+    /** Re-offer finalized history after a display reset or resize replay. */
+    resetHistory?(): void;
+}
 export interface TUIStartOptions {
     /** Clear saved native scrollback before the first paint. */
     clearScrollback?: boolean;
+    /**
+     * Paint without owning stdin: the terminal stays in cooked mode (kernel
+     * echo + line editing at the hardware cursor) until {@link TUI.enableInput}
+     * switches to raw input and replays the kernel-buffered keystrokes.
+     */
+    deferInput?: boolean;
 }
 /**
  * Component interface - all components must implement this
@@ -75,109 +105,6 @@ export interface OverlayFocusOwner {
     /** Returns true when `component` is a focus target inside this overlay. */
     ownsOverlayFocusTarget(component: Component): boolean;
 }
-/**
- * Component seam for append-only native-scrollback commits. A component whose
- * rendered rows can still change reports, after each render, the local line
- * index where that mutable suffix begins. Rows above the boundary are declared
- * FINAL — byte-stable at the current width for the component's lifetime — and
- * commit to native scrollback as exact, audited content. Rows at/after the
- * boundary repaint in place inside the visible window; when they scroll above
- * the window top they normally commit as frozen visual snapshots.
- *
- * A viewport-pinned region opts out of those mutable snapshot commits. Its
- * offscreen mutable rows are virtually clipped until the boundary advances;
- * use this for fixed-height dashboards whose frames replace each other rather
- * than append. A root that reports no seam commits everything that scrolls as
- * final (shell semantics).
- *
- * When several root children report a seam in the same frame, the topmost one
- * defines the boundary and pinning policy: commits are prefix-only, so
- * everything below the first seam is already excluded.
- */
-export interface NativeScrollbackLiveRegion {
-    getNativeScrollbackLiveRegionStart(): number | undefined;
-    /** Keeps the mutable suffix viewport-local instead of recording frozen snapshots. */
-    isNativeScrollbackLiveRegionPinned?(): boolean;
-    /**
-     * Local row where viewport pinning begins. When omitted, pinning (if
-     * reported) starts at {@link getNativeScrollbackLiveRegionStart}. A nested
-     * transcript uses this to keep an earlier unpinned live seam while still
-     * capping commits at a later pinned dashboard (hub wait, todo snapshot).
-     */
-    getNativeScrollbackLiveRegionPinnedStart?(): number | undefined;
-}
-export interface NativeScrollbackCommittedRows {
-    setNativeScrollbackCommittedRows(rows: number): void;
-}
-/**
- * Width-independent source boundary for multiplexer resize epochs. Capture
- * reads the last rendered source state; resolve maps that same logical boundary
- * into the most recent render's physical rows at its new width. The current
- * boundary identifies the source tail after updates queued during the resize.
- */
-export interface NativeScrollbackWidthEpoch {
-    captureNativeScrollbackWidthEpoch(): unknown;
-    resolveNativeScrollbackWidthEpoch(boundary: unknown): number | undefined;
-    getNativeScrollbackWidthEpochRows(): number | undefined;
-    /** False when updates can insert before captured trailing rows. */
-    isNativeScrollbackWidthEpochAppendOnly?(boundary: unknown): boolean;
-    /** Changes when child structure mutates independently of width reflow. */
-    getNativeScrollbackWidthEpochRevision?(): number;
-}
-/**
- * A component that discards rows after they enter native scrollback implements
- * this hook so a destructive full replay can rehydrate its complete frame.
- */
-export interface NativeScrollbackReplay {
-    prepareNativeScrollbackReplay(): void;
-}
-/**
- * Opt-in stability report for components that mutate their returned render
- * array in place across frames (instead of returning a fresh array per
- * change). The engine reads it right after the component's `render()` returns:
- * the report counts the leading rows of the just-returned array that are
- * byte-identical to the array state the reader last observed. The engine uses
- * it to reuse the composed frame's prefix — skipping marker extraction, line
- * preparation, and the committed-prefix audit for those rows.
- *
- * Contract:
- * - Reading CONSUMES the report: it re-bases the baseline to the current
- *   array state. The accumulated count therefore covers every render since
- *   the previous read, so out-of-band `render()` calls between engine frames
- *   (an exporter walking the tree) can only lower the report, never inflate
- *   it past what the engine actually has.
- * - An implementer that cannot prove stability for a frame must lower the
- *   accumulated count to 0 for that render.
- * - Rows at or beyond the report may have been mutated in place; rows before
- *   it must be the identical string values at the identical indices.
- */
-export interface RenderStablePrefix {
-    getRenderStablePrefixRows(): number;
-}
-/**
- * Opt-in fast path for composing only the visible tail of a tall component
- * during a terminal resize. A drag emits a SIGWINCH burst, and the width
- * changes on every event: a full compose re-lays-out (and, for markdown,
- * re-lexes) the entire transcript per event — O(history) work that is
- * discarded the instant the next event arrives. While the resize is in flight
- * the engine paints only the viewport, so it asks each tall root child for at
- * most `maxRows` rows from the bottom of its render at `width` and skips
- * composing everything above the fold. The authoritative full paint replays
- * once the drag settles (see {@link TUI} resize handling).
- *
- * Contract:
- * - Returns the BOTTOM rows of the component's full render at `width`, in
- *   top-to-bottom order, capped at `maxRows` (fewer when the component is
- *   shorter). The rows MUST be byte-identical to the corresponding tail of
- *   what `render(width)` would have returned, modulo a one-row separator at
- *   the very top edge (a transient frame the settle paint overwrites).
- * - MUST NOT mutate any persistent full-compose state: the next `render()`
- *   (the settle paint) has to reconcile exactly as if the tail render never
- *   happened. Warming pure per-width render caches is fine and desirable.
- */
-export interface ViewportTailProvider {
-    renderViewportTail(width: number, maxRows: number): readonly string[];
-}
 /**
  * Interface for components that can receive focus and display a cursor.
  * When focused, the component should emit CURSOR_MARKER at the cursor position
@@ -200,6 +127,13 @@ export interface RenderRequestOptions {
     /** Clear terminal scrollback for intentional transcript replacement. */
     clearScrollback?: boolean;
 }
+/**
+ * Controls how a settled terminal resize refreshes native history.
+ *
+ * `append` replays the current transcript below retained history, `rebuild`
+ * clears history before replaying it, and `preserve` repaints only the viewport.
+ */
+export type ResizeScrollbackMode = "append" | "rebuild" | "preserve";
 /** Type guard to check if a component implements Focusable */
 export declare function isFocusable(component: Component | null): component is Component & Focusable;
 /**
@@ -283,7 +217,7 @@ export interface OverlayHandle {
 /**
  * Container - a component that contains other components
  */
-export declare class Container implements Component, NativeScrollbackCommittedRows, NativeScrollbackReplay, NativeScrollbackWidthEpoch {
+export declare class Container implements Component {
     #private;
     children: Component[];
     setIgnoreTight(ignore: boolean): this;
@@ -299,21 +233,6 @@ export declare class Container implements Component, NativeScrollbackCommittedRo
      * {@link clear} for that). Idempotent per child via each child's own dispose.
      */
     dispose(): void;
-    /**
-     * Split the committed prefix from the container's most recently rendered
-     * rows across its children. The memoized child arrays are the exact geometry
-     * that produced that frame; when the child list was invalidated or rebuilt,
-     * there is no safe old-to-new coordinate mapping, so propagation waits for
-     * the next render/post-emit publication.
-     */
-    setNativeScrollbackCommittedRows(rows: number): void;
-    /** Recursively discard layout locks that are meaningful only to the old tape. */
-    prepareNativeScrollbackReplay(): void;
-    captureNativeScrollbackWidthEpoch(): unknown;
-    resolveNativeScrollbackWidthEpoch(boundary: unknown): number | undefined;
-    getNativeScrollbackWidthEpochRows(): number | undefined;
-    isNativeScrollbackWidthEpochAppendOnly(boundary: unknown): boolean;
-    getNativeScrollbackWidthEpochRevision(): number;
     render(width: number): readonly string[];
 }
 /**
@@ -323,41 +242,6 @@ export declare class Container implements Component, NativeScrollbackCommittedRo
  * merges, so SGR-light lines incur only a single `indexOf` scan.
  */
 export declare function coalesceAdjacentSgr(line: string): string;
-/**
- * Decide whether `frame` still aligns with the committed prefix, and where to
- * re-anchor the commit index when it does not. Returns the resync row index,
- * or -1 when no resync is needed.
- *
- * Zones (verifiedTo ≤ finalTo ≤ prefix.length):
- *   [0, verifiedTo)         VERIFIED exact rows — sampled with tolerance.
- *   [verifiedTo, finalTo)   NEWLY-FINAL rows — frozen visual snapshots whose
- *       source just became declared-final (the block finalized / a barrier
- *       cleared). Hard-scanned in FULL with no tolerance: any content change
- *       (a pending header settling, a preview replaced by its result, a tail
- *       shifting up after a barrier removal) re-anchors so the engine can
- *       erase-and-replay history with the final content exactly once (or, on
- *       ED3-unsafe multiplexers, recommit it below the frozen snapshot —
- *       duplication, never loss) instead of committing it nowhere and
- *       painting it nowhere.
- *   [finalTo, prefix.length) FROZEN visual snapshots of still-live rows —
- *       exempt: their drift is expected (a collapsing preview, a ticking
- *       progress tree) and must never spray re-anchors mid-run.
- *
- * The verified zone's sampled check exploits the asymmetry between the two
- * mutation classes: an in-place edit/restyle disturbs only the touched rows
- * (alignment below stays intact; the stale copy in history is the accepted
- * artifact), while an insertion/deletion shifts EVERY row below it. Up to 8
- * non-blank rows within the last 24 verified rows are compared SGR-stripped
- * (theme changes stay quiet), tolerating a SINGLE mismatch. The tolerance is
- * load-bearing for roots that report NO seam: an animated row already in
- * history would otherwise re-anchor on every glyph tick.
- *
- * Highly repetitive tails (identical filler rows) can mask a shift in the tail
- * sample, in which case the skipped rows are content-identical to the committed
- * ones — observationally harmless. Exported for the render-stress harness, whose
- * shadow commit ledger must mirror the engine's law exactly.
- */
-export declare function findCommittedPrefixResync(frame: readonly string[], prefix: readonly string[], verifiedTo?: number, finalTo?: number): number;
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -373,19 +257,9 @@ export declare class TUI extends Container {
         hidden: boolean;
     }[];
     constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: TUIOptions);
-    captureNativeScrollbackWidthEpoch(): unknown;
-    resolveNativeScrollbackWidthEpoch(boundary: unknown): number | undefined;
-    getNativeScrollbackWidthEpochRows(): number | undefined;
-    render(width: number): readonly string[];
+    /** Install the product-owned bounded frame provider. */
+    setFrameProvider(provider: TerminalFrameProvider | undefined): void;
     get fullRedraws(): number;
-    /**
-     * Transient viewport-only paints emitted by the non-multiplexer resize fast
-     * path. These never touch native scrollback or the commit ledger, so they
-     * are counted apart from {@link fullRedraws}.
-     */
-    get resizeViewportPaints(): number;
-    /** Whether a non-multiplexer resize drag is currently in flight. */
-    get resizeViewportActive(): boolean;
     /** Shared budget that caps how many inline images render as live graphics. */
     get imageBudget(): ImageBudget;
     /**
@@ -394,19 +268,12 @@ export declare class TUI extends Container {
      * plus a full redraw on the frame after a new image exceeds the cap.
      */
     setMaxInlineImages(cap: number): void;
+    /** Return how settled resizes refresh native scrollback. */
+    getResizeScrollback(): ResizeScrollbackMode;
+    /** Set how settled resizes refresh native scrollback. */
+    setResizeScrollback(mode: ResizeScrollbackMode): void;
     /** Delete every tracked Kitty image from the terminal graphics store. */
     clearInlineImages(): void;
-    /**
-     * Get whether scrollback divergence rebuild is enabled.
-     */
-    getScrollbackRebuild(): boolean;
-    /**
-     * Enable or disable scrollback divergence rebuild (default off).
-     * When enabled, the engine will erase and replay the terminal's
-     * scrollback (using ED3 / alt buffer / scrollback replay) to avoid
-     * duplicate blocks when a block's final form replaces its live preview.
-     */
-    setScrollbackRebuild(enabled: boolean): void;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
     /**
@@ -430,58 +297,36 @@ export declare class TUI extends Container {
     hasOverlay(): boolean;
     invalidate(): void;
     start(options?: TUIStartOptions): void;
+    /**
+     * Take ownership of stdin after a `deferInput` start: raw mode, input
+     * handlers, and the response-eliciting capability probes start() skipped.
+     * Keystrokes typed in cooked mode meanwhile arrive through the normal input
+     * path. Idempotent; no-op when input was never deferred.
+     */
+    enableInput(): void;
     addStartListener(listener: StartListener): () => void;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
     stop(): void;
     /**
-     * Force an immediate full replay of the current frame, including native
-     * scrollback. This is the keyboard-accessible equivalent of the resize reset:
-     * no queued diff frame or terminal scrollback probe can downgrade it to a
-     * viewport-only repaint.
-     *
-     * Invalidates every component first so the replay reflects current state. A
-     * geometry-driven reset thaws frozen scrollback snapshots implicitly (the new
-     * width misses every cached snapshot), but a same-width reset would otherwise
-     * replay stale snapshots — leaving host-frozen blocks (e.g. a transcript whose
-     * committed rows are immutable on ED3-risk terminals) showing pre-mutation
-     * content. Invalidation is the generic signal those containers use to retire
-     * their snapshots, which is exactly what a user-driven display reset wants.
+     * Destructive user-gesture reset: invalidate every component, erase native
+     * history, then repaint from row zero. Reachable only from explicit gestures (session
+     * replace, /tree, an explicit clear) — never from ordinary rendering,
+     * animation, resize, or finalization.
      */
     resetDisplay(): void;
     requestRender(force?: boolean, options?: RenderRequestOptions): void;
     /**
-     * Opt `component` into subtree-only renders when input leaves focus stable.
-     *
-     * The host must explicitly request renders for every sibling mutated by the
-     * component's input callbacks. Components without this opt-in retain the
-     * legacy full-root render after input.
+     * Paint a forced frame synchronously when startup must hand off an already
+     * visible component tree before further async initialization. Same as
+     * {@link requestRender} minus the `setImmediate` hop.
      */
-    enableScopedInputRender(component: Component): void;
+    renderNow(options?: RenderRequestOptions): void;
     /**
      * Schedule a render on behalf of `component` after a self-contained change
-     * (spinner frame, blink) that cannot have affected any other component.
-     *
-     * When every request since the last frame is component-scoped and the
-     * frame is otherwise quiet — no resize or geometry change, no overlays, no
-     * live inline images, no forced repaint, unchanged root child list — the
-     * next compose re-renders only the root subtrees containing the requesting
-     * components and reuses the previous frame's rows (and seam reports) for
-     * every other root child, skipping the full component-tree walk that makes
-     * long transcripts expensive to repaint at animation rate. Any concurrent
-     * full request or unsafe condition downgrades the frame to a normal full
-     * compose, so this is never less correct than `requestRender()` — only
-     * cheaper.
-     */
-    requestComponentRender(component: Component): void;
-    /**
-     * Rewrite a quiet, visible component segment directly.
-     *
-     * Loader-style animation changes one already-positioned segment at a fixed
-     * size. When the current frame geometry is still valid, rewrite just those
-     * rows and update the diff baseline instead of scheduling a full render
-     * cycle. Unsafe states fall back to `requestComponentRender()`, preserving
-     * the ordinary renderer as the correctness path.
+     * (spinner frame, blink). Frames always compose the bounded viewport from
+     * scratch — retired blocks no longer render — so a scoped request is simply
+     * an ordinary render.
      */
-    requestDirectWrite(component: Component): void;
+    requestComponentRender(_component: Component): void;
 }

package/dist/types/utils.d.ts

@@ -42,8 +42,9 @@ export declare function getSegmenter(): Intl.Segmenter;
  * Visible width of a string in terminal columns, excluding ANSI/OSC escapes.
  *
  * `Bun.stringWidth` does the heavy lifting (UAX#11 width tables + ANSI/OSC
- * stripping); this adds the two corrections it omits — tabs (expanded to
- * `tabWidth` cells) and OSC 66 text-sizing payloads (scaled by `s=`).
+ * stripping); this adds the corrections it omits — tabs (expanded to
+ * `tabWidth` cells), OSC 66 text-sizing payloads (scaled by `s=`), and APC
+ * sequences (counted as printable by Bun, actually zero cells).
  */
 export declare function visibleWidth(str: string): number;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "17.4.2",
+	"version": "18.0.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -37,11 +37,11 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "17.4.2",
-		"@oh-my-pi/pi-utils": "17.4.2"
+		"@oh-my-pi/pi-natives": "18.0.1",
+		"@oh-my-pi/pi-utils": "18.0.1"
 	},
 	"devDependencies": {
-		"ghostty-web": "^0.4.0"
+		"kitty-vt-wasm": "^0.2.0"
 	},
 	"engines": {
 		"bun": ">=1.3.14"