omk-tui 1.3.1 → 1.4.0

package/dist/visible-width.d.ts

@@ -0,0 +1,14 @@
+/** Shared grapheme segmenter; `getGraphemeSegmenter()` in utils.ts returns this instance. */
+export declare const graphemeSegmenter: Intl.Segmenter;
+export declare function isPrintableAscii(str: string): boolean;
+/**
+ * Calculate the terminal width of a single grapheme cluster.
+ * Based on code from the string-width library, but includes a possible-emoji
+ * check to avoid running the RGI_Emoji regex unnecessarily.
+ */
+export declare function graphemeWidth(segment: string): number;
+/**
+ * Calculate the visible width of a string in terminal columns.
+ */
+export declare function visibleWidth(str: string): number;
+//# sourceMappingURL=visible-width.d.ts.map

package/dist/visible-width.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible-width.d.ts","sourceRoot":"","sources":["../src/visible-width.ts"],"names":[],"mappings":"AAIA,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,gBAA6D,CAAC;AAa5F,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQrD;AAoBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA4CrD;AAyCD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuChD","sourcesContent":["import { eastAsianWidth } from \"get-east-asian-width\";\nimport { extractAnsiCode } from \"./ansi-codes.ts\";\nimport { leadingNonPrintingRegex, rgiEmojiRegex, zeroWidthRegex } from \"./unicode-regex.ts\";\n\n/** Shared grapheme segmenter; `getGraphemeSegmenter()` in utils.ts returns this instance. */\nexport const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: \"grapheme\" });\n\n/**\n * Width cache for strings that need grapheme segmentation. Styled ASCII, Hangul and CJK\n * ideographs never reach it (see `simpleWidth`), so the entries go to emoji, combining\n * marks and other scripts. A render pass over a long transcript touches thousands of distinct lines;\n * 512 entries made such passes miss on every line (FIFO eviction under a cyclic scan).\n */\nconst WIDTH_CACHE_SIZE = 8192;\n/** Longer strings are measured without caching so the cache cannot pin large text. */\nconst WIDTH_CACHE_MAX_KEY_LENGTH = 4096;\nconst widthCache = new Map<string, number>();\n\nexport function isPrintableAscii(str: string): boolean {\n\tfor (let i = 0; i < str.length; i++) {\n\t\tconst code = str.charCodeAt(i);\n\t\tif (code < 0x20 || code > 0x7e) {\n\t\t\treturn false;\n\t\t}\n\t}\n\treturn true;\n}\n\n/**\n * Check if a grapheme cluster (after segmentation) could possibly be an RGI emoji.\n * This is a fast heuristic to avoid the expensive rgiEmojiRegex test.\n * The tested Unicode blocks are deliberately broad to account for future\n * Unicode additions.\n */\nfunction couldBeEmoji(segment: string): boolean {\n\tconst cp = segment.codePointAt(0)!;\n\treturn (\n\t\t(cp >= 0x1f000 && cp <= 0x1fbff) || // Emoji and Pictograph\n\t\t(cp >= 0x2300 && cp <= 0x23ff) || // Misc technical\n\t\t(cp >= 0x2600 && cp <= 0x27bf) || // Misc symbols, dingbats\n\t\t(cp >= 0x2b50 && cp <= 0x2b55) || // Specific stars/circles\n\t\tsegment.includes(\"\\uFE0F\") || // Contains VS16 (emoji presentation selector)\n\t\tsegment.length > 2 // Multi-codepoint sequences (ZWJ, skin tones, etc.)\n\t);\n}\n\n/**\n * Calculate the terminal width of a single grapheme cluster.\n * Based on code from the string-width library, but includes a possible-emoji\n * check to avoid running the RGI_Emoji regex unnecessarily.\n */\nexport function graphemeWidth(segment: string): number {\n\tif (segment === \"\\t\") {\n\t\treturn 3;\n\t}\n\n\t// Zero-width clusters\n\tif (zeroWidthRegex.test(segment)) {\n\t\treturn 0;\n\t}\n\n\t// Emoji check with pre-filter\n\tif (couldBeEmoji(segment) && rgiEmojiRegex.test(segment)) {\n\t\treturn 2;\n\t}\n\n\t// Get base visible codepoint\n\tconst base = segment.replace(leadingNonPrintingRegex, \"\");\n\tconst cp = base.codePointAt(0);\n\tif (cp === undefined) {\n\t\treturn 0;\n\t}\n\n\t// Regional indicator symbols (U+1F1E6..U+1F1FF) are often rendered as\n\t// full-width emoji in terminals, even when isolated during streaming.\n\t// Keep width conservative (2) to avoid terminal auto-wrap drift artifacts.\n\tif (cp >= 0x1f1e6 && cp <= 0x1f1ff) {\n\t\treturn 2;\n\t}\n\n\tlet width = eastAsianWidth(cp);\n\n\t// Trailing halfwidth/fullwidth forms and AM vowels that segment with a base.\n\tif (segment.length > 1) {\n\t\tfor (const char of segment.slice(1)) {\n\t\t\tconst c = char.codePointAt(0)!;\n\t\t\tif (c >= 0xff00 && c <= 0xffef) {\n\t\t\t\twidth += eastAsianWidth(c);\n\t\t\t} else if (c === 0x0e33 || c === 0x0eb3) {\n\t\t\t\twidth += 1;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn width;\n}\n\n/**\n * Normalize for measuring: tabs become 3 spaces and supported ANSI/OSC/APC escape\n * sequences (CSI styling/cursor codes, OSC hyperlinks and prompt markers, APC sequences\n * like CURSOR_MARKER) are removed. An ESC that starts no complete sequence is kept.\n */\nfunction stripForWidth(str: string): string {\n\tconst clean = str.includes(\"\\t\") ? str.replace(/\\t/g, \"   \") : str;\n\tlet esc = clean.indexOf(\"\\x1b\");\n\tif (esc === -1) return clean;\n\tlet stripped = \"\";\n\tlet copied = 0;\n\twhile (esc !== -1) {\n\t\tconst ansi = extractAnsiCode(clean, esc);\n\t\tif (ansi) {\n\t\t\tstripped += clean.slice(copied, esc);\n\t\t\tcopied = esc + ansi.length;\n\t\t}\n\t\tesc = clean.indexOf(\"\\x1b\", ansi ? copied : esc + 1);\n\t}\n\treturn stripped + clean.slice(copied);\n}\n\n/**\n * Width of text made only of printable ASCII (1 column), Hangul syllables and CJK unified\n * ideographs (2 columns each, UAX #11 Wide), or -1 when anything else appears. Each of these\n * code points is a grapheme cluster on its own: a Hangul syllable joins only trailing jamo\n * (U+1160..U+11FF) and an ideograph only variation selectors, both of which fall back here.\n */\nfunction simpleWidth(clean: string): number {\n\tlet width = 0;\n\tfor (let i = 0; i < clean.length; i++) {\n\t\tconst code = clean.charCodeAt(i);\n\t\tif (code >= 0x20 && code <= 0x7e) width += 1;\n\t\telse if ((code >= 0xac00 && code <= 0xd7a3) || (code >= 0x4e00 && code <= 0x9fff)) width += 2;\n\t\telse return -1;\n\t}\n\treturn width;\n}\n\n/**\n * Calculate the visible width of a string in terminal columns.\n */\nexport function visibleWidth(str: string): number {\n\tif (str.length === 0) {\n\t\treturn 0;\n\t}\n\n\t// Fast path: pure ASCII printable\n\tif (isPrintableAscii(str)) {\n\t\treturn str.length;\n\t}\n\n\t// Styled ASCII, Hangul and CJK (the bulk of rendered lines): once escapes are\n\t// stripped, every character is its own cluster, so segmentation is unnecessary.\n\tconst clean = stripForWidth(str);\n\tconst simple = simpleWidth(clean);\n\tif (simple >= 0) {\n\t\treturn simple;\n\t}\n\n\tconst cached = widthCache.get(str);\n\tif (cached !== undefined) {\n\t\treturn cached;\n\t}\n\n\tlet width = 0;\n\tfor (const { segment } of graphemeSegmenter.segment(clean)) {\n\t\twidth += graphemeWidth(segment);\n\t}\n\n\tif (str.length <= WIDTH_CACHE_MAX_KEY_LENGTH) {\n\t\tif (widthCache.size >= WIDTH_CACHE_SIZE) {\n\t\t\tconst firstKey = widthCache.keys().next().value;\n\t\t\tif (firstKey !== undefined) {\n\t\t\t\twidthCache.delete(firstKey);\n\t\t\t}\n\t\t}\n\t\twidthCache.set(str, width);\n\t}\n\n\treturn width;\n}\n"]}

