@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/cells.js

@@ -0,0 +1,334 @@
+/**
+ * Terminal cell width calculation.
+ * Handles ASCII, CJK (double-width), and emoji characters.
+ */
+import stringWidth from "string-width";
+import { Memo } from "./memo.js";
+// [LAW:one-source-of-truth] string-width is the single authority for cell width
+const cellLenMemo = new Memo();
+/**
+ * Returns the terminal cell width of a string.
+ */
+export function cellLen(text) {
+    if (text.length === 0)
+        return 0;
+    // Short strings recur (words, cells, labels); a long one is rarely measured twice.
+    return text.length <= 64 ? cellLenMemo.get(text, stringWidth) : stringWidth(text);
+}
+/** Brand a raw number as a CellCol. Use only at trust boundaries. */
+export function asCellCol(n) { return n; }
+/** Brand a raw number as a CodeUnit. Use only at trust boundaries. */
+export function asCodeUnit(n) { return n; }
+/** Brand a raw number as a CodePoint. Use only when the value is known to be
+ *  on a Unicode code-point boundary. */
+export function asCodePoint(n) { return n; }
+/**
+ * [LAW:parse-dont-validate] A caller's number as a count of cells — the checked
+ * counterpart to `asCellCol`'s unchecked brand, and the one place the rule "a
+ * cell count is a non-negative integer" is written.
+ *
+ * [LAW:one-source-of-truth] Every renderable is handed `RenderOptions.maxWidth`
+ * as a plain `number`, so every renderable used to answer this for itself and
+ * they disagreed: at NaN, `Table` collapsed to one cell of garbage, `Columns`
+ * and `Layout` threw `Invalid array length`, and `RichText` ignored the request
+ * and emitted its full natural width. Parse at the entry to `render`/`measure`
+ * and nothing downstream re-asks.
+ *
+ * The comparison is the point, not `Math.max(0, n)`: NaN fails every comparison
+ * and so floors here, where `Math.max` would return it and let it poison every
+ * bounds check downstream. Integral because a cell is not divisible — a
+ * fractional budget reaches a largest-remainder division, which grants a whole
+ * cell against a fractional residue and hands out more width than it was given.
+ *
+ * `Infinity` is outside what the comparison floors, so it passes through
+ * unchanged, and no clamp belongs here: the finite answer to an unbounded offer
+ * is the renderable's own natural width, which this function cannot see from
+ * the number alone. `withBoundedWidth` in `protocol.ts` is the second half of
+ * the parse and the only place that value is resolved.
+ */
+export function cellCount(n) {
+    return (n > 0 ? Math.floor(n) : 0);
+}
+// ── Cell-aware string utilities ──────────────────────────────────────────────
+/**
+ * Pads or crops a string to exactly `totalWidth` terminal cells.
+ * Invariant: cellLen(setCellSize(text, n)) === n (unless n is 0)
+ */
+export function setCellSize(text, totalWidth) {
+    if (totalWidth === 0)
+        return "";
+    const currentWidth = cellLen(text);
+    if (currentWidth === totalWidth)
+        return text;
+    if (currentWidth < totalWidth) {
+        return text + " ".repeat(totalWidth - currentWidth);
+    }
+    return splitText(text, totalWidth)[0];
+}
+/**
+ * Splits text at a cell position. Returns [left, right].
+ * When the position falls mid-wide-character, the left side is padded
+ * to reach exactly `position` cells. The wide char remains in the right side.
+ *
+ * [LAW:one-source-of-truth] The left side is `cellFit`'s, so the cut falls
+ * between the grapheme clusters `cellLen` measures and never inside one.
+ */
+export function splitText(text, position) {
+    if (position <= 0)
+        return ["", text];
+    if (position >= cellLen(text))
+        return [text, ""];
+    const left = cellFit(text, position);
+    return [left + " ".repeat(position - cellLen(left)), text.slice(left.length)];
+}
+/**
+ * Cuts `text` into exactly `position` cells and the rest, as the reference's
+ * `Segment.split_cells` does: a wide glyph the cut goes through fits neither
+ * side, so it leaves a space in each of its cells, where `splitText` keeps it
+ * whole on the right. Every other character lands on exactly one side.
+ * `position` must fall inside `text`, between 0 and its width.
+ */
+export function cutCells(text, position) {
+    const head = cellFit(text, position);
+    // Cells of the glyph the cut goes through that lie left of it; 0 when the
+    // cut falls between glyphs, and then there is no such glyph.
+    const straddle = position - cellLen(head);
+    const [glyph = ""] = straddle > 0 ? clustersFrom(text, asCodePoint(head.length)) : [];
+    return [
+        head + " ".repeat(straddle),
+        " ".repeat(cellLen(glyph) - straddle) + text.slice(head.length + glyph.length),
+    ];
+}
+/**
+ * Wraps text into lines of at most `maxWidth` cells, preserving every code
+ * point: `chopCells(t, w).join("") === t`. Unlike `splitText` this never pads,
+ * so a line ending before a wide glyph is narrower than `maxWidth` rather than
+ * padded out to it.
+ *
+ * A line overflows exactly where the budget cannot be met: a glyph wider than
+ * `maxWidth` is force-taken whole rather than dropped, and a `maxWidth` of zero
+ * or less is no budget at all, so the text comes back as one line.
+ */
+export function chopCells(text, maxWidth) {
+    if (maxWidth <= 0 || text.length === 0)
+        return [text];
+    const lines = [];
+    let start = asCodePoint(0);
+    while (start < text.length) {
+        const end = cellStepFrom(text, start, maxWidth);
+        lines.push(text.slice(start, end));
+        start = end;
+    }
+    return lines;
+}
+/**
+ * `line` split at each of `cuts`, in one walk over it. Converting each cut to a
+ * code-unit offset on its own rescans the line from the start every time, which
+ * is quadratic in a long enough string.
+ */
+export function splitAtCells(line, cuts) {
+    const pieces = [];
+    let start = 0;
+    let offset = 0;
+    let cells = 0;
+    for (const ch of graphemes(line)) {
+        if (pieces.length < cuts.length && cells >= cuts[pieces.length]) {
+            pieces.push(line.slice(start, offset));
+            start = offset;
+        }
+        cells += cellLen(ch);
+        offset += ch.length;
+    }
+    return [...pieces, line.slice(start)];
+}
+// [LAW:no-shared-mutable-globals] Private memos, written only by `segmentsOf`:
+// the segmenter, and the segmentation of the last string walked, so a caller
+// stepping along one string does not re-segment the whole of it every step.
+let segmenter;
+let lastSegmented;
+/** The grapheme segmentation of `text`, reusing the last one when it is the same string. */
+function segmentsOf(text) {
+    if (lastSegmented?.text !== text) {
+        segmenter ??= new Intl.Segmenter(undefined, { granularity: "grapheme" });
+        lastSegmented = { text, segments: segmenter.segment(text) };
+    }
+    return lastSegmented.segments;
+}
+/**
+ * The grapheme clusters of `text`, in order: the unit `string-width` measures,
+ * and so the unit `cellLen` of a whole string is the sum of. Summing `cellLen`
+ * over code points instead disagrees with it on every glyph built from several:
+ * `❤️` is 1 + 0 by code point and 2 as a cluster, `👨‍👩‍👧` is 6 and 2, and a cut
+ * between two of its code points leaves half a glyph.
+ */
+export function graphemes(text) {
+    return Array.from(clustersFrom(text, asCodePoint(0)));
+}
+/**
+ * The clusters of `text` from code unit `start` on, lazily, so a walk that
+ * stops early pays only for the clusters it reads.
+ */
+function* clustersFrom(text, start) {
+    const segments = segmentsOf(text);
+    for (let at = start, s = segments.containing(at); s; s = segments.containing(at)) {
+        const end = s.index + s.segment.length;
+        yield text.slice(at, end);
+        at = asCodePoint(end);
+    }
+}
+/**
+ * Returns the largest prefix of `text` whose cell width fits within `cap` cells,
+ * cut between grapheme clusters. No padding — the returned string may be
+ * narrower than `cap` when the next glyph is wide and would overshoot. Never
+ * wider than `cap` cells.
+ *
+ * When the first glyph already exceeds `cap` cells, returns "" (the caller
+ * must decide whether to force-take the glyph or skip it).
+ */
+export function cellFit(text, cap) {
+    return text.slice(0, fitLength(clustersFrom(text, asCodePoint(0)), cap));
+}
+/** `cellFit` from the other end: the largest suffix of `text` within `cap` cells. */
+export function cellFitEnd(text, cap) {
+    return text.slice(text.length - fitLength(graphemes(text).reverse(), cap));
+}
+/** The code units of the leading `clusters` that fit within `cap` cells. */
+function fitLength(clusters, cap) {
+    let w = 0;
+    let n = 0;
+    for (const cluster of clusters) {
+        const cw = cellLen(cluster);
+        if (w + cw > cap)
+            break;
+        w += cw;
+        n += cluster.length;
+    }
+    return n;
+}
+/**
+ * Returns the largest code-unit end offset starting from `startCU` whose
+ * prefix (from `startCU`) has cell width ≤ `cap`. Iterates from the given
+ * offset without slicing the tail, avoiding O(N²) allocation when called
+ * repeatedly across a long string.
+ *
+ * [LAW:types-are-the-program] returns CodePoint because it stops between
+ * grapheme clusters, and every cluster boundary is a code-point boundary.
+ */
+export function cellFitFrom(text, startCU, cap) {
+    return asCodePoint(startCU + fitLength(clustersFrom(text, startCU), cap));
+}
+/**
+ * Like `cellFitFrom`, but for any `startCU` inside `text` the result is
+ * strictly past it: a glyph too wide for `cap` is force-taken whole and
+ * overflows `cap` by its own width. So a `while (i < text.length)` loop driven
+ * by this terminates by construction, and the re-brand is honest — both
+ * operands land on code-point boundaries, so their max does too.
+ *
+ * [LAW:single-enforcer] `cellFit` documents that its caller must choose between
+ * force-taking and skipping; this is that choice, made once. It was made twice
+ * before and the copies drifted — the textarea's soft wrap force-took,
+ * `chopCells` did neither and hung.
+ */
+export function cellStepFrom(text, startCU, cap) {
+    const [first = ""] = clustersFrom(text, startCU);
+    return asCodePoint(Math.max(cellFitFrom(text, startCU, cap), startCU + first.length));
+}
+/**
+ * The code-unit offset a visual column falls at: the end of the largest
+ * prefix of `content` within `cellCol` cells, so a column inside a wide glyph
+ * lands before it. The inverse of `cellLen(content.slice(0, offset))`.
+ */
+export function cellColToCodeUnitOffset(content, cellCol) {
+    return cellFitFrom(content, asCodePoint(0), cellCol);
+}
+/**
+ * The offset just past the grapheme cluster at `cu`: one step of a cursor, a
+ * Delete, a transposition, so `👍🏽` or `👨‍👩‍👧` moves and goes as the one
+ * glyph `cellLen` measures, never a code point at a time. `cu` is a cluster
+ * boundary in `s` (see `graphemeBoundary`); `s.length` gives `s.length`.
+ */
+export function nextGrapheme(s, cu) {
+    const [cluster = ""] = clustersFrom(s, cu);
+    return asCodePoint(cu + cluster.length);
+}
+/** `nextGrapheme` backwards: the start of the cluster ending at `cu`; 0 at the start. */
+export function prevGrapheme(s, cu) {
+    if (cu <= 0)
+        return asCodePoint(0);
+    return asCodePoint(segmentsOf(s).containing(cu - 1).index);
+}
+/**
+ * Where an offset into `s` comes to rest as a cursor: itself when it is a
+ * cluster boundary, else the end of the cluster it falls inside, and never
+ * past `s.length`. The one parse from any number to the boundaries
+ * `nextGrapheme` and `prevGrapheme` step between.
+ */
+export function graphemeBoundary(s, cu) {
+    const at = Math.min(cu, s.length);
+    const cluster = segmentsOf(s).containing(at);
+    return asCodePoint(cluster === undefined || cluster.index === at ? at : cluster.index + cluster.segment.length);
+}
+/**
+ * `n` as a `TabSize`, or a `RangeError` naming it. Rich divides by the tab
+ * size and raises on 0; here the value is refused where it is given, not at
+ * the first tab it meets.
+ */
+export function parseTabSize(n) {
+    if (!Number.isInteger(n) || n < 1) {
+        throw new RangeError(`tabSize must be a positive integer, got ${n}`);
+    }
+    return n;
+}
+/**
+ * `text` with each tab widened to the next tab stop — a multiple of `tabSize`
+ * cells from the start of its line — as Rich's `Text.expand_tabs` widens it, and
+ * `offsetOf`, where each code-unit offset into `text` lands in the result.
+ *
+ * A tab is a column position, not a run of spaces: one that already sits a
+ * cell short of a stop widens to a single space. `offsetOf` is there because a
+ * caller that annotates the text by offset — a `RichText`'s spans — has to move
+ * its offsets with the characters, or every annotation after a tab lands short
+ * of what it styled.
+ */
+export function expandTabs(text, tabSize) {
+    const [head, ...rest] = text.split("\t");
+    const tabAt = []; // offset of each tab in `text`
+    const grownBy = []; // code units added by this tab and every one before it
+    const columnAfter = (piece, column) => {
+        const newline = piece.lastIndexOf("\n");
+        return (newline < 0 ? column : 0) + cellLen(piece.slice(newline + 1));
+    };
+    // A piece's column is read only when a tab follows it, so text with no tab
+    // costs one `split` and no measuring.
+    let expanded = head;
+    let before = head; // the piece the next tab follows
+    let column = 0; // the column `before` starts at
+    let offset = head.length;
+    let grown = 0;
+    for (const piece of rest) {
+        column = columnAfter(before, column);
+        const spaces = tabSize - (column % tabSize);
+        grown += spaces - 1;
+        tabAt.push(offset);
+        grownBy.push(grown);
+        expanded += " ".repeat(spaces) + piece;
+        column += spaces;
+        before = piece;
+        offset += 1 + piece.length;
+    }
+    // An offset moves by what every tab before it grew: the count of tabs at
+    // offsets below it, found by bisection since `tabAt` ascends.
+    const offsetOf = (at) => {
+        let low = 0;
+        let high = tabAt.length;
+        while (low < high) {
+            const mid = (low + high) >> 1;
+            if (tabAt[mid] < at)
+                low = mid + 1;
+            else
+                high = mid;
+        }
+        return at + (low === 0 ? 0 : grownBy[low - 1]);
+    };
+    return { text: expanded, offsetOf };
+}

