@svelterm/core 0.1.0 → 0.23.0

package/dist/src/render/color-depth.js

@@ -0,0 +1,59 @@
+/**
+ * Colour quantization for terminals without truecolor: hex → the xterm
+ * 256-colour palette, or the nearest of the 16 base colours.
+ */
+/** Nominal xterm RGB values for the 16 SGR names. */
+const BASE16 = [
+    { name: 'black', rgb: [0, 0, 0] },
+    { name: 'red', rgb: [205, 0, 0] },
+    { name: 'green', rgb: [0, 205, 0] },
+    { name: 'yellow', rgb: [205, 205, 0] },
+    { name: 'blue', rgb: [0, 0, 238] },
+    { name: 'magenta', rgb: [205, 0, 205] },
+    { name: 'cyan', rgb: [0, 205, 205] },
+    { name: 'white', rgb: [229, 229, 229] },
+];
+function hexToRgb(hex) {
+    return [
+        parseInt(hex.slice(1, 3), 16),
+        parseInt(hex.slice(3, 5), 16),
+        parseInt(hex.slice(5, 7), 16),
+    ];
+}
+/** The 0–5 colour-cube step nearest a channel value, per xterm's levels. */
+const CUBE_LEVELS = [0, 95, 135, 175, 215, 255];
+function nearestCubeStep(value) {
+    let best = 0;
+    for (let i = 1; i < CUBE_LEVELS.length; i++) {
+        if (Math.abs(CUBE_LEVELS[i] - value) < Math.abs(CUBE_LEVELS[best] - value))
+            best = i;
+    }
+    return best;
+}
+function distance(a, b) {
+    return (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2;
+}
+/** Map #rrggbb to the nearest xterm 256-palette index (cube or grey ramp). */
+export function quantizeTo256(hex) {
+    const rgb = hexToRgb(hex);
+    const [r, g, b] = rgb;
+    const steps = [nearestCubeStep(r), nearestCubeStep(g), nearestCubeStep(b)];
+    const cubeIndex = 16 + 36 * steps[0] + 6 * steps[1] + steps[2];
+    const cubeRgb = [CUBE_LEVELS[steps[0]], CUBE_LEVELS[steps[1]], CUBE_LEVELS[steps[2]]];
+    // Grey ramp: 232–255 covering 8..238 in steps of 10
+    const grey = Math.round((r + g + b) / 3);
+    const greyStep = Math.min(23, Math.max(0, Math.round((grey - 8) / 10)));
+    const greyValue = 8 + greyStep * 10;
+    const greyRgb = [greyValue, greyValue, greyValue];
+    return distance(rgb, greyRgb) < distance(rgb, cubeRgb) ? 232 + greyStep : cubeIndex;
+}
+/** Map #rrggbb to the nearest of the 16 base colour names. */
+export function quantizeTo16(hex) {
+    const rgb = hexToRgb(hex);
+    let best = BASE16[0];
+    for (const candidate of BASE16) {
+        if (distance(rgb, candidate.rgb) < distance(rgb, best.rgb))
+            best = candidate;
+    }
+    return best.name;
+}

package/dist/src/render/context.d.ts

@@ -11,6 +11,7 @@ export declare class RenderContext {
     onSetText(node: TermNode, newText: string): void;
     onSetAttribute(node: TermNode, key: string, value: string): void;
     onRemoveAttribute(node: TermNode, key: string): void;
+    private invalidateStyles;
     onInsert(parent: TermNode, child: TermNode): void;
     onRemove(child: TermNode, parent: TermNode): void;
     onScroll(node: TermNode): void;

package/dist/src/render/context.js

@@ -19,35 +19,31 @@ export class RenderContext {
         this.onScheduleRender?.();
     }
     onSetAttribute(node, key, value) {
-        if (key === 'class') {
-            if (node.cache.classAttr === value)
-                return; // no change
+        if (node.attributes.get(key) === value)
+            return; // no change
+        // Any attribute can participate in selector matching ([attr=…],
+        // :checked, details[open] > …, inline style), so re-resolve the
+        // node and its descendants.
+        if (key === 'class')
             node.cache.classAttr = value;
-            node.invalidateStyle();
-            this.queue.enqueueStyleResolve(node);
-            // Also invalidate descendants — descendant selectors may change
-            this.invalidateDescendantStyles(node);
-        }
-        else if (key === 'id' || key === 'data-focused' || key === 'data-hovered') {
-            node.invalidateStyle();
-            this.queue.enqueueStyleResolve(node);
-        }
-        else {
-            this.queue.enqueuePaintOnly(node);
-        }
         node.attributes.set(key, value);
+        this.invalidateStyles(node);
         this.onScheduleRender?.();
     }
     onRemoveAttribute(node, key) {
-        node.attributes.delete(key);
-        if (key === 'class' || key === 'id' || key === 'data-focused' || key === 'data-hovered') {
+        if (!node.attributes.has(key))
+            return; // no change
+        if (key === 'class')
             node.cache.classAttr = '';
-            node.invalidateStyle();
-            this.queue.enqueueStyleResolve(node);
-            this.invalidateDescendantStyles(node);
-        }
+        node.attributes.delete(key);
+        this.invalidateStyles(node);
         this.onScheduleRender?.();
     }
+    invalidateStyles(node) {
+        node.invalidateStyle();
+        this.queue.enqueueStyleResolve(node);
+        this.invalidateDescendantStyles(node);
+    }
     onInsert(parent, child) {
         // New node needs full computation
         child.invalidateAll();

package/dist/src/render/cursor-emit.d.ts

@@ -0,0 +1,18 @@
+import { TermNode } from '../renderer/node.js';
+/**
+ * After every paint, decide where the real terminal cursor should be
+ * and emit ANSI to position it.
+ *
+ * Priority:
+ *   1. Focused node owns a cursor (focused input/textarea publishes one
+ *      via cache.cursorScreen) — show it at that position, or hide if
+ *      the cursor cell is outside its content viewport. Region cursors
+ *      stay dormant in this branch.
+ *   2. Otherwise walk the tree for an `<svt-region>` with a registered
+ *      cursor (e.g. an embedded terminal mirroring its shell prompt).
+ *   3. Otherwise hide the cursor.
+ *
+ * Always returns a non-empty string — `hideCursor()` on miss — so the
+ * caller doesn't need to track transitions.
+ */
+export declare function emitFocusCursor(root: TermNode, focused: TermNode | null): string;

package/dist/src/render/cursor-emit.js

@@ -0,0 +1,50 @@
+import { SvtRegionNode } from '../renderer/node.js';
+import * as ansi from './ansi.js';
+/**
+ * After every paint, decide where the real terminal cursor should be
+ * and emit ANSI to position it.
+ *
+ * Priority:
+ *   1. Focused node owns a cursor (focused input/textarea publishes one
+ *      via cache.cursorScreen) — show it at that position, or hide if
+ *      the cursor cell is outside its content viewport. Region cursors
+ *      stay dormant in this branch.
+ *   2. Otherwise walk the tree for an `<svt-region>` with a registered
+ *      cursor (e.g. an embedded terminal mirroring its shell prompt).
+ *   3. Otherwise hide the cursor.
+ *
+ * Always returns a non-empty string — `hideCursor()` on miss — so the
+ * caller doesn't need to track transitions.
+ */
+export function emitFocusCursor(root, focused) {
+    const focusedPos = focused?.getCursorScreenPos();
+    if (focusedPos) {
+        if (!focusedPos.inViewport)
+            return ansi.hideCursor() + ansi.resetCursorShape();
+        // A bar reads as "text insertion point"; everything else keeps the
+        // terminal's configured shape.
+        return ansi.moveTo(focusedPos.x + 1, focusedPos.y + 1)
+            + ansi.setCursorShape('bar') + ansi.showCursor();
+    }
+    const regionOut = findRegionCursor(root);
+    if (regionOut)
+        return ansi.resetCursorShape() + regionOut;
+    return ansi.hideCursor() + ansi.resetCursorShape();
+}
+function findRegionCursor(node) {
+    if (node instanceof SvtRegionNode) {
+        const cursor = node.getCursor();
+        if (cursor) {
+            const x = node.lastBoxX + cursor.col + 1;
+            const y = node.lastBoxY + cursor.row + 1;
+            const visibility = cursor.visible ? ansi.showCursor() : ansi.hideCursor();
+            return ansi.moveTo(x, y) + visibility;
+        }
+    }
+    for (const child of node.children) {
+        const out = findRegionCursor(child);
+        if (out)
+            return out;
+    }
+    return null;
+}

package/dist/src/render/diff.d.ts

@@ -1,2 +1,14 @@
 import { CellBuffer } from './buffer.js';
+export interface VerticalShift {
+    /** Rows content moved: +N = scrolled up (content moved toward row 0). */
+    delta: number;
+    /** Row indices in `next` that are newly revealed (must be repainted). */
+    enteringRows: number[];
+}
+/**
+ * Detect whether `next` is `prev` translated vertically by ±N rows over
+ * the full width — a scroll. Returns null unless the retained rows match
+ * exactly and at least one row is reused (so a scroll command saves work).
+ */
+export declare function detectVerticalShift(prev: CellBuffer, next: CellBuffer): VerticalShift | null;
 export declare function diffBuffers(prev: CellBuffer | null, next: CellBuffer): string;

package/dist/src/render/diff.js

@@ -1,6 +1,65 @@
 import { cellsEqual } from './buffer.js';
 import * as ansi from './ansi.js';
+/**
+ * Detect whether `next` is `prev` translated vertically by ±N rows over
+ * the full width — a scroll. Returns null unless the retained rows match
+ * exactly and at least one row is reused (so a scroll command saves work).
+ */
+export function detectVerticalShift(prev, next) {
+    if (prev.width !== next.width || prev.height !== next.height)
+        return null;
+    const height = next.height;
+    for (let delta = 1; delta < height; delta++) {
+        if (rowsMatchShifted(prev, next, delta)) {
+            return { delta, enteringRows: range(height - delta, height) };
+        }
+        if (rowsMatchShifted(prev, next, -delta)) {
+            return { delta: -delta, enteringRows: range(0, delta) };
+        }
+    }
+    return null;
+}
+/**
+ * Do next's retained rows equal prev shifted up (delta>0) or down
+ * (delta<0)? next row R comes from prev row R+delta; rows whose source
+ * falls off the buffer are the entering rows and aren't compared.
+ */
+function rowsMatchShifted(prev, next, delta) {
+    const height = next.height;
+    let comparedAny = false;
+    for (let row = 0; row < height; row++) {
+        const sourceRow = row + delta;
+        if (sourceRow < 0 || sourceRow >= height)
+            continue; // an entering row
+        comparedAny = true;
+        if (!rowsEqual(prev, next, sourceRow, row))
+            return false;
+    }
+    return comparedAny;
+}
+function rowsEqual(a, b, aRow, bRow) {
+    for (let col = 0; col < a.width; col++) {
+        const ca = a.getCell(col, aRow);
+        const cb = b.getCell(col, bRow);
+        if (!ca || !cb || !cellsEqual(ca, cb))
+            return false;
+    }
+    return true;
+}
+function range(start, end) {
+    const out = [];
+    for (let i = start; i < end; i++)
+        out.push(i);
+    return out;
+}
 export function diffBuffers(prev, next) {
+    // Whole-screen scroll: let the terminal shift rows via DECSTBM instead
+    // of rewriting every cell. Only the entering rows are painted.
+    if (prev) {
+        const shift = detectVerticalShift(prev, next);
+        if (shift)
+            return scrollDiff(next, shift);
+    }
     const parts = [];
     let lastStyle = null;
     let currentHyperlink = undefined;
@@ -10,6 +69,9 @@ export function diffBuffers(prev, next) {
             const prevCell = prev?.getCell(col, row);
             if (prevCell && cellsEqual(prevCell, cell))
                 continue;
+            // Continuation cell of a wide glyph — the glyph writes it
+            if (cell.char === '')
+                continue;
             parts.push(ansi.moveTo(col + 1, row + 1));
             const styleCode = buildStyleCode(cell);
             if (styleCode !== lastStyle) {
@@ -33,6 +95,62 @@ export function diffBuffers(prev, next) {
         parts.push(ansi.resetStyle());
     return parts.join('');
 }
+/**
+ * Emit a scroll via DECSTBM: set the region to the full height, index
+ * (or reverse-index) |delta| times to shift the retained rows, then
+ * paint only the entering rows. Resets the region afterwards.
+ */
+function scrollDiff(next, shift) {
+    const parts = [ansi.setScrollRegion(1, next.height)];
+    const count = Math.abs(shift.delta);
+    if (shift.delta > 0) {
+        // Scrolled up: cursor to bottom, index N times (each scrolls up)
+        parts.push(ansi.moveTo(1, next.height));
+        for (let i = 0; i < count; i++)
+            parts.push(ansi.index());
+    }
+    else {
+        // Scrolled down: cursor to top, reverse-index N times
+        parts.push(ansi.moveTo(1, 1));
+        for (let i = 0; i < count; i++)
+            parts.push(ansi.reverseIndex());
+    }
+    parts.push(ansi.resetScrollRegion());
+    parts.push(paintRows(next, shift.enteringRows));
+    return parts.join('');
+}
+/** Paint the given rows in full (used for the entering rows of a scroll). */
+function paintRows(next, rows) {
+    const parts = [];
+    let lastStyle = null;
+    let currentHyperlink = undefined;
+    for (const row of rows) {
+        for (let col = 0; col < next.width; col++) {
+            const cell = next.getCell(col, row);
+            if (cell.char === '')
+                continue;
+            parts.push(ansi.moveTo(col + 1, row + 1));
+            const styleCode = buildStyleCode(cell);
+            if (styleCode !== lastStyle) {
+                parts.push(ansi.resetStyle(), styleCode);
+                lastStyle = styleCode;
+            }
+            if (cell.hyperlink !== currentHyperlink) {
+                if (currentHyperlink)
+                    parts.push(ansi.hyperlinkClose());
+                if (cell.hyperlink)
+                    parts.push(ansi.hyperlinkOpen(cell.hyperlink));
+                currentHyperlink = cell.hyperlink;
+            }
+            parts.push(cell.char);
+        }
+    }
+    if (currentHyperlink)
+        parts.push(ansi.hyperlinkClose());
+    if (parts.length > 0)
+        parts.push(ansi.resetStyle());
+    return parts.join('');
+}
 function buildStyleCode(cell) {
     const parts = [];
     if (cell.fg !== 'default')
@@ -49,5 +167,7 @@ function buildStyleCode(cell) {
         parts.push(ansi.underline());
     if (cell.strikethrough)
         parts.push(ansi.strikethrough());
+    if (cell.inverse)
+        parts.push(ansi.inverse());
     return parts.join('');
 }

package/dist/src/render/generation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Full-paint generation counter. Values cached on nodes during paint
+ * (cursor positions) carry the generation that wrote them; a full paint
+ * bumps it, so anything culled that frame reads as absent instead of
+ * reporting stale coordinates. Incremental paints don't bump — nodes
+ * they skip are unchanged, so their cached values stay valid.
+ */
+export declare function bumpPaintGeneration(): number;
+export declare function paintGeneration(): number;

package/dist/src/render/generation.js

@@ -0,0 +1,14 @@
+/**
+ * Full-paint generation counter. Values cached on nodes during paint
+ * (cursor positions) carry the generation that wrote them; a full paint
+ * bumps it, so anything culled that frame reads as absent instead of
+ * reporting stale coordinates. Incremental paints don't bump — nodes
+ * they skip are unchanged, so their cached values stay valid.
+ */
+let generation = 0;
+export function bumpPaintGeneration() {
+    return ++generation;
+}
+export function paintGeneration() {
+    return generation;
+}

package/dist/src/render/graphics-layer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Graphics layer — post-frame kitty-image placement over `<img>` boxes.
+ * The half-block cells are still painted into the buffer (fallback and
+ * layout truth); when the terminal supports kitty graphics, this covers
+ * them with real pixels, keyed to each img node.
+ *
+ * Correctness over cleverness: each frame deletes the previous placement
+ * for every img we track and re-places the visible ones, so a moved,
+ * resized, scrolled-away, or unmounted image never leaves a ghost. Pixel
+ * data transmits once per (node, src).
+ */
+import { TermNode } from '../renderer/node.js';
+import type { LayoutBox } from '../layout/engine.js';
+export declare class GraphicsLayer {
+    private tracked;
+    private nextId;
+    /**
+     * Emit graphics commands for the current frame: clear last frame's
+     * placements, then transmit (once) and place every visible img.
+     * Returns the ANSI to write after the cell diff.
+     */
+    render(root: TermNode, layout: Map<number, LayoutBox> | undefined): string;
+    /** Delete every active placement (teardown, suspend). */
+    clear(): string;
+    private entryFor;
+    private collectVisibleImages;
+}

package/dist/src/render/graphics-layer.js

@@ -0,0 +1,86 @@
+/**
+ * Graphics layer — post-frame kitty-image placement over `<img>` boxes.
+ * The half-block cells are still painted into the buffer (fallback and
+ * layout truth); when the terminal supports kitty graphics, this covers
+ * them with real pixels, keyed to each img node.
+ *
+ * Correctness over cleverness: each frame deletes the previous placement
+ * for every img we track and re-places the visible ones, so a moved,
+ * resized, scrolled-away, or unmounted image never leaves a ghost. Pixel
+ * data transmits once per (node, src).
+ */
+import { moveTo } from './ansi.js';
+import { transmitImage, placeImage, deletePlacement } from './kitty-graphics.js';
+import { imageFor } from './image.js';
+export class GraphicsLayer {
+    tracked = new Map();
+    nextId = 1;
+    /**
+     * Emit graphics commands for the current frame: clear last frame's
+     * placements, then transmit (once) and place every visible img.
+     * Returns the ANSI to write after the cell diff.
+     */
+    render(root, layout) {
+        const parts = [];
+        const visible = layout ? this.collectVisibleImages(root, layout) : [];
+        const visibleIds = new Set(visible.map(v => v.node.id));
+        // Clear placements that were shown last frame (moved or gone)
+        for (const [nodeId, entry] of this.tracked) {
+            if (entry.placed && !visibleIds.has(nodeId)) {
+                parts.push(deletePlacement(entry.imageId, entry.placementId));
+                entry.placed = false;
+            }
+        }
+        for (const { node, box } of visible) {
+            const image = imageFor(node);
+            if (!image)
+                continue;
+            const entry = this.entryFor(node.id);
+            const src = node.attributes.get('src') ?? '';
+            if (entry.transmittedSrc !== src) {
+                parts.push(transmitImage(entry.imageId, image));
+                entry.transmittedSrc = src;
+            }
+            // Re-place every frame so it tracks the box exactly
+            if (entry.placed)
+                parts.push(deletePlacement(entry.imageId, entry.placementId));
+            parts.push(moveTo(box.x + 1, box.y + 1));
+            parts.push(placeImage(entry.imageId, entry.placementId, box.width, box.height));
+            entry.placed = true;
+        }
+        return parts.join('');
+    }
+    /** Delete every active placement (teardown, suspend). */
+    clear() {
+        const parts = [];
+        for (const entry of this.tracked.values()) {
+            if (entry.placed) {
+                parts.push(deletePlacement(entry.imageId, entry.placementId));
+                entry.placed = false;
+            }
+        }
+        return parts.join('');
+    }
+    entryFor(nodeId) {
+        let entry = this.tracked.get(nodeId);
+        if (!entry) {
+            entry = { imageId: this.nextId++, placementId: 1, transmittedSrc: null, placed: false };
+            this.tracked.set(nodeId, entry);
+        }
+        return entry;
+    }
+    collectVisibleImages(node, layout) {
+        const out = [];
+        const walk = (n) => {
+            if (n.nodeType === 'element' && n.tag === 'img') {
+                const box = layout.get(n.id);
+                if (box && box.width > 0 && box.height > 0 && imageFor(n))
+                    out.push({ node: n, box });
+            }
+            for (const child of n.children)
+                walk(child);
+        };
+        walk(node);
+        return out;
+    }
+}

package/dist/src/render/image.d.ts

@@ -0,0 +1,27 @@
+/**
+ * <img> support: pixel store, async source loading (file path or
+ * data:image/png URI), and half-block painting — each cell shows two
+ * vertically stacked pixels via '▀' with fg = top, bg = bottom.
+ */
+import { TermNode } from '../renderer/node.js';
+import { CellBuffer } from './buffer.js';
+import { type DecodedImage } from './png.js';
+import type { LayoutBox } from '../layout/engine.js';
+/** The decoded image for a node, if its current src has loaded. */
+export declare function imageFor(node: TermNode): DecodedImage | null;
+/** Directly provide pixels (embedders, tests) — bypasses src loading. */
+export declare function setImagePixels(node: TermNode, image: DecodedImage): void;
+/** Kick off an async load of the node's src if not already under way. */
+export declare function ensureImageLoading(node: TermNode): void;
+/** Intrinsic size in cells: 1 px per column, 2 px per row (half-blocks). */
+export declare function imageIntrinsicSize(node: TermNode): {
+    width: number;
+    height: number;
+} | null;
+/** Paint the image into its box as half-blocks, nearest-neighbour scaled. */
+export declare function paintImage(node: TermNode, buffer: CellBuffer, box: LayoutBox, clip?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null): void;

package/dist/src/render/image.js

@@ -0,0 +1,113 @@
+/**
+ * <img> support: pixel store, async source loading (file path or
+ * data:image/png URI), and half-block painting — each cell shows two
+ * vertically stacked pixels via '▀' with fg = top, bg = bottom.
+ */
+import { decodePng } from './png.js';
+const imagesByNode = new WeakMap();
+const loadedSrcByNode = new WeakMap();
+/** The decoded image for a node, if its current src has loaded. */
+export function imageFor(node) {
+    if (loadedSrcByNode.get(node) !== node.attributes.get('src'))
+        return null;
+    const state = imagesByNode.get(node);
+    return state?.kind === 'loaded' ? state.image : null;
+}
+/** Directly provide pixels (embedders, tests) — bypasses src loading. */
+export function setImagePixels(node, image) {
+    imagesByNode.set(node, { kind: 'loaded', image });
+    loadedSrcByNode.set(node, node.attributes.get('src') ?? '');
+}
+/** Kick off an async load of the node's src if not already under way. */
+export function ensureImageLoading(node) {
+    const src = node.attributes.get('src');
+    if (!src)
+        return;
+    if (loadedSrcByNode.get(node) === src)
+        return;
+    loadedSrcByNode.set(node, src);
+    imagesByNode.set(node, { kind: 'loading' });
+    loadSource(src).then(image => {
+        // src may have changed while decoding
+        if (loadedSrcByNode.get(node) !== src)
+            return;
+        imagesByNode.set(node, { kind: 'loaded', image });
+        invalidate(node, 'loaded');
+    }).catch(() => {
+        if (loadedSrcByNode.get(node) !== src)
+            return;
+        imagesByNode.set(node, { kind: 'failed' });
+        invalidate(node, 'failed');
+    });
+}
+/**
+ * Pixels arriving change the element's *intrinsic size*, which no style
+ * property reflects — invalidate layout directly, not just styles.
+ */
+function invalidate(node, state) {
+    node.attributes.set('data-image', state);
+    if (!node.ctx)
+        return;
+    node.ctx.queue.enqueueLayoutBubble(node);
+    node.ctx.onScheduleRender?.();
+}
+async function loadSource(src) {
+    if (src.startsWith('data:image/png;base64,')) {
+        const base64 = src.slice('data:image/png;base64,'.length);
+        return decodePng(base64ToBytes(base64));
+    }
+    if (src.startsWith('data:'))
+        throw new Error('Only data:image/png URIs are supported');
+    const fs = await import('node:fs/promises');
+    return decodePng(new Uint8Array(await fs.readFile(src)));
+}
+function base64ToBytes(base64) {
+    if (typeof Buffer !== 'undefined')
+        return new Uint8Array(Buffer.from(base64, 'base64'));
+    const binary = atob(base64);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+/** Intrinsic size in cells: 1 px per column, 2 px per row (half-blocks). */
+export function imageIntrinsicSize(node) {
+    const image = imageFor(node);
+    if (!image)
+        return null;
+    return { width: image.width, height: Math.ceil(image.height / 2) };
+}
+/** Paint the image into its box as half-blocks, nearest-neighbour scaled. */
+export function paintImage(node, buffer, box, clip) {
+    const image = imageFor(node);
+    if (!image || box.width <= 0 || box.height <= 0)
+        return;
+    const pxHeight = box.height * 2;
+    for (let row = 0; row < box.height; row++) {
+        const y = box.y + row;
+        if (clip && (y < clip.y || y >= clip.y + clip.height))
+            continue;
+        for (let col = 0; col < box.width; col++) {
+            const x = box.x + col;
+            if (clip && (x < clip.x || x >= clip.x + clip.width))
+                continue;
+            const top = sample(image, col, row * 2, box.width, pxHeight);
+            const bottom = sample(image, col, row * 2 + 1, box.width, pxHeight);
+            buffer.setCell(x, y, {
+                char: '▀',
+                fg: top,
+                bg: bottom,
+            });
+        }
+    }
+}
+/** Nearest-neighbour sample scaled to (targetW × targetH); hex colour. */
+function sample(image, x, y, targetW, targetH) {
+    const sx = Math.min(image.width - 1, Math.floor((x / targetW) * image.width));
+    const sy = Math.min(image.height - 1, Math.floor((y / targetH) * image.height));
+    const at = (sy * image.width + sx) * 4;
+    if (image.rgba[at + 3] < 128)
+        return 'default'; // transparent → terminal bg
+    return '#' + [image.rgba[at], image.rgba[at + 1], image.rgba[at + 2]]
+        .map(c => c.toString(16).padStart(2, '0')).join('');
+}

package/dist/src/render/incremental-paint.d.ts

@@ -3,8 +3,12 @@ import { CellBuffer } from './buffer.js';
 import { ResolvedStyle } from '../css/compute.js';
 import { LayoutBox } from '../layout/engine.js';
 /**
- * Repaint only specific nodes' cells in the buffer.
- * Clears the old area and writes the new content.
- * Handles text-align, text-overflow, and white-space from ancestors.
+ * Repaint only the region affected by dirty nodes.
+ *
+ * Computes the union bounding box of all dirty nodes, clears that
+ * region, then does a full repaint of the entire tree clipped to
+ * that region. This correctly handles overlapping elements like
+ * parent borders, list markers in padding areas, and z-indexed
+ * siblings.
  */
 export declare function paintNodes(nodes: Set<TermNode>, buffer: CellBuffer, styles: Map<number, ResolvedStyle>, layout: Map<number, LayoutBox>, root: TermNode): void;