@promptctl/rich-js 0.19.0 → 0.20.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/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;

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));
+}

package/dist/core/strip.d.ts

@@ -70,83 +70,114 @@ export declare class Strip<T extends StyledRenderable = StyledRenderable> implem
     };
 }
 /**
- * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
- * arrow between them to be seen. Below it the arrow is drawn in a colour the
- * eye cannot tell from its own background, so the joiner draws the divider
+ * A colour a joiner's cell is drawn in. Each variant names where the colour
+ * comes from when the join is drawn:
+ *   • an `edge` — a neighbour's ground (`bg`) or text (`fg`) at the column
+ *     facing the join, read through `StyledRenderable.edgeStyle`;
+ *   • a `role` — a style name, resolved against the render's theme, whose
+ *     foreground colour is the colour;
+ *   • a `mix` — two colours blended at `t` (0 is the first, 1 the second).
+ */
+export type Paint = {
+    readonly edge: "left" | "right";
+    readonly part: "bg" | "fg";
+} | {
+    readonly role: string;
+} | {
+    readonly mix: readonly [Paint, Paint, number];
+};
+/**
+ * A `Paint`, or `"ground"`: the terminal's own background, whose colour nobody
+ * knows. That is why it is never mixed (`Paint` excludes it), and why a cell
+ * may put it on one side only. As a cell's `fg` it is drawn in reverse video —
+ * the glyph's ink shows the terminal's background through a cell filled with
+ * the `bg` colour — so an inverted shape is the same glyph, never a glyph of
+ * its own.
+ */
+export type CellColor = Paint | "ground";
+/**
+ * One styled run of a join. A `oneOf` glyph is a set any member of which may
+ * stand in the cell; every member has the same width, because consumers
+ * measure a join by rendering it.
+ */
+export interface JoinCell {
+    readonly glyph: string | {
+        readonly oneOf: readonly string[];
+    };
+    readonly fg: CellColor;
+    readonly bg: CellColor;
+}
+/**
+ * The cells a joiner draws at each kind of join:
+ *   • `seam` — between two neighbours;
+ *   • `divider` — in the seam's place where the two grounds are drawn as one
+ *     colour (see `SEAM_MIN_DELTA_E`), so the seam would vanish into them;
+ *     the same width as `seam`;
+ *   • `lead` — where a run is entered from nothing: the strip's start, or a
+ *     neighbour with no ground for the seam to paint. It cannot name `left`;
+ *   • `tail` — where a run leaves into nothing. It cannot name `right`.
+ */
+export interface JoinShape {
+    readonly seam: readonly JoinCell[];
+    readonly divider: readonly JoinCell[];
+    readonly lead: readonly JoinCell[];
+    readonly tail: readonly JoinCell[];
+}
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for a seam drawn
+ * between them to be seen. Below it the seam is drawn in a colour the eye
+ * cannot tell from its own background, so the joiner draws the divider
  * instead. Twice the ~.02 threshold of a visible difference, because a seam is
  * one cell wide.
  */
 export declare const SEAM_MIN_DELTA_E = 0.04;
-export interface PowerlineJoinerOptions {
-    /** Glyph for every join between two coloured items. */
-    glyph: string;
-    /**
-     * Glyph drawn between neighbours whose backgrounds the eye cannot tell apart,
-     * in the left item's text colour — the arrow itself would vanish into the
-     * shared background.
-     */
-    divider: string;
-    /**
-     * Glyph for every join a coloured item is entered from nothing — the strip's
-     * start, or a colourless left neighbour — painted in the right item's
-     * background. `""` begins a coloured run flat.
-     */
-    lead: string;
-    /**
-     * Glyph for every join a coloured item leaves into nothing — the strip's end,
-     * or a colourless right neighbour — painted in the left item's background.
-     * `""` ends a coloured run flat.
-     */
-    tail: string;
-}
 /**
- * The powerline set: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow),
- * led by U+E0D7 (Nerd Fonts ple-left_hard_divider_inverse, the right-arrow's
- * inverse) and tailed by the arrow itself. The lead leaves empty a triangle
- * whose base is its cell's left edge and whose point touches the first item, so
- * the run opens notched — as if an arrow before it pointed in — rather than
- * with a shape pointing out. The notch is the terminal's own background showing
- * through, never a colour painted to imitate it, so it matches under a
- * translucent terminal background too. The lead is a Powerline Extra glyph: a
- * classic powerline font lacks it.
+ * The one joiner: what it draws at each join is the `JoinShape` it is given,
+ * so a new joiner is a value, never a class.
+ *
+ * Which part a join draws is read off its two neighbours. A neighbour is
+ * missing at the strip's ends, and counts as missing — an endpoint — when the
+ * shape paints with its ground anywhere and it has none to paint. With both present the
+ * join is the seam, or the divider where the two grounds are drawn as one
+ * colour at `options.colorSystem`; with only the right, the lead; with only
+ * the left, the tail; with neither, nothing.
+ *
+ * `ascii` is the shape an ASCII-only output draws instead, whole.
  */
