@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/ui/components/submitted-prompt.js

@@ -0,0 +1,50 @@
+import { displayWidth, truncateToWidth } from "./text.js";
+/** Visible width of the submitted-prompt prefix (`❯ `). */
+export const SUBMITTED_PROMPT_PREFIX_WIDTH = 2;
+const TIMESTAMP_MARGIN = 3;
+const MIN_USEFUL_CONTENT_WIDTH = 8;
+/** Formats transcript metadata, never render time, as local 24-hour HH:mm. */
+export function formatSubmittedPromptTime(source) {
+    const date = source instanceof Date ? source : new Date(source);
+    if (!Number.isFinite(date.getTime()))
+        return null;
+    return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}
+/**
+ * Computes the width at which the prompt's Markdown body must be rendered.
+ * The timestamp is omitted rather than allowing it to crowd useful content.
+ */
+export function submittedPromptLayout(width, source) {
+    const boundedWidth = Math.max(1, width);
+    const timestamp = source === undefined || source === null ? null : formatSubmittedPromptTime(source);
+    const timestampReserve = timestamp === null ? 0 : displayWidth(timestamp) + TIMESTAMP_MARGIN;
+    const canShowTimestamp = timestamp !== null
+        && boundedWidth - SUBMITTED_PROMPT_PREFIX_WIDTH - timestampReserve >= MIN_USEFUL_CONTENT_WIDTH;
+    return {
+        contentWidth: Math.max(1, boundedWidth - SUBMITTED_PROMPT_PREFIX_WIDTH - (canShowTimestamp ? timestampReserve : 0)),
+        timestamp: canShowTimestamp ? timestamp : null,
+    };
+}
+/**
+ * Composes already-rendered prompt content into the compact submitted bar.
+ * Continuations align below the content, not below the prefix, and no row can
+ * exceed the supplied terminal width even when the content renderer misbehaves.
+ */
+export function composeSubmittedPromptRows(contentRows, width, source, style = {}) {
+    if (width <= 0)
+        return [];
+    const layout = submittedPromptLayout(width, source);
+    const prefix = (style.prefix ?? identity)("❯ ");
+    const rows = (contentRows.length === 0 ? [""] : contentRows).map((row, index) => {
+        const content = truncateToWidth(row, layout.contentWidth);
+        return `${index === 0 ? prefix : " ".repeat(SUBMITTED_PROMPT_PREFIX_WIDTH)}${content}`;
+    });
+    if (layout.timestamp !== null && rows[0] !== undefined) {
+        const gap = Math.max(1, width - displayWidth(rows[0]) - displayWidth(layout.timestamp));
+        rows[0] = `${rows[0]}${" ".repeat(gap)}${(style.timestamp ?? identity)(layout.timestamp)}`;
+    }
+    return rows.map(row => truncateToWidth(row, width));
+}
+function identity(text) {
+    return text;
+}

package/dist/ui/components/surface.d.ts

@@ -0,0 +1,20 @@
+import { type ScrollbarGeometry, type ScrollbarPresentation } from "./scrollbar.js";
+import type { UiTheme } from "./theme.js";
+/** Columns the rail occupies: its own, plus the gap before it. */
+export declare const RAIL_COLUMNS = 2;
+export interface RailOptions {
+    /** Rows at the top the rail does not run beside, such as a sticky header. */
+    readonly topInset?: number;
+    /** How the rail shows. Absent draws the thin rail whenever the content overflows. */
+    readonly presentation?: ScrollbarPresentation;
+}
+/**
+ * Draws the rail beside each row, padding the rows to a common width first.
+ * A presentation that reserves no space returns the rows untouched.
+ */
+export declare function withScrollbarRail(lines: readonly string[], geometry: ScrollbarGeometry | null, contentWidth: number, theme: UiTheme, options?: RailOptions): readonly string[];
+/**
+ * What a list shows instead of rows: a mark and a line, both quiet, sitting in
+ * the middle of the space the rows would have had.
+ */
+export declare function renderEmptyState(message: string, mark: string, height: number, width: number, theme: UiTheme): readonly string[];

package/dist/ui/components/surface.js

