@svelterm/core 0.1.0 → 0.23.0

package/dist/src/render/scrollbar.js

@@ -1,19 +1,76 @@
-const TRACK_CHAR = '│';
-const THUMB_CHAR = '┃';
-export function renderScrollbar(buffer, box, contentHeight, scrollTop) {
-    if (contentHeight <= box.height)
+const V_THUMB = '┃';
+const H_THUMB = '▁';
+const SCROLLBAR_COLOR = { r: 180, g: 180, b: 180 };
+/**
+ * Render a vertical scrollbar overlay on the rightmost column.
+ */
+export function renderScrollbar(buffer, viewportX, viewportY, viewportWidth, viewportHeight, contentHeight, scrollTop, opacity) {
+    if (contentHeight <= viewportHeight || opacity <= 0)
         return;
-    const col = box.x + box.width - 1;
-    const trackHeight = box.height;
-    const thumbSize = Math.max(1, Math.round(trackHeight * (box.height / contentHeight)));
-    const maxScroll = contentHeight - box.height;
-    const thumbPos = Math.round((scrollTop / maxScroll) * (trackHeight - thumbSize));
-    for (let row = 0; row < trackHeight; row++) {
+    const col = viewportX + viewportWidth - 1;
+    const thumbSize = Math.max(1, Math.round(viewportHeight * (viewportHeight / contentHeight)));
+    const maxScroll = contentHeight - viewportHeight;
+    const thumbPos = Math.round((scrollTop / maxScroll) * (viewportHeight - thumbSize));
+    for (let row = 0; row < viewportHeight; row++) {
+        const y = viewportY + row;
         const isThumb = row >= thumbPos && row < thumbPos + thumbSize;
-        buffer.setCell(col, box.y + row, {
-            char: isThumb ? THUMB_CHAR : TRACK_CHAR,
-            fg: isThumb ? 'white' : 'default',
-            dim: !isThumb,
+        const existing = buffer.getCell(col, y);
+        const bg = parseColor(existing?.bg ?? 'default');
+        const fg = lerpColor(bg, SCROLLBAR_COLOR, isThumb ? opacity : opacity * 0.3);
+        buffer.setCell(col, y, {
+            char: isThumb ? V_THUMB : ' ',
+            fg: isThumb ? toHex(fg) : undefined,
+            dim: false,
         });
     }
 }
+/**
+ * Render a horizontal scrollbar overlay on the bottom row.
+ */
+export function renderHScrollbar(buffer, viewportX, viewportY, viewportWidth, viewportHeight, contentWidth, scrollLeft, opacity) {
+    if (contentWidth <= viewportWidth || opacity <= 0)
+        return;
+    const row = viewportY + viewportHeight - 1;
+    const thumbSize = Math.max(1, Math.round(viewportWidth * (viewportWidth / contentWidth)));
+    const maxScroll = contentWidth - viewportWidth;
+    const thumbPos = Math.round((scrollLeft / maxScroll) * (viewportWidth - thumbSize));
+    for (let col = 0; col < viewportWidth; col++) {
+        const x = viewportX + col;
+        const isThumb = col >= thumbPos && col < thumbPos + thumbSize;
+        const existing = buffer.getCell(x, row);
+        const bg = parseColor(existing?.bg ?? 'default');
+        const fg = lerpColor(bg, SCROLLBAR_COLOR, isThumb ? opacity : opacity * 0.3);
+        buffer.setCell(x, row, {
+            char: isThumb ? H_THUMB : ' ',
+            fg: isThumb ? toHex(fg) : undefined,
+            dim: false,
+        });
+    }
+}
+function parseColor(color) {
+    if (color.startsWith('#')) {
+        const hex = color.length === 4
+            ? `#${color[1]}${color[1]}${color[2]}${color[2]}${color[3]}${color[3]}`
+            : color;
+        return {
+            r: parseInt(hex.slice(1, 3), 16),
+            g: parseInt(hex.slice(3, 5), 16),
+            b: parseInt(hex.slice(5, 7), 16),
+        };
+    }
+    // Default/unknown — assume dark background
+    return { r: 13, g: 17, b: 23 };
+}
+function lerpColor(a, b, t) {
+    return {
+        r: Math.round(a.r + (b.r - a.r) * t),
+        g: Math.round(a.g + (b.g - a.g) * t),
+        b: Math.round(a.b + (b.b - a.b) * t),
+    };
+}
+function toHex(c) {
+    return `#${hex(c.r)}${hex(c.g)}${hex(c.b)}`;
+}
+function hex(n) {
+    return n.toString(16).padStart(2, '0');
+}

package/dist/src/render/snapshot.js

@@ -53,6 +53,8 @@ export function bufferToStyledText(buffer) {
                     parts.push('underline');
                 if (cell.dim)
                     parts.push('dim');
+                if (cell.inverse)
+                    parts.push('inverse');
                 styles.push(`[${col}:${parts.join(',')}]`);
             }
         }
@@ -109,7 +111,7 @@ export function bufferToSvg(buffer, options) {
 function hasStyle(cell) {
     return cell.fg !== 'default' || cell.bg !== 'default'
         || cell.bold || cell.italic || cell.underline
-        || cell.strikethrough || cell.dim;
+        || cell.strikethrough || cell.dim || cell.inverse;
 }
 function colorToHex(color) {
     if (color.startsWith('#'))

package/dist/src/renderer/default.d.ts

@@ -1,3 +1,10 @@
 import { createTermRenderer } from './index.js';
 declare const renderer: ReturnType<typeof createTermRenderer>;
 export default renderer;
+/**
+ * True inside a Svelte component being rendered into svelterm's cell tree
+ * (i.e. mounted via svelterm's `run()`); false for plain browser-Svelte
+ * mounts. Components that render structurally different output per target
+ * use this to dispatch.
+ */
+export declare function isTerminal(): boolean;

package/dist/src/renderer/default.js

@@ -1,3 +1,14 @@
+import { getContext } from 'svelte';
 import { createTermRenderer } from './index.js';
 const renderer = createTermRenderer();
 export default renderer;
+const TARGET_KEY = Symbol.for('@svelterm/target');
+/**
+ * True inside a Svelte component being rendered into svelterm's cell tree
+ * (i.e. mounted via svelterm's `run()`); false for plain browser-Svelte
+ * mounts. Components that render structurally different output per target
+ * use this to dispatch.
+ */
+export function isTerminal() {
+    return getContext(TARGET_KEY) === 'terminal';
+}

package/dist/src/renderer/index.d.ts

@@ -1,6 +1,12 @@
 import { createRenderer as svelteCreateRenderer } from 'svelte/renderer';
 import { TermNode } from './node.js';
-export declare function createTermRenderer(): ReturnType<typeof svelteCreateRenderer<TermNode, TermNode, TermNode, TermNode>>;
+type TermNodes = {
+    fragment: TermNode;
+    element: TermNode;
+    text: TermNode;
+    comment: TermNode;
+};
+export declare function createTermRenderer(): ReturnType<typeof svelteCreateRenderer<TermNodes>>;
 /**
  * Keep the custom renderer active globally so Svelte's effects
  * use our renderer methods (setText, setAttribute, etc.) instead
@@ -8,4 +14,4 @@ export declare function createTermRenderer(): ReturnType<typeof svelteCreateRend
  *
  * Call this AFTER renderer.render() which pops the renderer.
  */
-export { TermNode } from './node.js';
+export { TermNode, SvtRegionNode } from './node.js';

package/dist/src/renderer/index.js

@@ -1,11 +1,13 @@
 import { createRenderer as svelteCreateRenderer } from 'svelte/renderer';
-import { TermNode } from './node.js';
+import { TermNode, SvtRegionNode } from './node.js';
 export function createTermRenderer() {
     return svelteCreateRenderer({
         createFragment() {
             return new TermNode('fragment');
         },
         createElement(name) {
+            if (name === 'svt-region')
+                return new SvtRegionNode();
             return new TermNode('element', name);
         },
         createTextNode(data) {
@@ -113,4 +115,4 @@ export function createTermRenderer() {
  *
  * Call this AFTER renderer.render() which pops the renderer.
  */
-export { TermNode } from './node.js';
+export { TermNode, SvtRegionNode } from './node.js';

package/dist/src/renderer/node.d.ts

@@ -2,11 +2,26 @@ import type { ResolvedStyle } from '../css/compute.js';
 import type { LayoutBox } from '../layout/engine.js';
 import type { RenderContext } from '../render/context.js';
 import { TextBuffer } from '../components/text-buffer.js';
+import type { Cell } from '../render/buffer.js';
 export type NodeType = 'element' | 'text' | 'comment' | 'fragment';
+export interface CursorScreenPos {
+    x: number;
+    y: number;
+    /** Full-paint generation that wrote this position (see render/generation). */
+    generation?: number;
+    /** False when the cursor falls outside the node's content viewport
+     *  (scrolled off, clipped by an ancestor). The emitter hides the
+     *  cursor in that case. */
+    inViewport: boolean;
+}
 export interface RenderCache {
     resolvedStyle: ResolvedStyle | null;
     layoutBox: LayoutBox | null;
     classAttr: string;
+    /** Last known screen position of the node's text cursor. Set by
+     *  paint when the node owns a cursor (focused input/textarea);
+     *  consumed by the post-paint cursor emitter. */
+    cursorScreen: CursorScreenPos | null;
 }
 export declare class TermNode {
     readonly id: number;
@@ -16,20 +31,47 @@ export declare class TermNode {
     ctx: RenderContext | null;
     parent: TermNode | null;
     children: TermNode[];
+    /**
+     * Synthetic ::before/::after boxes. Renderer-owned: kept out of
+     * `children` so selectors (:empty, :nth-*), focus walks and Svelte's
+     * anchor bookkeeping never see them; layout and paint include them
+     * via childrenWithPseudos().
+     */
+    pseudoBefore: TermNode | null;
+    pseudoAfter: TermNode | null;
     attributes: Map<string, string>;
     listeners: Map<string, Set<(...args: any[]) => void>>;
     scrollTop: number;
     scrollLeft: number;
+    scrollbarVisibleUntil: number;
+    hScrollbarVisibleUntil: number;
     textBuffer: TextBuffer | null;
     cache: RenderCache;
     /** DOM compatibility — Svelte's effects set nodeValue directly when renderer is not pushed */
     get nodeValue(): string | null;
     set nodeValue(value: string | null);
+    /** DOM compatibility — form control value as a property */
+    get value(): string;
+    set value(newValue: string);
+    /** DOM compatibility — checkbox/radio state as a property */
+    get checked(): boolean;
+    set checked(value: boolean);
     /** DOM compatibility — Svelte may also use textContent */
     get textContent(): string;
     set textContent(value: string);
     constructor(nodeType: NodeType, tagOrText?: string);
     get classes(): Set<string>;
+    /** DOM compat — returns the root of the tree */
+    getRootNode(): TermNode;
+    /** DOM compat — append_styles uses querySelector */
+    querySelector(selector: string): TermNode | null;
+    private findById;
+    /** DOM compat — append_styles checks for .host on the root */
+    get host(): undefined;
+    /** DOM compat — append_styles accesses .head */
+    get head(): TermNode;
+    /** DOM compat — append_styles accesses .ownerDocument */
+    get ownerDocument(): TermNode;
     getFirstChild(): TermNode | null;
     getLastChild(): TermNode | null;
     getNextSibling(): TermNode | null;
@@ -37,8 +79,75 @@ export declare class TermNode {
     removeChild(node: TermNode): void;
     remove(): void;
     collectText(): string;
+    /**
+     * Screen-space position of this node's text cursor, set by paint.
+     * Returns null unless the node currently owns a cursor (e.g. a
+     * focused input/textarea repainted this frame). Consumed by the
+     * post-paint cursor emitter.
+     */
+    getCursorScreenPos(): CursorScreenPos | null;
     invalidateStyle(): void;
     invalidateLayout(): void;
     invalidateAll(): void;
     cleanup(): void;
 }
+/** The children layout and paint should flow: ::before, real children, ::after. */
+export declare function childrenWithPseudos(node: TermNode): TermNode[];
+/**
+ * HTML boolean attribute semantics, with one renderer-specific twist:
+ * Svelte passes attribute values through `String(value)`, so a literal
+ * "false" means the author set `disabled={false}` and expects it off.
+ */
+export declare function hasBooleanAttribute(node: TermNode, name: string): boolean;
+/**
+ * A layout-participating region whose contents are filled by an external
+ * source. The consumer (typically `EmbeddedTerminal`) registers a
+ * cell-source function via `setCellSource`, and the paint phase calls
+ * it for each cell of the region's allocated box.
+ *
+ * Local coordinates: the cell-source function receives `(col, row)`
+ * relative to the region's own top-left, NOT the surrounding buffer.
+ *
+ * Resize: when the layout-allocated cell dimensions change between
+ * paints, a `resize` event fires with `{ cols, rows }` so the consumer
+ * can resize the upstream Terminal / stream to match.
+ */
+export interface RegionCursor {
+    col: number;
+    row: number;
+    visible: boolean;
+}
+export declare class SvtRegionNode extends TermNode {
+    private cellSource;
+    private lastCols;
+    private lastRows;
+    private cursor;
+    /** Last allocated screen origin. Set by paintRegion so the post-diff
+     *  cursor emitter can translate region-local coords to absolute. */
+    lastBoxX: number;
+    lastBoxY: number;
+    constructor();
+    setCellSource(fn: (col: number, row: number) => Cell): void;
+    getCellSource(): ((col: number, row: number) => Cell) | null;
+    /**
+     * Called by the paint phase with the region's currently-allocated
+     * dimensions. Fires `resize` if they've changed since the last call.
+     * Returns the (possibly newly-fired) dimensions.
+     */
+    notifyAllocatedSize(cols: number, rows: number, fire: (cols: number, rows: number) => void): void;
+    /**
+     * Position (and show/hide) a cursor inside the region. Coordinates are
+     * region-local; the post-paint cursor emitter translates them to
+     * screen coordinates using the region's last allocated box. Pass
+     * `null` to suppress cursor emission for this region.
+     */
+    setCursor(cursor: RegionCursor | null): void;
+    getCursor(): RegionCursor | null;
+    /**
+     * Mark the region as needing a repaint. Consumers call this when
+     * their cell source's output has changed (e.g. after their upstream
+     * Terminal has consumed new bytes from a stream). Schedules a paint
+     * via the render context and re-runs the paint pipeline.
+     */
+    markDirty(): void;
+}

package/dist/src/renderer/node.js

@@ -1,3 +1,4 @@
+import { paintGeneration } from '../render/generation.js';
 let nextId = 1;
 export class TermNode {
     id;
@@ -7,12 +8,22 @@ export class TermNode {
     ctx = null;
     parent = null;
     children = [];
+    /**
+     * Synthetic ::before/::after boxes. Renderer-owned: kept out of
+     * `children` so selectors (:empty, :nth-*), focus walks and Svelte's
+     * anchor bookkeeping never see them; layout and paint include them
+     * via childrenWithPseudos().
+     */
+    pseudoBefore = null;
+    pseudoAfter = null;
     attributes = new Map();
     listeners = new Map();
     scrollTop = 0;
     scrollLeft = 0;
+    scrollbarVisibleUntil = 0;
+    hScrollbarVisibleUntil = 0;
     textBuffer = null;
-    cache = { resolvedStyle: null, layoutBox: null, classAttr: '' };
+    cache = { resolvedStyle: null, layoutBox: null, classAttr: '', cursorScreen: null };
     /** DOM compatibility — Svelte's effects set nodeValue directly when renderer is not pushed */
     get nodeValue() {
         if (this.nodeType === 'text' || this.nodeType === 'comment')
@@ -30,6 +41,34 @@ export class TermNode {
             }
         }
     }
+    /** DOM compatibility — form control value as a property */
+    get value() {
+        return this.attributes.get('value') ?? '';
+    }
+    set value(newValue) {
+        if (this.ctx)
+            this.ctx.onSetAttribute(this, 'value', newValue);
+        else
+            this.attributes.set('value', newValue);
+    }
+    /** DOM compatibility — checkbox/radio state as a property */
+    get checked() {
+        return hasBooleanAttribute(this, 'checked');
+    }
+    set checked(value) {
+        if (value) {
+            if (this.ctx)
+                this.ctx.onSetAttribute(this, 'checked', 'true');
+            else
+                this.attributes.set('checked', 'true');
+        }
+        else {
+            if (this.ctx)
+                this.ctx.onRemoveAttribute(this, 'checked');
+            else
+                this.attributes.delete('checked');
+        }
+    }
     /** DOM compatibility — Svelte may also use textContent */
     get textContent() {
         return this.collectText();
@@ -60,6 +99,38 @@ export class TermNode {
             return new Set();
         return new Set(raw.split(/\s+/).filter(Boolean));
     }
+    /** DOM compat — returns the root of the tree */
+    getRootNode() {
+        let node = this;
+        while (node.parent)
+            node = node.parent;
+        return node;
+    }
+    /** DOM compat — append_styles uses querySelector */
+    querySelector(selector) {
+        // Simple #id selector support for append_styles
+        if (selector.startsWith('#')) {
+            const id = selector.slice(1);
+            return this.findById(id);
+        }
+        return null;
+    }
+    findById(id) {
+        if (this.attributes.get('id') === id)
+            return this;
+        for (const child of this.children) {
+            const found = child.findById(id);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    /** DOM compat — append_styles checks for .host on the root */
+    get host() { return undefined; }
+    /** DOM compat — append_styles accesses .head */
+    get head() { return this; }
+    /** DOM compat — append_styles accesses .ownerDocument */
+    get ownerDocument() { return this.getRootNode(); }
     getFirstChild() {
         return this.children[0] ?? null;
     }
@@ -120,6 +191,23 @@ export class TermNode {
             return '';
         return this.children.map(c => c.collectText()).join('');
     }
+    /**
+     * Screen-space position of this node's text cursor, set by paint.
+     * Returns null unless the node currently owns a cursor (e.g. a
+     * focused input/textarea repainted this frame). Consumed by the
+     * post-paint cursor emitter.
+     */
+    getCursorScreenPos() {
+        const pos = this.cache.cursorScreen;
+        if (!pos)
+            return null;
+        // A position stamped by an older full paint is stale — the node
+        // was culled offscreen this frame, so it no longer owns a cursor.
+        // Unstamped positions (set directly by embedders/tests) stay valid.
+        if (pos.generation !== undefined && pos.generation !== paintGeneration())
+            return null;
+        return pos;
+    }
     invalidateStyle() {
         this.cache.resolvedStyle = null;
         this.cache.classAttr = '';
@@ -139,6 +227,82 @@ export class TermNode {
         }
     }
 }
+/** The children layout and paint should flow: ::before, real children, ::after. */
+export function childrenWithPseudos(node) {
+    if (!node.pseudoBefore && !node.pseudoAfter)
+        return node.children;
+    const flowed = [];
+    if (node.pseudoBefore)
+        flowed.push(node.pseudoBefore);
+    flowed.push(...node.children);
+    if (node.pseudoAfter)
+        flowed.push(node.pseudoAfter);
+    return flowed;
+}
+/**
+ * HTML boolean attribute semantics, with one renderer-specific twist:
+ * Svelte passes attribute values through `String(value)`, so a literal
+ * "false" means the author set `disabled={false}` and expects it off.
+ */
+export function hasBooleanAttribute(node, name) {
+    const value = node.attributes.get(name);
+    return value !== undefined && value !== 'false';
+}
+export class SvtRegionNode extends TermNode {
+    cellSource = null;
+    lastCols = -1;
+    lastRows = -1;
+    cursor = null;
+    /** Last allocated screen origin. Set by paintRegion so the post-diff
+     *  cursor emitter can translate region-local coords to absolute. */
+    lastBoxX = 0;
+    lastBoxY = 0;
+    constructor() {
+        super('element', 'svt-region');
+    }
+    setCellSource(fn) {
+        this.cellSource = fn;
+    }
+    getCellSource() {
+        return this.cellSource;
+    }
+    /**
+     * Called by the paint phase with the region's currently-allocated
+     * dimensions. Fires `resize` if they've changed since the last call.
+     * Returns the (possibly newly-fired) dimensions.
+     */
+    notifyAllocatedSize(cols, rows, fire) {
+        if (cols === this.lastCols && rows === this.lastRows)
+            return;
+        this.lastCols = cols;
+        this.lastRows = rows;
+        fire(cols, rows);
+    }
+    /**
+     * Position (and show/hide) a cursor inside the region. Coordinates are
+     * region-local; the post-paint cursor emitter translates them to
+     * screen coordinates using the region's last allocated box. Pass
+     * `null` to suppress cursor emission for this region.
+     */
+    setCursor(cursor) {
+        this.cursor = cursor;
+    }
+    getCursor() {
+        return this.cursor;
+    }
+    /**
+     * Mark the region as needing a repaint. Consumers call this when
+     * their cell source's output has changed (e.g. after their upstream
+     * Terminal has consumed new bytes from a stream). Schedules a paint
+     * via the render context and re-runs the paint pipeline.
+     */
+    markDirty() {
+        if (!this.ctx)
+            return;
+        this.ctx.queue.enqueuePaintOnly(this);
+        this.ctx.onScheduleRender?.();
+    }
+}
 function propagateCtx(node, ctx) {
     node.ctx = ctx;
     for (const child of node.children) {

package/dist/src/terminal/capabilities.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Terminal capability detection: colour depth from the environment and
+ * XTVERSION, synchronized-output support via DECRQM. Queries run through
+ * the StdinRouter with timeouts, so unresponsive terminals just get
+ * conservative defaults.
+ */
+import type { StdinRouter } from './stdin-router.js';
+export type ColorDepth = 'truecolor' | '256' | '16' | 'mono';
+export interface TerminalCapabilities {
+    colorDepth: ColorDepth;
+    /** DEC 2026 begin/end synchronized update. */
+    syncOutput: boolean;
+    /** Kitty graphics protocol (crisp images instead of half-blocks). */
+    graphics: boolean;
+    /** Terminal name and version from XTVERSION, when it answered. */
+    terminal: string | null;
+}
+export declare function resolveColorDepth(env: Record<string, string | undefined>, xtversion?: string | null): ColorDepth;
+/** Match a DCS > | <text> ST reply to XTVERSION, returning the text. */
+export declare function matchXTVERSION(data: string): string | null;
+/** Match a DECRQM reply for the given mode. */
+export declare function matchDECRQM(mode: number): (data: string) => string | null;
+/** Match a CPR (cursor position report) reply: CSI row ; col R. */
+export declare function matchCPR(data: string): string | null;
+/** The 1-based row from a CPR reply, or null. */
+export declare function parseCPRRow(reply: string | null): number | null;
+/** Whether a DECRQM reply says the mode is recognised (set or reset). */
+export declare function decrqmSupported(reply: string | null): boolean;
+/**
+ * Query the live terminal. COLORTERM/NO_COLOR decide colour depth without
+ * a query; otherwise XTVERSION identifies known-truecolor terminals.
+ */
+export declare function detectCapabilities(router: StdinRouter, env?: Record<string, string | undefined>): Promise<TerminalCapabilities>;

package/dist/src/terminal/capabilities.js

@@ -0,0 +1,66 @@
+/**
+ * Terminal capability detection: colour depth from the environment and
+ * XTVERSION, synchronized-output support via DECRQM. Queries run through
+ * the StdinRouter with timeouts, so unresponsive terminals just get
+ * conservative defaults.
+ */
+import { graphicsSupported } from '../render/kitty-graphics.js';
+/** Terminals that render truecolor but predate COLORTERM adoption. */
+const TRUECOLOR_TERMINALS = /iterm|kitty|wezterm|ghostty|alacritty|contour|rio|vscode/i;
+export function resolveColorDepth(env, xtversion) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return 'mono';
+    const colorterm = env.COLORTERM ?? '';
+    if (colorterm === 'truecolor' || colorterm === '24bit')
+        return 'truecolor';
+    if (xtversion && TRUECOLOR_TERMINALS.test(xtversion))
+        return 'truecolor';
+    if ((env.TERM ?? '').includes('256color'))
+        return '256';
+    return '16';
+}
+/** Match a DCS > | <text> ST reply to XTVERSION, returning the text. */
+export function matchXTVERSION(data) {
+    const match = /\x1bP>\|([^\x1b]*)\x1b\\/.exec(data);
+    return match ? match[1] : null;
+}
+/** Match a DECRQM reply for the given mode. */
+export function matchDECRQM(mode) {
+    const pattern = new RegExp(`\\x1b\\[\\?${mode};\\d\\$y`);
+    return data => pattern.exec(data)?.[0] ?? null;
+}
+/** Match a CPR (cursor position report) reply: CSI row ; col R. */
+export function matchCPR(data) {
+    return /\x1b\[\d+;\d+R/.exec(data)?.[0] ?? null;
+}
+/** The 1-based row from a CPR reply, or null. */
+export function parseCPRRow(reply) {
+    if (!reply)
+        return null;
+    const row = /\x1b\[(\d+);/.exec(reply)?.[1];
+    return row ? parseInt(row, 10) : null;
+}
+/** Whether a DECRQM reply says the mode is recognised (set or reset). */
+export function decrqmSupported(reply) {
+    if (!reply)
+        return false;
+    const value = /;(\d)\$y/.exec(reply)?.[1];
+    return value === '1' || value === '2';
+}
+/**
+ * Query the live terminal. COLORTERM/NO_COLOR decide colour depth without
+ * a query; otherwise XTVERSION identifies known-truecolor terminals.
+ */
+export async function detectCapabilities(router, env = process.env) {
+    const [xtversion, decrqm] = await Promise.all([
+        // Identifies known-truecolor terminals AND graphics support
+        router.query('\x1b[>0q', matchXTVERSION, 150),
+        router.query('\x1b[?2026$p', matchDECRQM(2026), 150),
+    ]);
+    return {
+        colorDepth: resolveColorDepth(env, xtversion),
+        syncOutput: decrqmSupported(decrqm),
+        graphics: graphicsSupported(xtversion),
+        terminal: xtversion,
+    };
+}

package/dist/src/terminal/clipboard.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Clipboard writes. OSC 52 travels in-band (works over ssh and through
+ * multiplexers that pass it on); a platform tool runs as well when one
+ * exists, covering terminals with OSC 52 disabled. Failures are silent —
+ * copying is best-effort by nature here.
+ */
+export declare function osc52Copy(text: string): string;
+/** Write text to the clipboard: OSC 52 through `write`, plus a platform tool. */
+export declare function copyToClipboard(text: string, write: (data: string) => void): void;