@timurproko/a1 0.1.8-dev.235df0e → 0.1.8-dev.260

package/dist/ui/components/spans.js

@@ -0,0 +1,257 @@
+import { displayWidth } from "./text.js";
+/**
+ * Ported from the A1 UI reference implementation (`core/presentation/spans.ts`).
+ * Writing over part of a rendered row is not string slicing: the row carries
+ * styling and hyperlink sequences, and cutting through them either loses the
+ * styling of the tail or leaks the span's own reset into it.
+ */
+const ANSI_SEQUENCE = "\\u001b(?:\\[[0-?]*[ -/]*[@-~]|[\\]_][^\\u0007\\u001b]*(?:\\u0007|\\u001b\\\\|$))";
+const ANSI_SPLIT = new RegExp(`(${ANSI_SEQUENCE})`);
+const HYPERLINK = /^\]8;;([^]*)(?:|\\)?$/;
+const HYPERLINK_OFF = "]8;;\\";
+const SGR = /^\[[0-9;]*m$/;
+const BARE_URL = /https?:\/\/[^\s\u0000-\u001f\u007f<>"']+/giu;
+const TRAILING_URL_PUNCTUATION = /[.,;:!?]/u;
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/**
+ * Replaces the visible columns `[from, to)` of `line` with `span`, preserving
+ * the styling before it and re-asserting whatever was still open afterwards, so
+ * the tail keeps the colour it had. A wide character straddling either edge is
+ * replaced by spaces rather than split.
+ */
+export function overlaySpan(line, from, to, span) {
+    let head = "";
+    let replay = "";
+    let tail = "";
+    let column = 0;
+    let hyperlinkOpen = false;
+    for (const token of line.split(ANSI_SPLIT)) {
+        if (!token)
+            continue;
+        if (token.startsWith("")) {
+            if (column >= to) {
+                tail += token;
+                continue;
+            }
+            if (column < from) {
+                head += token;
+                const link = HYPERLINK.exec(token);
+                if (link)
+                    hyperlinkOpen = (link[1] ?? "").length > 0;
+            }
+            // Invariant: re-assert everything still active: the span's own reset clobbers the tail.
+            replay += token;
+            continue;
+        }
+        for (const { segment } of GRAPHEMES.segment(token)) {
+            const width = displayWidth(segment);
+            if (column + width <= from)
+                head += segment;
+            else if (column >= to)
+                tail += segment;
+            else if (column < from)
+                head += " ".repeat(from - column);
+            else if (column + width > to)
+                tail += " ".repeat(column + width - to);
+            column += width;
+        }
+    }
+    if (column < from)
+        head += " ".repeat(from - column);
+    return head + (hyperlinkOpen ? HYPERLINK_OFF : "") + span + replay + tail;
+}
+/** Wraps visible columns `[from,to)` in an explicit OSC 8 hyperlink. */
+export function hyperlinkSgrSpan(line, from, to, target, widthOf = displayWidth) {
+    const on = `\u001b]8;;${target}\u001b\\`;
+    const off = "\u001b]8;;\u001b\\";
+    let output = "";
+    let column = 0;
+    let inside = false;
+    for (const token of line.split(ANSI_SPLIT)) {
+        if (!token)
+            continue;
+        if (token.startsWith("\u001b")) {
+            output += token;
+            continue;
+        }
+        for (const { segment } of GRAPHEMES.segment(token)) {
+            const shouldBeInside = column >= from && column < to;
+            if (shouldBeInside !== inside) {
+                output += shouldBeInside ? on : off;
+                inside = shouldBeInside;
+            }
+            output += segment;
+            column += widthOf(segment);
+        }
+    }
+    if (inside)
+        output += off;
+    return output;
+}
+/** Returns the OSC 8 target painted at a zero-based visible terminal column. */
+export function hyperlinkTargetAtColumn(line, targetColumn, widthOf = displayWidth) {
+    if (targetColumn < 0)
+        return undefined;
+    let hyperlinkTarget;
+    let column = 0;
+    for (const token of line.split(ANSI_SPLIT)) {
+        if (!token)
+            continue;
+        const link = HYPERLINK.exec(token);
+        if (link) {
+            hyperlinkTarget = (link[1] ?? "") || undefined;
+            continue;
+        }
+        if (token.startsWith("\u001b"))
+            continue;
+        for (const { segment } of GRAPHEMES.segment(token)) {
+            const width = widthOf(segment);
+            if (targetColumn >= column && targetColumn < column + width)
+                return hyperlinkTarget;
+            column += width;
+        }
+    }
+    return undefined;
+}
+/**
+ * Gives existing and bare web links explicit, tightly bounded OSC 8 regions so
+ * the terminal owns dotted-idle/solid-hover decoration without leaking hover
+ * state into cells repainted during scrolling.
+ */
+export function nativeHyperlinkStyle(line, color = text => text) {
+    let hyperlinkTarget;
+    let sgrReplay = "";
+    let output = "";
+    for (const token of line.split(ANSI_SPLIT)) {
+        if (!token)
+            continue;
+        const link = HYPERLINK.exec(token);
+        if (link) {
+            hyperlinkTarget = (link[1] ?? "") || undefined;
+            output += token;
+            continue;
+        }
+        if (!token.startsWith("\u001b")) {
+            output += hyperlinkTarget === undefined
+                ? decorateBareUrls(token, color, sgrReplay)
+                : color(token, hyperlinkTarget);
+            continue;
+        }
+        if (SGR.test(token)) {
+            if (token === "\u001b[0m")
+                sgrReplay = token;
+            else
+                sgrReplay += token;
+        }
+        if (hyperlinkTarget === undefined || (token !== "\u001b[4m" && token !== "\u001b[24m"))
+            output += token;
+    }
+    return hyperlinkTarget === undefined ? output : output + HYPERLINK_OFF;
+}
+/**
+ * Held-button paint for terminal-native links. OSC 8 is removed so the terminal
+ * cannot switch a selected link to its solid hover underline. A dotted SGR
+ * underline preserves the idle appearance, and VS15 transiently breaks native
+ * plain-text URL detection without changing visible width.
+ */
+export function heldNativeHyperlinkStyle(line) {
+    let hyperlinkTarget;
+    let fileDetectorBroken = false;
+    let output = "";
+    for (const token of line.split(ANSI_SPLIT)) {
+        if (!token)
+            continue;
+        const link = HYPERLINK.exec(token);
+        if (link) {
+            const nextTarget = (link[1] ?? "") || undefined;
+            if ((nextTarget !== undefined) !== (hyperlinkTarget !== undefined)) {
+                output += nextTarget === undefined ? "\u001b[24m" : "\u001b[4:4m";
+            }
+            if (nextTarget !== hyperlinkTarget)
+                fileDetectorBroken = false;
+            hyperlinkTarget = nextTarget;
+            continue;
+        }
+        if (token.startsWith("\u001b")) {
+            output += token;
+            // Protocol: foreground helpers may reset every SGR attribute; restore the held
+            // dotted underline without disturbing the source colour or intensity.
+            if (hyperlinkTarget !== undefined && SGR.test(token))
+                output += "\u001b[4:4m";
+            continue;
+        }
+        if (hyperlinkTarget === undefined) {
+            output += token;
+            continue;
+        }
+        let painted = token.replaceAll("https://", "https:\uFE0E//").replaceAll("http://", "http:\uFE0E//");
+        // Platform: Windows Terminal also detects file-link labels such as package.json and
+        // D:/work/file.ts after OSC 8 is removed. Break that detector once inside
+        // the paint-only label; semantic transcript text remains untouched.
+        if (!fileDetectorBroken && /^file:/iu.test(hyperlinkTarget)) {
+            const firstVisible = /\S/u.exec(painted);
+            if (firstVisible?.index !== undefined) {
+                const index = firstVisible.index;
+                const codePoint = painted.codePointAt(index) ?? 0;
+                const end = index + (codePoint > 0xffff ? 2 : 1);
+                painted = `${painted.slice(0, end)}\uFE0E${painted.slice(end)}`;
+                fileDetectorBroken = true;
+            }
+        }
+        output += painted;
+    }
+    return hyperlinkTarget === undefined ? output : `${output}\u001b[24m`;
+}
+function decorateBareUrls(text, color, sgrReplay) {
+    return text.replace(BARE_URL, candidate => {
+        const { target, trailing } = splitUrlTrailingPunctuation(candidate);
+        if (target.length === 0)
+            return candidate;
+        return `\u001b]8;;${target}\u001b\\\u001b[24m${color(target, target)}${HYPERLINK_OFF}${sgrReplay}${trailing}`;
+    });
+}
+function splitUrlTrailingPunctuation(candidate) {
+    let end = candidate.length;
+    while (end > 0 && TRAILING_URL_PUNCTUATION.test(candidate[end - 1] ?? ""))
+        end -= 1;
+    for (const [opening, closing] of [["(", ")"], ["[", "]"], ["{", "}"]]) {
+        while (candidate.slice(0, end).endsWith(closing)
+            && occurrences(candidate.slice(0, end), closing) > occurrences(candidate.slice(0, end), opening)) {
+            end -= 1;
+        }
+    }
+    return { target: candidate.slice(0, end), trailing: candidate.slice(end) };
+}
+function occurrences(text, value) {
+    return text.split(value).length - 1;
+}
+export function backgroundSgrSpan(line, from, to, on = "\u001b[47m", off = "\u001b[49m", widthOf = displayWidth) {
+    let output = "";
+    let seen = "";
+    let column = 0;
+    let inside = false;
+    for (const token of line.split(ANSI_SPLIT)) {
+        if (!token)
+            continue;
+        if (token.startsWith("\u001b")) {
+            output += token;
+            if (SGR.test(token))
+                seen += token;
+            if (inside)
+                output += on;
+            continue;
+        }
+        for (const { segment } of GRAPHEMES.segment(token)) {
+            const shouldBeInside = column >= from && column < to;
+            if (shouldBeInside !== inside) {
+                output += shouldBeInside ? on : off + seen;
+                inside = shouldBeInside;
+            }
+            output += segment;
+            column += widthOf(segment);
+        }
+    }
+    if (inside)
+        output += off;
+    return output;
+}

package/dist/ui/components/submitted-prompt.d.ts

@@ -0,0 +1,23 @@
+/** Visible width of the submitted-prompt prefix (`❯ `). */
+export declare const SUBMITTED_PROMPT_PREFIX_WIDTH = 2;
+export interface SubmittedPromptStyle {
+    readonly prefix?: (text: string) => string;
+    readonly timestamp?: (text: string) => string;
+}
+export interface SubmittedPromptLayout {
+    readonly contentWidth: number;
+    readonly timestamp: string | null;
+}
+/** Formats transcript metadata, never render time, as local 24-hour HH:mm. */
+export declare function formatSubmittedPromptTime(source: Date | number): string | null;
+/**
+ * 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 declare function submittedPromptLayout(width: number, source?: Date | number | null): SubmittedPromptLayout;
+/**
+ * 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 declare function composeSubmittedPromptRows(contentRows: readonly string[], width: number, source?: Date | number | null, style?: SubmittedPromptStyle): readonly string[];

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/{src/foundation/ui-components → ui/components}/surface.d.ts

@@ -1,10 +1,5 @@
 import { type ScrollbarGeometry } from "./scrollbar.js";
 import type { UiTheme } from "./theme.js";
-/**
- * The chrome around a list: the rail down its right edge, and what it shows when
- * there is nothing to list. Both are the same on any screen, so neither is a
- * screen's to draw.
- */
 /** Columns the rail occupies: its own, plus the gap before it. */
 export declare const RAIL_COLUMNS = 2;
 export interface RailOptions {

package/dist/{src/foundation/ui-components → ui/components}/surface.js

@@ -1,10 +1,6 @@
 import { isThumbRow } from "./scrollbar.js";
 import { displayWidth } from "./text.js";
-/**
- * The chrome around a list: the rail down its right edge, and what it shows when
- * there is nothing to list. Both are the same on any screen, so neither is a
- * screen's to draw.
- */
+// 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. */

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,208 @@
+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;
+    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/{src/foundation/ui-components → ui/components}/text.d.ts

@@ -6,6 +6,20 @@
  */
 /** 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;
 /**