-export declare const POWERLINE_JOINER_GLYPHS: Readonly<PowerlineJoinerOptions>;
-export declare class PowerlineJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    private readonly _glyphs;
-    constructor(options?: PowerlineJoinerOptions);
-    join(left: T | null, right: T | null): Renderable;
-}
-export interface CapsuleJoinerOptions {
-    /** Left-cap glyph (default: U+E0B6, powerline rounded left). */
-    left?: string;
-    /** Right-cap glyph (default: U+E0B4, powerline rounded right). */
-    right?: string;
-    /** Separator inserted between adjacent capsules in the middle position. */
-    separator?: string;
-}
-export declare class CapsuleJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    private readonly _caps;
-    private readonly _separator;
-    constructor(options?: CapsuleJoinerOptions);
-    _emit(left: T | null, right: T | null, options: RenderOptions): Iterable<Segment>;
-    join(left: T | null, right: T | null): Renderable;
-}
-export interface PlainJoinerOptions {
-    separator?: string;
-    style?: Style;
-}
-export declare class PlainJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    private readonly _separator;
-    private readonly _style;
-    constructor(options?: PlainJoinerOptions);
-    join(left: T | null, right: T | null): Renderable;
-}
-export interface GradientJoinerOptions {
-    /** Number of cells between adjacent items (default: 4). */
-    steps?: number;
-}
-export declare class GradientJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
-    private readonly _steps;
-    constructor(options?: GradientJoinerOptions);
+export declare class CellJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
+    readonly shape: JoinShape;
+    readonly ascii: JoinShape;
+    private readonly _forms;
+    constructor(shape: JoinShape, ascii: JoinShape);
     join(left: T | null, right: T | null): Renderable;
 }
+/**
+ * The powerline joiner: U+E0B0 (right-arrow) in the left ground over the
+ * right, divided by U+E0B1 (thin right-arrow) in the left item's text. The
+ * lead is the arrow with the left ground replaced by the terminal's — drawn
+ * in reverse video it leaves a notch whose base is the cell's left edge, inked
+ * in the terminal's background colour. That ink is opaque, so under a
+ * translucent terminal the notch does not let what is behind it through. The
+ * tail is the arrow over the terminal's ground.
+ * ASCII draws `>` everywhere and begins each run flat.
+ */
+export declare const POWERLINE_JOINER: CellJoiner<StyledRenderable>;
+/**
+ * Rounded pills: each run opened by U+E0B6 and closed by U+E0B4, both in its
+ * ground over the terminal's, a space between pills. ASCII draws `(` and `)`.
+ */
+export declare const CAPSULE_JOINER: CellJoiner<StyledRenderable>;
+/**
+ * ` | ` between every pair of items, in the theme's `strip.separator` colour;
+ * nothing at the ends. Its shape names no neighbour, so it joins items with no
+ * ground too.
+ */
+export declare const PLAIN_JOINER: CellJoiner<StyledRenderable>;
+/**
+ * A ramp of `steps` cells from the left ground to the right. Each cell is the
+ * half block U+258C, ink on its left half and ground on its right, so it
+ * carries two samples; ASCII draws a space, keeping the grounds alone. Nothing
+ * at the ends, or beside a neighbour with no ground — there is no colour to
+ * ramp toward.
+ */
+export declare function gradientJoiner(steps?: number): CellJoiner;