@north-light/api 0.3.579 → 0.3.587

package/dist/clients/attach/render/markdown-source.js

@@ -0,0 +1,279 @@
+// Source-text transforms the attach viewer applies before pi-tui parses a
+// Markdown block. Every transform here rewrites the DISPLAY copy only —
+// persisted messages and copied text stay ordinary Markdown without terminal
+// escape sequences.
+//
+// HEADINGS. pi-tui's MarkdownTheme exposes one `heading(text)` callback without
+// the heading depth. Its renderer does know the depth, but does not pass it to
+// the theme, so every heading otherwise receives the same yellow mdHeading
+// paint. Decorate only the source text of H3–H6: pi still owns parsing,
+// wrapping, inline formatting, and H1/H2's established styling.
+//
+// XML TAG LINES. crouter's own context is XML-framed (`<crtr-bearings>`,
+// `<memory …>`, `<environment …>`), and agents quote XML in replies. A line
+// that is nothing but a tag opens a CommonMark HTML block, which runs to the
+// next blank line and renders as undecorated raw text — so `# Heading` on the
+// line after `<memory …>` came out as literal text with its `#`, and a closing
+// tag hanging off a list got absorbed into the last list item. Painting the tag
+// line means it no longer starts with `<`, so no HTML block opens and the
+// Markdown inside the envelope parses normally; a blank line on each side keeps
+// the tag from joining the paragraph or list beside it.
+//
+// GLYPHS. Private-use `U+XXXX` references become their glyphs (see
+// glyph-codepoints.ts), so an agent that cannot type a Nerd Font character can
+// still put one on screen.
+import { pathToFileURL } from 'node:url';
+import { expandGlyphCodepoints } from './glyph-codepoints.js';
+import { rewriteProseDocLinks } from './doc-links.js';
+const ATX_HEADING = /^(\s{0,3})(#{3,6})(?:[ \t]+|$)(.*?)([ \t]+#+[ \t]*)?$/;
+const FENCE_OPEN = /^\s{0,3}(`{3,}|~{3,})/;
+/** A line holding one tag and nothing else: `<name …>`, `</name>`, `<name/>`.
+ *  Attribute text may not contain angle brackets, so a tag whose value carries
+ *  a literal `>` stays untouched rather than being mis-split. */
+const XML_TAG_LINE = /^([ \t]{0,3})(<\/?)([A-Za-z][\w.:-]*)((?:[ \t]+[^<>]*?)?)(\/?)>[ \t]*$/;
+const XML_ATTRIBUTE = /([^\s=]+)(?:=("[^"]*"|'[^']*'|[^\s]*))?/g;
+// A constant-lightness ramp from warm yellow to cool blue, with saturation
+// deliberately reduced at each step so the hierarchy recedes rather than
+// becoming a tour of unrelated accent colors.
+const HEADING_COLORS = [
+    [232, 194, 104],
+    [207, 194, 145],
+    [181, 184, 174],
+    [157, 170, 180],
+    [135, 153, 164],
+    [116, 135, 147],
+];
+// Structural framing, not content. The hue relationships mirror the XML
+// highlighting pi already applies inside fenced code — blue tag name, duller
+// blue attribute, warm quoted value — at a lower brightness, because an
+// envelope tag wrapping prose should be scannable without competing with the
+// prose the way a code block does.
+const XML_PUNCTUATION = [104, 112, 124];
+const XML_NAME = [138, 166, 196];
+const XML_ATTRIBUTE_NAME = [124, 146, 164];
+const XML_VALUE = [168, 142, 118];
+/** Paint a fragment with a foreground color and restore only the foreground,
+ *  so a surrounding message style (background, weight) survives. */
+function paint(color, text) {
+    return `\x1b[38;2;${color[0]};${color[1]};${color[2]}m${text}\x1b[39m`;
+}
+function headingColor(level) {
+    const [r, g, b] = HEADING_COLORS[level - 1];
+    return (text) => `\x1b[1;38;2;${r};${g};${b}m${text}\x1b[22;39m`;
+}
+/** Style one ATX H3–H6 line. The Markdown markers are syntax, not content, so
+ *  omit them from the rendered line. */
+function styleHeadingLine(line) {
+    const match = ATX_HEADING.exec(line);
+    if (!match)
+        return undefined;
+    const [, indent, hashes, body] = match;
+    if (body === '')
+        return undefined;
+    return `${indent}${headingColor(hashes.length)(body)}`;
+}
+function styleAttributes(attributes) {
+    return attributes.replace(XML_ATTRIBUTE, (whole, name, value) => (value === undefined
+        ? paint(XML_ATTRIBUTE_NAME, whole)
+        : `${paint(XML_ATTRIBUTE_NAME, name)}${paint(XML_PUNCTUATION, '=')}${paint(XML_VALUE, value)}`));
+}
+/** Style a line that is exactly one XML tag, or return undefined to leave it. */
+function styleXmlTagLine(line) {
+    const match = XML_TAG_LINE.exec(line);
+    if (!match)
+        return undefined;
+    const [, indent, open, name, attributes, selfClose] = match;
+    return indent
+        + paint(XML_PUNCTUATION, open)
+        + paint(XML_NAME, name)
+        + styleAttributes(attributes)
+        + paint(XML_PUNCTUATION, `${selfClose}>`);
+}
+/** Decorate a Markdown block for terminal rendering: heading hierarchy and XML
+ *  tag lines. Fenced examples remain literal Markdown, never decorated
+ *  terminal output. */
+export function styleAttachMarkdownSource(markdown) {
+    const lines = markdown.split('\n');
+    const out = [];
+    let fence;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const fenceMatch = FENCE_OPEN.exec(line);
+        if (fence !== undefined) {
+            if (fenceMatch?.[1][0] === fence)
+                fence = undefined;
+            out.push(line);
+            continue;
+        }
+        if (fenceMatch) {
+            fence = fenceMatch[1][0];
+            out.push(line);
+            continue;
+        }
+        const tag = styleXmlTagLine(line);
+        if (tag !== undefined) {
+            if (out.length > 0 && out[out.length - 1].trim() !== '')
+                out.push('');
+            out.push(tag);
+            if (lines[index + 1] !== undefined && lines[index + 1].trim() !== '')
+                out.push('');
+            continue;
+        }
+        out.push(styleHeadingLine(line) ?? line);
+    }
+    return out.join('\n');
+}
+/** Every source-text transform the viewer applies to AGENT-authored Markdown,
+ *  in one place: heading and XML syntax, then glyph expansion. A human's own
+ *  message keeps `styleAttachMarkdownSource` alone — the `U+XXXX` escape hatch
+ *  exists for agents that cannot type a Nerd Font character. */
+export function styleAttachAgentMarkdown(markdown) {
+    return expandGlyphCodepoints(styleAttachMarkdownSource(rewriteAbsoluteFileLinks(markdown)));
+}
+/** Give iTerm a hidden fragment so its Semantic History action receives the local target,
+ *  and name `[[owner/name]]` document links readably (render/doc-links.ts). */
+function rewriteAbsoluteFileLinks(markdown) {
+    return rewriteProse(markdown, (prose) => rewriteProseFileLinks(rewriteProseDocLinks(prose)));
+}
+/** Name `[[owner/name]]` document links readably and link them to their
+ *  materialized page (render/doc-links.ts), leaving code spans and fences
+ *  literal. For Markdown the viewer renders outside the transcript — inbox
+ *  pages and inline page blocks. */
+export function rewriteMarkdownDocLinks(markdown) {
+    return markdown.includes('[[') ? rewriteProse(markdown, (prose) => rewriteProseDocLinks(prose)) : markdown;
+}
+/** Apply `rewrite` to every prose fragment of `markdown`, never to a code span or fence. */
+function rewriteProse(markdown, rewrite) {
+    let fence;
+    return markdown.split('\n').map((line) => {
+        const fenceMatch = FENCE_OPEN.exec(line);
+        if (fence !== undefined) {
+            if (fenceMatch?.[1][0] === fence)
+                fence = undefined;
+            return line;
+        }
+        if (fenceMatch) {
+            fence = fenceMatch[1][0];
+            return line;
+        }
+        return rewriteInlineProse(line, rewrite);
+    }).join('\n');
+}
+function rewriteInlineProse(line, rewrite) {
+    let result = '';
+    let rest = line;
+    while (rest !== '') {
+        const opening = rest.match(/`+/);
+        const prose = opening === null ? rest : rest.slice(0, opening.index);
+        result += rewrite(prose);
+        if (opening === null)
+            break;
+        const delimiter = opening[0];
+        const end = rest.indexOf(delimiter, prose.length + delimiter.length);
+        if (end === -1)
+            return result + rest.slice(prose.length);
+        result += rest.slice(prose.length, end + delimiter.length);
+        rest = rest.slice(end + delimiter.length);
+    }
+    return result;
+}
+function rewriteProseFileLinks(prose) {
+    let result = '';
+    let index = 0;
+    while (index < prose.length) {
+        const start = prose.indexOf('[', index);
+        if (start === -1)
+            return result + prose.slice(index);
+        const link = parseLocalMarkdownLink(prose, start);
+        if (link === undefined) {
+            result += prose.slice(index, start + 1);
+            index = start + 1;
+            continue;
+        }
+        result += prose.slice(index, start) + `[${link.label}](${pathToFileURL(link.path).href}#crtr-file-open)`;
+        index = link.end;
+    }
+    return result;
+}
+function parseLocalMarkdownLink(line, start) {
+    const labelEnd = closingDelimiter(line, start + 1, ']');
+    if (labelEnd === undefined || line[labelEnd + 1] !== '(')
+        return undefined;
+    const destinationStart = labelEnd + 2;
+    if (line[destinationStart] === '<') {
+        const destinationEnd = closingDelimiter(line, destinationStart + 1, '>');
+        if (destinationEnd === undefined || line[destinationEnd + 1] !== ')')
+            return undefined;
+        const path = localPathFromDestination(line.slice(destinationStart + 1, destinationEnd));
+        return path === undefined ? undefined : { label: line.slice(start + 1, labelEnd), path, end: destinationEnd + 2 };
+    }
+    let depth = 0;
+    for (let index = destinationStart; index < line.length; index++) {
+        if (line[index] === '\\') {
+            index++;
+            continue;
+        }
+        if (line[index] === '(') {
+            depth++;
+            continue;
+        }
+        if (line[index] !== ')' || depth-- > 0)
+            continue;
+        const path = localPathFromDestination(line.slice(destinationStart, index));
+        return path === undefined ? undefined : { label: line.slice(start + 1, labelEnd), path, end: index + 1 };
+    }
+    return undefined;
+}
+function closingDelimiter(text, start, delimiter) {
+    for (let index = start; index < text.length; index++) {
+        if (text[index] === '\\') {
+            index++;
+            continue;
+        }
+        if (text[index] === delimiter)
+            return index;
+    }
+    return undefined;
+}
+function localPathFromDestination(destination) {
+    const unescaped = destination.replace(/\\([!"#$%&'()*+,./:;<=>?@[\\\]^_`{|}~-])/g, '$1');
+    let path = unescaped;
+    try {
+        path = decodeURIComponent(unescaped);
+    }
+    catch {
+        // A literal percent is legal in a path but not in URI decoding.
+    }
+    return path.startsWith('/') ? path : undefined;
+}
+/** Copy a pi message for terminal rendering and decorate only Markdown-bearing
+ * text/thinking blocks. The broker's source event is never mutated. */
+export function styleAttachMessageMarkdown(message) {
+    if (typeof message !== 'object' || message === null || !('content' in message))
+        return message;
+    const candidate = message;
+    if (typeof candidate.content === 'string') {
+        return { ...candidate, content: styleAttachAgentMarkdown(candidate.content) };
+    }
+    if (!Array.isArray(candidate.content))
+        return message;
+    return {
+        ...candidate,
+        content: candidate.content.map((part) => {
+            if (typeof part !== 'object' || part === null)
+                return part;
+            const block = part;
+            if (block.type === 'text' && typeof block.text === 'string') {
+                return { ...block, text: styleAttachAgentMarkdown(block.text) };
+            }
+            if (block.type === 'thinking' && typeof block.thinking === 'string') {
+                return { ...block, thinking: styleAttachAgentMarkdown(block.thinking) };
+            }
+            return part;
+        }),
+    };
+}
+/** Copy an expanded pi summary without changing its persisted source. */
+export function styleAttachSummaryMarkdown(message) {
+    return { ...message, summary: styleAttachAgentMarkdown(message.summary) };
+}

package/dist/clients/attach/render/measured-container.d.ts

@@ -0,0 +1,96 @@
+import { Container, type Component } from '@earendil-works/pi-tui';
+/** The block at the viewport's top row, plus the line offset within it. */
+export interface ScrollAnchor {
+    block: Component;
+    offset: number;
+}
+/** A measurable, sliceable ordered block list. The viewport never touches
+ * components directly — it addresses blocks by flat index, and holds scroll
+ * position as a block identity. */
+export interface ViewportSource {
+    /** Visible blocks, in visual order. */
+    blockCount(): number;
+    /** Rendered line count of block `i` at `width` (renders + caches on miss). */
+    blockHeight(i: number, width: number): number;
+    /** Cached rendered lines of block `i` at `width`. */
+    blockLines(i: number, width: number): readonly string[];
+    /** Total rendered lines at `width`. */
+    totalHeight(width: number): number;
+    /** Absolute content line at which block `i` starts. */
+    blockStart(i: number, width: number): number;
+    /** The block component at flat index `i`. */
+    blockAt(i: number): Component | undefined;
+    /** The anchor for the block containing absolute line `line`. */
+    anchorAt(line: number, width: number): ScrollAnchor | undefined;
+    /** Absolute top line for `anchor` against current measurements, or undefined
+     * when the block is gone entirely. */
+    anchorLine(anchor: ScrollAnchor, width: number): number | undefined;
+    /** Clear cached measurements after a component-level invalidation. */
+    invalidate(): void;
+    /** Monotonic; bumped by every structural or content mutation. */
+    revision(): number;
+}
+/**
+ * A container whose direct children are independently rendered and measured.
+ *
+ * `children` is public on pi-tui's Container, but it must never be mutated from
+ * outside these methods: this class owns the visible-index, height, and prefix
+ * invariants that make identity anchors safe across transcript mutations.
+ */
+export declare class MeasuredContainer extends Container implements ViewportSource {
+    private readonly childCache;
+    /** Direct children hidden by a collapsed tool-group summary. Never wrap a
+     * child: the cache and pi callback paths both key on this exact identity. */
+    readonly hiddenChildren: Set<Component>;
+    /** Rendered line counts for visible children at `measureWidth`. */
+    private heights;
+    /** `prefix[i]` is the start line of visible child `i`. */
+    private prefix;
+    /** The first visible-child index whose prefix onward must be rebuilt. */
+    private prefixValidTo;
+    private visibleChildren;
+    private measureWidth;
+    private mutationRevision;
+    addChild(component: Component): void;
+    setHidden(component: Component, hidden: boolean): void;
+    markDirty(component?: Component): void;
+    removeChild(component: Component): void;
+    clear(): void;
+    invalidate(): void;
+    render(width: number): string[];
+    blockCount(): number;
+    blockHeight(index: number, width: number): number;
+    blockLines(index: number, width: number): readonly string[];
+    totalHeight(width: number): number;
+    blockStart(index: number, width: number): number;
+    blockAt(index: number): Component | undefined;
+    anchorAt(line: number, width: number): ScrollAnchor | undefined;
+    anchorLine(anchor: ScrollAnchor, width: number): number | undefined;
+    revision(): number;
+    private visible;
+    private visibleIndexOf;
+    private ensureWidth;
+    private dropMeasurements;
+    private linesFor;
+    private rawLinesFor;
+    private invalidateHeight;
+    /** Rebuild the prefix ending at `endExclusive`; `prefixValidTo` is the first
+     * child whose height/prefix may be stale, so `prefix[prefixValidTo]` is valid. */
+    private rebuildPrefixThrough;
+}
+/** Concatenates measured containers into the transcript's one flat block space. */
+export declare class CompositeViewportSource implements ViewportSource {
+    private readonly parts;
+    constructor(parts: readonly MeasuredContainer[]);
+    blockCount(): number;
+    blockHeight(index: number, width: number): number;
+    blockLines(index: number, width: number): readonly string[];
+    totalHeight(width: number): number;
+    blockStart(index: number, width: number): number;
+    blockAt(index: number): Component | undefined;
+    anchorAt(line: number, width: number): ScrollAnchor | undefined;
+    anchorLine(anchor: ScrollAnchor, width: number): number | undefined;
+    invalidate(): void;
+    revision(): number;
+    private locate;
+}

package/dist/clients/attach/render/measured-container.js

@@ -0,0 +1,322 @@
+import { Container } from '@earendil-works/pi-tui';
+/**
+ * A container whose direct children are independently rendered and measured.
+ *
+ * `children` is public on pi-tui's Container, but it must never be mutated from
+ * outside these methods: this class owns the visible-index, height, and prefix
+ * invariants that make identity anchors safe across transcript mutations.
+ */
+export class MeasuredContainer extends Container {
+    childCache = new Map();
+    /** Direct children hidden by a collapsed tool-group summary. Never wrap a
+     * child: the cache and pi callback paths both key on this exact identity. */
+    hiddenChildren = new Set();
+    /** Rendered line counts for visible children at `measureWidth`. */
+    heights = [];
+    /** `prefix[i]` is the start line of visible child `i`. */
+    prefix = [0];
+    /** The first visible-child index whose prefix onward must be rebuilt. */
+    prefixValidTo = 0;
+    visibleChildren;
+    measureWidth;
+    mutationRevision = 0;
+    addChild(component) {
+        const visibleCount = this.visible().length;
+        super.addChild(component);
+        this.visibleChildren = undefined;
+        this.heights.push(undefined);
+        this.prefixValidTo = Math.min(this.prefixValidTo, visibleCount);
+        this.mutationRevision++;
+    }
+    setHidden(component, hidden) {
+        const wasHidden = this.hiddenChildren.has(component);
+        const oldVisibleIndex = wasHidden ? undefined : this.visibleIndexOf(component);
+        if (hidden)
+            this.hiddenChildren.add(component);
+        else
+            this.hiddenChildren.delete(component);
+        this.childCache.delete(component);
+        if (!wasHidden && hidden && oldVisibleIndex !== undefined) {
+            this.heights.splice(oldVisibleIndex, 1);
+            this.invalidateHeight(oldVisibleIndex);
+        }
+        else if (wasHidden && !hidden) {
+            this.visibleChildren = undefined;
+            const insertionIndex = this.visibleIndexOf(component);
+            if (insertionIndex !== undefined) {
+                this.heights.splice(insertionIndex, 0, undefined);
+                this.invalidateHeight(insertionIndex);
+                this.invalidateHeight(insertionIndex + 1);
+            }
+        }
+        else if (oldVisibleIndex !== undefined) {
+            // Preserve RenderCacheContainer's behavior when this is called with the
+            // current state: evict this child and re-measure it on its next render.
+            this.invalidateHeight(oldVisibleIndex);
+            this.invalidateHeight(oldVisibleIndex + 1);
+        }
+        this.visibleChildren = undefined;
+        this.mutationRevision++;
+    }
+    markDirty(component) {
+        if (component) {
+            const visibleIndex = this.visibleIndexOf(component);
+            this.childCache.delete(component);
+            if (visibleIndex !== undefined) {
+                this.invalidateHeight(visibleIndex);
+                this.invalidateHeight(visibleIndex + 1);
+            }
+        }
+        else {
+            this.dropMeasurements();
+        }
+        this.mutationRevision++;
+    }
+    removeChild(component) {
+        const visibleIndex = this.visibleIndexOf(component);
+        super.removeChild(component);
+        this.childCache.delete(component);
+        this.hiddenChildren.delete(component);
+        if (visibleIndex !== undefined) {
+            this.heights.splice(visibleIndex, 1);
+            this.invalidateHeight(visibleIndex);
+        }
+        this.visibleChildren = undefined;
+        this.mutationRevision++;
+    }
+    clear() {
+        super.clear();
+        this.childCache.clear();
+        this.hiddenChildren.clear();
+        this.heights = [];
+        this.prefix = [0];
+        this.prefixValidTo = 0;
+        this.visibleChildren = undefined;
+        this.mutationRevision++;
+    }
+    invalidate() {
+        super.invalidate();
+        this.dropMeasurements();
+        this.mutationRevision++;
+    }
+    render(width) {
+        this.ensureWidth(width);
+        const lines = [];
+        for (let i = 0; i < this.visible().length; i++)
+            lines.push(...this.linesFor(i, width));
+        return lines;
+    }
+    blockCount() {
+        return this.visible().length;
+    }
+    blockHeight(index, width) {
+        this.ensureWidth(width);
+        return this.linesFor(index, width).length;
+    }
+    blockLines(index, width) {
+        this.ensureWidth(width);
+        return this.linesFor(index, width);
+    }
+    totalHeight(width) {
+        this.ensureWidth(width);
+        this.rebuildPrefixThrough(this.visible().length, width);
+        return this.prefix[this.visible().length] ?? 0;
+    }
+    blockStart(index, width) {
+        this.ensureWidth(width);
+        if (index < 0 || index >= this.visible().length)
+            return 0;
+        this.rebuildPrefixThrough(index, width);
+        return this.prefix[index] ?? 0;
+    }
+    blockAt(index) {
+        return this.visible()[index];
+    }
+    anchorAt(line, width) {
+        this.ensureWidth(width);
+        const count = this.visible().length;
+        this.rebuildPrefixThrough(count, width);
+        const total = this.prefix[count] ?? 0;
+        if (line < 0 || line >= total)
+            return undefined;
+        let low = 0;
+        let high = count - 1;
+        while (low <= high) {
+            const middle = Math.floor((low + high) / 2);
+            const start = this.prefix[middle] ?? 0;
+            const end = this.prefix[middle + 1] ?? start;
+            if (line < start)
+                high = middle - 1;
+            else if (line >= end)
+                low = middle + 1;
+            else
+                return { block: this.visible()[middle], offset: line - start };
+        }
+        return undefined;
+    }
+    anchorLine(anchor, width) {
+        this.ensureWidth(width);
+        const childIndex = this.children.indexOf(anchor.block);
+        if (childIndex === -1)
+            return undefined;
+        const visibleIndex = this.visibleIndexOf(anchor.block);
+        if (visibleIndex !== undefined) {
+            const height = this.blockHeight(visibleIndex, width);
+            if (height === 0)
+                return this.blockStart(visibleIndex, width);
+            return this.blockStart(visibleIndex, width) + Math.min(anchor.offset, height - 1);
+        }
+        // A hidden child resolves to the visible sibling that preceded it, so a fold
+        // leaves the viewport on its summary rather than throwing it to live bottom.
+        for (let i = childIndex - 1; i >= 0; i--) {
+            const preceding = this.children[i];
+            const precedingVisibleIndex = this.visibleIndexOf(preceding);
+            if (precedingVisibleIndex !== undefined)
+                return this.blockStart(precedingVisibleIndex, width);
+        }
+        return 0;
+    }
+    revision() {
+        return this.mutationRevision;
+    }
+    visible() {
+        if (!this.visibleChildren)
+            this.visibleChildren = this.children.filter((child) => !this.hiddenChildren.has(child));
+        return this.visibleChildren;
+    }
+    visibleIndexOf(component) {
+        const index = this.visible().indexOf(component);
+        return index === -1 ? undefined : index;
+    }
+    ensureWidth(width) {
+        if (this.measureWidth === width)
+            return;
+        this.measureWidth = width;
+        this.dropMeasurements();
+    }
+    dropMeasurements() {
+        this.childCache.clear();
+        this.heights = this.visible().map(() => undefined);
+        this.prefix = [0];
+        this.prefixValidTo = 0;
+    }
+    linesFor(index, width) {
+        const lines = this.rawLinesFor(index, width);
+        const previous = this.rawLinesFor(index - 1, width);
+        // Transcript blocks own their own one-row outer breathing room. Like CSS
+        // margins, adjacent blank boundaries collapse instead of summing to two.
+        const rendered = previous.at(-1) === '' && lines[0] === '' ? lines.slice(1) : lines;
+        this.heights[index] = rendered.length;
+        return rendered;
+    }
+    rawLinesFor(index, width) {
+        const child = this.visible()[index];
+        if (!child)
+            return [];
+        let cached = this.childCache.get(child);
+        if (!cached || cached.width !== width) {
+            cached = { width, lines: child.render(width) };
+            this.childCache.set(child, cached);
+        }
+        return cached.lines;
+    }
+    invalidateHeight(index) {
+        if (index < 0)
+            return;
+        if (index < this.heights.length)
+            this.heights[index] = undefined;
+        this.prefix.length = this.heights.length + 1;
+        this.prefixValidTo = Math.min(this.prefixValidTo, Math.min(index, this.heights.length));
+    }
+    /** Rebuild the prefix ending at `endExclusive`; `prefixValidTo` is the first
+     * child whose height/prefix may be stale, so `prefix[prefixValidTo]` is valid. */
+    rebuildPrefixThrough(endExclusive, width) {
+        const count = this.visible().length;
+        const end = Math.min(Math.max(endExclusive, 0), count);
+        const start = Math.min(this.prefixValidTo, end);
+        if (this.prefix.length === 0)
+            this.prefix = [0];
+        this.prefix[0] = 0;
+        for (let i = start; i < end; i++) {
+            const height = this.heights[i] ?? this.linesFor(i, width).length;
+            this.prefix[i + 1] = (this.prefix[i] ?? 0) + height;
+        }
+        if (end > this.prefixValidTo)
+            this.prefixValidTo = end;
+    }
+}
+/** Concatenates measured containers into the transcript's one flat block space. */
+export class CompositeViewportSource {
+    parts;
+    constructor(parts) {
+        this.parts = parts;
+    }
+    blockCount() {
+        return this.parts.reduce((count, part) => count + part.blockCount(), 0);
+    }
+    blockHeight(index, width) {
+        const located = this.locate(index);
+        return located ? located.part.blockHeight(located.index, width) : 0;
+    }
+    blockLines(index, width) {
+        const located = this.locate(index);
+        return located ? located.part.blockLines(located.index, width) : [];
+    }
+    totalHeight(width) {
+        return this.parts.reduce((total, part) => total + part.totalHeight(width), 0);
+    }
+    blockStart(index, width) {
+        let offset = 0;
+        for (const part of this.parts) {
+            const count = part.blockCount();
+            if (index < count)
+                return offset + part.blockStart(index, width);
+            index -= count;
+            offset += part.totalHeight(width);
+        }
+        return 0;
+    }
+    blockAt(index) {
+        const located = this.locate(index);
+        return located?.part.blockAt(located.index);
+    }
+    anchorAt(line, width) {
+        if (line < 0)
+            return undefined;
+        for (const part of this.parts) {
+            const height = part.totalHeight(width);
+            if (line < height)
+                return part.anchorAt(line, width);
+            line -= height;
+        }
+        return undefined;
+    }
+    anchorLine(anchor, width) {
+        let offset = 0;
+        for (const part of this.parts) {
+            const line = part.anchorLine(anchor, width);
+            if (line !== undefined)
+                return offset + line;
+            offset += part.totalHeight(width);
+        }
+        return undefined;
+    }
+    invalidate() {
+        for (const part of this.parts)
+            part.invalidate();
+    }
+    revision() {
+        return this.parts.reduce((revision, part) => revision + part.revision(), 0);
+    }
+    locate(index) {
+        if (index < 0)
+            return undefined;
+        for (const part of this.parts) {
+            const count = part.blockCount();
+            if (index < count)
+                return { part, index };
+            index -= count;
+        }
+        return undefined;
+    }
+}