package/dist/core/clock.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Clock — the time source and timer whoever draws frames is handed, and the
+ * frame rate it ticks at.
+ *
+ * [LAW:no-ambient-temporal-coupling] Frame rate belongs to whoever draws the
+ * frames — an `App`, a `Live` — never to what is drawn, and each ticks on the
+ * `Clock` it was given. An `App` reads the frame's time through that clock and
+ * hands it to its view as data, so nothing rendered reads a clock, and an
+ * effect sampled thirty times a second or once every two seconds runs the
+ * same code.
+ *
+ * [LAW:effects-at-boundaries] The clock is a capability passed in, like the
+ * `TerminalHost`: a test hands over a clock whose time it moves by hand and
+ * counts frames with no real timer, and nothing it starts can outlive the
+ * thing that started it. `systemClock` is the one place the library reads the
+ * platform's clock and timers, and it reads them only when called.
+ */
+import type { Unsubscribe } from "./subscription.js";
+declare const parsed: unique symbol;
+/**
+ * How often frames are drawn: a positive, finite number of frames a second,
+ * fractional included — 0.5 is one frame every two seconds.
+ *
+ * [LAW:parse-dont-validate] Only `frameRate` makes one, so holding a
+ * `FrameRate` is the proof the number was checked, and nothing that takes one
+ * checks it again.
+ */
+export interface FrameRate {
+    readonly perSecond: number;
+    /** Seconds from one frame to the next. */
+    readonly interval: number;
+    readonly [parsed]: true;
+}
+/**
+ * `perSecond` as a `FrameRate`; anything but a positive, finite number throws,
+ * and so does a rate whose frames are further apart than a timer can wait —
+ * about 24.8 days.
+ */
+export declare function frameRate(perSecond: number): FrameRate;
+export interface Clock {
+    /** The time now, in seconds, on this clock's own timeline, which never runs backwards. */
+    now(): number;
+    /** Call `tick` once a frame at `rate` until the returned function is called. */
+    every(rate: FrameRate, tick: () => void): Unsubscribe;
+}
+/** The platform's monotonic clock and its interval timer. */
+export declare function systemClock(): Clock;
+export {};