@@ -0,0 +1,44 @@
+import { isThumbRow } from "./scrollbar.js";
+import { displayWidth } from "./text.js";
+// Rationale: shared list chrome belongs here rather than in individual screens.
+/** Columns the rail occupies: its own, plus the gap before it. */
+export const RAIL_COLUMNS = 2;
+/**
+ * Draws the rail beside each row, padding the rows to a common width first.
+ * A presentation that reserves no space returns the rows untouched.
+ */
+export function withScrollbarRail(lines, geometry, contentWidth, theme, options = {}) {
+    const inset = options.topInset ?? 0;
+    const presentation = options.presentation
+        ?? { visible: geometry !== null, reservesSpace: true, trackGlyph: "│", thumbGlyph: "│" };
+    if (!presentation.reservesSpace)
+        return lines;
+    const drawn = presentation.visible && geometry !== null;
+    return lines.map((line, offset) => {
+        const cell = offset < inset || !drawn
+            ? " "
+            : isThumbRow(geometry, offset - inset)
+                ? theme.fg("accent", presentation.thumbGlyph)
+                : theme.fg("dim", presentation.trackGlyph);
+        return `${pad(line, contentWidth)} ${cell}`;
+    });
+}
+/**
+ * What a list shows instead of rows: a mark and a line, both quiet, sitting in
+ * the middle of the space the rows would have had.
+ */
+export function renderEmptyState(message, mark, height, width, theme) {
+    const middle = Math.floor(height / 2);
+    return Array.from({ length: Math.max(0, height) }, (_line, index) => {
+        if (index === middle - 1)
+            return centre(theme.fg("muted", mark), mark, width);
+        return index === middle ? centre(theme.fg("muted", message), message, width) : "";
+    });
+}
+function centre(painted, raw, width) {
+    return `${" ".repeat(Math.max(0, Math.floor((width - displayWidth(raw)) / 2)))}${painted}`;
+}
+function pad(line, width) {
+    const visible = displayWidth(line);
+    return visible >= width ? line : line + " ".repeat(width - visible);
+}

package/dist/ui/components/text-selection.d.ts

@@ -0,0 +1,62 @@
+/** A reported pointer cell plus its grapheme-aligned zero-based boundaries. */
+export interface TextSelectionPoint {
+    readonly line: number;
+    readonly column: number;
+    readonly from?: number;
+    readonly to?: number;
+}
+export interface TextSelection {
+    readonly anchor: TextSelectionPoint;
+    readonly head: TextSelectionPoint;
+    readonly selecting: boolean;
+    /** Ordinary point selection has received at least one distinct motion report. */
+    readonly dragged?: boolean;
+    /** Word selection uses inclusive pointer-cell endpoints supplied by its semantic range. */
+    readonly cell?: boolean;
+    readonly fullRow?: boolean;
+    /** Paint an edge whitespace run through the viewport's overlaid rail cell. */
+    readonly throughFinalColumn?: boolean;
+}
+export interface TextSelectionClick {
+    readonly time: number;
+    readonly line: number;
+    readonly column: number;
+    readonly count: number;
+}
+export interface TextSelectionLineContent {
+    readonly from?: number;
+    readonly to?: number;
+    readonly selectable?: boolean;
+}
+/** Ordered zero-based, half-open display-column boundaries. */
+export interface OrderedTextSelection {
+    readonly start: TextSelectionPoint;
+    readonly end: TextSelectionPoint;
+    readonly fullRow?: boolean;
+    readonly throughFinalColumn?: boolean;
+}
+export interface TextSelectionPressInput {
+    readonly line: number;
+    readonly column: number;
+    readonly contentWidth: number;
+    readonly lineText: string;
+    readonly lineContent?: TextSelectionLineContent;
+    readonly previousClick?: TextSelectionClick;
+    readonly now?: number;
+}
+export declare const TEXT_SELECTION_MULTI_CLICK_MS = 500;
+export declare function orderedTextSelection(selection: TextSelection | undefined): OrderedTextSelection | undefined;
+export declare function pressTextSelection(input: TextSelectionPressInput): {
+    readonly selection?: TextSelection;
+    readonly click: TextSelectionClick;
+    readonly kind: "point" | "word" | "line";
+};
+export declare function extendTextSelection(selection: TextSelection | undefined, point: TextSelectionPoint): TextSelection | undefined;
+export declare function releaseTextSelection(selection: TextSelection | undefined): TextSelection | undefined;
+export declare function textSelectionLineExtendColumn(selection: TextSelection, line: number, contentWidth: number): number;
+/** Resolves a reported one-based pointer cell to the complete grapheme it intersects. */
+export declare function textSelectionPointAt(line: number, column: number, lineText: string): TextSelectionPoint;
+export declare function textSelectionText(selection: OrderedTextSelection, rows: readonly string[], lineContent?: (line: number) => TextSelectionLineContent | undefined): string;
+/** Returns the plain cells covered by [from,to), expanding at grapheme edges. */
+export declare function plainTextBetweenColumns(line: string, from: number, to: number): string;
+export declare function usefulTextLineContent(line: string, from?: number): TextSelectionLineContent;

