@tuidom/core 0.1.0

package/dist/backend/iTerminalBackend.d.ts

@@ -0,0 +1,41 @@
+import type { Point, Size } from "../common/geometryPromitives.js";
+import type { KeyPressEvent } from "../input/keyEvent.js";
+import type { MouseToken } from "../input/rawTerminalToken.js";
+import type { Grid } from "../rendering/grid.js";
+/**
+ * Unified abstraction over terminal I/O.
+ *
+ * Two implementations:
+ * - `NodeTerminalBackend` — real process.stdin/stdout
+ * - `MockTerminalBackend` — in-memory for tests
+ */
+export interface ITerminalBackend {
+    /** Subscribe to parsed keyboard input */
+    onInput(callback: (event: KeyPressEvent) => void): void;
+    /** Subscribe to raw mouse events */
+    onMouse(callback: (event: MouseToken) => void): void;
+    /** Subscribe to bracketed-paste text blocks (whole paste delivered as one string) */
+    onPaste(callback: (text: string) => void): void;
+    /** Subscribe to terminal resize events */
+    onResize(callback: (size: Size) => void): void;
+    /** Subscribe to OSC response sequences from the terminal (e.g. OSC 52 clipboard replies) */
+    onOscResponse(callback: (code: number, data: string) => void): void;
+    /**
+     * Asynchronously probe whether the terminal supports the Kitty keyboard protocol.
+     * The request/response escape-sequence dance is fully encapsulated by the backend;
+     * `onResult` fires exactly once with the answer (or `false` if the terminal doesn't
+     * reply within the probe window). Fire-and-forget — callers must not block on it.
+     */
+    probeKeyboardProtocol(onResult: (supported: boolean) => void): void;
+    /**
+     * Render a frame: receive the current grid and cursor position.
+     * The backend decides how to output it (ANSI diffing, simple copy, etc.).
+     */
+    renderFrame(grid: Grid, cursorPosition: Point | null): void;
+    /** Current terminal dimensions */
+    getSize(): Size;
+    /** Initialize terminal: alternate screen, raw mode, hide cursor, etc. */
+    setup(): void;
+    /** Restore terminal state: show cursor, normal screen, etc. */
+    teardown(): void;
+}

package/dist/backend/iTerminalBackend.js

@@ -0,0 +1 @@
+export {};

package/dist/common/colorUtils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Sentinel value meaning "use terminal's default color".
+ * Must be negative so it's never confused with a packed RGB value (0x000000–0xFFFFFF).
+ */
+export declare const DEFAULT_COLOR = -1;
+/** Pack three 8-bit channels into a single 24-bit integer. */
+export declare function packRgb(r: number, g: number, b: number): number;
+/** Extract the red channel (bits 16–23). */
+export declare function unpackR(color: number): number;
+/** Extract the green channel (bits 8–15). */
+export declare function unpackG(color: number): number;
+/** Extract the blue channel (bits 0–7). */
+export declare function unpackB(color: number): number;
+/**
+ * Накладывает полупрозрачный `fg` на непрозрачную подложку `bg` и возвращает
+ * непрозрачный результат: терминал альфы не умеет, поэтому композитинг
+ * выполняется заранее (`alpha` — доля 0..1).
+ */
+export declare function blendRgb(fg: number, bg: number, alpha: number): number;

package/dist/common/colorUtils.js

@@ -0,0 +1,30 @@
+/**
+ * Sentinel value meaning "use terminal's default color".
+ * Must be negative so it's never confused with a packed RGB value (0x000000–0xFFFFFF).
+ */
+export const DEFAULT_COLOR = -1;
+/** Pack three 8-bit channels into a single 24-bit integer. */
+export function packRgb(r, g, b) {
+    return (r << 16) | (g << 8) | b;
+}
+/** Extract the red channel (bits 16–23). */
+export function unpackR(color) {
+    return (color >> 16) & 0xff;
+}
+/** Extract the green channel (bits 8–15). */
+export function unpackG(color) {
+    return (color >> 8) & 0xff;
+}
+/** Extract the blue channel (bits 0–7). */
+export function unpackB(color) {
+    return color & 0xff;
+}
+/**
+ * Накладывает полупрозрачный `fg` на непрозрачную подложку `bg` и возвращает
+ * непрозрачный результат: терминал альфы не умеет, поэтому композитинг
+ * выполняется заранее (`alpha` — доля 0..1).
+ */
+export function blendRgb(fg, bg, alpha) {
+    const mix = (f, b) => Math.round(f * alpha + b * (1 - alpha));
+    return packRgb(mix(unpackR(fg), unpackR(bg)), mix(unpackG(fg), unpackG(bg)), mix(unpackB(fg), unpackB(bg)));
+}