package/dist/core/clock.js

@@ -0,0 +1,42 @@
+/**
+ * Clock — the time source and timer whoever draws frames is handed, and the
+ * frame rate it ticks at.
+ *
+ * [LAW:no-ambient-temporal-coupling] Frame rate belongs to whoever draws the
+ * frames — an `App`, a `Live` — never to what is drawn, and each ticks on the
+ * `Clock` it was given. An `App` reads the frame's time through that clock and
+ * hands it to its view as data, so nothing rendered reads a clock, and an
+ * effect sampled thirty times a second or once every two seconds runs the
+ * same code.
+ *
+ * [LAW:effects-at-boundaries] The clock is a capability passed in, like the
+ * `TerminalHost`: a test hands over a clock whose time it moves by hand and
+ * counts frames with no real timer, and nothing it starts can outlive the
+ * thing that started it. `systemClock` is the one place the library reads the
+ * platform's clock and timers, and it reads them only when called.
+ */
+// The longest delay a platform timer holds, in seconds: setInterval clamps a
+// longer one to a millisecond, which would turn the slowest rate into the
+// fastest.
+const LONGEST_INTERVAL = (2 ** 31 - 1) / 1000;
+/**
+ * `perSecond` as a `FrameRate`; anything but a positive, finite number throws,
+ * and so does a rate whose frames are further apart than a timer can wait —
+ * about 24.8 days.
+ */
+export function frameRate(perSecond) {
+    if (!(Number.isFinite(perSecond) && perSecond > 0 && 1 / perSecond <= LONGEST_INTERVAL)) {
+        throw new RangeError(`a frame rate is a positive, finite number of frames a second, at most ${LONGEST_INTERVAL} s apart, not ${perSecond}`);
+    }
+    return { perSecond, interval: 1 / perSecond };
+}
+/** The platform's monotonic clock and its interval timer. */
+export function systemClock() {
+    return {
+        now: () => performance.now() / 1000,
+        every: (rate, tick) => {
+            const timer = setInterval(tick, rate.interval * 1000);
+            return () => clearInterval(timer);
+        },
+    };
+}