package/dist/ui/components/text-selection.js

@@ -0,0 +1,210 @@
+import { displayWidth, stripAnsi } from "./text.js";
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+export const TEXT_SELECTION_MULTI_CLICK_MS = 500;
+export function orderedTextSelection(selection) {
+    if (selection === undefined)
+        return undefined;
+    const { anchor, head } = selection;
+    if (selection.fullRow) {
+        const startLine = Math.min(anchor.line, head.line);
+        const endLine = Math.max(anchor.line, head.line);
+        return {
+            start: { line: startLine, column: 0 },
+            end: { line: endLine, column: Number.MAX_SAFE_INTEGER },
+            fullRow: true,
+            ...(selection.throughFinalColumn ? { throughFinalColumn: true } : {}),
+        };
+    }
+    if (!selection.cell && selection.dragged !== true)
+        return undefined;
+    // Invariant: an accepted drag includes both endpoint graphemes, even after returning
+    // to its anchor. Only an unextended point press is empty; paint and copy stay half-open.
+    const anchorFirst = comparePoints(anchor, head) <= 0;
+    const first = anchorFirst ? anchor : head;
+    const last = anchorFirst ? head : anchor;
+    return {
+        start: { line: first.line, column: pointBefore(first) },
+        end: { line: last.line, column: pointAfter(last) },
+        ...(selection.throughFinalColumn ? { throughFinalColumn: true } : {}),
+    };
+}
+export function pressTextSelection(input) {
+    const now = input.now ?? Date.now();
+    const previous = input.previousClick;
+    const count = previous !== undefined
+        && now - previous.time <= TEXT_SELECTION_MULTI_CLICK_MS
+        && previous.line === input.line
+        && Math.abs(previous.column - input.column) <= 1
+        ? previous.count + 1
+        : 1;
+    const click = { time: now, line: input.line, column: input.column, count };
+    const column = clamp(input.column, 1, Math.max(1, input.contentWidth));
+    const kind = ((count - 1) % 3) + 1;
+    if (kind === 2) {
+        const selection = selectWord(input.line, column, input.contentWidth, input.lineText);
+        return selection === undefined ? { click, kind: "word" } : { selection, click, kind: "word" };
+    }
+    if (kind === 3) {
+        if (input.lineContent?.selectable === false)
+            return { click, kind: "line" };
+        const from = clamp(input.lineContent?.from ?? 1, 1, Math.max(1, input.contentWidth));
+        const to = clamp(input.lineContent?.to ?? input.contentWidth, from, Math.max(1, input.contentWidth));
+        return {
+            selection: {
+                anchor: { line: input.line, column: from },
+                head: { line: input.line, column: to },
+                selecting: true,
+                cell: true,
+                fullRow: true,
+            },
+            click,
+            kind: "line",
+        };
+    }
+    const point = textSelectionPointAt(input.line, column, input.lineText);
+    return {
+        selection: {
+            anchor: point,
+            head: point,
+            selecting: true,
+            dragged: false,
+        },
+        click,
+        kind: "point",
+    };
+}
+export function extendTextSelection(selection, point) {
+    if (selection?.selecting !== true)
+        return selection;
+    const distinctMotion = comparePoints(selection.head, point) !== 0;
+    if (!distinctMotion)
+        return selection;
+    if (selection.fullRow)
+        return { ...selection, head: point };
+    return {
+        ...selection,
+        head: point,
+        dragged: true,
+    };
+}
+export function releaseTextSelection(selection) {
+    if (selection === undefined)
+        return undefined;
+    const released = selection.selecting ? { ...selection, selecting: false } : selection;
+    return orderedTextSelection(released) === undefined ? undefined : released;
+}
+export function textSelectionLineExtendColumn(selection, line, contentWidth) {
+    return line < selection.anchor.line ? 1 : Math.max(1, contentWidth);
+}
+/** Resolves a reported one-based pointer cell to the complete grapheme it intersects. */
+export function textSelectionPointAt(line, column, lineText) {
+    const plain = stripAnsi(lineText);
+    const target = Math.max(0, column - 1);
+    let width = 0;
+    for (const { segment } of GRAPHEMES.segment(plain)) {
+        const cellWidth = displayWidth(segment);
+        const next = width + cellWidth;
+        if (cellWidth > 0 && target >= width && target < next) {
+            return { line, column, from: width, to: next };
+        }
+        width = next;
+    }
+    return { line, column, from: target, to: target + 1 };
+}
+export function textSelectionText(selection, rows, lineContent) {
+    const parts = [];
+    for (let line = selection.start.line; line <= selection.end.line && line < rows.length; line += 1) {
+        const plain = stripAnsi(rows[line] ?? "");
+        const content = lineContent?.(line);
+        if (content?.selectable === false) {
+            parts.push("");
+            continue;
+        }
+        const baseFrom = line === selection.start.line ? selection.start.column : 0;
+        const baseTo = line === selection.end.line ? selection.end.column : Number.MAX_SAFE_INTEGER;
+        const contentFrom = Math.max(0, (content?.from ?? 1) - 1);
+        const contentTo = Math.max(contentFrom, (content?.to ?? Number.MAX_SAFE_INTEGER) - 1);
+        const from = Math.max(baseFrom, contentFrom);
+        const to = Math.max(from, Math.min(baseTo, contentTo));
+        parts.push(plain.slice(indexAtDisplayBoundary(plain, from, "start"), indexAtDisplayBoundary(plain, to, "end")).trimEnd());
+    }
+    return parts.join("\n");
+}
+/** Returns the plain cells covered by [from,to), expanding at grapheme edges. */
+export function plainTextBetweenColumns(line, from, to) {
+    const plain = stripAnsi(line);
+    return plain.slice(indexAtDisplayBoundary(plain, from, "start"), indexAtDisplayBoundary(plain, to, "end"));
+}
+export function usefulTextLineContent(line, from = 1) {
+    const start = Math.max(1, from);
+    const end = displayWidth(stripAnsi(line).replace(/\s+$/, "")) + 1;
+    return { from: start, to: Math.max(start, end) };
+}
+function selectWord(line, column, contentWidth, lineText) {
+    const plain = stripAnsi(lineText);
+    const segments = [];
+    let width = 0;
+    for (const { segment } of GRAPHEMES.segment(plain)) {
+        const cellWidth = displayWidth(segment);
+        if (cellWidth <= 0)
+            continue;
+        segments.push({ cls: characterClass(segment), from: width, to: width + cellWidth });
+        width += cellWidth;
+    }
+    const at = clamp(column, 1, Math.max(1, contentWidth)) - 1;
+    const index = segments.findIndex(segment => at >= segment.from && at < segment.to);
+    if (index < 0)
+        return undefined;
+    let low = index;
+    let high = index;
+    while (low > 0 && segments[low - 1]?.cls === segments[index]?.cls)
+        low -= 1;
+    while (high + 1 < segments.length && segments[high + 1]?.cls === segments[index]?.cls)
+        high += 1;
+    const end = segments[high]?.to ?? 1;
+    return {
+        anchor: { line, column: (segments[low]?.from ?? 0) + 1 },
+        head: { line, column: end },
+        selecting: true,
+        cell: true,
+        throughFinalColumn: segments[index]?.cls === 0 && end >= contentWidth,
+    };
+}
+function characterClass(character) {
+    if (/\s/u.test(character))
+        return 0;
+    if (/[\p{L}\p{N}_]/u.test(character))
+        return 1;
+    return 2;
+}
+function indexAtDisplayBoundary(plain, column, edge) {
+    if (column <= 0)
+        return 0;
+    if (column >= Number.MAX_SAFE_INTEGER - 1)
+        return plain.length;
+    let width = 0;
+    let index = 0;
+    for (const { segment } of GRAPHEMES.segment(plain)) {
+        const cellWidth = displayWidth(segment);
+        const next = width + cellWidth;
+        if (column < next)
+            return edge === "start" ? index : index + segment.length;
+        index += segment.length;
+        width = next;
+        if (width >= column)
+            return index;
+    }
+    return index;
+}
+function pointBefore(point) {
+    return point.from ?? Math.max(0, point.column - 1);
+}
+function pointAfter(point) {
+    return point.to ?? Math.max(0, point.column);
+}
+function comparePoints(left, right) {
+    return left.line === right.line ? left.column - right.column : left.line - right.line;
+}
+function clamp(value, minimum, maximum) {
+    return Math.max(minimum, Math.min(value, maximum));
+}