package/dist/common/displayLine.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A single visual unit in a display line — one grapheme cluster with its
+ * mapping between string offset and screen column.
+ */
+export interface GraphemeSlot {
+    /** The grapheme cluster string (may contain multiple code points) */
+    readonly grapheme: string;
+    /** Display width in terminal columns (1, 2, or variable for tabs) */
+    readonly displayWidth: number;
+    /** Start index in the original string (code unit offset) */
+    readonly offset: number;
+    /** Length in code units in the original string */
+    readonly length: number;
+}
+/**
+ * Maps a raw document string to an array of grapheme slots with correct
+ * display widths, providing bidirectional offset↔column conversion.
+ *
+ * Handles: tabs, \\r, emoji, CJK wide chars, combining marks, surrogate pairs.
+ */
+export declare class DisplayLine {
+    /** Ordered array of grapheme slots */
+    readonly slots: readonly GraphemeSlot[];
+    /** Total display width in terminal columns */
+    readonly displayWidth: number;
+    /**
+     * `true`, если строка была длиннее `stopAfter` и разобран лишь префикс —
+     * рендер по этому флагу рисует маркер обрезки. При `stopAfter = Infinity`
+     * (дефолт) всегда `false`.
+     */
+    readonly isTruncated: boolean;
+    private readonly columnMap;
+    private readonly rawLength;
+    /**
+     * @param stopAfter Максимум code units, которые разбираем. За порогом
+     * сегментация обрывается (лениво — `Intl.Segmenter` не трогает хвост), а
+     * `columnMap` аллоцируется по длине **префикса**, а не всей строки, — иначе
+     * одна мегабайтная строка съедала бы мегабайтный `Int32Array`. Дефолт
+     * `Infinity` сохраняет прежнее поведение для всех не-редакторных вызовов.
+     */
+    constructor(raw: string, tabSize?: number, stopAfter?: number);
+    /**
+     * Convert a string offset (code unit index) to a display column.
+     * For offsets pointing into the middle of a grapheme cluster,
+     * returns the column of that cluster's start.
+     */
+    offsetToColumn(offset: number): number;
+    /**
+     * Convert a display column to a string offset.
+     * If the column falls on the second cell of a wide character,
+     * returns the offset of that wide character.
+     */
+    columnToOffset(column: number): number;
+    /**
+     * Get the grapheme slot that occupies the given display column,
+     * or undefined if the column is out of range.
+     */
+    graphemeAtColumn(column: number): GraphemeSlot | undefined;
+    /**
+     * Get the character to render at a given display column.
+     * - For the first column of a wide char: returns the grapheme.
+     * - For the second column of a wide char: returns "" (continuation).
+     * - For a tab: returns " " (space).
+     * - For out-of-range: returns " ".
+     */
+    charAtColumn(column: number): string;
+    /**
+     * Find the slot index for the grapheme at the given string offset,
+     * or -1 if out of range.
+     */
+    slotIndexAtOffset(offset: number): number;
+}

package/dist/common/displayLine.js

