@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/core/view.d.ts

@@ -22,9 +22,9 @@
  * anything it draws. What the drawn frame says about when it changes is on
  * the timeline's clock, and `drawView` carries it back onto the host's by
  * running the frame through the same timeline: the frame is a sample held
- * for the intersection of its cells' holds (`Segment.lastChange`,
- * `Segment.nextChange`) and the holds it was told that no cell carries
- * (`RenderOptions.onHold`), and `Timeline.run` is the one place a hold is
+ * for the intersection of its cells' holds (`Segment.validFrom`,
+ * `Segment.validUntil`) and the holds it was told that no cell carries
+ * (`RenderOptions.onValidity`), and `Timeline.run` is the one place a hold is
  * mapped onto host time, forwards, backwards or paused.
  *
  * What a host does with that is its own policy, and it reads it off the
@@ -33,7 +33,7 @@
  * auto-refresh, polls every frame.
  *
  * Tier 7 of `src/core/`: `./animation.ts`'s `Animation`, `./timeline.ts`,
- * `./segment.ts`, `./protocol.ts` and `./style.ts`'s `Hold`, nothing else.
+ * `./segment.ts`, `./protocol.ts` and `./style.ts`'s holds, nothing else.
  * [LAW:one-way-deps]
  */
 import { type HostFrame, type Renderable, type RenderOptions } from "./protocol.js";
@@ -86,7 +86,7 @@ export interface FrameSays {
     /** The host time the frame was drawn at. */
     readonly t: number;
     /** The first host moment, never before `t`, at which the frame may stop showing this: `t` while it moves, `Infinity` once it never will. */
-    readonly nextChange: number;
+    readonly validUntil: number;
 }
 /** A frame drawn from a view: its lines, and what it says. */
 export interface DrawnView extends FrameSays {

package/dist/core/view.js

@@ -22,9 +22,9 @@
  * anything it draws. What the drawn frame says about when it changes is on
  * the timeline's clock, and `drawView` carries it back onto the host's by
  * running the frame through the same timeline: the frame is a sample held
- * for the intersection of its cells' holds (`Segment.lastChange`,
- * `Segment.nextChange`) and the holds it was told that no cell carries
- * (`RenderOptions.onHold`), and `Timeline.run` is the one place a hold is
+ * for the intersection of its cells' holds (`Segment.validFrom`,
+ * `Segment.validUntil`) and the holds it was told that no cell carries
+ * (`RenderOptions.onValidity`), and `Timeline.run` is the one place a hold is
  * mapped onto host time, forwards, backwards or paused.
  *
  * What a host does with that is its own policy, and it reads it off the
@@ -33,11 +33,12 @@
  * auto-refresh, polls every frame.
  *
  * Tier 7 of `src/core/`: `./animation.ts`'s `Animation`, `./timeline.ts`,
- * `./segment.ts`, `./protocol.ts` and `./style.ts`'s `Hold`, nothing else.
+ * `./segment.ts`, `./protocol.ts` and `./style.ts`'s holds, nothing else.
  * [LAW:one-way-deps]
  */
 import { activePass, render } from "./protocol.js";
 import { Segment } from "./segment.js";
