@promptctl/rich-js 0.19.0 → 0.21.0

package/README.md

@@ -387,9 +387,10 @@ npm run demo
 | `npm run template-bindings` | rich-template-bindings | Type a template on the left and watch it render on the right. |
 | `npm run themes-and-color-studio` | themes-and-color-studio | A printed tour of colours, palettes, bundled themes, and contrast. Prints once and exits; set any of `EXPORT_HTML=out.html`, `EXPORT_SVG=out.svg` and `EXPORT_TEXT=out.txt` to also save it to each file named. |
 | `npm run strip` | rich-strip | Every built-in `Joiner`, printed side by side. Prints once and exits. |
-| `npm run effects-feel` | effects-feel | Shimmer, pulse, drift, sparkle, fade-in and dissolve-out on a powerline strip and a run of text, at a frame rate, colour depth and ground you choose. A demo for agreeing how the effects feel; `npm run effects-feel -- --help` lists the flags. |
+| `npm run effects-feel` | effects-feel | Shimmer, a gentle pulse on chosen elements, sparkle, a hue wheel, fade-in and a dissolve-out that eddies back before it goes, on a powerline strip and a run of text, at a colour depth you choose, with keys to step the frame rate, the demo's pace and the theme while it runs. A demo for agreeing how the effects feel; `npm run effects-feel -- --help` lists the flags and keys. |
 | `npm run markup-plugins` | rich-markup-plugins | Custom markup tags registered through `MarkupRegistry`. Prints once and exits. |
-| `npm run viewport` | rich-viewport | A cursor walking a list taller than its window, kept in view by `Viewport.ensureVisible`. |
+| `npm run viewport` | rich-viewport | A selection you move through a list taller than its window with the arrow keys, `j`/`k`, PgUp/PgDn and Home/End, kept in view by `Viewport.ensureVisible`; the mouse wheel scrolls the window, and `q` quits. |
+| `npm run terminal-host` | terminal-host | Each key you press printed as the bytes the terminal sends for it, and each resize as the new size — a program written against `TerminalHost` alone. `examples/terminal-host/embed.ts` runs the same program on an xterm.js terminal in your own page. |
 
 `Ctrl-C` quits any demo that stays running.
 

package/dist/core/anchor.d.ts

@@ -43,3 +43,8 @@ export interface Anchor {
  * every level of the nesting — each level names the same cell.
  */
 export declare function shiftAnchor(anchor: Anchor, cells: number): Anchor;
+/**
+ * Whether `owner` drew the cell `anchor` names, itself or through an owner
+ * nested in its output.
+ */
+export declare function drawnBy(anchor: Anchor | undefined, owner: object): boolean;

package/dist/core/anchor.js

@@ -37,3 +37,13 @@ export function shiftAnchor(anchor, cells) {
         inner: anchor.inner && shiftAnchor(anchor.inner, cells),
     };
 }
+/**
+ * Whether `owner` drew the cell `anchor` names, itself or through an owner
+ * nested in its output.
+ */
+export function drawnBy(anchor, owner) {
+    for (let level = anchor; level; level = level.inner)
+        if (level.owner === owner)
+            return true;
+    return false;
+}

package/dist/core/color.d.ts

@@ -58,6 +58,7 @@ export declare function relativeLuminance(c: ColorRgba): number;
  * foreground, flatten it first (or use `ensureContrast`, which does).
  */
 export declare function contrastRatio(a: ColorRgba, b: ColorRgba): number;