@@ -0,0 +1,190 @@
+import { getCharDisplayWidth, getGraphemeDisplayWidth } from "./unicodeWidth.js";
+const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+const DEFAULT_TAB_SIZE = 4;
+/**
+ * Maps a raw document string to an array of grapheme slots with correct
+ * display widths, providing bidirectional offset↔column conversion.
+ *
+ * Handles: tabs, \\r, emoji, CJK wide chars, combining marks, surrogate pairs.
+ */
+export class DisplayLine {
+    /** Ordered array of grapheme slots */
+    slots;
+    /** Total display width in terminal columns */
+    displayWidth;
+    /**
+     * `true`, если строка была длиннее `stopAfter` и разобран лишь префикс —
+     * рендер по этому флагу рисует маркер обрезки. При `stopAfter = Infinity`
+     * (дефолт) всегда `false`.
+     */
+    isTruncated;
+    columnMap;
+    rawLength;
+    /**
+     * @param stopAfter Максимум code units, которые разбираем. За порогом
+     * сегментация обрывается (лениво — `Intl.Segmenter` не трогает хвост), а
+     * `columnMap` аллоцируется по длине **префикса**, а не всей строки, — иначе
+     * одна мегабайтная строка съедала бы мегабайтный `Int32Array`. Дефолт
+     * `Infinity` сохраняет прежнее поведение для всех не-редакторных вызовов.
+     */
+    constructor(raw, tabSize = DEFAULT_TAB_SIZE, stopAfter = Infinity) {
+        const slots = [];
+        let column = 0;
+        // Длина разобранного префикса: либо вся строка, либо offset первой
+        // отброшенной графемы (сегменты непрерывны, поэтому это ровно граница).
+        let scannedLength = raw.length;
+        let truncated = false;
+        for (const { segment, index } of segmenter.segment(raw)) {
+            if (index >= stopAfter) {
+                truncated = true;
+                scannedLength = index;
+                break;
+            }
+            let displayWidth;
+            if (segment === "\t") {
+                displayWidth = tabSize - (column % tabSize);
+            }
+            else if (segment === "\r") {
+                displayWidth = 0;
+            }
+            else if (segment.length === 1) {
+                displayWidth = getCharDisplayWidth(segment.charCodeAt(0));
+            }
+            else {
+                displayWidth = getGraphemeDisplayWidth(segment);
+            }
+            slots.push({
+                grapheme: segment,
+                displayWidth,
+                offset: index,
+                length: segment.length,
+            });
+            column += displayWidth;
+        }
+        this.slots = slots;
+        this.displayWidth = column;
+        this.isTruncated = truncated;
+        // За порогом строка ведёт себя как оканчивающаяся на `scannedLength`:
+        // офсеты в хвосте клампятся к `displayWidth` (курсор прилипает к маркеру).
+        this.rawLength = scannedLength;
+        // Build reverse lookup: for each code unit offset → display column
+        // This allows O(1) offsetToColumn lookups.
+        const map = new Int32Array(scannedLength + 1);
+        column = 0;
+        for (const slot of slots) {
+            for (let i = 0; i < slot.length; i++) {
+                map[slot.offset + i] = column;
+            }
+            column += slot.displayWidth;
+        }
+        map[scannedLength] = column; // past-the-end = total width
+        this.columnMap = map;
+    }
+    /**
+     * Convert a string offset (code unit index) to a display column.
+     * For offsets pointing into the middle of a grapheme cluster,
+     * returns the column of that cluster's start.
+     */
+    offsetToColumn(offset) {
+        if (offset <= 0)
+            return 0;
+        if (offset >= this.rawLength)
+            return this.displayWidth;
+        return this.columnMap[offset];
+    }
+    /**
+     * Convert a display column to a string offset.
+     * If the column falls on the second cell of a wide character,
+     * returns the offset of that wide character.
+     */
+    columnToOffset(column) {
+        if (column <= 0)
+            return 0;
+        if (column >= this.displayWidth)
+            return this.rawLength;
+        let col = 0;
+        for (const slot of this.slots) {
+            if (column >= col && column < col + slot.displayWidth) {
+                return slot.offset;
+            }
+            col += slot.displayWidth;
+        }
+        /* v8 ignore start -- unreachable: column < displayWidth is guaranteed to fall inside some slot, since slots tile [0, displayWidth) */
+        return this.rawLength;
+        /* v8 ignore stop */
+    }
+    /**
+     * Get the grapheme slot that occupies the given display column,
+     * or undefined if the column is out of range.
+     */
+    graphemeAtColumn(column) {
+        if (column < 0 || column >= this.displayWidth)
+            return undefined;
+        let col = 0;
+        for (const slot of this.slots) {
+            if (column >= col && column < col + slot.displayWidth) {
+                return slot;
+            }
+            col += slot.displayWidth;
+        }
+        /* v8 ignore start -- unreachable: the guard above bounds column to [0, displayWidth), which always falls inside a slot */
+        return undefined;
+        /* v8 ignore stop */
+    }
+    /**
+     * Get the character to render at a given display column.
+     * - For the first column of a wide char: returns the grapheme.
+     * - For the second column of a wide char: returns "" (continuation).
+     * - For a tab: returns " " (space).
+     * - For out-of-range: returns " ".
+     */
+    charAtColumn(column) {
+        if (column < 0 || column >= this.displayWidth)
+            return " ";
+        let col = 0;
+        for (const slot of this.slots) {
+            const slotEnd = col + slot.displayWidth;
+            if (column >= col && column < slotEnd) {
+                if (slot.grapheme === "\t") {
+                    return " ";
+                }
+                if (column === col) {
+                    return slot.grapheme;
+                }
+                // Second (or later) column of a wide char
+                return "";
+            }
+            col = slotEnd;
+        }
+        /* v8 ignore start -- unreachable: the guard above bounds column to [0, displayWidth), which always falls inside a slot */
+        return " ";
+        /* v8 ignore stop */
+    }
+    /**
+     * Find the slot index for the grapheme at the given string offset,
+     * or -1 if out of range.
+     */
+    slotIndexAtOffset(offset) {
+        if (offset < 0 || offset >= this.rawLength)
+            return -1;
+        // Binary search by offset
+        let lo = 0;
+        let hi = this.slots.length - 1;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            const slot = this.slots[mid];
+            if (offset < slot.offset) {
+                hi = mid - 1;
+            }
+            else if (offset >= slot.offset + slot.length) {
+                lo = mid + 1;
+            }
+            else {
+                return mid;
+            }
+        }
+        /* v8 ignore start -- unreachable: every offset in [0, rawLength) belongs to exactly one slot, so the binary search always hits */
+        return -1;
+        /* v8 ignore stop */
+    }
+}