+import { intersection, NEVER_CHANGES } from "./style.js";
 import { Timeline } from "./timeline.js";
 /** `view` as the renderable a host holds: a function is asked each time it is drawn. */
 export function hostView(view) {
@@ -77,9 +78,9 @@ export function frameNow(host, time) {
     return { time: frameTime(time), host };
 }
 /** What a frame not yet drawn at host time `t` says: nothing. */
-export const undrawn = (t) => ({ t, nextChange: Number.POSITIVE_INFINITY });
+export const undrawn = (t) => ({ t, validUntil: Number.POSITIVE_INFINITY });
 /** The hold of the frame `lines` draw, told `told` besides: the intersection of its cells' holds and it. */
-const frameHold = (lines, told) => lines.reduce((hold, row) => ({ lastChange: Math.max(hold.lastChange, Segment.lastChange(row)), nextChange: Math.min(hold.nextChange, Segment.nextChange(row)) }), told);
+const frameValidity = (lines, told) => lines.reduce((validity, row) => intersection(validity, { validFrom: Segment.validFrom(row), validUntil: Segment.validUntil(row) }), told);
 /**
  * `view` drawn by `drawnBy` at `time` under `options`, its lines shaped by
  * `draw` — the host's own render under those options, with its height and
@@ -91,17 +92,17 @@ const frameHold = (lines, told) => lines.reduce((hold, row) => ({ lastChange: Ma
  */
 export function drawView(view, time, drawnBy, options, draw) {
     const { now: host, timeline } = time;
-    let told = { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY };
-    const onHold = (hold) => {
-        told = { lastChange: Math.max(told.lastChange, hold.lastChange), nextChange: Math.min(told.nextChange, hold.nextChange) };
+    let told = NEVER_CHANGES;
+    const onValidity = (validity) => {
+        told = intersection(told, validity);
     };
     // Made before the render opens: the one time the frame has.
     const frame = frameNow(drawnBy, time);
-    const lines = draw(view, { ...options, frame, onHold });
-    const hold = frameHold(lines, told);
+    const lines = draw(view, { ...options, frame, onValidity });
+    const validity = frameValidity(lines, told);
     // The frame as the sample of the view it is, on the timeline's clock; the
     // timeline says when the host's clock leaves its hold.
-    const sample = { at: () => lines, nextChange: () => hold.nextChange, lastChange: () => hold.lastChange, reduced: () => sample };
-    const nextChange = Timeline.run(timeline, sample).nextChange(host);
-    return { t: host, lines, nextChange };
+    const sample = { at: () => lines, validUntil: () => validity.validUntil, validFrom: () => validity.validFrom, reduced: () => sample };
+    const validUntil = Timeline.run(timeline, sample).validUntil(host);
+    return { t: host, lines, validUntil };
 }

package/dist/core/wrap.d.ts

@@ -18,16 +18,30 @@
  * line still too wide once wrapping is done. That order is the whole reason a
  * long sentence in a table cell grows the row while an unbreakable word in the
  * same cell still ellipsizes.
+ *
+ * Rich breaks only at whitespace, and that is what happens to any word holding
+ * nothing below: `test/core/text-wrap.golden.txt` pins it. Past that, a word
+ * breaks where its text says it may (UAX #14): after ZWSP, at a soft hyphen, and
+ * between the words of a script written without spaces. U+2060 and U+FEFF forbid
+ * a break, which here needs nothing but not being one.
  */
-import { type CellCol } from "./cells.js";
+import { type CellCol, type CodePoint } from "./cells.js";
+/** One place a line of text was cut. */
+export interface LineBreak {
+    /** Where the line is cut, in cells. */
+    readonly cell: CellCol;
+    /** The soft hyphen this break draws as `-`. Absent at any other break, and where no hyphen fits. */
+    readonly hyphen: CodePoint | undefined;
+}
 /**
- * The cells each word of `text` needs, in order — the widest is the narrowest
- * width `divideLine` can wrap it to without cutting a word.
+ * The cells each piece of `text` needs, in order — the widest is the narrowest
+ * width `divideLine` can wrap it to without cutting a word. A hyphen is not in
+ * them: where it does not fit, the break goes without it.
  */
 export declare function wordWidths(text: string): number[];
 /**
- * The cell offsets `text` should be cut at to wrap it into lines of at most
- * `width` cells, for `Segment.divide` to apply to the styled line.
+ * The breaks that wrap `text` into lines of at most `width` cells, for
+ * `Segment.divide` to apply to the styled line.
  *
  * `fold` decides what happens to a word that fits on no line at all: folded,
  * it is chopped across as many lines as it needs; unfolded, it is left whole
@@ -36,6 +50,10 @@ export declare function wordWidths(text: string): number[];
  * can truncate it, which is what makes an unbreakable word ellipsize while the
  * sentence around it merely wraps.
  *
+ * A piece that ends in a soft hyphen stays on a line only with room for the
+ * hyphen, so a line it closes holds it, and a word that fits whole needs none. A
+ * piece as wide as the line breaks with no hyphen rather than lose a letter to one.
+ *
  * Requires `width >= 1`. A zero-cell canvas gets no cuts, because "no cut
  * fits" and "no cell fits" are different facts and only one of them is a list
  * of offsets — the caller answers the second one by cropping the single
@@ -43,4 +61,4 @@ export declare function wordWidths(text: string): number[];
  */
 export declare function divideLine(text: string, width: CellCol, options: {
     fold: boolean;
-}): CellCol[];
+}): LineBreak[];

package/dist/core/wrap.js

@@ -18,8 +18,28 @@
  * line still too wide once wrapping is done. That order is the whole reason a
  * long sentence in a table cell grows the row while an unbreakable word in the
  * same cell still ellipsizes.
+ *
+ * Rich breaks only at whitespace, and that is what happens to any word holding
+ * nothing below: `test/core/text-wrap.golden.txt` pins it. Past that, a word
+ * breaks where its text says it may (UAX #14): after ZWSP, at a soft hyphen, and
+ * between the words of a script written without spaces. U+2060 and U+FEFF forbid
+ * a break, which here needs nothing but not being one.
  */
-import { cellLen, chopCells, asCellCol } from "./cells.js";
+import { asCellCol, asCodePoint, cellLen, chopCells } from "./cells.js";
+import { pattern } from "./pattern.js";
+const SOFT_HYPHEN = "\u00ad";
+const ZWSP = "\u200b";
+// The scripts UAX #14 sends to a dictionary (line break class SA) and ICU has one
+// for. Which words it finds varies by ICU, and a dictionary cannot be vendored as
+// the width table is; a word it misses is folded like any other.
+const UNSPACED = "[\\p{Script_Extensions=Thai}\\p{Script_Extensions=Lao}\\p{Script_Extensions=Khmer}\\p{Script_Extensions=Myanmar}]+";
+const BREAKABLE = pattern(new RegExp(`[${SOFT_HYPHEN}${ZWSP}]|${UNSPACED}`, "u"));
+const WORD_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "word" });
+// A break needs a glyph on both sides of it: with none before, nothing breaks away
+// or takes a hyphen, and with none after, the word was already over.
+const UNDRAWN = "\\s\\p{Cf}\\p{Mn}";
+const OPENING = pattern(new RegExp(`^[${UNDRAWN}]*`, "u"));
+const THROUGH_LAST_GLYPH = pattern(new RegExp(`^[^]*[^${UNDRAWN}]`, "u"));
 /**
  * Each word of `text` in order, where a "word" carries its own trailing
  * whitespace — the run of spaces that follows it belongs to it, because that
@@ -34,7 +54,9 @@ function* words(text) {
     // Constructed per call rather than hoisted: a sticky regex carries its
     // `lastIndex` as mutable state, and a shared one would corrupt any two
     // interleaved walks. [LAW:no-shared-mutable-globals]
-    const re = /\s*\S+\s*/y;
+    // U+FEFF is outside it, as it is outside Python's `\s` and Rich's words: it is a
+    // no-break space that JavaScript's `\s` counts as a space.
+    const re = /[^\S\ufeff]*[\S\ufeff]+[^\S\ufeff]*/y;
     for (let match = re.exec(text); match !== null; match = re.exec(text)) {
         yield match[0];
     }