package/dist/ui/components/text.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Display-width text handling. Terminals lay out by column, not by code unit,
+ * so measuring with `String.length` mis-sizes CJK, emoji, and combining marks,
+ * and counting styling escapes as visible width breaks every layout that uses
+ * colour.
+ */
+/** Removes styling sequences so only visible characters remain. */
+export declare function stripAnsi(text: string): string;
+export interface DisplayColumnRange {
+    readonly from: number;
+    readonly to: number;
+}
+/** Visible-column segment (word, whitespace, or punctuation) under a pointer column. */
+export declare function displayWordColumnRange(text: string, pointerColumn: number): DisplayColumnRange | null;
+export interface DisplayColumnSlice {
+    /** Grapheme-aligned visible bounds in the source row. */
+    readonly from: number;
+    readonly to: number;
+    readonly text: string;
+}
+/** Plain graphemes intersecting a visible-column range, expanded at wide-character edges. */
+export declare function displayColumnSlice(text: string, requestedFrom: number, requestedTo: number): DisplayColumnSlice;
+/** Columns this text occupies once styling is removed. */
+export declare function displayWidth(text: string): number;
+/**
+ * Truncates to a column budget without splitting a grapheme. Styling sequences
+ * are carried through and a reset is appended when any style was opened, so a
+ * truncated row cannot leak colour into the rest of the line.
+ */
+export declare function truncateToWidth(text: string, maxWidth: number): string;
+/** Pads to an exact column count, truncating when the text is already wider. */
+export declare function padToWidth(text: string, width: number): string;
+/**
+ * A control that is present but cannot be used: the terminal own faint
+ * attribute over whatever colour it already carries, so it reads as half of what
+ * it would otherwise be in any theme.
+ */
+export declare function faint(text: string): string;