package/dist/visible-width.js

@@ -0,0 +1,163 @@
+import { eastAsianWidth } from "get-east-asian-width";
+import { extractAnsiCode } from "./ansi-codes.js";
+import { leadingNonPrintingRegex, rgiEmojiRegex, zeroWidthRegex } from "./unicode-regex.js";
+/** Shared grapheme segmenter; `getGraphemeSegmenter()` in utils.ts returns this instance. */
+export const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/**
+ * Width cache for strings that need grapheme segmentation. Styled ASCII, Hangul and CJK
+ * ideographs never reach it (see `simpleWidth`), so the entries go to emoji, combining
+ * marks and other scripts. A render pass over a long transcript touches thousands of distinct lines;
+ * 512 entries made such passes miss on every line (FIFO eviction under a cyclic scan).
+ */
+const WIDTH_CACHE_SIZE = 8192;
+/** Longer strings are measured without caching so the cache cannot pin large text. */
+const WIDTH_CACHE_MAX_KEY_LENGTH = 4096;
+const widthCache = new Map();
+export function isPrintableAscii(str) {
+    for (let i = 0; i < str.length; i++) {
+        const code = str.charCodeAt(i);
+        if (code < 0x20 || code > 0x7e) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Check if a grapheme cluster (after segmentation) could possibly be an RGI emoji.
+ * This is a fast heuristic to avoid the expensive rgiEmojiRegex test.
+ * The tested Unicode blocks are deliberately broad to account for future
+ * Unicode additions.
+ */
+function couldBeEmoji(segment) {
+    const cp = segment.codePointAt(0);
+    return ((cp >= 0x1f000 && cp <= 0x1fbff) || // Emoji and Pictograph
+        (cp >= 0x2300 && cp <= 0x23ff) || // Misc technical
+        (cp >= 0x2600 && cp <= 0x27bf) || // Misc symbols, dingbats
+        (cp >= 0x2b50 && cp <= 0x2b55) || // Specific stars/circles
+        segment.includes("\uFE0F") || // Contains VS16 (emoji presentation selector)
+        segment.length > 2 // Multi-codepoint sequences (ZWJ, skin tones, etc.)
+    );
+}
+/**
+ * Calculate the terminal width of a single grapheme cluster.
+ * Based on code from the string-width library, but includes a possible-emoji
+ * check to avoid running the RGI_Emoji regex unnecessarily.
+ */
+export function graphemeWidth(segment) {
+    if (segment === "\t") {
+        return 3;
+    }
+    // Zero-width clusters
+    if (zeroWidthRegex.test(segment)) {
+        return 0;
+    }
+    // Emoji check with pre-filter
+    if (couldBeEmoji(segment) && rgiEmojiRegex.test(segment)) {
+        return 2;
+    }
+    // Get base visible codepoint
+    const base = segment.replace(leadingNonPrintingRegex, "");
+    const cp = base.codePointAt(0);
+    if (cp === undefined) {
+        return 0;
+    }
+    // Regional indicator symbols (U+1F1E6..U+1F1FF) are often rendered as
+    // full-width emoji in terminals, even when isolated during streaming.
+    // Keep width conservative (2) to avoid terminal auto-wrap drift artifacts.
+    if (cp >= 0x1f1e6 && cp <= 0x1f1ff) {
+        return 2;
+    }
+    let width = eastAsianWidth(cp);
+    // Trailing halfwidth/fullwidth forms and AM vowels that segment with a base.
+    if (segment.length > 1) {
+        for (const char of segment.slice(1)) {
+            const c = char.codePointAt(0);
+            if (c >= 0xff00 && c <= 0xffef) {
+                width += eastAsianWidth(c);
+            }
+            else if (c === 0x0e33 || c === 0x0eb3) {
+                width += 1;
+            }
+        }
+    }
+    return width;
+}
+/**
+ * Normalize for measuring: tabs become 3 spaces and supported ANSI/OSC/APC escape
+ * sequences (CSI styling/cursor codes, OSC hyperlinks and prompt markers, APC sequences
+ * like CURSOR_MARKER) are removed. An ESC that starts no complete sequence is kept.
+ */
+function stripForWidth(str) {
+    const clean = str.includes("\t") ? str.replace(/\t/g, "   ") : str;
+    let esc = clean.indexOf("\x1b");
+    if (esc === -1)
+        return clean;
+    let stripped = "";
+    let copied = 0;
+    while (esc !== -1) {
+        const ansi = extractAnsiCode(clean, esc);
+        if (ansi) {
+            stripped += clean.slice(copied, esc);
+            copied = esc + ansi.length;
+        }
+        esc = clean.indexOf("\x1b", ansi ? copied : esc + 1);
+    }
+    return stripped + clean.slice(copied);
+}
+/**
+ * Width of text made only of printable ASCII (1 column), Hangul syllables and CJK unified
+ * ideographs (2 columns each, UAX #11 Wide), or -1 when anything else appears. Each of these
+ * code points is a grapheme cluster on its own: a Hangul syllable joins only trailing jamo
+ * (U+1160..U+11FF) and an ideograph only variation selectors, both of which fall back here.
+ */
+function simpleWidth(clean) {
+    let width = 0;
+    for (let i = 0; i < clean.length; i++) {
+        const code = clean.charCodeAt(i);
+        if (code >= 0x20 && code <= 0x7e)
+            width += 1;
+        else if ((code >= 0xac00 && code <= 0xd7a3) || (code >= 0x4e00 && code <= 0x9fff))
+            width += 2;
+        else
+            return -1;
+    }
+    return width;
+}
+/**
+ * Calculate the visible width of a string in terminal columns.
+ */
+export function visibleWidth(str) {
+    if (str.length === 0) {
+        return 0;
+    }
+    // Fast path: pure ASCII printable
+    if (isPrintableAscii(str)) {
+        return str.length;
+    }
+    // Styled ASCII, Hangul and CJK (the bulk of rendered lines): once escapes are
+    // stripped, every character is its own cluster, so segmentation is unnecessary.
+    const clean = stripForWidth(str);
+    const simple = simpleWidth(clean);
+    if (simple >= 0) {
+        return simple;
+    }
+    const cached = widthCache.get(str);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let width = 0;
+    for (const { segment } of graphemeSegmenter.segment(clean)) {
+        width += graphemeWidth(segment);
+    }
+    if (str.length <= WIDTH_CACHE_MAX_KEY_LENGTH) {
+        if (widthCache.size >= WIDTH_CACHE_SIZE) {
+            const firstKey = widthCache.keys().next().value;
+            if (firstKey !== undefined) {
+                widthCache.delete(firstKey);
+            }
+        }
+        widthCache.set(str, width);
+    }
+    return width;
+}
+//# sourceMappingURL=visible-width.js.map

package/dist/visible-width.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible-width.js","sourceRoot":"","sources":["../src/visible-width.ts"],"names":[],"mappings":"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","sourcesContent":["import { eastAsianWidth } from \"get-east-asian-width\";\nimport { extractAnsiCode } from \"./ansi-codes.ts\";\nimport { leadingNonPrintingRegex, rgiEmojiRegex, zeroWidthRegex } from \"./unicode-regex.ts\";\n\n/** Shared grapheme segmenter; `getGraphemeSegmenter()` in utils.ts returns this instance. */\nexport const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: \"grapheme\" });\n\n/**\n * Width cache for strings that need grapheme segmentation. Styled ASCII, Hangul and CJK\n * ideographs never reach it (see `simpleWidth`), so the entries go to emoji, combining\n * marks and other scripts. A render pass over a long transcript touches thousands of distinct lines;\n * 512 entries made such passes miss on every line (FIFO eviction under a cyclic scan).\n */\nconst WIDTH_CACHE_SIZE = 8192;\n/** Longer strings are measured without caching so the cache cannot pin large text. */\nconst WIDTH_CACHE_MAX_KEY_LENGTH = 4096;\nconst widthCache = new Map<string, number>();\n\nexport function isPrintableAscii(str: string): boolean {\n\tfor (let i = 0; i < str.length; i++) {\n\t\tconst code = str.charCodeAt(i);\n\t\tif (code < 0x20 || code > 0x7e) {\n\t\t\treturn false;\n\t\t}\n\t}\n\treturn true;\n}\n\n/**\n * Check if a grapheme cluster (after segmentation) could possibly be an RGI emoji.\n * This is a fast heuristic to avoid the expensive rgiEmojiRegex test.\n * The tested Unicode blocks are deliberately broad to account for future\n * Unicode additions.\n */\nfunction couldBeEmoji(segment: string): boolean {\n\tconst cp = segment.codePointAt(0)!;\n\treturn (\n\t\t(cp >= 0x1f000 && cp <= 0x1fbff) || // Emoji and Pictograph\n\t\t(cp >= 0x2300 && cp <= 0x23ff) || // Misc technical\n\t\t(cp >= 0x2600 && cp <= 0x27bf) || // Misc symbols, dingbats\n\t\t(cp >= 0x2b50 && cp <= 0x2b55) || // Specific stars/circles\n\t\tsegment.includes(\"\\uFE0F\") || // Contains VS16 (emoji presentation selector)\n\t\tsegment.length > 2 // Multi-codepoint sequences (ZWJ, skin tones, etc.)\n\t);\n}\n\n/**\n * Calculate the terminal width of a single grapheme cluster.\n * Based on code from the string-width library, but includes a possible-emoji\n * check to avoid running the RGI_Emoji regex unnecessarily.\n */\nexport function graphemeWidth(segment: string): number {\n\tif (segment === \"\\t\") {\n\t\treturn 3;\n\t}\n\n\t// Zero-width clusters\n\tif (zeroWidthRegex.test(segment)) {\n\t\treturn 0;\n\t}\n\n\t// Emoji check with pre-filter\n\tif (couldBeEmoji(segment) && rgiEmojiRegex.test(segment)) {\n\t\treturn 2;\n\t}\n\n\t// Get base visible codepoint\n\tconst base = segment.replace(leadingNonPrintingRegex, \"\");\n\tconst cp = base.codePointAt(0);\n\tif (cp === undefined) {\n\t\treturn 0;\n\t}\n\n\t// Regional indicator symbols (U+1F1E6..U+1F1FF) are often rendered as\n\t// full-width emoji in terminals, even when isolated during streaming.\n\t// Keep width conservative (2) to avoid terminal auto-wrap drift artifacts.\n\tif (cp >= 0x1f1e6 && cp <= 0x1f1ff) {\n\t\treturn 2;\n\t}\n\n\tlet width = eastAsianWidth(cp);\n\n\t// Trailing halfwidth/fullwidth forms and AM vowels that segment with a base.\n\tif (segment.length > 1) {\n\t\tfor (const char of segment.slice(1)) {\n\t\t\tconst c = char.codePointAt(0)!;\n\t\t\tif (c >= 0xff00 && c <= 0xffef) {\n\t\t\t\twidth += eastAsianWidth(c);\n\t\t\t} else if (c === 0x0e33 || c === 0x0eb3) {\n\t\t\t\twidth += 1;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn width;\n}\n\n/**\n * Normalize for measuring: tabs become 3 spaces and supported ANSI/OSC/APC escape\n * sequences (CSI styling/cursor codes, OSC hyperlinks and prompt markers, APC sequences\n * like CURSOR_MARKER) are removed. An ESC that starts no complete sequence is kept.\n */\nfunction stripForWidth(str: string): string {\n\tconst clean = str.includes(\"\\t\") ? str.replace(/\\t/g, \"   \") : str;\n\tlet esc = clean.indexOf(\"\\x1b\");\n\tif (esc === -1) return clean;\n\tlet stripped = \"\";\n\tlet copied = 0;\n\twhile (esc !== -1) {\n\t\tconst ansi = extractAnsiCode(clean, esc);\n\t\tif (ansi) {\n\t\t\tstripped += clean.slice(copied, esc);\n\t\t\tcopied = esc + ansi.length;\n\t\t}\n\t\tesc = clean.indexOf(\"\\x1b\", ansi ? copied : esc + 1);\n\t}\n\treturn stripped + clean.slice(copied);\n}\n\n/**\n * Width of text made only of printable ASCII (1 column), Hangul syllables and CJK unified\n * ideographs (2 columns each, UAX #11 Wide), or -1 when anything else appears. Each of these\n * code points is a grapheme cluster on its own: a Hangul syllable joins only trailing jamo\n * (U+1160..U+11FF) and an ideograph only variation selectors, both of which fall back here.\n */\nfunction simpleWidth(clean: string): number {\n\tlet width = 0;\n\tfor (let i = 0; i < clean.length; i++) {\n\t\tconst code = clean.charCodeAt(i);\n\t\tif (code >= 0x20 && code <= 0x7e) width += 1;\n\t\telse if ((code >= 0xac00 && code <= 0xd7a3) || (code >= 0x4e00 && code <= 0x9fff)) width += 2;\n\t\telse return -1;\n\t}\n\treturn width;\n}\n\n/**\n * Calculate the visible width of a string in terminal columns.\n */\nexport function visibleWidth(str: string): number {\n\tif (str.length === 0) {\n\t\treturn 0;\n\t}\n\n\t// Fast path: pure ASCII printable\n\tif (isPrintableAscii(str)) {\n\t\treturn str.length;\n\t}\n\n\t// Styled ASCII, Hangul and CJK (the bulk of rendered lines): once escapes are\n\t// stripped, every character is its own cluster, so segmentation is unnecessary.\n\tconst clean = stripForWidth(str);\n\tconst simple = simpleWidth(clean);\n\tif (simple >= 0) {\n\t\treturn simple;\n\t}\n\n\tconst cached = widthCache.get(str);\n\tif (cached !== undefined) {\n\t\treturn cached;\n\t}\n\n\tlet width = 0;\n\tfor (const { segment } of graphemeSegmenter.segment(clean)) {\n\t\twidth += graphemeWidth(segment);\n\t}\n\n\tif (str.length <= WIDTH_CACHE_MAX_KEY_LENGTH) {\n\t\tif (widthCache.size >= WIDTH_CACHE_SIZE) {\n\t\t\tconst firstKey = widthCache.keys().next().value;\n\t\t\tif (firstKey !== undefined) {\n\t\t\t\twidthCache.delete(firstKey);\n\t\t\t}\n\t\t}\n\t\twidthCache.set(str, width);\n\t}\n\n\treturn width;\n}\n"]}