+export declare function rgbDistance(a: ColorRgba, b: ColorRgba): number;
 /**
  * An indexed palette: entry `i` of `colors` is terminal index `firstIndex + i`.
  * `firstIndex` lets a table hold only the part of a palette a downgrade may

package/dist/core/color.js

@@ -113,8 +113,9 @@ function luminanceRatio(la, lb) {
 }
 // --- ColorTable ---
 // [LAW:one-source-of-truth] The one distance every table scan ranks by, so
-// `matchWhere`'s "nearest by the distance `match` uses" cannot drift.
-function rgbDistance(a, b) {
+// `matchWhere`'s "nearest by the distance `match` uses" cannot drift, and
+// `Effected` weighs a written colour against `ColorSpec.matchOn` by it too.
+export function rgbDistance(a, b) {
     const dr = a.red - b.red;
     const dg = a.green - b.green;
     const db = a.blue - b.blue;
@@ -580,7 +581,17 @@ export class ColorSpec {
             throw new ColorParseError(`A blend's fraction is in [0, 1]; got ${t}`);
         const a = from.fixedValue;
         const b = to.fixedValue;
-        return a !== undefined && b !== undefined ? ColorSpec.fromRgba(blendRgb(a, b, t)) : new ColorBlend(from, to, t);
+        if (a !== undefined && b !== undefined)
+            return ColorSpec.fromRgba(blendRgb(a, b, t));
+        // A blend that draws as one of its ends is that end — not a blend whose
+        // name no comparison will ever match back to it: at t 0 or 1, or between
+        // one slot of one palette spelled twice.
+        if (t === 0)
+            return from;
+        if (t === 1)
+            return to;
+        const oneSlot = from.type === to.type && (from.number !== undefined ? from.number === to.number : from.name === to.name);
+        return oneSlot ? from : new ColorBlend(from, to, t);
     }
     /**
      * The spec that draws `value` nearest to it at `depth` on a terminal known

package/dist/core/noise.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Gradient noise, the texture every effect in `renderables/effects` is drawn
+ * from. Ken Perlin's improved noise (2002): a smooth pseudo-random
+ * field over space and time, continuous in its first and second derivatives,
+ * so a cell sampled a moment later has moved a little, never jumped. Things
+ * the eye knows as alive — water, wind, breath, a glow — vary like this:
+ * coherent nearby, uncorrelated far apart, never repeating exactly.
+ *
+ * [LAW:no-ambient-temporal-coupling] A pure function of its coordinates; time
+ * is one of them. The permutation is fixed, so a moment draws the same frame
+ * on every run.
+ *
+ * Tier 0 of `src/core/`: imports nothing. Not part of the package's surface;
+ * the effects playground reaches it as source.
+ */
+/** Noise at (x, y, z), in about [-1, 1]; zero at every integer lattice point. */
+export declare function noise(x: number, y: number, z: number): number;
+/**
+ * Fractal Brownian motion: `octaves` layers of noise, each twice the
+ * frequency and half the amplitude of the last, scaled back into about
+ * [-1, 1]. One layer is a soft swell; three is a swell with detail on it.
+ */
+export declare function fbm(x: number, y: number, z: number, octaves: number): number;
+/**
+ * A pseudo-random number in [0, 1) for the `n`th of something — a breath, a
+ * gust — uncorrelated with the `n ± 1`th, where `noise` would make
+ * neighbours alike. The classic shader hash: the fraction of a large sine.
+ */
+export declare function hash(n: number, z: number): number;
+/** Hermite smoothstep from `a` to `b`, clamped to [0, 1]. */
+export declare function smoothstep(a: number, b: number, x: number): number;

package/dist/core/noise.js

