@timurproko/a1 0.1.8-dev.157 → 0.1.8-dev.214

package/dist/integrations/pi/tui-runtime/input-presentation-coordinator.d.ts

@@ -0,0 +1,39 @@
+export type PiTuiInputCoordinationDecision = "safe" | "barrier";
+export type PiTuiInputSurfaceKind = "editor" | "owned" | "opaque";
+export interface PiTuiInputCoordinationScheduler {
+    scheduleImmediate(callback: () => void): ReturnType<typeof setImmediate>;
+    cancelImmediate(handle: ReturnType<typeof setImmediate>): void;
+}
+export interface PiTuiInputCoordinationTrace {
+    readonly phase: "receipt" | "semantic-start" | "semantic-end";
+    readonly revision: number;
+    readonly atMs: number;
+    readonly pendingDepth: number;
+    readonly pendingPresentationDepth: 0 | 1;
+    readonly appliedRevision: number;
+}
+export interface InputPresentationCoordinatorOptions {
+    readonly classify: (data: string) => PiTuiInputCoordinationDecision;
+    readonly deliver: (data: string) => void;
+    readonly onReceipt?: () => void;
+    readonly onTrace?: (event: PiTuiInputCoordinationTrace) => void;
+    readonly now?: () => number;
+    readonly scheduler?: PiTuiInputCoordinationScheduler;
+}
+/**
+ * Delivers complete terminal chunks in their original order while allowing Pi
+ * TUI's existing pending-render guard to present one current state per event
+ * loop turn. Unknown or effectful input is an immediate ordering barrier.
+ */
+export declare class InputPresentationCoordinator {
+    #private;
+    constructor(options: InputPresentationCoordinatorOptions);
+    get pendingDepth(): number;
+    get appliedRevision(): number;
+    get pendingPresentation(): boolean;
+    accept(data: string): void;
+    flush(): void;
+    dispose(deliverPending?: boolean): void;
+}
+/** Finite fail-closed grammar for input whose semantic handlers may run in one ordered drain. */
+export declare function classifyPiTuiInput(data: string, surface: PiTuiInputSurfaceKind): PiTuiInputCoordinationDecision;

package/dist/integrations/pi/tui-runtime/input-presentation-coordinator.js