@@ -47,12 +69,46 @@ function* words(text) {
 function widthOf(word) {
     return cellLen(word.trimEnd());
 }
+/** The offsets inside `word`, ascending, that it may break at. */
+function breaksIn(word) {
+    if (word.match(BREAKABLE) === null)
+        return [];
+    const found = new Set();
+    // One break to a run of marks: a second would open a piece with nothing in it.
+    for (const { 0: mark, index } of word.matchAll(new RegExp(`(?<![${SOFT_HYPHEN}${ZWSP}])[${SOFT_HYPHEN}${ZWSP}]`, "gu")))
+        found.add(index + mark.length);
+    for (const { 0: run, index } of word.matchAll(new RegExp(UNSPACED, "gu"))) {
+        // A run's start is where the segmenter's input began, not a boundary it found:
+        // UAX #14 has these scripts break as letters do against what comes before them.
+        for (const { index: at } of WORD_SEGMENTER.segment(run))
+            if (at > 0)
+                found.add(index + at);
+    }
+    const start = OPENING.exec(word)[0].length;
+    const end = THROUGH_LAST_GLYPH.exec(word)?.[0].length ?? 0;
+    return [...found].filter((at) => at > start && at < end).sort((a, b) => a - b);
+}
+/** `text` as what wraps: its words, tiled further wherever one may break. */
+function* piecesOf(text) {
+    for (const word of words(text)) {
+        let start = 0;
+        for (const at of breaksIn(word)) {
+            const piece = word.slice(start, at);
+            const cells = widthOf(piece);
+            yield { text: piece, cells, hyphenates: cells > 0 && piece.endsWith(SOFT_HYPHEN) };
+            start = at;
+        }
+        const last = word.slice(start);
+        yield { text: last, cells: widthOf(last), hyphenates: false };
+    }
+}
 /**
- * The cells each word of `text` needs, in order — the widest is the narrowest
- * width `divideLine` can wrap it to without cutting a word.
+ * The cells each piece of `text` needs, in order — the widest is the narrowest
+ * width `divideLine` can wrap it to without cutting a word. A hyphen is not in
+ * them: where it does not fit, the break goes without it.
  */
 export function wordWidths(text) {
-    return Array.from(words(text), widthOf);
+    return Array.from(piecesOf(text), (piece) => piece.cells);
 }
 /**
  * A word chopped into pieces of at most `width` cells, as the reference chops
@@ -78,8 +134,8 @@ function foldWord(word, width) {
     return cellLen(pieces[0]) > width ? ["", ...pieces] : pieces;
 }
 /**
- * The cell offsets `text` should be cut at to wrap it into lines of at most
- * `width` cells, for `Segment.divide` to apply to the styled line.
+ * The breaks that wrap `text` into lines of at most `width` cells, for
+ * `Segment.divide` to apply to the styled line.
  *
  * `fold` decides what happens to a word that fits on no line at all: folded,
  * it is chopped across as many lines as it needs; unfolded, it is left whole
@@ -88,6 +144,10 @@ function foldWord(word, width) {
  * can truncate it, which is what makes an unbreakable word ellipsize while the
  * sentence around it merely wraps.
  *
+ * A piece that ends in a soft hyphen stays on a line only with room for the
+ * hyphen, so a line it closes holds it, and a word that fits whole needs none. A
+ * piece as wide as the line breaks with no hyphen rather than lose a letter to one.
+ *
  * Requires `width >= 1`. A zero-cell canvas gets no cuts, because "no cut
  * fits" and "no cell fits" are different facts and only one of them is a list
  * of offsets — the caller answers the second one by cropping the single
@@ -96,19 +156,22 @@ function foldWord(word, width) {
 export function divideLine(text, width, options) {
     if (width <= 0)
         return [];
-    const cuts = [];
+    const breaks = [];
     // A cut at the start of the text is not a cut: it would open the line with
     // an empty piece. [LAW:single-enforcer] for that rule, so neither arm below
     // has to restate it.
     const cutAt = (cell) => {
         if (cell > 0)
-            cuts.push(asCellCol(cell));
+            breaks.push({ cell: asCellCol(cell), hyphen: width - used > 0 ? softHyphen : undefined });
     };
     let used = 0; // cells already committed to the line being filled
     let wordStart = 0; // absolute cell offset where the current word begins
-    for (const word of words(text)) {
-        const wordWidth = widthOf(word);
-        if (width - used >= wordWidth) {
+    let offset = 0; // code units before the current word
+    let softHyphen; // the one the line being filled ends in
+    for (const piece of piecesOf(text)) {
+        const word = piece.text;
+        const wordWidth = piece.cells;
+        if (width - used >= wordWidth + (piece.hyphenates ? 1 : 0)) {
             used += cellLen(word);
         }
         else if (options.fold && wordWidth > width) {
@@ -119,13 +182,14 @@ export function divideLine(text, width, options) {
             let pieceStart = wordStart;
             for (let index = 0; index < pieces.length; index += 1) {
                 cutAt(pieceStart);
-                const piece = pieces[index];
+                softHyphen = undefined;
+                const fold = pieces[index];
                 // The last piece is what the *next* word finds already on the line;
                 // the rest are whole lines of their own.
                 if (index === pieces.length - 1)
-                    used = cellLen(piece);
+                    used = cellLen(fold);
                 else
-                    pieceStart += cellLen(piece);
+                    pieceStart += cellLen(fold);
             }
         }
         else {
@@ -135,6 +199,8 @@ export function divideLine(text, width, options) {
             used = cellLen(word);
         }
         wordStart += cellLen(word);
+        offset += word.length;
+        softHyphen = piece.hyphenates ? asCodePoint(offset - 1) : undefined;
     }
-    return cuts;
+    return breaks;
 }

package/dist/host/app.d.ts

@@ -31,6 +31,7 @@
  * — a focused field in a `WidgetApp` included — can swallow them.
  */
 import { type Clock, type FrameRate } from "../core/clock.js";
+import { type TerminalColors } from "../core/color.js";
 import { type ConsoleOptions } from "../core/console.js";
 import { Segment } from "../core/segment.js";
 import { type Surface } from "../core/paint.js";
@@ -38,7 +39,7 @@ import { type HostFrame, type FrameHost } from "../core/protocol.js";
 import type { Unsubscribe } from "../core/subscription.js";
 import { Timeline } from "../core/timeline.js";
 import { type View } from "../core/view.js";
-import { type KeyPress, type ScreenMouseEvent } from "./input.js";
+import { type KeyEvent, type TerminalMouseEvent, type TerminalReply } from "./input.js";
 import type { TerminalHost } from "./terminal-host.js";
 /**
  * Where an app is in its life. `idle` has not run; `running` holds the
@@ -46,7 +47,7 @@ import type { TerminalHost } from "./terminal-host.js";
  * the program; `stopped` has handed it back for good.
  */
 export type AppPhase = "idle" | "running" | "suspended" | "stopped";
-declare const DRAW_OPTIONS: readonly ["asciiOnly", "reducedMotion", "theme", "onStyleError", "markup", "highlight", "highlighter"];
+declare const DRAW_OPTIONS: readonly ["asciiOnly", "reducedMotion", "textOrder", "terminal", "theme", "onStyleError", "markup", "highlight", "highlighter"];
 type DrawOption = (typeof DRAW_OPTIONS)[number];
 type DrawOptions = Readonly<Pick<ConsoleOptions, DrawOption>>;
 export interface AppOptions extends DrawOptions {
@@ -88,7 +89,7 @@ export interface AppOptions extends DrawOptions {
  * A turn of the wheel, where the pointer was when it turned: `lines` is
  * positive towards the end of the content, a line a notch.
  */
-export interface Wheel {
+export interface WheelEvent {
     readonly x: number;
     readonly y: number;
     readonly lines: number;
@@ -97,11 +98,26 @@ declare const WHEEL_LINES: {
     readonly scroll_up: -1;
     readonly scroll_down: 1;
 };
-type WheelTurn = Extract<ScreenMouseEvent, {
+type WheelTurn = Extract<TerminalMouseEvent, {
     type: keyof typeof WHEEL_LINES;
 }>;
 /** A pointer event `onMouse` hears: every one but the vertical wheel, which is `onWheel`'s. */
-export type AppMouseEvent = Exclude<ScreenMouseEvent, WheelTurn>;
+export type AppMouseEvent = Exclude<TerminalMouseEvent, WheelTurn>;
+/**
+ * How an ask ended, with the replies heard before it did. `answered`: the
+ * terminal answered DA1, so a query with no reply among `replies` is one it
+ * does not support. `timeout`: it answered nothing in time, DA1 included.
+ * `left`: the app handed the terminal back first. `unasked`: the host writes
+ * to no terminal, so nothing was asked.
+ */
+export interface Asked {
+    readonly ended: "answered" | "timeout" | "left" | "unasked";
+    readonly replies: readonly TerminalReply[];
+}
+export interface AskOptions {
+    /** Seconds to wait for a terminal that answers nothing. Half a second, unless given. */
+    readonly timeout?: number;
+}
 export declare class App implements FrameHost {
     private readonly host;
     private readonly surface;
@@ -113,7 +129,11 @@ export declare class App implements FrameHost {
     private ticking;
     private said;
     private waking;
-    private readonly console;
+    private console;
+    private drawing;
+    private asking;
+    private asked;
+    private owedDa1;
     private _phase;
     private _frame;
     private readonly painter;
@@ -127,6 +147,26 @@ export declare class App implements FrameHost {
     private readonly input;
     private settle;
     constructor(options: AppOptions);
+    /**
+     * The terminal the app draws on: the colors a cell that sets none is drawn
+     * in, and the sixteen an ANSI color names — as given, or as the color
+     * depth assumes (`resolveTerminal`).
+     */
+    get terminal(): TerminalColors;
+    /** Draw on `terminal` from the next frame on — what `terminalColors` learned, say. */
+    set terminal(terminal: TerminalColors);
+    /**
+     * Ask the terminal: write `queries`, then DA1, and resolve with the replies
+     * heard before DA1's, or before the timeout or the app handing the terminal
+     * back. It rejects only when writing to the terminal throws. Asks run one
+     * after another, and only while the app runs: it holds raw mode and reads
+     * the input, so a reply reaches the ask and never a key handler. A reply no
+     * ask is waiting for is dropped. `queries` must not ask for DA1 itself: its
+     * reply would end the ask early.
+     */
+    ask(queries: readonly string[], options?: AskOptions): Promise<Asked>;
+    private drawingConsole;
+    private askNow;
     get phase(): AppPhase;
     /** The clock the app reads the time from: where the host time a `Timeline` operation takes is read. */
     get clock(): Clock;
@@ -186,10 +226,10 @@ export declare class App implements FrameHost {
      */
     onPaint(handler: (frame: readonly (readonly Segment[])[]) => void): Unsubscribe;
     /**
-     * Hear every key the app does not quit on, by the `KeyPress` the terminal
+     * Hear every key the app does not quit on, by the `KeyEvent` the terminal
      * reported; `keyName` names it. A handler that throws fails the app.
      */
-    onKey(handler: (press: KeyPress) => void): Unsubscribe;
+    onKey(handler: (press: KeyEvent) => void): Unsubscribe;
     /**
      * Hear every pointer event but the vertical wheel, which is `onWheel`'s,
      * in terminal cells. Only the alternate surface reports the pointer. A
@@ -204,7 +244,7 @@ export declare class App implements FrameHost {
      * and the first that moves something takes it. A handler that throws fails
      * the app.
      */
-    onWheel(handler: (wheel: Wheel) => boolean): Unsubscribe;
+    onWheel(handler: (wheel: WheelEvent) => boolean): Unsubscribe;
     /** Hand the terminal back for good; `run` resolves. */
     stop(): void;
     /**
@@ -217,6 +257,7 @@ export declare class App implements FrameHost {
     private enter;
     private leave;
     private end;
+    private reply;
     private key;
     private mouse;
     private hear;