@@ -0,0 +1,94 @@
+/**
+ * Gradient noise, the texture every effect in `renderables/effects` is drawn
+ * from. Ken Perlin's improved noise (2002): a smooth pseudo-random
+ * field over space and time, continuous in its first and second derivatives,
+ * so a cell sampled a moment later has moved a little, never jumped. Things
+ * the eye knows as alive — water, wind, breath, a glow — vary like this:
+ * coherent nearby, uncorrelated far apart, never repeating exactly.
+ *
+ * [LAW:no-ambient-temporal-coupling] A pure function of its coordinates; time
+ * is one of them. The permutation is fixed, so a moment draws the same frame
+ * on every run.
+ *
+ * Tier 0 of `src/core/`: imports nothing. Not part of the package's surface;
+ * the effects playground reaches it as source.
+ */
+/** Ken Perlin's reference permutation, doubled so a lookup never wraps. */
+const P = (() => {
+    const base = [
+        151, 160, 137, 91, 90, 15, 131, 13, 201, 95, 96, 53, 194, 233, 7, 225, 140, 36, 103, 30, 69, 142, 8, 99, 37, 240, 21, 10,
+        23, 190, 6, 148, 247, 120, 234, 75, 0, 26, 197, 62, 94, 252, 219, 203, 117, 35, 11, 32, 57, 177, 33, 88, 237, 149, 56, 87,
+        174, 20, 125, 136, 171, 168, 68, 175, 74, 165, 71, 134, 139, 48, 27, 166, 77, 146, 158, 231, 83, 111, 229, 122, 60, 211,
+        133, 230, 220, 105, 92, 41, 55, 46, 245, 40, 244, 102, 143, 54, 65, 25, 63, 161, 1, 216, 80, 73, 209, 76, 132, 187, 208,
+        89, 18, 169, 200, 196, 135, 130, 116, 188, 159, 86, 164, 100, 109, 198, 173, 186, 3, 64, 52, 217, 226, 250, 124, 123, 5,
+        202, 38, 147, 118, 126, 255, 82, 85, 212, 207, 206, 59, 227, 47, 16, 58, 17, 182, 189, 28, 42, 223, 183, 170, 213, 119,
+        248, 152, 2, 44, 154, 163, 70, 221, 153, 101, 155, 167, 43, 172, 9, 129, 22, 39, 253, 19, 98, 108, 110, 79, 113, 224, 232,
+        178, 185, 112, 104, 218, 246, 97, 228, 251, 34, 242, 193, 238, 210, 144, 12, 191, 179, 162, 241, 81, 51, 145, 235, 249,
+        14, 239, 107, 49, 192, 214, 31, 181, 199, 106, 157, 184, 84, 204, 176, 115, 121, 50, 45, 127, 4, 150, 254, 138, 236, 205,
+        93, 222, 114, 67, 29, 24, 72, 243, 141, 128, 195, 78, 66, 215, 61, 156, 180,
+    ];
+    return [...base, ...base];
+})();
+/** Quintic smoothstep: zero first and second derivative at 0 and 1. */
+const fade = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+const lerp = (a, b, t) => a + t * (b - a);
+/** The dot of one of twelve edge gradients, picked by `hash`, with (x, y, z). */
+function grad(hash, x, y, z) {
+    const h = hash & 15;
+    const u = h < 8 ? x : y;
+    const v = h < 4 ? y : h === 12 || h === 14 ? x : z;
+    return ((h & 1) === 0 ? u : -u) + ((h & 2) === 0 ? v : -v);
+}
+/** Noise at (x, y, z), in about [-1, 1]; zero at every integer lattice point. */
+export function noise(x, y, z) {
+    const fx = Math.floor(x);
+    const fy = Math.floor(y);
+    const fz = Math.floor(z);
+    const X = fx & 255;
+    const Y = fy & 255;
+    const Z = fz & 255;
+    x -= fx;
+    y -= fy;
+    z -= fz;
+    const u = fade(x);
+    const v = fade(y);
+    const w = fade(z);
+    const A = P[X] + Y;
+    const AA = P[A] + Z;
+    const AB = P[A + 1] + Z;
+    const B = P[X + 1] + Y;
+    const BA = P[B] + Z;
+    const BB = P[B + 1] + Z;
+    return lerp(lerp(lerp(grad(P[AA], x, y, z), grad(P[BA], x - 1, y, z), u), lerp(grad(P[AB], x, y - 1, z), grad(P[BB], x - 1, y - 1, z), u), v), lerp(lerp(grad(P[AA + 1], x, y, z - 1), grad(P[BA + 1], x - 1, y, z - 1), u), lerp(grad(P[AB + 1], x, y - 1, z - 1), grad(P[BB + 1], x - 1, y - 1, z - 1), u), v), w);
+}
+/**
+ * Fractal Brownian motion: `octaves` layers of noise, each twice the
+ * frequency and half the amplitude of the last, scaled back into about
+ * [-1, 1]. One layer is a soft swell; three is a swell with detail on it.
+ */
+export function fbm(x, y, z, octaves) {
+    let sum = 0;
+    let amplitude = 1;
+    let total = 0;
+    for (let i = 0; i < octaves; i++) {
+        const f = 2 ** i;
+        sum += amplitude * noise(x * f, y * f, z * f);
+        total += amplitude;
+        amplitude /= 2;
+    }
+    return sum / total;
+}
+/**
+ * A pseudo-random number in [0, 1) for the `n`th of something — a breath, a
+ * gust — uncorrelated with the `n ± 1`th, where `noise` would make
+ * neighbours alike. The classic shader hash: the fraction of a large sine.
+ */
+export function hash(n, z) {
+    const x = Math.sin(n * 12.9898 + z * 78.233) * 43758.5453;
+    return x - Math.floor(x);
+}
+/** Hermite smoothstep from `a` to `b`, clamped to [0, 1]. */
+export function smoothstep(a, b, x) {
+    const t = Math.min(1, Math.max(0, (x - a) / (b - a)));
+    return t * t * (3 - 2 * t);
+}

