@askdkc/dsh-cli 0.11.3

package/lib/types/ink/sixel-graphics.js

@@ -0,0 +1,498 @@
+import { Worker } from 'node:worker_threads';
+import { DEFAULT_TERMINAL_CELL_SIZE, normalizeTerminalCellSize, TERMINAL_IMAGE_MAX_EDGE, TERMINAL_IMAGE_MAX_BYTES, TERMINAL_IMAGE_PREVIEW_MAX_EDGE, TERMINAL_IMAGE_PREVIEW_MAX_BYTES, SIXEL_MAX_ENCODED_BYTES, SIXEL_THUMBNAIL_FRAME_BYTES, SIXEL_CACHE_BYTES, SIXEL_CACHE_ENTRIES, } from './terminal-image.js';
+import { cellAt, clearRegion } from './screen.js';
+import { stringWidth } from './stringWidth.js';
+import { backgroundOpenCode } from './colorize.js';
+function overlaps(a, b) {
+    return a.x < b.x + b.columns && a.x + a.columns > b.x &&
+        a.y < b.y + b.rows && a.y + a.rows > b.y;
+}
+/** Intersection of two cell rects, or undefined when they do not overlap. */
+function intersectRects(a, b) {
+    const x = Math.max(a.x, b.x);
+    const y = Math.max(a.y, b.y);
+    const right = Math.min(a.x + a.columns, b.x + b.columns);
+    const bottom = Math.min(a.y + a.rows, b.y + b.rows);
+    if (right <= x || bottom <= y)
+        return undefined;
+    return { x, y, columns: right - x, rows: bottom - y };
+}
+/** Viewport-owned pixels. Encoding is shared; placement/erasure is per DOM node. */
+export class SixelGraphicsManager {
+    onReady;
+    encoder;
+    cell = DEFAULT_TERMINAL_CELL_SIZE;
+    ids = new WeakMap();
+    nextId = 1;
+    cache = new Map();
+    cachedBytes = 0;
+    readyBytes = 0;
+    active;
+    pending = [];
+    frame = new Map();
+    desired = new Set();
+    displayed = new Map();
+    nextDisplay = new Map();
+    /** Rects kept on screen this frame (replacement pending or covered). */
+    held = new Map();
+    repaint = new Set();
+    worker;
+    workerKeys = new Set();
+    workerReject;
+    disposed = false;
+    dirty = false;
+    columns = 0;
+    rows = 0;
+    displayModeSet = false;
+    constructor(onReady, encoder) {
+        this.onReady = onReady;
+        this.encoder = encoder;
+    }
+    get hasImage() { return this.displayed.size > 0 || this.nextDisplay.size > 0; }
+    setDisplayMode(enabled) {
+        this.displayModeSet = enabled;
+        this.invalidateAll();
+    }
+    setCellSize(cell) {
+        const next = normalizeTerminalCellSize(cell);
+        if (next.width === this.cell.width && next.height === this.cell.height)
+            return false;
+        this.cell = next;
+        this.invalidateAll();
+        return true;
+    }
+    beginFrame(columns, rows) {
+        this.columns = columns;
+        this.rows = rows;
+        this.frame.clear();
+        this.readyBytes = 0;
+    }
+    prepare = (placement) => {
+        if (this.disposed || (placement.presentation !== 'preview' && placement.presentation !== 'transcript'))
+            return false;
+        const variant = this.variant(placement);
+        if (!variant)
+            return false;
+        const raster = this.cache.get(variant.key);
+        const budget = placement.presentation === 'preview' ? SIXEL_MAX_ENCODED_BYTES : SIXEL_THUMBNAIL_FRAME_BYTES;
+        variant.ready = !!raster && this.readyBytes + raster.data.length <= budget;
+        if (variant.ready) {
+            this.readyBytes += raster.data.length;
+            this.cache.delete(variant.key);
+            this.cache.set(variant.key, raster);
+        }
+        this.frame.set(placement.node, variant);
+        return variant.ready;
+    };
+    variant(placement) {
+        let id = this.ids.get(placement.source.data);
+        if (id === undefined) {
+            id = this.nextId++;
+            this.ids.set(placement.source.data, id);
+        }
+        const pixelWidth = placement.columns * this.cell.width;
+        const pixelHeight = placement.rows * this.cell.height;
+        const maxEdge = placement.presentation === 'preview' ? TERMINAL_IMAGE_PREVIEW_MAX_EDGE : TERMINAL_IMAGE_MAX_EDGE;
+        const maxPixels = (placement.presentation === 'preview' ? TERMINAL_IMAGE_PREVIEW_MAX_BYTES : TERMINAL_IMAGE_MAX_BYTES) / 4;
+        // Fit the pixels, not the cell box: encoded letterboxing becomes opaque
+        // black bars when the terminal background itself is transparent.
+        const scale = Math.min(pixelWidth / placement.source.width, pixelHeight / placement.source.height, maxEdge / Math.max(placement.source.width, placement.source.height), Math.sqrt(maxPixels / (placement.source.width * placement.source.height)));
+        let width = Math.max(1, Math.round(placement.source.width * scale));
+        let height = Math.max(1, Math.round(placement.source.height * scale));
+        if (width * height > maxPixels) {
+            if (width >= height)
+                width = Math.floor(maxPixels / height);
+            else
+                height = Math.floor(maxPixels / width);
+        }
+        const canvasColumns = Math.ceil(width / this.cell.width);
+        const canvasRows = Math.ceil(height / this.cell.height);
+        const originX = placement.x + Math.floor((placement.columns - canvasColumns) / 2);
+        const originY = placement.y + Math.floor((placement.rows - canvasRows) / 2);
+        const clip = placement.clip ?? placement;
+        const x = Math.max(0, originX, clip.x);
+        const y = Math.max(0, originY, clip.y);
+        const right = Math.min(this.columns, originX + canvasColumns, clip.x + clip.columns);
+        const bottom = Math.min(this.rows - 1, originY + canvasRows, clip.y + clip.rows);
+        if (right <= x || bottom <= y)
+            return undefined;
+        const left = (x - originX) * this.cell.width;
+        const top = (y - originY) * this.cell.height;
+        const cropWidth = Math.min((right - x) * this.cell.width, width - left);
+        const cropHeight = Math.min((bottom - y) * this.cell.height, height - top, Math.floor((this.rows - y) * this.cell.height / 6) * 6);
+        if (cropWidth <= 0 || cropHeight <= 0)
+            return undefined;
+        const background = placement.background ?? '#000000';
+        const assetKey = `${id}:${placement.source.width}:${placement.source.height}:${width}:${height}:${background}`;
+        const key = `${assetKey}:${left}:${top}:${cropWidth}:${cropHeight}`;
+        return {
+            assetKey, key, placement, ready: false,
+            rect: { x, y, columns: Math.ceil(cropWidth / this.cell.width), rows: Math.ceil(cropHeight / this.cell.height) },
+            request: { source: placement.source, width, height, background, presentation: placement.presentation,
+                crop: { left, top, width: cropWidth, height: cropHeight } },
+        };
+    }
+    /**
+     * Reconcile ALL old rectangles before diffing, with only one baseline copy.
+     *
+     * A rect is erased only when this frame replaces it (a ready raster at a new
+     * key/geometry, erased and drawn in the same write) or drops it entirely.
+     * Rects whose replacement is still being encoded, or which a later paint
+     * covers, are held: erasing them without drawing a replacement in the same
+     * frame is exactly the black flash seen while scrolling and the vanishing
+     * image under an overlay. {@link paint} folds the held rects back into
+     * `displayed`, and the frame that finally replaces one forces a repaint
+     * through the `held` marker.
+     *
+     * A held rect that an overlay PARTLY covers still has to give up the covered
+     * cells: its pixels outlive cell writes (a background-only space cell diffs
+     * as unchanged, so the frame never rewrites it) and would show through the
+     * overlay. Those sub-rects are erased with the placement's surface color.
+     */
+    reconcile(screen, previous, placements) {
+        const actual = placements ? new Map(placements.map(p => [p.node, p])) : undefined;
+        const visible = [];
+        this.desired = new Set();
+        this.nextDisplay.clear();
+        this.held.clear();
+        this.repaint.clear();
+        // Nodes whose raster this frame drops (the paint no longer registers an
+        // image, or a later paint covers every visible cell): their pixels must be
+        // erased, unlike the ones merely held below.
+        const dropped = new Set();
+        for (const [node, variant] of this.frame) {
+            const placement = actual?.get(node);
+            if (actual && !placement) {
+                dropped.add(node);
+                continue;
+            }
+            if (placement?.occludedFully) {
+                dropped.add(node);
+                continue;
+            }
+            visible.push(variant);
+            this.desired.add(variant.key);
+            // Partially covered: drawing would pierce the overlay that covers it, so
+            // keep the pixels already on screen and wait for the cover to clear.
+            if (placement?.occluded)
+                continue;
+            const raster = this.cache.get(variant.key);
+            if (variant.ready && raster && placement?.graphicsReady !== false && this.isUncovered(variant.rect, screen)) {
+                const background = variant.placement.background;
+                this.nextDisplay.set(node, {
+                    ...variant.rect,
+                    key: variant.key,
+                    raster,
+                    ...(background === undefined ? {} : { background }),
+                });
+            }
+        }
+        const unique = new Map();
+        for (const variant of visible) {
+            if (!this.cache.has(variant.key) && this.active?.key !== variant.key)
+                unique.set(variant.key, variant);
+        }
+        this.pending = [...unique.values()].sort((a, b) => Number(b.placement.presentation === 'preview') - Number(a.placement.presentation === 'preview'));
+        this.drain();
+        const erased = [];
+        let coverErase = '';
+        for (const [node, old] of this.displayed) {
+            const next = this.nextDisplay.get(node);
+            if (next !== undefined) {
+                if (this.dirty || old.key !== next.key || old.x !== next.x || old.y !== next.y)
+                    erased.push(old);
+                continue;
+            }
+            // Still requested this frame, but its replacement raster is not ready
+            // (scrolling re-crops per row and the encoder is async) or a later paint
+            // covers it. Erasing here would leave a hole with no draw in the same
+            // frame — the black flash while scrolling and the vanishing image under
+            // a tooltip. Keep the pixels already on screen until a replacement can
+            // be drawn in the same write.
+            if (!this.dirty && this.frame.has(node) && !dropped.has(node)) {
+                const placement = actual?.get(node);
+                const coveredRects = placement?.coveredRects;
+                const coveredKey = coveredRects === undefined || coveredRects.length === 0
+                    ? undefined
+                    : coveredRects.map(rect => `${rect.x},${rect.y},${rect.width},${rect.height}`).join(';');
+                if (coveredKey !== undefined && coveredKey !== old.covered) {
+                    // The overlay paints these cells, but only the ones whose style
+                    // changes get a write: an unchanged background-only space keeps the
+                    // raster's pixels. Erase the covered cells (with the surface color,
+                    // so they match the cell model) and leave the rest held.
+                    const visibleRect = { x: old.x, y: old.y, columns: old.columns, rows: old.rows };
+                    for (const rect of coveredRects) {
+                        const clipped = intersectRects(visibleRect, { x: rect.x, y: rect.y, columns: rect.width, rows: rect.height });
+                        if (clipped !== undefined)
+                            coverErase += this.erase(clipped, old.background);
+                    }
+                }
+                this.held.set(node, coveredKey === undefined
+                    ? { ...old, held: true }
+                    : { ...old, held: true, covered: coveredKey });
+                continue;
+            }
+            erased.push(old);
+        }
+        for (const [node, next] of this.nextDisplay) {
+            const old = this.displayed.get(node);
+            if (!old || this.dirty || old.held === true ||
+                old.key !== next.key || old.x !== next.x || old.y !== next.y ||
+                erased.some(rect => overlaps(rect, next)))
+                this.repaint.add(node);
+        }
+        if (erased.length === 0) {
+            return coverErase === ''
+                ? { erase: '', baseline: previous }
+                : { erase: coverErase + '\x1b[H', baseline: previous };
+        }
+        const cells = previous.cells.slice();
+        const baseline = { ...previous, cells, cells64: new BigInt64Array(cells.buffer), noSelect: previous.noSelect.slice() };
+        let erase = '';
+        for (const rect of erased) {
+            clearRegion(baseline, rect.x, rect.y, rect.columns, rect.rows);
+            // Erase at the terminal default, never at the placement's surface color:
+            // clearRegion just reset these cells to a default blank in the model, so
+            // the frame writes back everything it has to show and leaves the rest
+            // alone — an erase filled with the surface color would keep that color
+            // on screen with no write to correct it (the white card of a closed
+            // light-theme preview, cleared only when unrelated text scrolls past).
+            erase += this.erase(rect);
+        }
+        return { erase: coverErase + erase + '\x1b[H', baseline };
+    }
+    /** Unchanged images have zero transport cost, including unrelated text ticks. */
+    paint(diff) {
+        let damage;
+        let draw = '';
+        for (const [node, next] of this.nextDisplay) {
+            if (!this.dirty && !this.repaint.has(node)) {
+                if (damage === undefined)
+                    damage = this.textDamage(diff);
+                if (damage !== null && !damage.some(rect => overlaps(rect, next)))
+                    continue;
+            }
+            draw += `\x1b[${next.y + 1};${next.x + 1}H${next.raster.data}`;
+        }
+        this.displayed = new Map(this.nextDisplay);
+        // Rects held this frame stay on screen: they were neither erased nor
+        // redrawn, so the terminal still shows them.
+        for (const [node, entry] of this.held)
+            this.displayed.set(node, entry);
+        this.dirty = false;
+        if (draw === '')
+            return '';
+        return this.displayModeSet ? `\x1b[?80l${draw}\x1b[?80h` : draw;
+    }
+    invalidateAll() { this.dirty = true; }
+    clear() {
+        const output = [...this.displayed.values()].map(rect => this.erase(rect)).join('');
+        this.displayed.clear();
+        this.nextDisplay.clear();
+        this.held.clear();
+        this.frame.clear();
+        this.desired.clear();
+        this.pending = [];
+        return output === '' ? '' : output + '\x1b[H';
+    }
+    dispose() {
+        const output = this.clear();
+        this.disposed = true;
+        this.cache.clear();
+        this.cachedBytes = 0;
+        this.workerReject?.(new Error('Sixel worker disposed'));
+        this.workerReject = undefined;
+        void this.worker?.terminate();
+        this.worker = undefined;
+        this.workerKeys.clear();
+        return output;
+    }
+    erase(rect, background) {
+        const columns = Math.min(rect.columns, this.columns - rect.x);
+        const rows = Math.min(rect.rows, this.rows - rect.y);
+        if (columns <= 0 || rows <= 0)
+            return '';
+        // Erase-Character fills with the cell's current background and is the only
+        // way to drop pixels a frame never rewrites. The surface color is for the
+        // one rect the frame cannot correct afterwards — cells a later paint
+        // covers while keeping their style (see reconcile); every caller that
+        // hands those cells back to the diff passes no color.
+        // The placement carries the raw color string; Color is its renderer form.
+        const open = background === undefined ? '' : backgroundOpenCode(background);
+        let data = `\x1b[0m${open}`;
+        for (let y = rect.y; y < rect.y + rows; y++)
+            data += `\x1b[${y + 1};${rect.x + 1}H\x1b[${columns}X`;
+        if (open !== '')
+            data += '\x1b[0m';
+        return data;
+    }
+    isUncovered(rect, screen) {
+        // Any visible glyph under the raster blocks it; background-only cells do
+        // not. Image-owned cells carry the surface background in Sixel mode (an
+        // opaque backing is required there), and comparing against the empty
+        // style would reject the raster's own backing.
+        for (let y = rect.y; y < rect.y + rect.rows; y++) {
+            for (let x = rect.x; x < rect.x + rect.columns; x++) {
+                const cell = cellAt(screen, x, y);
+                if (cell && cell.char !== ' ' && cell.char !== '')
+                    return false;
+            }
+        }
+        return true;
+    }
+    textDamage(diff) {
+        const regions = [];
+        let x = 0;
+        let y = 0;
+        for (const patch of diff) {
+            if (patch.type === 'clear' || patch.type === 'clearTerminal')
+                return null;
+            if (patch.type === 'cursorMove') {
+                x += patch.x;
+                y += patch.y;
+            }
+            else if (patch.type === 'cursorTo')
+                x = patch.col;
+            else if (patch.type === 'carriageReturn')
+                x = 0;
+            else if (patch.type === 'stdout') {
+                if (patch.content.includes('\x1b'))
+                    return null;
+                for (const line of patch.content.split(/(?<=\n)/u)) {
+                    const width = stringWidth(line.replace(/[\r\n]/gu, ''));
+                    if (width)
+                        regions.push({ x, y, columns: width, rows: 1 });
+                    x += width;
+                    if (x > this.columns)
+                        return null;
+                    if (line.includes('\r'))
+                        x = 0;
+                    if (line.endsWith('\n')) {
+                        y++;
+                        x = 0;
+                    }
+                }
+            }
+        }
+        return regions;
+    }
+    drain() {
+        if (this.active || this.disposed)
+            return;
+        const job = this.pending.shift();
+        if (!job)
+            return;
+        if (!this.desired.has(job.key) || this.cache.has(job.key)) {
+            this.drain();
+            return;
+        }
+        this.active = job;
+        void (this.encoder ? this.encoder(job.request) : this.encodeInWorker(job))
+            .then(raster => this.complete(job, raster), () => this.complete(job, null))
+            .finally(() => { this.active = undefined; this.drain(); });
+    }
+    complete(job, raster) {
+        if (this.disposed)
+            return;
+        this.cachedBytes -= this.cache.get(job.key)?.data.length ?? 0;
+        this.cache.delete(job.key);
+        this.cache.set(job.key, raster);
+        this.cachedBytes += raster?.data.length ?? 0;
+        while (this.cache.size > SIXEL_CACHE_ENTRIES || this.cachedBytes > SIXEL_CACHE_BYTES) {
+            const key = this.cache.keys().next().value;
+            this.cachedBytes -= this.cache.get(key)?.data.length ?? 0;
+            this.cache.delete(key);
+        }
+        if (this.desired.has(job.key))
+            this.onReady();
+    }
+    encodeInWorker(job) {
+        return new Promise((resolve, reject) => {
+            if (!this.worker) {
+                this.workerKeys.clear();
+                this.worker = new Worker(new URL('./sixel-worker.js', import.meta.url), {
+                    stdout: true, stderr: true, resourceLimits: { maxOldGenerationSizeMb: 256 },
+                });
+                const worker = this.worker;
+                const forget = () => {
+                    if (this.worker === worker) {
+                        this.worker = undefined;
+                        this.workerKeys.clear();
+                    }
+                };
+                worker.on('error', forget);
+                worker.once('exit', forget);
+                worker.stdout?.resume();
+                worker.stderr?.resume();
+            }
+            const worker = this.worker;
+            worker.ref();
+            let retried = false;
+            const finish = (error, raster) => {
+                clearTimeout(timeout);
+                worker.removeListener('message', onMessage);
+                worker.removeListener('error', onError);
+                worker.removeListener('exit', onExit);
+                this.workerReject = undefined;
+                if (error) {
+                    if (this.worker === worker) {
+                        this.worker = undefined;
+                        this.workerKeys.clear();
+                    }
+                    void worker.terminate();
+                    reject(error);
+                }
+                else {
+                    worker.unref();
+                    resolve(raster);
+                }
+            };
+            const send = (includeSource) => {
+                const { source, ...request } = job.request;
+                const message = { assetKey: job.assetKey, request };
+                if (includeSource) {
+                    // Copy only these pixels, never detach a shared Buffer or clone its pool.
+                    const data = new Uint8Array(source.data);
+                    worker.postMessage({ ...message, request: { ...request, source: { ...source, data } } }, [data.buffer]);
+                }
+                else
+                    worker.postMessage(message);
+            };
+            const onMessage = (message) => {
+                if (message.missing && !retried) {
+                    retried = true;
+                    try {
+                        send(true);
+                    }
+                    catch {
+                        finish(new Error('Sixel worker unavailable'));
+                    }
+                    return;
+                }
+                const r = message.raster;
+                const expected = job.request.crop ?? job.request;
+                if (!r || r.width !== expected.width || r.height !== expected.height ||
+                    typeof r.data !== 'string' || r.data.length > SIXEL_MAX_ENCODED_BYTES) {
+                    finish(new Error('Sixel encoding failed'));
+                }
+                else {
+                    this.workerKeys = new Set(message.preparedKeys ?? []);
+                    finish(undefined, r);
+                }
+            };
+            const onError = (error) => finish(error);
+            const onExit = () => finish(new Error('Sixel worker exited'));
+            const timeout = setTimeout(() => finish(new Error('Sixel encoding timed out')), 30_000);
+            this.workerReject = onError;
+            worker.on('message', onMessage);
+            worker.once('error', onError);
+            worker.once('exit', onExit);
+            try {
+                send(!this.workerKeys.has(job.assetKey));
+            }
+            catch {
+                finish(new Error('Sixel worker unavailable'));
+            }
+        });
+    }
+}