@@ -0,0 +1,139 @@
+const SYSTEM_SCHEDULER = {
+    scheduleImmediate: callback => setImmediate(callback),
+    cancelImmediate: handle => clearImmediate(handle),
+};
+/**
+ * Delivers complete terminal chunks in their original order while allowing Pi
+ * TUI's existing pending-render guard to present one current state per event
+ * loop turn. Unknown or effectful input is an immediate ordering barrier.
+ */
+export class InputPresentationCoordinator {
+    #classify;
+    #deliver;
+    #onReceipt;
+    #onTrace;
+    #now;
+    #scheduler;
+    #pending = [];
+    #scheduled;
+    #nextRevision = 1;
+    #appliedRevision = 0;
+    #disposed = false;
+    constructor(options) {
+        this.#classify = options.classify;
+        this.#deliver = options.deliver;
+        this.#onReceipt = options.onReceipt;
+        this.#onTrace = options.onTrace;
+        this.#now = options.now ?? (() => performance.now());
+        this.#scheduler = options.scheduler ?? SYSTEM_SCHEDULER;
+    }
+    get pendingDepth() { return this.#pending.length; }
+    get appliedRevision() { return this.#appliedRevision; }
+    get pendingPresentation() { return this.#scheduled !== undefined; }
+    accept(data) {
+        if (this.#disposed || data.length === 0)
+            return;
+        const input = { revision: this.#nextRevision++, data };
+        this.#onReceipt?.();
+        if (this.#classify(data) === "barrier") {
+            this.#trace("receipt", input.revision);
+            this.flush();
+            this.#deliverOne(input);
+            return;
+        }
+        this.#pending.push(input);
+        if (this.#scheduled === undefined) {
+            this.#scheduled = this.#scheduler.scheduleImmediate(() => {
+                this.#scheduled = undefined;
+                this.#drain();
+            });
+        }
+        this.#trace("receipt", input.revision);
+    }
+    flush() {
+        if (this.#scheduled !== undefined)
+            this.#scheduler.cancelImmediate(this.#scheduled);
+        this.#scheduled = undefined;
+        this.#drain();
+    }
+    dispose(deliverPending = true) {
+        if (this.#disposed)
+            return;
+        if (deliverPending)
+            this.flush();
+        else {
+            if (this.#scheduled !== undefined)
+                this.#scheduler.cancelImmediate(this.#scheduled);
+            this.#scheduled = undefined;
+            this.#pending.length = 0;
+        }
+        this.#disposed = true;
+    }
+    #drain() {
+        while (this.#pending.length > 0)
+            this.#deliverOne(this.#pending.shift());
+    }
+    #deliverOne(input) {
+        this.#trace("semantic-start", input.revision);
+        try {
+            this.#deliver(input.data);
+        }
+        finally {
+            this.#appliedRevision = input.revision;
+            this.#trace("semantic-end", input.revision);
+        }
+    }
+    #trace(phase, revision) {
+        this.#onTrace?.({
+            phase,
+            revision,
+            atMs: this.#now(),
+            pendingDepth: this.#pending.length,
+            pendingPresentationDepth: this.#scheduled === undefined ? 0 : 1,
+            appliedRevision: this.#appliedRevision,
+        });
+    }
+}
+const SAFE_EDITING_INPUTS = new Set([
+    "\b",
+    "\u007f",
+    "\u001b[A",
+    "\u001b[B",
+    "\u001b[C",
+    "\u001b[D",
+    "\u001b[1;2A",
+    "\u001b[1;2B",
+    "\u001b[1;5C",
+    "\u001b[1;5D",
+    "\u001b[3~",
+    "\u001b[H",
+    "\u001b[F",
+    "\u001b[1~",
+    "\u001b[4~",
+]);
+const MAX_SAFE_TEXT_DELIVERY = 4096;
+/** Finite fail-closed grammar for input whose semantic handlers may run in one ordered drain. */
+export function classifyPiTuiInput(data, surface) {
+    if (surface === "opaque" || data.length === 0 || data.length > MAX_SAFE_TEXT_DELIVERY)
+        return "barrier";
+    if (SAFE_EDITING_INPUTS.has(data))
+        return "safe";
+    if (data.includes("\u001b") || data.includes("\r") || data.includes("\n") || data.includes("\u0003"))
+        return "barrier";
+    for (let index = 0; index < data.length; index += 1) {
+        const code = data.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            return "barrier";
+        if (code >= 0xd800 && code <= 0xdbff) {
+            if (index + 1 >= data.length)
+                return "barrier";
+            const next = data.charCodeAt(index + 1);
+            if (next < 0xdc00 || next > 0xdfff)
+                return "barrier";
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return "barrier";
+    }
+    return "safe";
+}

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-08-28T12:29:51.254Z",
+  "builtAt": "2026-09-02T16:56:10.577Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "7524bf568992517f50ed53196c861c5edeba0d7275633bb4735ab45bd5963a28",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-28T12:30:02.835Z",
+  "builtAt": "2026-09-02T16:56:00.627Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "ee8a00eaaf79c707459bbbfb52518e9739314967049fbe5fa625f36ce33db9ee",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-28T12:30:44.840Z",
+  "builtAt": "2026-09-02T16:57:49.437Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "ba7b712f918bc77cdf847bcb7b2473ded2aaf10b057bd12360ac3fa654b5f36c",
+    "sha256": "ec35b032d6aad590e2d8e9889958b552e5f2f6345324442dc2a3ba60be02fdd5",
     "size": 177664
   },
   "provenance": {

package/dist/ui/apps/host.js

@@ -1,5 +1,5 @@
 import { FrameCache, finalizeFrame, } from "../components/index.js";
-// The interrupt byte, written as an escape: as a raw byte it is invisible to
+// Invariant: the interrupt byte is written as an escape: as a raw byte it is invisible to
 // every text tool, and this constant had already been emptied by one.
 const INTERRUPT = "";
 /** How long the first interrupt of the chord stays armed. */
@@ -14,7 +14,7 @@ export class UiAppHost {
     #surface;
     #closeOnInterrupt;
     #theme;
-    /** When the first interrupt of a chord was seen, or null when disarmed. */
+    // Invariant: the first interrupt timestamp is null whenever the chord is disarmed.
     #interruptArmedAt = null;
     #renderedInterruptArmed;
     #cache = new FrameCache();
@@ -91,11 +91,7 @@ export class UiAppHost {
             this.render();
         return result;
     }
-    /**
-     * Two interrupts leave A1, from any screen. One arms the chord and repaints so
-     * the screen can say so; a second within the window exits rather than merely
-     * closing the screen, which is what the chord means everywhere else.
-     */
+    // Protocol: two interrupts within the chord window leave A1 from every screen.
     #interrupt() {
         const now = Date.now();
         const armed = this.#interruptArmedAt;
@@ -106,7 +102,7 @@ export class UiAppHost {
             return { consumed: true, render: true };
         }
         this.#interruptArmedAt = now;
-        // Host-owned state participates in the app's next frame independently of
+        // Invariant: host-owned state participates in the app's next frame independently of
         // the app's own revision contract.
         this.#cache.invalidate();
         return { consumed: true, render: true };
@@ -143,7 +139,7 @@ export class UiAppHost {
             ...(this.#theme === undefined ? {} : { theme: this.#theme }),
         };
     }
-    /** Contains a failure: the app is closed and the surface restored, never left broken. */
+    // Security: an app failure closes its app and restores the surface.
     #guard(work) {
         try {
             return work();

package/dist/ui/apps/registry.d.ts

@@ -1,4 +1,5 @@
 import { type AppRegistration } from "./contracts.js";
+/** Registers owned applications under unique routes and unregisters only the matching definition. */
 export declare class UiAppRegistry {
     #private;
     /** Registering a known id replaces its definition rather than adding a second app. */

package/dist/ui/apps/registry.js

@@ -1,4 +1,5 @@
 import { assertAppRegistration } from "./contracts.js";
+/** Registers owned applications under unique routes and unregisters only the matching definition. */
 export class UiAppRegistry {
     #byId = new Map();
     /** Registering a known id replaces its definition rather than adding a second app. */

package/dist/ui/components/dialog-panel.js

@@ -17,9 +17,11 @@ export function renderDialogPanel(state, width, theme) {
         const padded = `${row.label}${" ".repeat(Math.max(0, labelColumn - displayWidth(row.label)))}`;
         const cursor = selected ? "→ " : "  ";
         const raw = `${cursor}${padded}  ${row.value}`;
-        // An unselected label is left unpainted and its value quietened, both lifted
-        // to the accent on the row the cursor is on — as the engine paints its own.
-        const painted = `${theme.fg("accent", cursor)}${selected ? theme.fg("accent", padded) : padded}  ${theme.fg("muted", row.value)}`;
+        // Compatibility: match pinned SettingsList: selected cursor, label, and value all use the
+        // accent role; an unselected label is plain and its value is muted.
+        const painted = selected
+            ? `${theme.fg("accent", cursor)}${theme.fg("accent", padded)}  ${theme.fg("accent", row.value)}`
+            : `${cursor}${padded}  ${theme.fg("muted", row.value)}`;
         return pad(truncateToWidth(painted, width), width, raw);
     });
     const description = state.rows[state.index]?.description ?? "";

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

@@ -2,6 +2,7 @@ export interface PaneRect {
     readonly width: number;
     readonly height: number;
 }
+/** Identifies the pane whose bounded frame geometry or rendered rows violated the contract. */
 export declare class FrameContractError extends Error {
     readonly pane: string;
     constructor(pane: string, message: string);

package/dist/ui/components/frame.js

@@ -1,4 +1,5 @@
 import { displayWidth, truncateToWidth } from "./text.js";
+/** Identifies the pane whose bounded frame geometry or rendered rows violated the contract. */
 export class FrameContractError extends Error {
     pane;
     constructor(pane, message) {

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

@@ -6,6 +6,7 @@ export * from "./list-block.js";
 export * from "./list-view.js";
 export * from "./mouse.js";
 export * from "./pane.js";
+export * from "./progress-status.js";
 export * from "./revision.js";
 export * from "./scrollbar.js";
 export * from "./shortcuts.js";

package/dist/ui/components/index.js

@@ -6,6 +6,7 @@ export * from "./list-block.js";
 export * from "./list-view.js";
 export * from "./mouse.js";
 export * from "./pane.js";
+export * from "./progress-status.js";
 export * from "./revision.js";
 export * from "./scrollbar.js";
 export * from "./shortcuts.js";

package/dist/ui/components/line-input.d.ts

@@ -47,12 +47,7 @@ export declare class LineInput {
 }
 /** Applies one key to the input and reports whether the caller should commit. */
 export declare function handleLineInputKey(input: LineInput, data: string): LineInputOutcome;
-/**
- * The prompt the reference draws at the head of an input row, in the grey it
- * uses for one (#9AA0A6), painted foreground-only so anything drawn behind the
- * row survives.
- */
-/** A rule drawn in the prompt's own grey, as the reference rules an input row. */
+/** Draws the reference prompt rule foreground-only so underlying cells survive. */
 export declare function promptRule(width: number): string;
 export declare const PROMPT_GLYPH = "\u001B[38;2;154;160;166m\u276F\u001B[39m ";
 /**

package/dist/ui/components/line-input.js

@@ -148,7 +148,7 @@ export function handleLineInputKey(input, data) {
         return { kind: "accepted", value: input.value };
     if (data === "\u001b" || data === "\u0003")
         return { kind: "cancelled" };
-    // A word delete is decided before a plain one: on Windows Terminal the raw
+    // Platform: a word delete is decided before a plain one: on Windows Terminal the raw
     // backspace byte IS ctrl+backspace, and the plain branch would swallow it.
     if (data === "\b" || data === "\u001b\u007f" || data === "\u0017") {
         input.deleteWordBefore();
@@ -190,7 +190,7 @@ export function handleLineInputKey(input, data) {
         input.moveCaretToEnd();
         return { kind: "editing" };
     }
-    // Any other escape sequence is a key this input has no answer for - a page
+    // Rationale: any other escape sequence is a key this input has no answer for - a page
     // key, a function key, a chord. It is swallowed rather than typed, because the
     // one thing it certainly is not is text the reader meant to enter.
     if (data.startsWith("\u001b"))
@@ -198,12 +198,7 @@ export function handleLineInputKey(input, data) {
     input.insert(data);
     return { kind: "editing" };
 }
-/**
- * The prompt the reference draws at the head of an input row, in the grey it
- * uses for one (#9AA0A6), painted foreground-only so anything drawn behind the
- * row survives.
- */
-/** A rule drawn in the prompt's own grey, as the reference rules an input row. */
+/** Draws the reference prompt rule foreground-only so underlying cells survive. */
 export function promptRule(width) {
     return `\u001b[38;2;154;160;166m${"─".repeat(Math.max(0, width))}\u001b[39m`;
 }
@@ -224,7 +219,7 @@ export function renderInputRow(input, width, options = {}) {
     const before = view.text.slice(0, view.caretColumn);
     const under = view.text.slice(view.caretColumn, view.caretColumn + 1) || " ";
     const after = view.text.slice(view.caretColumn + 1);
-    // Typed text is left unpainted, the caret reverses its cell, and the
+    // Rationale: typed text is left unpainted, the caret reverses its cell, and the
     // placeholder is quietened by weight rather than by a colour of its own.
     const body = empty
         ? `${caretCell(placeholder.slice(0, 1))}${faint(placeholder.slice(1))}`

package/dist/ui/components/list-view.d.ts

@@ -1,10 +1,4 @@
 import type { UiTheme } from "./theme.js";
-/**
- * A list of things that each carry a label and a value. It owns where a value
- * starts, how a row reads when it is selected or pointed at, and which part of a
- * row the pointer is on — so a screen decides what a row means and this decides
- * how it looks and where it can be touched.
- */
 /** The part of a row the pointer is over. A label selects; a value acts. */
 export type ListRegion = "label" | "value" | "minus" | "plus";
 /** Columns a stepper's controls occupy on either side of the value. */

package/dist/ui/components/list-view.js

@@ -6,8 +6,8 @@ export const STEPPER_RESERVE = 2;
  * and with the stepper's columns reserved for every row when any row has one, so
  * a number does not shift its own value out of the column it shares.
  */
-export function valueColumnFor(rows, indent = 4, gap = 2) {
-    const widest = Math.max(0, ...rows.map(row => displayWidth(row.label)));
+export function valueColumnFor(rows, indent = 2, gap = 2) {
+    const widest = Math.min(30, Math.max(0, ...rows.map(row => displayWidth(row.label))));
     const stepper = rows.some(row => row.stepper !== undefined) ? STEPPER_RESERVE : 0;
     return indent + widest + gap + stepper;
 }
@@ -22,14 +22,21 @@ export function renderGroupHeader(title, width, theme) {
  */
 export function renderListRow(row, state, valueColumn, width, theme) {
     const cursor = state.selected ? "→ " : "  ";
-    const leftRaw = `${cursor}  ${row.label}`;
-    const left = `${theme.fg("accent", cursor)}  ${state.selected ? theme.fg("accent", row.label) : theme.plain(row.label)}`;
+    const labelColumn = Math.max(displayWidth(row.label), valueColumn - 4 - (row.stepper === undefined ? 0 : STEPPER_RESERVE));
+    const labelPadded = `${row.label}${" ".repeat(Math.max(0, labelColumn - displayWidth(row.label)))}`;
+    const leftRaw = `${cursor}${labelPadded}`;
+    const left = state.selected
+        ? `${theme.fg("accent", cursor)}${theme.fg("accent", labelPadded)}`
+        : `${cursor}${theme.plain(labelPadded)}`;
     const gap = Math.max(2, valueColumn - displayWidth(leftRaw));
-    // Pointing anywhere on the row is pointing at the item; pointing at the value
-    // is what brightens it. The selection speaks through the label alone.
+    // Compatibility: pinned SettingsList gives the selected label and value the same accent
+    // role. Pointer hover may brighten an unselected value without changing the
+    // keyboard selection.
     const valueHovered = state.hovered && state.region !== "label";
     const stepper = row.stepper !== undefined && valueHovered;
-    const value = valueHovered ? theme.plain(row.value) : theme.fg("muted", row.value);
+    const value = state.selected
+        ? theme.fg("accent", row.value)
+        : valueHovered ? theme.plain(row.value) : theme.fg("muted", row.value);
     const minus = stepper
         ? row.stepper?.lower === true
             ? state.region === "minus" ? theme.plain("- ") : theme.fg("dim", "- ")

package/dist/ui/components/progress-status.d.ts

@@ -0,0 +1,2 @@
+/** Returns spinner-backed status text with A1's canonical three-period marker. */
+export declare function progressStatusText(message: string): string;

package/dist/ui/components/progress-status.js

@@ -0,0 +1,4 @@
+/** Returns spinner-backed status text with A1's canonical three-period marker. */
+export function progressStatusText(message) {
+    return `${message.replace(/(?:…|\.+)$/u, "")}...`;
+}

package/dist/ui/components/scrollbar.js

@@ -14,7 +14,7 @@ export function scrollbarSelectionRows(speed) {
 /** Pure appearance decision; activity time is supplied so tests own the clock. */
 export function scrollbarPresentation(input) {
     const overflowing = input.geometry !== null;
-    // As in v2, auto/always reserve the final rail cell even while content fits.
+    // Invariant: auto/always reserve the final rail cell even while content fits.
     // The blank gutter prevents prompt timestamps from touching the terminal edge
     // and keeps later scrollbar appearance from reflowing the transcript.
     const reservesSpace = input.appearance !== "hidden";

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

@@ -40,6 +40,7 @@ export interface ShortcutRegistryResult {
  */
 export declare function assembleShortcuts(declarations: readonly ShortcutDeclaration[]): ShortcutRegistryResult;
 export declare function assertNoShortcutConflicts(result: ShortcutRegistryResult): void;
+/** Keeps shortcut dispatch and reader-facing listings derived from one ordered declaration set. */
 export declare class ShortcutRegistry<Action extends string = string> {
     #private;
     declare(declaration: ShortcutDeclaration, action: Action): void;

package/dist/ui/components/shortcuts.js

@@ -40,6 +40,7 @@ export function assertNoShortcutConflicts(result) {
             + `"${duplicate.descriptions[0]}" and "${duplicate.descriptions[1]}"`);
     }
 }
+/** Keeps shortcut dispatch and reader-facing listings derived from one ordered declaration set. */
 export class ShortcutRegistry {
     #declarations = [];
     #actions = new Map();

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

@@ -5,13 +5,10 @@
  * replaced by spaces rather than split.
  */
 export declare function overlaySpan(line: string, from: number, to: number, span: string): string;
-/**
- * Paints only a background over [from,to), preserving every glyph and its
- * foreground, bold, underline, and hyperlink styling. Embedded resets reapply
- * the selection background, while leaving the span restores the row's styles.
- */
 /** Wraps visible columns `[from,to)` in an explicit OSC 8 hyperlink. */
 export declare function hyperlinkSgrSpan(line: string, from: number, to: number, target: string, widthOf?: (text: string) => number): string;
+/** Returns the OSC 8 target painted at a zero-based visible terminal column. */
+export declare function hyperlinkTargetAtColumn(line: string, targetColumn: number, widthOf?: (text: string) => number): string | 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

package/dist/ui/components/spans.js

@@ -39,7 +39,7 @@ export function overlaySpan(line, from, to, span) {
                 if (link)
                     hyperlinkOpen = (link[1] ?? "").length > 0;
             }
-            // Re-assert everything still active: the span's own reset clobbers the tail.
+            // Invariant: re-assert everything still active: the span's own reset clobbers the tail.
             replay += token;
             continue;
         }
@@ -60,11 +60,6 @@ export function overlaySpan(line, from, to, span) {
         head += " ".repeat(from - column);
     return head + (hyperlinkOpen ? HYPERLINK_OFF : "") + span + replay + tail;
 }
-/**
- * Paints only a background over [from,to), preserving every glyph and its
- * foreground, bold, underline, and hyperlink styling. Embedded resets reapply
- * the selection background, while leaving the span restores the row's styles.
- */
 /** 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\\`;
@@ -93,6 +88,31 @@ export function hyperlinkSgrSpan(line, from, to, target, widthOf = displayWidth)
         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
@@ -154,7 +174,7 @@ export function heldNativeHyperlinkStyle(line) {
         }
         if (token.startsWith("\u001b")) {
             output += token;
-            // Foreground helpers may reset every SGR attribute; restore the held
+            // 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";
@@ -165,7 +185,7 @@ export function heldNativeHyperlinkStyle(line) {
             continue;
         }
         let painted = token.replaceAll("https://", "https:\uFE0E//").replaceAll("http://", "http:\uFE0E//");
-        // Windows Terminal also detects file-link labels such as package.json and
+        // 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)) {

package/dist/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/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

@@ -1,11 +1,17 @@
+/** 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. */
@@ -22,6 +28,7 @@ export interface TextSelectionLineContent {
     readonly to?: number;
     readonly selectable?: boolean;
 }
+/** Ordered zero-based, half-open display-column boundaries. */
 export interface OrderedTextSelection {
     readonly start: TextSelectionPoint;
     readonly end: TextSelectionPoint;
@@ -47,7 +54,9 @@ export declare function pressTextSelection(input: TextSelectionPressInput): {
 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), using terminal grapheme widths. */
+/** 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;