package/dist/common/disposable.d.ts

@@ -0,0 +1,9 @@
+export interface IDisposable {
+    dispose(): void;
+}
+export declare class Disposable implements IDisposable {
+    private disposables;
+    private disposed;
+    protected register<T extends IDisposable>(disposable: T): T;
+    dispose(): void;
+}

package/dist/common/disposable.js

@@ -0,0 +1,18 @@
+export class Disposable {
+    disposables = [];
+    disposed = false;
+    register(disposable) {
+        this.disposables.push(disposable);
+        return disposable;
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Dispose in reverse order (LIFO)
+        for (let i = this.disposables.length - 1; i >= 0; i--) {
+            this.disposables[i].dispose();
+        }
+        this.disposables.length = 0;
+    }
+}

package/dist/common/geometryPromitives.d.ts

@@ -0,0 +1,47 @@
+export declare class Point {
+    readonly x: number;
+    readonly y: number;
+    constructor(x: number, y: number);
+}
+export declare class Offset {
+    readonly dx: number;
+    readonly dy: number;
+    constructor(dx: number, dy: number);
+}
+export declare class Size {
+    readonly width: number;
+    readonly height: number;
+    constructor(width: number, height: number);
+}
+export declare class BoxConstraints {
+    readonly minWidth: number;
+    readonly maxWidth: number;
+    readonly minHeight: number;
+    readonly maxHeight: number;
+    constructor(minWidth: number, maxWidth: number, minHeight: number, maxHeight: number);
+    static tight(size: Size): BoxConstraints;
+    static loose(size: Size): BoxConstraints;
+    constrain(size: Size): Size;
+    /** Удовлетворяет ли размер этим constraints (контракт layout: см. docs/LAYOUT.md). */
+    isSatisfiedBy(size: Size): boolean;
+}
+export declare class Rect {
+    readonly origin: Point;
+    readonly size: Size;
+    constructor(origin: Point, size: Size);
+    get x(): number;
+    get y(): number;
+    get width(): number;
+    get height(): number;
+    get right(): number;
+    get bottom(): number;
+    containsPoint(point: Point): boolean;
+    intersect(other: Rect): Rect;
+    get isEmpty(): boolean;
+    /** Есть ли непустое пересечение (касание рёбрами — не пересечение). */
+    intersects(other: Rect): boolean;
+    /** Минимальный rect, накрывающий оба. */
+    union(other: Rect): Rect;
+    /** Содержит ли целиком другой rect (пустой содержится в любом). */
+    containsRect(other: Rect): boolean;
+}

package/dist/common/geometryPromitives.js