package/lib/types/ink/sixel-worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sixel-worker.d.ts.map

package/lib/types/ink/sixel-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sixel-worker.d.ts","sourceRoot":"","sources":["../../../src/ink/sixel-worker.ts"],"names":[],"mappings":""}

package/lib/types/ink/sixel-worker.js

@@ -0,0 +1,12 @@
+import { parentPort } from 'node:worker_threads';
+import { SixelEncoderCache } from './sixel-codec.js';
+const cache = new SixelEncoderCache();
+parentPort?.on('message', async (request) => {
+    try {
+        parentPort?.postMessage(await cache.render(request));
+    }
+    catch {
+        // Do not send image contents, paths or native decoder diagnostics to TTY.
+        parentPort?.postMessage({ error: true });
+    }
+});

package/lib/types/ink/squash-text-nodes.d.ts

@@ -0,0 +1,30 @@
+import type { DOMElement } from './dom.js';
+import type { TextStyles } from './styles.js';
+/**
+ * A segment of text with its associated styles.
+ * Used for structured rendering without ANSI string transforms.
+ */
+export type StyledSegment = {
+    text: string;
+    styles: TextStyles;
+    hyperlink?: string;
+};
+/**
+ * Squash text nodes into styled segments, propagating styles down through the tree.
+ * This allows structured styling without relying on ANSI string transforms.
+ * @param node - the subtree root whose text nodes are collected.
+ * @param inheritedStyles - styles inherited from ancestors, merged with the node's own.
+ * @param inheritedHyperlink - the hyperlink inherited from ancestor ink-link elements.
+ * @param out - the array segments are appended to; defaults to a fresh array.
+ * @returns `out` containing one segment per non-empty text node.
+ */
+export declare function squashTextNodesToSegments(node: DOMElement, inheritedStyles?: TextStyles, inheritedHyperlink?: string, out?: StyledSegment[]): StyledSegment[];
+/**
+ * Squash text nodes into a plain string (without styles).
+ * Used for text measurement in layout calculations.
+ * @param node - the subtree root whose text nodes are concatenated.
+ * @returns the concatenated text content of every text node in the subtree.
+ */
+declare function squashTextNodes(node: DOMElement): string;
+export default squashTextNodes;
+//# sourceMappingURL=squash-text-nodes.d.ts.map