package/dist/windowed-container.d.ts

@@ -0,0 +1,63 @@
+import { type Component, Container } from "./tui.ts";
+export interface WindowedRenderStats {
+    /** Children rendered live this frame (live tail plus unsettled gaps). */
+    liveChildren: number;
+    /** Frozen children re-rendered because their generation moved. */
+    refreshedChildren: number;
+    /** Frozen segments whose line buffer was rebuilt this frame. */
+    refreshedSegments: number;
+}
+/**
+ * Container that freezes settled children above a live-line budget into
+ * bounded line segments and stops re-rendering them.
+ *
+ * - Settledness comes from `isRenderSettled()` (missing ⇒ settled). Unsettled
+ *   children always render live; settled runs on both sides of them freeze.
+ * - Each frozen child remembers its `getRenderGeneration()`. When it moves,
+ *   only that child is re-rendered and only its segment is rebuilt.
+ * - An unsettled frozen child drops just its segment. Width changes,
+ *   `invalidate()`, `clear()` and foreign edits of `children` thaw everything.
+ * - Freezing releases the child's render caches (frozen lines are the only
+ *   retained copy); a later change re-renders that one child from source.
+ */
+export declare class WindowedContainer extends Container {
+    private segments;
+    private frozenWidth;
+    private liveLineBudget;
+    private viewportRows?;
+    private lastLiveLineBudget;
+    private stats;
+    /** Fixed budget (tests, embedders); detaches any viewport set by `setViewportRows`. */
+    setLiveLineBudget(lines: number): void;
+    /**
+     * Follow the terminal height: budget = max(120, 2 × rows), re-read on every
+     * render so a resize applies on the next frame.
+     */
+    setViewportRows(rows: () => number): void;
+    getLiveLineBudget(): number;
+    getFrozenChildCount(): number;
+    getFrozenLineCount(): number;
+    /** Diagnostics: number of frozen segments. */
+    getFrozenSegmentCount(): number;
+    /** Diagnostics: frozen child index ranges [from, to). */
+    getFrozenRanges(): ReadonlyArray<{
+        from: number;
+        to: number;
+    }>;
+    /** Diagnostics: what the most recent `render` had to redo. */
+    getLastRenderStats(): Readonly<WindowedRenderStats>;
+    /** Subclasses may add their own lifecycle knowledge (e.g. an agent_end backstop). */
+    protected isChildSettled(child: Component): boolean;
+    removeChild(component: Component): void;
+    clear(): void;
+    invalidate(): void;
+    /** Drop every frozen segment; the next render re-renders all children. */
+    thaw(): void;
+    render(width: number): string[];
+    /** Drop unsettled segments and refresh children whose generation moved. */
+    private reconcile;
+    private refreshSegment;
+    /** Freeze settled live children that sit above the live-line budget. */
+    private freezeAboveBudget;
+}
+//# sourceMappingURL=windowed-container.d.ts.map