package/dist/core/paint.js

@@ -47,6 +47,15 @@ const GEOMETRY = {
 // frames. The erase leads its row: after a row that fills the width, the
 // cursor sits on its last cell, and an erase there would take it.
 const ROW_START = "\r\x1b[2K";
+// A frame's bytes between these two are shown at once: a terminal that has
+// synchronized output (DEC private mode 2026 — iTerm2, kitty, WezTerm,
+// Ghostty, foot, Windows Terminal …) holds the screen until the frame has
+// fully arrived, so a repaint can never show a row erased and not yet
+// redrawn. Thirty full-screen repaints a second show exactly that on a
+// terminal that paints whenever bytes land, as a flicker over the whole
+// frame. A terminal without the mode ignores both sequences.
+const SYNC_START = "\x1b[?2026h";
+const SYNC_END = "\x1b[?2026l";
 const HIDE_CURSOR = "\x1b[?25l";
 const SHOW_CURSOR = "\x1b[?25h";
 const RESET_STYLE = "\x1b[0m";
@@ -79,7 +88,7 @@ export class SurfacePainter {
      */
     paint(frame, screen, destination) {
         const rows = fitRows(frame(), screen);
-        this.write(this.over(rows, screen, destination));
+        this.write(SYNC_START + this.over(rows, screen, destination) + SYNC_END);
         return rows;
     }
     /**
@@ -93,7 +102,9 @@ export class SurfacePainter {
         const rows = fitRows(frame(), screen);
         const erase = this.over([], screen, destination);
         const ended = text.endsWith("\n") ? text : `${text}\n`;
-        return erase + ended + this.over(rows, screen, destination);
+        // One synchronized block around all three, so the terminal is released
+        // only once the frame is back.
+        return SYNC_START + erase + ended + this.over(rows, screen, destination) + SYNC_END;
     }
     // The bytes that paint `rows` over the last frame. They go out in one
     // string, so whatever takes the last frame away arrives with the new one.

package/dist/core/pretty.d.ts

@@ -120,12 +120,33 @@ export declare class Pretty implements Renderable, Measurable {
      * traversals.
      */
     private _scalar;
+    /**
+     * `value` quoted, and cut to `maxString` when it is longer.
+     *
+     * The dropped count is an annotation about the value, not part of it, so it
+     * goes after the closing quote — the way `maxLength`'s `... +N` sits beside
+     * the kept entries rather than inside the last one. Inside the quotes it
+     * reads as content, and copying it out yields a string the program never
+     * held.
+     *
+     * A cluster is at least one code unit, so a string no longer than the cap in
+     * code units is within it in clusters, and needs no segmenting.
+     */
+    private _string;
+    /**
+     * A key as an object literal would spell it: bare when it is a name or an
+     * index, which reads as itself, and quoted as a string otherwise. Rich reprs
+     * every key; printed raw, `"a b"` was indistinguishable from two words and a
+     * `\r` in one was dropped by `RichText`, so the key shown was not the key held.
+     * Quoting only what needs it keeps the JavaScript reading `{ a: 1 }`. A
+     * quoted key is a string and `maxString` cuts it; a bare one is a name.
+     */
+    private _key;
     /**
      * `value` cut to `max` grapheme clusters, with the rest counted after the
      * closing quote.
      *
-     * The unit is the cluster of the value, counted before `JSON.stringify`
-     * escapes it. A code unit cut can keep half a surrogate pair, which
+     * The unit is the cluster of the value, counted before `quoted` escapes it. A code unit cut can keep half a surrogate pair, which
      * JSON.stringify prints as a `\ud83d` escape; a code point cut can keep half
      * a flag or a ZWJ family. Either way the kept prefix shows something the
      * value never held, and the dropped count is in a unit nobody can see.

package/dist/core/pretty.js

@@ -447,6 +447,26 @@ const SEPARATOR = ", ";
 const EXPAND_SEPARATOR = SEPARATOR.trimEnd();
 /** The marker for positions the bound dropped, or nothing when it dropped none. */
 const elided = (dropped) => dropped > 0 ? [{ head: `... +${dropped}`, join: "", holes: [] }] : [];
+/**
+ * A key `Pretty._key` may leave bare. The bare form refuses a default-ignorable code point, which prints as
+ * nothing, so `"a\ufe0f"` cannot pass for `a`; `ID_Continue` admits several.
+ * An index is at most 15 digits: every such literal is a safe integer and
+ * names itself, where `99999999999999999999` would name `1e20`'s key.
+ */
+const BARE_KEY = /^(?![^]*\p{Default_Ignorable_Code_Point})(?:[\p{ID_Start}$_][\p{ID_Continue}$]*|0|[1-9]\d{0,14})$/u;
+/**
+ * What Python's `str.isprintable` refuses \u2014 control, format, private-use,
+ * unassigned, and every separator but the space \u2014 which Rich's repr escapes
+ * and JSON.stringify leaves raw past C0. Raw, DEL vanishes in `RichText`, a C1
+ * byte reaches the terminal as a control, and a format character hides or
+ * reorders what is around it.
+ */
+const UNPRINTABLE = /(?! )[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/gu;
+/** `value` in double quotes, every character that does not print escaped. */
+const quoted = (value) => JSON.stringify(value).replace(UNPRINTABLE, (c) => {
+    const hex = c.codePointAt(0).toString(16).padStart(4, "0");
+    return hex.length > 4 ? `\\u{${hex}}` : `\\u${hex}`;
+});
 export class Pretty {
     data;
     indent;
@@ -520,19 +540,8 @@ export class Pretty {
         if (value === undefined)
             return "undefined";
         switch (typeof value) {
-            case "string": {
-                // The dropped count is an annotation about the value, not part of it,
-                // so it goes after the closing quote — the way `maxLength`'s `... +N`
-                // sits beside the kept entries rather than inside the last one. Inside
-                // the quotes it reads as content, and copying it out yields a string
-                // the program never held.
-                //
-                // A cluster is at least one code unit, so a string no longer than the
-                // cap in code units is within it in clusters, and needs no segmenting.
-                if (this.maxString === undefined || value.length <= this.maxString)
-                    return JSON.stringify(value);
-                return this._cutString(value, this.maxString);
-            }
+            case "string":
+                return this._string(value);
             case "number":
             case "bigint":
             case "boolean":
@@ -544,12 +553,39 @@ export class Pretty {
         }
         return null;
     }
+    /**
+     * `value` quoted, and cut to `maxString` when it is longer.
+     *
+     * The dropped count is an annotation about the value, not part of it, so it
+     * goes after the closing quote — the way `maxLength`'s `... +N` sits beside
+     * the kept entries rather than inside the last one. Inside the quotes it
+     * reads as content, and copying it out yields a string the program never
+     * held.
+     *
+     * A cluster is at least one code unit, so a string no longer than the cap in
+     * code units is within it in clusters, and needs no segmenting.
+     */
+    _string(value) {
+        if (this.maxString === undefined || value.length <= this.maxString)
+            return quoted(value);
+        return this._cutString(value, this.maxString);
+    }
+    /**
+     * A key as an object literal would spell it: bare when it is a name or an
+     * index, which reads as itself, and quoted as a string otherwise. Rich reprs
+     * every key; printed raw, `"a b"` was indistinguishable from two words and a
+     * `\r` in one was dropped by `RichText`, so the key shown was not the key held.
+     * Quoting only what needs it keeps the JavaScript reading `{ a: 1 }`. A
+     * quoted key is a string and `maxString` cuts it; a bare one is a name.
+     */
+    _key(key) {
+        return BARE_KEY.test(key) ? key : this._string(key);
+    }
     /**
      * `value` cut to `max` grapheme clusters, with the rest counted after the
      * closing quote.
      *
-     * The unit is the cluster of the value, counted before `JSON.stringify`
-     * escapes it. A code unit cut can keep half a surrogate pair, which
+     * The unit is the cluster of the value, counted before `quoted` escapes it. A code unit cut can keep half a surrogate pair, which
      * JSON.stringify prints as a `\ud83d` escape; a code point cut can keep half
      * a flag or a ZWJ family. Either way the kept prefix shows something the
      * value never held, and the dropped count is in a unit nobody can see.
@@ -563,8 +599,8 @@ export class Pretty {
         if (cut === undefined) {
             const clusters = graphemes(value);
             cut = clusters.length <= max
-                ? JSON.stringify(value)
-                : JSON.stringify(clusters.slice(0, max).join("")) + `+${clusters.length - max}`;
+                ? quoted(value)
+                : quoted(clusters.slice(0, max).join("")) + `+${clusters.length - max}`;
             this.cutStrings.set(value, cut);
         }
         return cut;
@@ -640,7 +676,7 @@ export class Pretty {
                 const { record } = form;
                 const keys = Object.keys(record);
                 return this._container("{", "}", " ", keys.length, level, () => keys.slice(0, cap).map((k) => ({
-                    head: k,
+                    head: this._key(k),
                     join: ": ",
                     holes: [{ read: () => record[k], tail: flat("") }],
                 })));

package/dist/core/protocol.d.ts

@@ -96,6 +96,8 @@ export interface RenderOptions {
      */
     onDraw?: (owner: object) => void;
 }
+/** Whether `text` is all ASCII — what an `asciiOnly` output can draw. */
+export declare const isAscii: (text: string) => boolean;
 /**
  * `chosen` as this output can draw it: `ascii` in its place when the output is
  * ASCII-only and `chosen` spends a glyph outside ASCII, otherwise `chosen`

package/dist/core/protocol.js

@@ -4,9 +4,10 @@
  */
 import { cellCount } from "./cells.js";
 import { DEFAULT_THEME } from "./style.js";
-const ASCII_TEXT = /^[\x00-\x7F]*$/;
+/** Whether `text` is all ASCII — what an `asciiOnly` output can draw. */
+export const isAscii = (text) => /^[\x00-\x7F]*$/.test(text);
 export function drawable(options, chosen, ascii, glyphs = String) {
-    return options.asciiOnly === true && !ASCII_TEXT.test(glyphs(chosen)) ? ascii : chosen;
+    return options.asciiOnly === true && !isAscii(glyphs(chosen)) ? ascii : chosen;
 }
 /**
  * The budget a renderable hands the one child filling its space: its own, less

package/dist/core/selection.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The list cursor: one clamp, shared by every list that moves a selection —
+ * `ListView`'s callers and `Dropdown` alike — so it has one definition.
+ */
+/**
+ * The selection `delta` items on from `index` in a list of `length`, held to
+ * the list's ends: `-Infinity` is the first item and `Infinity` the last. A
+ * move that cannot go anywhere returns `index` itself, so `next === index`
+ * says nothing moved and the caller can skip a repaint. An empty list has
+ * nowhere to move to and returns `index`.
+ */
+export declare function moveSelection(index: number, delta: number, length: number): number;

package/dist/core/selection.js

@@ -0,0 +1,14 @@
+/**
+ * The list cursor: one clamp, shared by every list that moves a selection —
+ * `ListView`'s callers and `Dropdown` alike — so it has one definition.
+ */
+/**
+ * The selection `delta` items on from `index` in a list of `length`, held to
+ * the list's ends: `-Infinity` is the first item and `Infinity` the last. A
+ * move that cannot go anywhere returns `index` itself, so `next === index`
+ * says nothing moved and the caller can skip a repaint. An empty list has
+ * nowhere to move to and returns `index`.
+ */
+export function moveSelection(index, delta, length) {
+    return length === 0 ? index : Math.max(0, Math.min(length - 1, index + delta));
+}