package/lib/types/ink/squash-text-nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"squash-text-nodes.d.ts","sourceRoot":"","sources":["../../../src/ink/squash-text-nodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,UAAU,EAChB,eAAe,GAAE,UAAe,EAChC,kBAAkB,CAAC,EAAE,MAAM,EAC3B,GAAG,GAAE,aAAa,EAAO,GACxB,aAAa,EAAE,CAwCjB;AAED;;;;;GAKG;AACH,iBAAS,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAqBjD;AAED,eAAe,eAAe,CAAA"}

package/lib/types/ink/squash-text-nodes.js

@@ -0,0 +1,63 @@
+/**
+ * Squash text nodes into styled segments, propagating styles down through the tree.
+ * This allows structured styling without relying on ANSI string transforms.
+ * @param node - the subtree root whose text nodes are collected.
+ * @param inheritedStyles - styles inherited from ancestors, merged with the node's own.
+ * @param inheritedHyperlink - the hyperlink inherited from ancestor ink-link elements.
+ * @param out - the array segments are appended to; defaults to a fresh array.
+ * @returns `out` containing one segment per non-empty text node.
+ */
+export function squashTextNodesToSegments(node, inheritedStyles = {}, inheritedHyperlink, out = []) {
+    const mergedStyles = node.textStyles
+        ? { ...inheritedStyles, ...node.textStyles }
+        : inheritedStyles;
+    for (const childNode of node.childNodes) {
+        if (childNode === undefined) {
+            continue;
+        }
+        if (childNode.nodeName === '#text') {
+            if (childNode.nodeValue.length > 0) {
+                out.push({
+                    text: childNode.nodeValue,
+                    styles: mergedStyles,
+                    hyperlink: inheritedHyperlink,
+                });
+            }
+        }
+        else if (childNode.nodeName === 'ink-text' ||
+            childNode.nodeName === 'ink-virtual-text') {
+            squashTextNodesToSegments(childNode, mergedStyles, inheritedHyperlink, out);
+        }
+        else if (childNode.nodeName === 'ink-link') {
+            const href = childNode.attributes['href'];
+            squashTextNodesToSegments(childNode, mergedStyles, href || inheritedHyperlink, out);
+        }
+    }
+    return out;
+}
+/**
+ * Squash text nodes into a plain string (without styles).
+ * Used for text measurement in layout calculations.
+ * @param node - the subtree root whose text nodes are concatenated.
+ * @returns the concatenated text content of every text node in the subtree.
+ */
+function squashTextNodes(node) {
+    let text = '';
+    for (const childNode of node.childNodes) {
+        if (childNode === undefined) {
+            continue;
+        }
+        if (childNode.nodeName === '#text') {
+            text += childNode.nodeValue;
+        }
+        else if (childNode.nodeName === 'ink-text' ||
+            childNode.nodeName === 'ink-virtual-text') {
+            text += squashTextNodes(childNode);
+        }
+        else if (childNode.nodeName === 'ink-link') {
+            text += squashTextNodes(childNode);
+        }
+    }
+    return text;
+}
+export default squashTextNodes;

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

@@ -0,0 +1,3 @@
+/** Terminal display cells, including ANSI, emoji and combining marks. */
+export declare const stringWidth: (str: string) => number;
+//# sourceMappingURL=stringWidth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stringWidth.d.ts","sourceRoot":"","sources":["../../../src/ink/stringWidth.ts"],"names":[],"mappings":"AAwQA,yEAAyE;AACzE,eAAO,MAAM,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAA8B,CAAA"}