package/dist/windowed-container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windowed-container.d.ts","sourceRoot":"","sources":["../src/windowed-container.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAgCrD,MAAM,WAAW,mBAAmB;IACnC,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,kBAAkB,CAAwB;IAClD,OAAO,CAAC,KAAK,CAAwF;IAErG,uFAAuF;IACvF,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGrC;IAED;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,MAAM,GAAG,IAAI,CAExC;IAED,iBAAiB,IAAI,MAAM,CAI1B;IAED,mBAAmB,IAAI,MAAM,CAI5B;IAED,kBAAkB,IAAI,MAAM,CAI3B;IAED,8CAA8C;IAC9C,qBAAqB,IAAI,MAAM,CAE9B;IAED,yDAAyD;IACzD,eAAe,IAAI,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAE7D;IAED,8DAA8D;IAC9D,kBAAkB,IAAI,QAAQ,CAAC,mBAAmB,CAAC,CAElD;IAED,qFAAqF;IACrF,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAElD;IAEQ,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAkB/C;IAEQ,KAAK,IAAI,IAAI,CAGrB;IAEQ,UAAU,IAAI,IAAI,CAG1B;IAED,0EAA0E;IAC1E,IAAI,IAAI,IAAI,CAGX;IAEQ,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAsCvC;IAED,2EAA2E;IAC3E,OAAO,CAAC,SAAS;IA4BjB,OAAO,CAAC,cAAc;IAwBtB,wEAAwE;IACxE,OAAO,CAAC,iBAAiB;CA8CzB","sourcesContent":["import { isRenderSettled, releaseRenderCache, renderGeneration } from \"./render-generation.ts\";\nimport { type Component, Container } from \"./tui.ts\";\n\n/**\n * A frozen segment never grows past this many lines (a single larger child\n * gets a segment of its own). Bounds the work of refreshing one changed child:\n * only its segment's line buffer is rebuilt, never the whole frozen history.\n */\nconst SEGMENT_MAX_LINES = 512;\n\n/**\n * Live-line budget: the bottom `max(120, 2 × terminal rows)` lines always\n * render live. Two viewports keep components that change without announcing\n * it (animations, stateful extension renderers) live wherever the user can\n * see them, also after scrolling back one screen; the 120 floor is the budget\n * when no viewport is attached and on small terminals.\n */\nconst MIN_LIVE_LINE_BUDGET = 120;\nconst LIVE_VIEWPORTS = 2;\n\n/** Contiguous settled children whose rendered lines are reused verbatim. */\ntype FrozenSegment = {\n\t/** Index in `children` of the first frozen child. */\n\tfrom: number;\n\t/** The frozen children themselves (identity-checked every frame). */\n\tchildren: Component[];\n\tlineCounts: number[];\n\t/** `getRenderGeneration()` of each child when its lines were taken. */\n\tgenerations: number[];\n\t/** Concatenation of the children's lines. */\n\tlines: string[];\n};\n\nexport interface WindowedRenderStats {\n\t/** Children rendered live this frame (live tail plus unsettled gaps). */\n\tliveChildren: number;\n\t/** Frozen children re-rendered because their generation moved. */\n\trefreshedChildren: number;\n\t/** Frozen segments whose line buffer was rebuilt this frame. */\n\trefreshedSegments: number;\n}\n\n/**\n * Container that freezes settled children above a live-line budget into\n * bounded line segments and stops re-rendering them.\n *\n * - Settledness comes from `isRenderSettled()` (missing ⇒ settled). Unsettled\n *   children always render live; settled runs on both sides of them freeze.\n * - Each frozen child remembers its `getRenderGeneration()`. When it moves,\n *   only that child is re-rendered and only its segment is rebuilt.\n * - An unsettled frozen child drops just its segment. Width changes,\n *   `invalidate()`, `clear()` and foreign edits of `children` thaw everything.\n * - Freezing releases the child's render caches (frozen lines are the only\n *   retained copy); a later change re-renders that one child from source.\n */\nexport class WindowedContainer extends Container {\n\tprivate segments: FrozenSegment[] = [];\n\tprivate frozenWidth = -1;\n\tprivate liveLineBudget = MIN_LIVE_LINE_BUDGET;\n\tprivate viewportRows?: () => number;\n\tprivate lastLiveLineBudget = MIN_LIVE_LINE_BUDGET;\n\tprivate stats: WindowedRenderStats = { liveChildren: 0, refreshedChildren: 0, refreshedSegments: 0 };\n\n\t/** Fixed budget (tests, embedders); detaches any viewport set by `setViewportRows`. */\n\tsetLiveLineBudget(lines: number): void {\n\t\tthis.viewportRows = undefined;\n\t\tthis.liveLineBudget = Math.max(1, Math.floor(lines));\n\t}\n\n\t/**\n\t * Follow the terminal height: budget = max(120, 2 × rows), re-read on every\n\t * render so a resize applies on the next frame.\n\t */\n\tsetViewportRows(rows: () => number): void {\n\t\tthis.viewportRows = rows;\n\t}\n\n\tgetLiveLineBudget(): number {\n\t\tif (!this.viewportRows) return this.liveLineBudget;\n\t\tconst rows = Math.floor(this.viewportRows());\n\t\treturn Math.max(MIN_LIVE_LINE_BUDGET, Number.isFinite(rows) ? rows * LIVE_VIEWPORTS : 0);\n\t}\n\n\tgetFrozenChildCount(): number {\n\t\tlet count = 0;\n\t\tfor (const segment of this.segments) count += segment.children.length;\n\t\treturn count;\n\t}\n\n\tgetFrozenLineCount(): number {\n\t\tlet count = 0;\n\t\tfor (const segment of this.segments) count += segment.lines.length;\n\t\treturn count;\n\t}\n\n\t/** Diagnostics: number of frozen segments. */\n\tgetFrozenSegmentCount(): number {\n\t\treturn this.segments.length;\n\t}\n\n\t/** Diagnostics: frozen child index ranges [from, to). */\n\tgetFrozenRanges(): ReadonlyArray<{ from: number; to: number }> {\n\t\treturn this.segments.map((segment) => ({ from: segment.from, to: segment.from + segment.children.length }));\n\t}\n\n\t/** Diagnostics: what the most recent `render` had to redo. */\n\tgetLastRenderStats(): Readonly<WindowedRenderStats> {\n\t\treturn this.stats;\n\t}\n\n\t/** Subclasses may add their own lifecycle knowledge (e.g. an agent_end backstop). */\n\tprotected isChildSettled(child: Component): boolean {\n\t\treturn isRenderSettled(child);\n\t}\n\n\toverride removeChild(component: Component): void {\n\t\tconst index = this.children.indexOf(component);\n\t\tif (index === -1) return;\n\t\tsuper.removeChild(component);\n\t\tfor (const segment of this.segments) {\n\t\t\tif (index < segment.from) {\n\t\t\t\tsegment.from -= 1;\n\t\t\t} else if (index < segment.from + segment.children.length) {\n\t\t\t\tconst j = index - segment.from;\n\t\t\t\tlet offset = 0;\n\t\t\t\tfor (let k = 0; k < j; k++) offset += segment.lineCounts[k];\n\t\t\t\tsegment.lines.splice(offset, segment.lineCounts[j]);\n\t\t\t\tsegment.children.splice(j, 1);\n\t\t\t\tsegment.lineCounts.splice(j, 1);\n\t\t\t\tsegment.generations.splice(j, 1);\n\t\t\t}\n\t\t}\n\t\tthis.segments = this.segments.filter((segment) => segment.children.length > 0);\n\t}\n\n\toverride clear(): void {\n\t\tthis.thaw();\n\t\tsuper.clear();\n\t}\n\n\toverride invalidate(): void {\n\t\tthis.thaw();\n\t\tsuper.invalidate();\n\t}\n\n\t/** Drop every frozen segment; the next render re-renders all children. */\n\tthaw(): void {\n\t\tthis.segments = [];\n\t\tthis.frozenWidth = -1;\n\t}\n\n\toverride render(width: number): string[] {\n\t\tconst budget = this.getLiveLineBudget();\n\t\t// A taller terminal widens the live window: thaw so rows now inside it render live.\n\t\tif (width !== this.frozenWidth || budget > this.lastLiveLineBudget) this.thaw();\n\t\tthis.lastLiveLineBudget = budget;\n\t\tthis.frozenWidth = width;\n\t\tthis.stats = { liveChildren: 0, refreshedChildren: 0, refreshedSegments: 0 };\n\t\tthis.reconcile(width);\n\n\t\tconst parts: string[][] = [];\n\t\tconst partStarts: number[] = [];\n\t\tconst live: number[] = [];\n\t\tconst liveLines: string[][] = [];\n\t\tlet segmentIndex = 0;\n\t\tfor (let i = 0; i < this.children.length; ) {\n\t\t\tconst segment = this.segments[segmentIndex];\n\t\t\tlet lines: string[];\n\t\t\tpartStarts.push(i);\n\t\t\tif (segment && segment.from === i) {\n\t\t\t\tlines = segment.lines;\n\t\t\t\ti += segment.children.length;\n\t\t\t\tsegmentIndex += 1;\n\t\t\t} else {\n\t\t\t\tlines = this.children[i].render(width);\n\t\t\t\tlive.push(i);\n\t\t\t\tliveLines.push(lines);\n\t\t\t\ti += 1;\n\t\t\t}\n\t\t\tparts.push(lines);\n\t\t}\n\t\tthis.stats.liveChildren = live.length;\n\n\t\t// Copy before freezing: freezing appends to segment line buffers. Native\n\t\t// concat is a bulk copy; spread arguments stay far below engine limits\n\t\t// because frozen rows arrive as a few hundred segment arrays.\n\t\tconst out = parts.length < 8192 ? ([] as string[]).concat(...parts) : parts.flat();\n\t\tthis.freezeAboveBudget(parts, partStarts, live, liveLines, budget);\n\t\treturn out;\n\t}\n\n\t/** Drop unsettled segments and refresh children whose generation moved. */\n\tprivate reconcile(width: number): void {\n\t\tconst kept: FrozenSegment[] = [];\n\t\tfor (const segment of this.segments) {\n\t\t\tlet dirty: number[] | undefined;\n\t\t\tlet settled = true;\n\t\t\tfor (let j = 0; j < segment.children.length; j++) {\n\t\t\t\tconst child = segment.children[j];\n\t\t\t\tif (this.children[segment.from + j] !== child) {\n\t\t\t\t\t// `children` was edited behind our back: nothing frozen can be trusted.\n\t\t\t\t\tthis.segments = [];\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tif (!this.isChildSettled(child)) {\n\t\t\t\t\tsettled = false;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tif (renderGeneration(child) !== segment.generations[j]) {\n\t\t\t\t\tdirty ??= [];\n\t\t\t\t\tdirty.push(j);\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (!settled) continue;\n\t\t\tif (dirty) this.refreshSegment(segment, dirty, width);\n\t\t\tkept.push(segment);\n\t\t}\n\t\tthis.segments = kept;\n\t}\n\n\tprivate refreshSegment(segment: FrozenSegment, dirty: number[], width: number): void {\n\t\tconst lines: string[] = [];\n\t\tlet offset = 0;\n\t\tlet next = 0;\n\t\tfor (let j = 0; j < segment.children.length; j++) {\n\t\t\tconst count = segment.lineCounts[j];\n\t\t\tif (dirty[next] === j) {\n\t\t\t\tnext += 1;\n\t\t\t\tconst child = segment.children[j];\n\t\t\t\tconst fresh = child.render(width);\n\t\t\t\tfor (const line of fresh) lines.push(line);\n\t\t\t\tsegment.lineCounts[j] = fresh.length;\n\t\t\t\tsegment.generations[j] = renderGeneration(child);\n\t\t\t\treleaseRenderCache(child);\n\t\t\t} else {\n\t\t\t\tfor (let l = offset; l < offset + count; l++) lines.push(segment.lines[l]);\n\t\t\t}\n\t\t\toffset += count;\n\t\t}\n\t\tsegment.lines = lines;\n\t\tthis.stats.refreshedChildren += dirty.length;\n\t\tthis.stats.refreshedSegments += 1;\n\t}\n\n\t/** Freeze settled live children that sit above the live-line budget. */\n\tprivate freezeAboveBudget(\n\t\tparts: string[][],\n\t\tpartStarts: number[],\n\t\tlive: number[],\n\t\tliveLines: string[][],\n\t\tbudget: number,\n\t): void {\n\t\tlet acc = 0;\n\t\tlet liveStart = this.children.length;\n\t\tfor (let p = parts.length - 1; p >= 0; p--) {\n\t\t\tacc += parts[p].length;\n\t\t\tliveStart = partStarts[p];\n\t\t\tif (acc >= budget) break;\n\t\t}\n\t\tlet segmentIndex = 0;\n\t\tfor (let n = 0; n < live.length && live[n] < liveStart; n++) {\n\t\t\tconst index = live[n];\n\t\t\tconst child = this.children[index];\n\t\t\tif (!this.isChildSettled(child)) continue;\n\t\t\tconst lines = liveLines[n];\n\t\t\twhile (segmentIndex < this.segments.length && this.segments[segmentIndex].from < index) segmentIndex += 1;\n\t\t\tconst previous = this.segments[segmentIndex - 1];\n\t\t\tconst generation = renderGeneration(child);\n\t\t\tif (\n\t\t\t\tprevious &&\n\t\t\t\tprevious.from + previous.children.length === index &&\n\t\t\t\tprevious.lines.length + lines.length <= SEGMENT_MAX_LINES\n\t\t\t) {\n\t\t\t\tprevious.children.push(child);\n\t\t\t\tprevious.lineCounts.push(lines.length);\n\t\t\t\tprevious.generations.push(generation);\n\t\t\t\tfor (const line of lines) previous.lines.push(line);\n\t\t\t} else {\n\t\t\t\tconst segment: FrozenSegment = {\n\t\t\t\t\tfrom: index,\n\t\t\t\t\tchildren: [child],\n\t\t\t\t\tlineCounts: [lines.length],\n\t\t\t\t\tgenerations: [generation],\n\t\t\t\t\tlines: lines.slice(),\n\t\t\t\t};\n\t\t\t\tthis.segments.splice(segmentIndex, 0, segment);\n\t\t\t\tsegmentIndex += 1;\n\t\t\t}\n\t\t\treleaseRenderCache(child);\n\t\t}\n\t}\n}\n"]}