@@ -0,0 +1,115 @@
+export class Point {
+    x;
+    y;
+    constructor(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+}
+export class Offset {
+    dx;
+    dy;
+    constructor(dx, dy) {
+        this.dx = dx;
+        this.dy = dy;
+    }
+}
+export class Size {
+    width;
+    height;
+    constructor(width, height) {
+        this.width = width;
+        this.height = height;
+    }
+}
+export class BoxConstraints {
+    minWidth;
+    maxWidth;
+    minHeight;
+    maxHeight;
+    constructor(minWidth, maxWidth, minHeight, maxHeight) {
+        this.minWidth = minWidth;
+        this.maxWidth = maxWidth;
+        this.minHeight = minHeight;
+        this.maxHeight = maxHeight;
+    }
+    static tight(size) {
+        return new BoxConstraints(size.width, size.width, size.height, size.height);
+    }
+    static loose(size) {
+        return new BoxConstraints(0, size.width, 0, size.height);
+    }
+    constrain(size) {
+        return new Size(Math.min(this.maxWidth, Math.max(this.minWidth, size.width)), Math.min(this.maxHeight, Math.max(this.minHeight, size.height)));
+    }
+    /** Удовлетворяет ли размер этим constraints (контракт layout: см. docs/LAYOUT.md). */
+    isSatisfiedBy(size) {
+        return (size.width >= this.minWidth &&
+            size.width <= this.maxWidth &&
+            size.height >= this.minHeight &&
+            size.height <= this.maxHeight);
+    }
+}
+export class Rect {
+    origin;
+    size;
+    constructor(origin, size) {
+        this.origin = origin;
+        this.size = size;
+    }
+    get x() {
+        return this.origin.x;
+    }
+    get y() {
+        return this.origin.y;
+    }
+    get width() {
+        return this.size.width;
+    }
+    get height() {
+        return this.size.height;
+    }
+    get right() {
+        return this.origin.x + this.size.width;
+    }
+    get bottom() {
+        return this.origin.y + this.size.height;
+    }
+    containsPoint(point) {
+        return point.x >= this.x && point.x < this.right && point.y >= this.y && point.y < this.bottom;
+    }
+    intersect(other) {
+        const x = Math.max(this.x, other.x);
+        const y = Math.max(this.y, other.y);
+        const right = Math.min(this.right, other.right);
+        const bottom = Math.min(this.bottom, other.bottom);
+        const width = Math.max(0, right - x);
+        const height = Math.max(0, bottom - y);
+        return new Rect(new Point(x, y), new Size(width, height));
+    }
+    get isEmpty() {
+        return this.size.width <= 0 || this.size.height <= 0;
+    }
+    /** Есть ли непустое пересечение (касание рёбрами — не пересечение). */
+    intersects(other) {
+        return this.x < other.right && other.x < this.right && this.y < other.bottom && other.y < this.bottom;
+    }
+    /** Минимальный rect, накрывающий оба. */
+    union(other) {
+        if (this.isEmpty)
+            return other;
+        if (other.isEmpty)
+            return this;
+        const x = Math.min(this.x, other.x);
+        const y = Math.min(this.y, other.y);
+        const right = Math.max(this.right, other.right);
+        const bottom = Math.max(this.bottom, other.bottom);
+        return new Rect(new Point(x, y), new Size(right - x, bottom - y));
+    }
+    /** Содержит ли целиком другой rect (пустой содержится в любом). */
+    containsRect(other) {
+        if (other.isEmpty)
+            return true;
+        return other.x >= this.x && other.y >= this.y && other.right <= this.right && other.bottom <= this.bottom;
+    }
+}

package/dist/common/iTerminalSurface.d.ts

@@ -0,0 +1,68 @@
+import type { IDisposable } from "./disposable.js";
+/**
+ * Переиспользуемый out-параметр `readCell` — вызывающий аллоцирует один раз,
+ * без аллокаций на ячейку.
+ */
+export interface TerminalCell {
+    char: string;
+    fg: number;
+    bg: number;
+    style: number;
+    width: number;
+}
+export type TerminalMouseButton = "left" | "middle" | "right" | "none" | "wheel";
+export type TerminalMouseAction = "down" | "up" | "move" | "wheelUp" | "wheelDown" | "wheelLeft" | "wheelRight";
+export interface TerminalMouseEventData {
+    col: number;
+    row: number;
+    button: TerminalMouseButton;
+    action: TerminalMouseAction;
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+}
+export interface ITerminalSurface {
+    /**
+     * Прочитать ячейку вьюпорта в переданный `out`. Координата `y` отсчитывается от верха
+     * вьюпорта — с учётом текущего `scrollOffset`, поэтому при заглядывании в скролбэк
+     * виджету ничего пересчитывать не надо.
+     * `false` = continuation-ячейка wide-char (голова уже нарисована с width=2) либо
+     * координата вне диапазона; в обоих случаях `out` не тронут.
+     */
+    readCell(x: number, y: number, out: TerminalCell): boolean;
+    /** Позиция курсора в видимой области или `null`, когда его показывать не надо. */
+    getCursor(): {
+        x: number;
+        y: number;
+    } | null;
+    readonly isExited: boolean;
+    /**
+     * Уже закодированные байты в PTY (см. encodeKeyForPty). Ввод возвращает вьюпорт
+     * на дно — печатать, глядя в историю, бессмысленно.
+     */
+    write(data: string): void;
+    sendMouse(event: TerminalMouseEventData): void;
+    /**
+     * Включила ли запущенная в шелле программа mouse-tracking (htop/vim/less --mouse).
+     * Пока `true` — колесо принадлежит программе и уходит в `sendMouse`; пока `false` —
+     * колесо обрабатывает виджет сам и крутит вьюпорт по скролбэку (как xterm.js
+     * смотрит на `coreMouseService.areMouseEventsActive`).
+     */
+    readonly mouseEventsActive: boolean;
+    /**
+     * На сколько строк вьюпорт поднят в скролбэк. `0` — смотрим на дно, живой вывод.
+     * Пока значение > 0, `getCursor()` отдаёт `null`: курсор шелла живёт на дне, и
+     * показывать его поверх истории нельзя.
+     */
+    readonly scrollOffset: number;
+    /**
+     * Прокрутить вьюпорт: `delta < 0` — вверх, в историю, `delta > 0` — вниз, к живому
+     * выводу. Результат клампится в `[0, <длина скролбэка>]`. Если смещение изменилось,
+     * поверхность дёргает `onUpdate` — виджету достаточно обычной подписки.
+     */
+    scrollLines(delta: number): void;
+    /** Держать PTY+эмулятор по выделенной области; no-op при совпадении. */
+    resize(cols: number, rows: number): void;
+    onUpdate(cb: () => void): IDisposable;
+    onExit(cb: (exitCode: number) => void): IDisposable;
+}

package/dist/common/iTerminalSurface.js

@@ -0,0 +1,8 @@
+// Абстрактная модель ячеек терминала — то, что тикет требует держать в TUIDom «чистым».
+//
+// `TerminalViewElement` рендерится ТОЛЬКО через этот интерфейс и ничего не знает про
+// PTY и VT-эмулятор. Реальная связка (node-pty + @xterm/headless) реализует
+// `ITerminalSurface` на слой выше — в Workbench, — поэтому под `src/TUIDom/` не
+// протекают импорты `@xterm/headless`/`node-pty`, а виджет остаётся тестируемым
+// через скриптованный фейк (см. TestUtils/FakeTerminalSurface).
+export {};

package/dist/common/measureTextWidth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Display width of `raw` in terminal columns.
+ *
+ * Returns **exactly** the same number as
+ * `new DisplayLine(raw, tabSize, stopAfter).displayWidth`, but without
+ * allocating the per-grapheme slot array or the offset→column `Int32Array`.
+ * Used by the horizontal-scrollbar width cache ({@link LineWidthCache}), where
+ * only the width matters and building a full `DisplayLine` per document line is
+ * what freezes the editor on long lines.
+ *
+ * `stopAfter` bounds the scan: any grapheme whose start offset is at or past it
+ * is ignored (segmentation is lazy, so the tail is never touched). An extreme
+ * line therefore costs O(stopAfter), not O(length) — mirroring VS Code's
+ * `stopRenderingLineAfter`.
+ *
+ * The per-grapheme width rules are kept in lock-step with `DisplayLine`'s
+ * constructor: tab expands to the next tab stop, `\r` is zero-width, single
+ * code units go through {@link getCharDisplayWidth}, multi-code-unit clusters
+ * through {@link getGraphemeDisplayWidth}.
+ */
+export declare function measureTextWidth(raw: string, tabSize?: number, stopAfter?: number): number;