package/dist/ui/components/text.js

@@ -0,0 +1,185 @@
+/**
+ * Display-width text handling. Terminals lay out by column, not by code unit,
+ * so measuring with `String.length` mis-sizes CJK, emoji, and combining marks,
+ * and counting styling escapes as visible width breaks every layout that uses
+ * colour.
+ */
+const ANSI_PATTERN = /\[[0-9;:?]*[ -/]*[@-~]|[\]_][^]*(?:|\\)|[@-Z\\-_]/g;
+const SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const WORD_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "word" });
+/**
+ * Recommended-for-general-interchange emoji. Terminals give every one of these
+ * two columns wherever its code points sit, so the wide blocks in
+ * `codePointWidth` cannot carry the measurement alone: a lone U+26A1 or any
+ * U+FE0F presentation sequence escapes them and would measure one column short.
+ */
+const RGI_EMOJI_PATTERN = /^\p{RGI_Emoji}$/v;
+/** Columns a terminal advances for a tab, matching the host runtime. */
+const TAB_WIDTH = 3;
+/** Removes styling sequences so only visible characters remain. */
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, "");
+}
+function codePointWidth(codePoint) {
+    // Protocol: zero-width includes combining marks, joiners, variation selectors, and format characters.
+    if (codePoint === 0x200d || codePoint === 0xfeff)
+        return 0;
+    if (codePoint >= 0x0300 && codePoint <= 0x036f)
+        return 0;
+    if (codePoint >= 0x200b && codePoint <= 0x200f)
+        return 0;
+    if (codePoint >= 0xfe00 && codePoint <= 0xfe0f)
+        return 0;
+    if (codePoint >= 0x20d0 && codePoint <= 0x20f0)
+        return 0;
+    if (codePoint >= 0x1ab0 && codePoint <= 0x1aff)
+        return 0;
+    if (codePoint >= 0x1dc0 && codePoint <= 0x1dff)
+        return 0;
+    if (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
+        return 0;
+    // Protocol: wide cells include CJK, Hangul, fullwidth forms, and the emoji planes terminals render double-width.
+    if (codePoint >= 0x1100 && codePoint <= 0x115f)
+        return 2;
+    if (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f)
+        return 2;
+    if (codePoint >= 0xac00 && codePoint <= 0xd7a3)
+        return 2;
+    if (codePoint >= 0xf900 && codePoint <= 0xfaff)
+        return 2;
+    if (codePoint >= 0xfe30 && codePoint <= 0xfe6f)
+        return 2;
+    if (codePoint >= 0xff00 && codePoint <= 0xff60)
+        return 2;
+    if (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+        return 2;
+    if (codePoint >= 0x1f300 && codePoint <= 0x1f64f)
+        return 2;
+    if (codePoint >= 0x1f900 && codePoint <= 0x1f9ff)
+        return 2;
+    if (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+        return 2;
+    // Protocol: a tab advances to the host runtime's stop; other control characters occupy nothing.
+    if (codePoint === 0x09)
+        return TAB_WIDTH;
+    if (codePoint < 0x20 || (codePoint >= 0x7f && codePoint < 0xa0))
+        return 0;
+    return 1;
+}
+/** Cheap pre-filter: only clusters that could be emoji pay for the RGI test. */
+function couldBeEmoji(grapheme) {
+    const codePoint = grapheme.codePointAt(0) ?? 0;
+    return ((codePoint >= 0x1f000 && codePoint <= 0x1fbff) ||
+        (codePoint >= 0x2300 && codePoint <= 0x23ff) ||
+        (codePoint >= 0x2600 && codePoint <= 0x27bf) ||
+        (codePoint >= 0x2b00 && codePoint <= 0x2bff) ||
+        grapheme.length > 1);
+}
+/** Width of one grapheme cluster: two for emoji, else the widest code point it contains. */
+function graphemeWidth(grapheme) {
+    if (couldBeEmoji(grapheme) && RGI_EMOJI_PATTERN.test(grapheme))
+        return 2;
+    let width = 0;
+    for (const character of grapheme) {
+        width = Math.max(width, codePointWidth(character.codePointAt(0) ?? 0));
+    }
+    return width;
+}
+/** Visible-column segment (word, whitespace, or punctuation) under a pointer column. */
+export function displayWordColumnRange(text, pointerColumn) {
+    const plain = stripAnsi(text);
+    const pointer = Math.max(0, pointerColumn);
+    let column = 0;
+    for (const { segment } of WORD_SEGMENTER.segment(plain)) {
+        const width = displayWidth(segment);
+        const from = column;
+        const to = column + width;
+        if (pointer >= from && pointer < to)
+            return { from, to };
+        column = to;
+    }
+    return null;
+}
+/** Plain graphemes intersecting a visible-column range, expanded at wide-character edges. */
+export function displayColumnSlice(text, requestedFrom, requestedTo) {
+    const plain = stripAnsi(text);
+    const from = Math.max(0, requestedFrom);
+    const to = Math.max(from, requestedTo);
+    let column = 0;
+    let actualFrom;
+    let actualTo = from;
+    let selected = "";
+    for (const { segment } of SEGMENTER.segment(plain)) {
+        const width = graphemeWidth(segment);
+        const start = column;
+        const end = column + width;
+        if (end > from && start < to) {
+            actualFrom ??= start;
+            actualTo = end;
+            selected += segment;
+        }
+        column = end;
+        if (start >= to)
+            break;
+    }
+    return { from: actualFrom ?? from, to: actualFrom === undefined ? from : actualTo, text: selected };
+}
+/** Columns this text occupies once styling is removed. */
+export function displayWidth(text) {
+    let width = 0;
+    for (const { segment } of SEGMENTER.segment(stripAnsi(text)))
+        width += graphemeWidth(segment);
+    return width;
+}
+/**
+ * Truncates to a column budget without splitting a grapheme. Styling sequences
+ * are carried through and a reset is appended when any style was opened, so a
+ * truncated row cannot leak colour into the rest of the line.
+ */
+export function truncateToWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return "";
+    if (displayWidth(text) <= maxWidth)
+        return text;
+    let out = "";
+    let width = 0;
+    let styled = false;
+    let index = 0;
+    while (index < text.length) {
+        ANSI_PATTERN.lastIndex = index;
+        const match = ANSI_PATTERN.exec(text);
+        if (match && match.index === index) {
+            out += match[0];
+            styled = true;
+            index += match[0].length;
+            continue;
+        }
+        const nextEscape = match ? match.index : text.length;
+        for (const { segment } of SEGMENTER.segment(text.slice(index, nextEscape))) {
+            const segmentWidth = graphemeWidth(segment);
+            if (width + segmentWidth > maxWidth)
+                return styled ? `${out}` : out;
+            out += segment;
+            width += segmentWidth;
+        }
+        index = nextEscape;
+    }
+    return styled ? `${out}` : out;
+}
+/** Pads to an exact column count, truncating when the text is already wider. */
+export function padToWidth(text, width) {
+    if (width <= 0)
+        return "";
+    const current = displayWidth(text);
+    if (current > width)
+        return truncateToWidth(text, width);
+    return text + " ".repeat(width - current);
+}
+/**
+ * A control that is present but cannot be used: the terminal own faint
+ * attribute over whatever colour it already carries, so it reads as half of what
+ * it would otherwise be in any theme.
+ */
+export function faint(text) {
+    return `${text}`;
+}