package/dist/windowed-container.js

@@ -0,0 +1,259 @@
+import { isRenderSettled, releaseRenderCache, renderGeneration } from "./render-generation.js";
+import { Container } from "./tui.js";
+/**
+ * A frozen segment never grows past this many lines (a single larger child
+ * gets a segment of its own). Bounds the work of refreshing one changed child:
+ * only its segment's line buffer is rebuilt, never the whole frozen history.
+ */
+const SEGMENT_MAX_LINES = 512;
+/**
+ * Live-line budget: the bottom `max(120, 2 × terminal rows)` lines always
+ * render live. Two viewports keep components that change without announcing
+ * it (animations, stateful extension renderers) live wherever the user can
+ * see them, also after scrolling back one screen; the 120 floor is the budget
+ * when no viewport is attached and on small terminals.
+ */
+const MIN_LIVE_LINE_BUDGET = 120;
+const LIVE_VIEWPORTS = 2;
+/**
+ * Container that freezes settled children above a live-line budget into
+ * bounded line segments and stops re-rendering them.
+ *
+ * - Settledness comes from `isRenderSettled()` (missing ⇒ settled). Unsettled
+ *   children always render live; settled runs on both sides of them freeze.
+ * - Each frozen child remembers its `getRenderGeneration()`. When it moves,
+ *   only that child is re-rendered and only its segment is rebuilt.
+ * - An unsettled frozen child drops just its segment. Width changes,
+ *   `invalidate()`, `clear()` and foreign edits of `children` thaw everything.
+ * - Freezing releases the child's render caches (frozen lines are the only
+ *   retained copy); a later change re-renders that one child from source.
+ */
+export class WindowedContainer extends Container {
+    segments = [];
+    frozenWidth = -1;
+    liveLineBudget = MIN_LIVE_LINE_BUDGET;
+    viewportRows;
+    lastLiveLineBudget = MIN_LIVE_LINE_BUDGET;
+    stats = { liveChildren: 0, refreshedChildren: 0, refreshedSegments: 0 };
+    /** Fixed budget (tests, embedders); detaches any viewport set by `setViewportRows`. */
+    setLiveLineBudget(lines) {
+        this.viewportRows = undefined;
+        this.liveLineBudget = Math.max(1, Math.floor(lines));
+    }
+    /**
+     * Follow the terminal height: budget = max(120, 2 × rows), re-read on every
+     * render so a resize applies on the next frame.
+     */
+    setViewportRows(rows) {
+        this.viewportRows = rows;
+    }
+    getLiveLineBudget() {
+        if (!this.viewportRows)
+            return this.liveLineBudget;
+        const rows = Math.floor(this.viewportRows());
+        return Math.max(MIN_LIVE_LINE_BUDGET, Number.isFinite(rows) ? rows * LIVE_VIEWPORTS : 0);
+    }
+    getFrozenChildCount() {
+        let count = 0;
+        for (const segment of this.segments)
+            count += segment.children.length;
+        return count;
+    }
+    getFrozenLineCount() {
+        let count = 0;
+        for (const segment of this.segments)
+            count += segment.lines.length;
+        return count;
+    }
+    /** Diagnostics: number of frozen segments. */
+    getFrozenSegmentCount() {
+        return this.segments.length;
+    }
+    /** Diagnostics: frozen child index ranges [from, to). */
+    getFrozenRanges() {
+        return this.segments.map((segment) => ({ from: segment.from, to: segment.from + segment.children.length }));
+    }
+    /** Diagnostics: what the most recent `render` had to redo. */
+    getLastRenderStats() {
+        return this.stats;
+    }
+    /** Subclasses may add their own lifecycle knowledge (e.g. an agent_end backstop). */
+    isChildSettled(child) {
+        return isRenderSettled(child);
+    }
+    removeChild(component) {
+        const index = this.children.indexOf(component);
+        if (index === -1)
+            return;
+        super.removeChild(component);
+        for (const segment of this.segments) {
+            if (index < segment.from) {
+                segment.from -= 1;
+            }
+            else if (index < segment.from + segment.children.length) {
+                const j = index - segment.from;
+                let offset = 0;
+                for (let k = 0; k < j; k++)
+                    offset += segment.lineCounts[k];
+                segment.lines.splice(offset, segment.lineCounts[j]);
+                segment.children.splice(j, 1);
+                segment.lineCounts.splice(j, 1);
+                segment.generations.splice(j, 1);
+            }
+        }
+        this.segments = this.segments.filter((segment) => segment.children.length > 0);
+    }
+    clear() {
+        this.thaw();
+        super.clear();
+    }
+    invalidate() {
+        this.thaw();
+        super.invalidate();
+    }
+    /** Drop every frozen segment; the next render re-renders all children. */
+    thaw() {
+        this.segments = [];
+        this.frozenWidth = -1;
+    }
+    render(width) {
+        const budget = this.getLiveLineBudget();
+        // A taller terminal widens the live window: thaw so rows now inside it render live.
+        if (width !== this.frozenWidth || budget > this.lastLiveLineBudget)
+            this.thaw();
+        this.lastLiveLineBudget = budget;
+        this.frozenWidth = width;
+        this.stats = { liveChildren: 0, refreshedChildren: 0, refreshedSegments: 0 };
+        this.reconcile(width);
+        const parts = [];
+        const partStarts = [];
+        const live = [];
+        const liveLines = [];
+        let segmentIndex = 0;
+        for (let i = 0; i < this.children.length;) {
+            const segment = this.segments[segmentIndex];
+            let lines;
+            partStarts.push(i);
+            if (segment && segment.from === i) {
+                lines = segment.lines;
+                i += segment.children.length;
+                segmentIndex += 1;
+            }
+            else {
+                lines = this.children[i].render(width);
+                live.push(i);
+                liveLines.push(lines);
+                i += 1;
+            }
+            parts.push(lines);
+        }
+        this.stats.liveChildren = live.length;
+        // Copy before freezing: freezing appends to segment line buffers. Native
+        // concat is a bulk copy; spread arguments stay far below engine limits
+        // because frozen rows arrive as a few hundred segment arrays.
+        const out = parts.length < 8192 ? [].concat(...parts) : parts.flat();
+        this.freezeAboveBudget(parts, partStarts, live, liveLines, budget);
+        return out;
+    }
+    /** Drop unsettled segments and refresh children whose generation moved. */
+    reconcile(width) {
+        const kept = [];
+        for (const segment of this.segments) {
+            let dirty;
+            let settled = true;
+            for (let j = 0; j < segment.children.length; j++) {
+                const child = segment.children[j];
+                if (this.children[segment.from + j] !== child) {
+                    // `children` was edited behind our back: nothing frozen can be trusted.
+                    this.segments = [];
+                    return;
+                }
+                if (!this.isChildSettled(child)) {
+                    settled = false;
+                    break;
+                }
+                if (renderGeneration(child) !== segment.generations[j]) {
+                    dirty ??= [];
+                    dirty.push(j);
+                }
+            }
+            if (!settled)
+                continue;
+            if (dirty)
+                this.refreshSegment(segment, dirty, width);
+            kept.push(segment);
+        }
+        this.segments = kept;
+    }
+    refreshSegment(segment, dirty, width) {
+        const lines = [];
+        let offset = 0;
+        let next = 0;
+        for (let j = 0; j < segment.children.length; j++) {
+            const count = segment.lineCounts[j];
+            if (dirty[next] === j) {
+                next += 1;
+                const child = segment.children[j];
+                const fresh = child.render(width);
+                for (const line of fresh)
+                    lines.push(line);
+                segment.lineCounts[j] = fresh.length;
+                segment.generations[j] = renderGeneration(child);
+                releaseRenderCache(child);
+            }
+            else {
+                for (let l = offset; l < offset + count; l++)
+                    lines.push(segment.lines[l]);
+            }
+            offset += count;
+        }
+        segment.lines = lines;
+        this.stats.refreshedChildren += dirty.length;
+        this.stats.refreshedSegments += 1;
+    }
+    /** Freeze settled live children that sit above the live-line budget. */
+    freezeAboveBudget(parts, partStarts, live, liveLines, budget) {
+        let acc = 0;
+        let liveStart = this.children.length;
+        for (let p = parts.length - 1; p >= 0; p--) {
+            acc += parts[p].length;
+            liveStart = partStarts[p];
+            if (acc >= budget)
+                break;
+        }
+        let segmentIndex = 0;
+        for (let n = 0; n < live.length && live[n] < liveStart; n++) {
+            const index = live[n];
+            const child = this.children[index];
+            if (!this.isChildSettled(child))
+                continue;
+            const lines = liveLines[n];
+            while (segmentIndex < this.segments.length && this.segments[segmentIndex].from < index)
+                segmentIndex += 1;
+            const previous = this.segments[segmentIndex - 1];
+            const generation = renderGeneration(child);
+            if (previous &&
+                previous.from + previous.children.length === index &&
+                previous.lines.length + lines.length <= SEGMENT_MAX_LINES) {
+                previous.children.push(child);
+                previous.lineCounts.push(lines.length);
+                previous.generations.push(generation);
+                for (const line of lines)
+                    previous.lines.push(line);
+            }
+            else {
+                const segment = {
+                    from: index,
+                    children: [child],
+                    lineCounts: [lines.length],
+                    generations: [generation],
+                    lines: lines.slice(),
+                };
+                this.segments.splice(segmentIndex, 0, segment);
+                segmentIndex += 1;
+            }
+            releaseRenderCache(child);
+        }
+    }
+}
+//# sourceMappingURL=windowed-container.js.map

package/dist/windowed-container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windowed-container.js","sourceRoot":"","sources":["../src/windowed-container.ts"],"names":[],"mappings":"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","sourcesContent":["import { isRenderSettled, releaseRenderCache, renderGeneration } from \"./render-generation.ts\";\nimport { type Component, Container } from \"./tui.ts\";\n\n/**\n * A frozen segment never grows past this many lines (a single larger child\n * gets a segment of its own). Bounds the work of refreshing one changed child:\n * only its segment's line buffer is rebuilt, never the whole frozen history.\n */\nconst SEGMENT_MAX_LINES = 512;\n\n/**\n * Live-line budget: the bottom `max(120, 2 × terminal rows)` lines always\n * render live. Two viewports keep components that change without announcing\n * it (animations, stateful extension renderers) live wherever the user can\n * see them, also after scrolling back one screen; the 120 floor is the budget\n * when no viewport is attached and on small terminals.\n */\nconst MIN_LIVE_LINE_BUDGET = 120;\nconst LIVE_VIEWPORTS = 2;\n\n/** Contiguous settled children whose rendered lines are reused verbatim. */\ntype FrozenSegment = {\n\t/** Index in `children` of the first frozen child. */\n\tfrom: number;\n\t/** The frozen children themselves (identity-checked every frame). */\n\tchildren: Component[];\n\tlineCounts: number[];\n\t/** `getRenderGeneration()` of each child when its lines were taken. */\n\tgenerations: number[];\n\t/** Concatenation of the children's lines. */\n\tlines: string[];\n};\n\nexport interface WindowedRenderStats {\n\t/** Children rendered live this frame (live tail plus unsettled gaps). */\n\tliveChildren: number;\n\t/** Frozen children re-rendered because their generation moved. */\n\trefreshedChildren: number;\n\t/** Frozen segments whose line buffer was rebuilt this frame. */\n\trefreshedSegments: number;\n}\n\n/**\n * Container that freezes settled children above a live-line budget into\n * bounded line segments and stops re-rendering them.\n *\n * - Settledness comes from `isRenderSettled()` (missing ⇒ settled). Unsettled\n *   children always render live; settled runs on both sides of them freeze.\n * - Each frozen child remembers its `getRenderGeneration()`. When it moves,\n *   only that child is re-rendered and only its segment is rebuilt.\n * - An unsettled frozen child drops just its segment. Width changes,\n *   `invalidate()`, `clear()` and foreign edits of `children` thaw everything.\n * - Freezing releases the child's render caches (frozen lines are the only\n *   retained copy); a later change re-renders that one child from source.\n */\nexport class WindowedContainer extends Container {\n\tprivate segments: FrozenSegment[] = [];\n\tprivate frozenWidth = -1;\n\tprivate liveLineBudget = MIN_LIVE_LINE_BUDGET;\n\tprivate viewportRows?: () => number;\n\tprivate lastLiveLineBudget = MIN_LIVE_LINE_BUDGET;\n\tprivate stats: WindowedRenderStats = { liveChildren: 0, refreshedChildren: 0, refreshedSegments: 0 };\n\n\t/** Fixed budget (tests, embedders); detaches any viewport set by `setViewportRows`. */\n\tsetLiveLineBudget(lines: number): void {\n\t\tthis.viewportRows = undefined;\n\t\tthis.liveLineBudget = Math.max(1, Math.floor(lines));\n\t}\n\n\t/**\n\t * Follow the terminal height: budget = max(120, 2 × rows), re-read on every\n\t * render so a resize applies on the next frame.\n\t */\n\tsetViewportRows(rows: () => number): void {\n\t\tthis.viewportRows = rows;\n\t}\n\n\tgetLiveLineBudget(): number {\n\t\tif (!this.viewportRows) return this.liveLineBudget;\n\t\tconst rows = Math.floor(this.viewportRows());\n\t\treturn Math.max(MIN_LIVE_LINE_BUDGET, Number.isFinite(rows) ? rows * LIVE_VIEWPORTS : 0);\n\t}\n\n\tgetFrozenChildCount(): number {\n\t\tlet count = 0;\n\t\tfor (const segment of this.segments) count += segment.children.length;\n\t\treturn count;\n\t}\n\n\tgetFrozenLineCount(): number {\n\t\tlet count = 0;\n\t\tfor (const segment of this.segments) count += segment.lines.length;\n\t\treturn count;\n\t}\n\n\t/** Diagnostics: number of frozen segments. */\n\tgetFrozenSegmentCount(): number {\n\t\treturn this.segments.length;\n\t}\n\n\t/** Diagnostics: frozen child index ranges [from, to). */\n\tgetFrozenRanges(): ReadonlyArray<{ from: number; to: number }> {\n\t\treturn this.segments.map((segment) => ({ from: segment.from, to: segment.from + segment.children.length }));\n\t}\n\n\t/** Diagnostics: what the most recent `render` had to redo. */\n\tgetLastRenderStats(): Readonly<WindowedRenderStats> {\n\t\treturn this.stats;\n\t}\n\n\t/** Subclasses may add their own lifecycle knowledge (e.g. an agent_end backstop). */\n\tprotected isChildSettled(child: Component): boolean {\n\t\treturn isRenderSettled(child);\n\t}\n\n\toverride removeChild(component: Component): void {\n\t\tconst index = this.children.indexOf(component);\n\t\tif (index === -1) return;\n\t\tsuper.removeChild(component);\n\t\tfor (const segment of this.segments) {\n\t\t\tif (index < segment.from) {\n\t\t\t\tsegment.from -= 1;\n\t\t\t} else if (index < segment.from + segment.children.length) {\n\t\t\t\tconst j = index - segment.from;\n\t\t\t\tlet offset = 0;\n\t\t\t\tfor (let k = 0; k < j; k++) offset += segment.lineCounts[k];\n\t\t\t\tsegment.lines.splice(offset, segment.lineCounts[j]);\n\t\t\t\tsegment.children.splice(j, 1);\n\t\t\t\tsegment.lineCounts.splice(j, 1);\n\t\t\t\tsegment.generations.splice(j, 1);\n\t\t\t}\n\t\t}\n\t\tthis.segments = this.segments.filter((segment) => segment.children.length > 0);\n\t}\n\n\toverride clear(): void {\n\t\tthis.thaw();\n\t\tsuper.clear();\n\t}\n\n\toverride invalidate(): void {\n\t\tthis.thaw();\n\t\tsuper.invalidate();\n\t}\n\n\t/** Drop every frozen segment; the next render re-renders all children. */\n\tthaw(): void {\n\t\tthis.segments = [];\n\t\tthis.frozenWidth = -1;\n\t}\n\n\toverride render(width: number): string[] {\n\t\tconst budget = this.getLiveLineBudget();\n\t\t// A taller terminal widens the live window: thaw so rows now inside it render live.\n\t\tif (width !== this.frozenWidth || budget > this.lastLiveLineBudget) this.thaw();\n\t\tthis.lastLiveLineBudget = budget;\n\t\tthis.frozenWidth = width;\n\t\tthis.stats = { liveChildren: 0, refreshedChildren: 0, refreshedSegments: 0 };\n\t\tthis.reconcile(width);\n\n\t\tconst parts: string[][] = [];\n\t\tconst partStarts: number[] = [];\n\t\tconst live: number[] = [];\n\t\tconst liveLines: string[][] = [];\n\t\tlet segmentIndex = 0;\n\t\tfor (let i = 0; i < this.children.length; ) {\n\t\t\tconst segment = this.segments[segmentIndex];\n\t\t\tlet lines: string[];\n\t\t\tpartStarts.push(i);\n\t\t\tif (segment && segment.from === i) {\n\t\t\t\tlines = segment.lines;\n\t\t\t\ti += segment.children.length;\n\t\t\t\tsegmentIndex += 1;\n\t\t\t} else {\n\t\t\t\tlines = this.children[i].render(width);\n\t\t\t\tlive.push(i);\n\t\t\t\tliveLines.push(lines);\n\t\t\t\ti += 1;\n\t\t\t}\n\t\t\tparts.push(lines);\n\t\t}\n\t\tthis.stats.liveChildren = live.length;\n\n\t\t// Copy before freezing: freezing appends to segment line buffers. Native\n\t\t// concat is a bulk copy; spread arguments stay far below engine limits\n\t\t// because frozen rows arrive as a few hundred segment arrays.\n\t\tconst out = parts.length < 8192 ? ([] as string[]).concat(...parts) : parts.flat();\n\t\tthis.freezeAboveBudget(parts, partStarts, live, liveLines, budget);\n\t\treturn out;\n\t}\n\n\t/** Drop unsettled segments and refresh children whose generation moved. */\n\tprivate reconcile(width: number): void {\n\t\tconst kept: FrozenSegment[] = [];\n\t\tfor (const segment of this.segments) {\n\t\t\tlet dirty: number[] | undefined;\n\t\t\tlet settled = true;\n\t\t\tfor (let j = 0; j < segment.children.length; j++) {\n\t\t\t\tconst child = segment.children[j];\n\t\t\t\tif (this.children[segment.from + j] !== child) {\n\t\t\t\t\t// `children` was edited behind our back: nothing frozen can be trusted.\n\t\t\t\t\tthis.segments = [];\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tif (!this.isChildSettled(child)) {\n\t\t\t\t\tsettled = false;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tif (renderGeneration(child) !== segment.generations[j]) {\n\t\t\t\t\tdirty ??= [];\n\t\t\t\t\tdirty.push(j);\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (!settled) continue;\n\t\t\tif (dirty) this.refreshSegment(segment, dirty, width);\n\t\t\tkept.push(segment);\n\t\t}\n\t\tthis.segments = kept;\n\t}\n\n\tprivate refreshSegment(segment: FrozenSegment, dirty: number[], width: number): void {\n\t\tconst lines: string[] = [];\n\t\tlet offset = 0;\n\t\tlet next = 0;\n\t\tfor (let j = 0; j < segment.children.length; j++) {\n\t\t\tconst count = segment.lineCounts[j];\n\t\t\tif (dirty[next] === j) {\n\t\t\t\tnext += 1;\n\t\t\t\tconst child = segment.children[j];\n\t\t\t\tconst fresh = child.render(width);\n\t\t\t\tfor (const line of fresh) lines.push(line);\n\t\t\t\tsegment.lineCounts[j] = fresh.length;\n\t\t\t\tsegment.generations[j] = renderGeneration(child);\n\t\t\t\treleaseRenderCache(child);\n\t\t\t} else {\n\t\t\t\tfor (let l = offset; l < offset + count; l++) lines.push(segment.lines[l]);\n\t\t\t}\n\t\t\toffset += count;\n\t\t}\n\t\tsegment.lines = lines;\n\t\tthis.stats.refreshedChildren += dirty.length;\n\t\tthis.stats.refreshedSegments += 1;\n\t}\n\n\t/** Freeze settled live children that sit above the live-line budget. */\n\tprivate freezeAboveBudget(\n\t\tparts: string[][],\n\t\tpartStarts: number[],\n\t\tlive: number[],\n\t\tliveLines: string[][],\n\t\tbudget: number,\n\t): void {\n\t\tlet acc = 0;\n\t\tlet liveStart = this.children.length;\n\t\tfor (let p = parts.length - 1; p >= 0; p--) {\n\t\t\tacc += parts[p].length;\n\t\t\tliveStart = partStarts[p];\n\t\t\tif (acc >= budget) break;\n\t\t}\n\t\tlet segmentIndex = 0;\n\t\tfor (let n = 0; n < live.length && live[n] < liveStart; n++) {\n\t\t\tconst index = live[n];\n\t\t\tconst child = this.children[index];\n\t\t\tif (!this.isChildSettled(child)) continue;\n\t\t\tconst lines = liveLines[n];\n\t\t\twhile (segmentIndex < this.segments.length && this.segments[segmentIndex].from < index) segmentIndex += 1;\n\t\t\tconst previous = this.segments[segmentIndex - 1];\n\t\t\tconst generation = renderGeneration(child);\n\t\t\tif (\n\t\t\t\tprevious &&\n\t\t\t\tprevious.from + previous.children.length === index &&\n\t\t\t\tprevious.lines.length + lines.length <= SEGMENT_MAX_LINES\n\t\t\t) {\n\t\t\t\tprevious.children.push(child);\n\t\t\t\tprevious.lineCounts.push(lines.length);\n\t\t\t\tprevious.generations.push(generation);\n\t\t\t\tfor (const line of lines) previous.lines.push(line);\n\t\t\t} else {\n\t\t\t\tconst segment: FrozenSegment = {\n\t\t\t\t\tfrom: index,\n\t\t\t\t\tchildren: [child],\n\t\t\t\t\tlineCounts: [lines.length],\n\t\t\t\t\tgenerations: [generation],\n\t\t\t\t\tlines: lines.slice(),\n\t\t\t\t};\n\t\t\t\tthis.segments.splice(segmentIndex, 0, segment);\n\t\t\t\tsegmentIndex += 1;\n\t\t\t}\n\t\t\treleaseRenderCache(child);\n\t\t}\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "omk-tui",
-	"version": "1.3.1",
+	"version": "1.4.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"type": "module",
 	"main": "dist/index.js",