@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/core/control-codes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The census of code points that do not print: every one in Unicode's general
+ * categories Cc, Cf, Zl and Zp, and the variation selectors, with what `RichText`
+ * does when content carries it. [LAW:one-source-of-truth] The sanitizer
+ * (`sanitized`), the wire (`wireText`) and the cell-width measure
+ * (`cellLen`) all read this table, so whether content keeps a code point has one
+ * statement. `docs/control-codes.md` is each family's use and harm, and what real
+ * terminals were measured doing with it.
+ *
+ * A row does not carry a width. A kept code point takes the cells Rich's table
+ * gives it (`cell-widths.ts`), and a second statement of them here would be one
+ * that could drift.
+ */
+/**
+ * What `RichText` does with a code point. `strip` deletes it from content. `keep`
+ * holds it as a character. `line-break` is a line ending, so content holds an LF
+ * in its place. `pictured` means nothing inside a span, so content holds the
+ * stand-in `pictureOf` gives in its place and the reader sees something was there.
+ * `zeroWidth` is held in content and measured as nothing, and `wireText` decides
+ * from its neighbours whether it is written.
+ *
+ * Only `keep`, and a `zeroWidth` code point `wireText` lets by, reaches the wire. A
+ * raw `Segment` is not content, so what it holds of the others is deleted there.
+ */
+export type Disposition = "strip" | "keep" | "line-break" | "pictured" | "zeroWidth";
+/**
+ * The code points `first` to `last`, inclusive, and what is done with each. A
+ * `pictured` row carries what content shows in place of each of its code points.
+ */
+export type ControlCodeRow = {
+    readonly first: number;
+    readonly last: number;
+    readonly disposition: Exclude<Disposition, "pictured">;
+} | {
+    readonly first: number;
+    readonly last: number;
+    readonly disposition: "pictured";
+    readonly picture: (codePoint: number) => string;
+};
+/**
+ * Ascending and disjoint, every Cc, Cf, Zl, Zp and Variation_Selector code point
+ * in exactly one row (`test/core/control-codes.test.ts`).
+ *
+ * Rich's `Text` strips only `STRIP_CONTROL_CODES` (BEL, BS, VT, FF, CR) and writes
+ * every other code point to the wire. Here a directive reaches the wire only
+ * through the library's own constructs: `Style`, a link, `Console.bell`, the paint
+ * layer.
+ */
+export declare const CONTROL_CODES: readonly ControlCodeRow[];
+/** What content shows in place of `codePoint`, whose disposition is `pictured`. */
+export declare function pictureOf(codePoint: number): string;
+/** A regular expression class of the code points in rows `chosen` picks, for `u`. */
+export declare function controlClass(chosen: (disposition: Disposition) => boolean): string;
+/**
+ * UTS #51's subdivision flag, as a `u` source: the black flag, a CLDR subdivision
+ * spelled in tag letters and digits, and CANCEL TAG. The one sequence tag
+ * characters have a reader for.
+ */
+export declare const SUBDIVISION_FLAG = "\uD83C\uDFF4[\uDB40\uDC30-\uDB40\uDC39\uDB40\uDC61-\uDB40\uDC7A]{3,6}\uDB40\uDC7F";
+/** What happens to `codePoint`. One in no row is kept. */
+export declare function dispositionOf(codePoint: number): Disposition;

package/dist/core/control-codes.js

@@ -0,0 +1,157 @@
+/**
+ * The census of code points that do not print: every one in Unicode's general
+ * categories Cc, Cf, Zl and Zp, and the variation selectors, with what `RichText`
+ * does when content carries it. [LAW:one-source-of-truth] The sanitizer
+ * (`sanitized`), the wire (`wireText`) and the cell-width measure
+ * (`cellLen`) all read this table, so whether content keeps a code point has one
+ * statement. `docs/control-codes.md` is each family's use and harm, and what real
+ * terminals were measured doing with it.
+ *
+ * A row does not carry a width. A kept code point takes the cells Rich's table
+ * gives it (`cell-widths.ts`), and a second statement of them here would be one
+ * that could drift.
+ */
+const strip = (first, last) => ({ first, last, disposition: "strip" });
+const keep = (first, last) => ({ first, last, disposition: "keep" });
+const lineBreak = (first, last) => ({ first, last, disposition: "line-break" });
+const pictured = (first, last, picture) => ({ first, last, disposition: "pictured", picture });
+/**
+ * The stand-ins. A C0 control's Control Pictures symbol is U+2400 up, DEL's is
+ * U+2421. Unicode gives C1 no pictures, so each shows U+2426 SYMBOL FOR SUBSTITUTE:
+ * one cell under every East Asian width setting, which U+FFFD is not, and apart
+ * from a real decoding error. Each is one code unit, so offsets hold.
+ */
+const controlPicture = (codePoint) => String.fromCharCode(0x2400 + codePoint);
+const deletePicture = () => "\u2421";
+const substitute = () => "\u2426";
+const zeroWidth = (first, last) => ({ first, last, disposition: "zeroWidth" });
+/**
+ * Ascending and disjoint, every Cc, Cf, Zl, Zp and Variation_Selector code point
+ * in exactly one row (`test/core/control-codes.test.ts`).
+ *
+ * Rich's `Text` strips only `STRIP_CONTROL_CODES` (BEL, BS, VT, FF, CR) and writes
+ * every other code point to the wire. Here a directive reaches the wire only
+ * through the library's own constructs: `Style`, a link, `Console.bell`, the paint
+ * layer.
+ */
+export const CONTROL_CODES = [
+    // NUL to BS. BEL's alert is `Console.bell`, and BS's overstrike, bold and
+    // underline in nroff output, is `decodeAnsi`: taken a code point at a time, text
+    // can turn neither into what it means.
+    pictured(0x00, 0x08, controlPicture),
+    keep(0x09, 0x0a),
+    // VT and FF, mandatory breaks in UAX #14 as LS and PS are.
+    lineBreak(0x0b, 0x0c),
+    // CR. A CRLF's LF ends its line however the two were chunked, and a CR's
+    // overwrite is `decodeAnsi`'s. What is given up is a classic Mac file's lines.
+    strip(0x0d, 0x0d),
+    // SO and SI switch the terminal's character set; DLE to SUB are transmission
+    // controls, and CAN and SUB abort a sequence; ESC begins one, and content that
+    // means styling says so with `decodeAnsi`; FS to US are data separators.
+    pictured(0x0e, 0x1f, controlPicture),
+    // DEL.
+    pictured(0x7f, 0x7f, deletePicture),
+    // The C1 controls. VTE, WezTerm and xterm.js read U+009B as CSI and U+009D as
+    // OSC; xterm, kitty and others ignore them. None has a meaning in text but NEL,
+    // which Unicode treats as CR, LF and CRLF are treated (§5.8). A stray one is
+    // often windows-1252 decoded as Latin-1, but which, a code point alone cannot
+    // say, so mojibake is the caller's to repair. `TextInput` refuses them as keys.
+    pictured(0x80, 0x84, substitute),
+    lineBreak(0x85, 0x85),
+    pictured(0x86, 0x9f, substitute),
+    // SOFT HYPHEN: a place a word may break, drawn as a hyphen only where one does.
+    // Terminals disagree on its cell, so it never reaches them.
+    zeroWidth(0xad, 0xad),
+    // The Arabic and Syriac number signs and other prepended concatenation marks,
+    // which draw a glyph.
+    keep(0x600, 0x605),
+    // ARABIC LETTER MARK, a bidi mark like LRM and RLM below: it holds no state,
+    // so right-to-left text can use it.
+    keep(0x61c, 0x61c),
+    // More prepended concatenation marks.
+    keep(0x6dd, 0x6dd),
+    keep(0x70f, 0x70f),
+    keep(0x890, 0x891),
+    keep(0x8e2, 0x8e2),
+    // The Mongolian free variation selectors.
+    zeroWidth(0x180b, 0x180d),
+    // MONGOLIAN VOWEL SEPARATOR, which shapes the vowel after it.
+    keep(0x180e, 0x180e),
+    zeroWidth(0x180f, 0x180f),
+    // ZWSP, a place a line may break (`wrap.ts`); ZWNJ, which Persian and Urdu spell
+    // with; ZWJ, for emoji and conjuncts; and the bidi marks LRM and RLM, which hold
+    // no state, so right-to-left text can use them. ZWJ's joining is Rich's width
+    // rule, which `cells.ts` holds apart from this row.
+    keep(0x200b, 0x200f),
+    // LINE SEPARATOR and PARAGRAPH SEPARATOR.
+    lineBreak(0x2028, 0x2029),
+    // The bidi embeddings and overrides with their closer PDF, and the isolates
+    // below. Content holds them; what reaches the wire is `sealed`'s to decide.
+    keep(0x202a, 0x202e),
+    // WORD JOINER, which only asks that nothing break here, and the invisible
+    // mathematical operators.
+    keep(0x2060, 0x2064),
+    // The bidi isolates with their closer PDI.
+    keep(0x2066, 0x2069),
+    // The deprecated shaping and swapping switches. Each holds state to the end of
+    // the text, Unicode deprecates them, and no terminal was found honouring one.
+    strip(0x206a, 0x206f),
+    // VARIATION SELECTOR-1 to 16: glyph variants, and text or emoji presentation.
+    zeroWidth(0xfe00, 0xfe0f),
+    // ZERO WIDTH NO-BREAK SPACE, the byte order mark, as a word joiner.
+    keep(0xfeff, 0xfeff),
+    // Interlinear annotation. No terminal draws ruby, the annotating text stays
+    // visible, and the anchors hold no state, so there is nothing to contain.
+    keep(0xfff9, 0xfffb),
+    // The Kaithi number signs, which draw a glyph.
+    keep(0x110bd, 0x110bd),
+    keep(0x110cd, 0x110cd),
+    // Egyptian hieroglyph, shorthand and musical format controls.
+    keep(0x13430, 0x1343f),
+    keep(0x1bca0, 0x1bca3),
+    keep(0x1d173, 0x1d17a),
+    // LANGUAGE TAG, deprecated.
+    strip(0xe0001, 0xe0001),
+    // The tag characters: an emoji subdivision flag, or text no reader can see.
+    zeroWidth(0xe0020, 0xe007f),
+    // The ideographic variation selectors: Japanese and Chinese glyph variants.
+    zeroWidth(0xe0100, 0xe01ef),
+];
+/** What content shows in place of `codePoint`, whose disposition is `pictured`. */
+export function pictureOf(codePoint) {
+    const row = rowOf(codePoint);
+    if (row?.disposition !== "pictured")
+        throw new RangeError(`U+${codePoint.toString(16).padStart(4, "0")} is not pictured`);
+    return row.picture(codePoint);
+}
+/** A regular expression class of the code points in rows `chosen` picks, for `u`. */
+export function controlClass(chosen) {
+    const hex = (codePoint) => `\\u{${codePoint.toString(16)}}`;
+    return `[${CONTROL_CODES.filter((row) => chosen(row.disposition)).map((row) => `${hex(row.first)}-${hex(row.last)}`).join("")}]`;
+}
+/**
+ * UTS #51's subdivision flag, as a `u` source: the black flag, a CLDR subdivision
+ * spelled in tag letters and digits, and CANCEL TAG. The one sequence tag
+ * characters have a reader for.
+ */
+export const SUBDIVISION_FLAG = "\u{1f3f4}[\u{e0030}-\u{e0039}\u{e0061}-\u{e007a}]{3,6}\u{e007f}";
+/** What happens to `codePoint`. One in no row is kept. */
+export function dispositionOf(codePoint) {
+    return rowOf(codePoint)?.disposition ?? "keep";
+}
+/** The row holding `codePoint`, if any. */
+function rowOf(codePoint) {
+    let low = 0;
+    let high = CONTROL_CODES.length - 1;
+    while (low <= high) {
+        const mid = (low + high) >> 1;
+        const row = CONTROL_CODES[mid];
+        if (codePoint < row.first)
+            high = mid - 1;
+        else if (codePoint > row.last)
+            low = mid + 1;
+        else
+            return row;
+    }
+    return undefined;
+}

package/dist/core/easing.d.ts

@@ -22,7 +22,7 @@
  *   `elastic`, Robert Penner's curves at the constants every animation
  *   library since has shipped. An ease that leaves [0, 1] — a spring or a
  *   back curve overshooting its rest — is still an ease: a `ColorRamp` holds
- *   its end colours where it does, and an effect's `Curve` saturates at its
+ *   its end colors where it does, and an effect's `Curve` saturates at its
  *   swing, so the overshoot is read by what can show it (a position, a
  *   count) and clipped by what cannot.
  *
@@ -33,15 +33,15 @@
  * [LAW:one-type-per-behavior] An ease is a plain function value. CSS's named
  * curves are four instances of `cubicBezier`, not four implementations, the
  * spring in `EASES` is one `spring()`, and `ColorRamp` and every effect take
- * the same `Ease`.
+ * the same `Easing`.
  *
  * Tier 0 of `src/core/`: imports nothing, so `themes/` and every later
  * `core/` module reach it downhill. [LAW:one-way-deps]
  */
 /** Progress in [0, 1] in, progress out: a reshaping of [0, 1] that may leave it, as a spring overshooting its rest does. */
-export type Ease = (x: number) => number;
+export type Easing = (x: number) => number;
 /** Time in seconds (plus any per-cell offset) in, progress in [0, 1] out. */
-export type Phase = (t: number) => number;
+export type WrapMode = (t: number) => number;
 /**
  * CSS `cubic-bezier(x1, y1, x2, y2)`: the curve from (0, 0) to (1, 1) with
  * those two control points, read as y at a given x. `x1` and `x2` must lie in
@@ -49,7 +49,7 @@ export type Phase = (t: number) => number;
  * every input has exactly one output. `y1` and `y2` may leave [0, 1]; the
  * curve then overshoots, as a CSS "back" curve does.
  */
-export declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): Ease;
+export declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): Easing;
 /**
  * Where a `steps()` curve jumps, in CSS's terms. `jump-start` jumps at 0,
  * `jump-end` at 1, `jump-both` at both, `jump-none` at neither; `start` and
@@ -62,11 +62,11 @@ export type StepPosition = "jump-start" | "jump-end" | "jump-none" | "jump-both"
  * `position` names — CSS's step algorithm, so `steps(1, "end")` is 0 until
  * the very end.
  */
-export declare function steps(n: number, position?: StepPosition): Ease;
+export declare function steps(n: number, position?: StepPosition): Easing;
 /**
  * The curve `shape` over [0, 1) as an ease that has arrived: its argument
  * held to [0, 1], and exactly 1 at 1. Every built-in ease is one, so the two
- * halves of the `Ease` contract — an argument in [0, 1], the end landed on —
+ * halves of the `Easing` contract — an argument in [0, 1], the end landed on —
  * are enforced here and nowhere else. [LAW:single-enforcer] The end matters
  * because a curve is 1 at its end only in the limit or up to a rounding — a
  * spring settles to within `SPRING_REST`, the elastic's ringing never quite
@@ -74,7 +74,7 @@ export declare function steps(n: number, position?: StepPosition): Ease;
  * and a count or a width eased by it must land on its target, not a
  * thousandth or an ulp short.
  */
-export declare const settled: (shape: (p: number) => number) => Ease;
+export declare const withSettlingTime: (shape: (p: number) => number) => Easing;
 /**
  * A spring's physics: the mass on it, the stiffness of its coil and the
  * damping it moves against, in the units every animation library spells them
@@ -93,19 +93,19 @@ export interface SpringOptions {
  * An ease over a duration: CSS's timing function and duration as one value,
  * the whole of what a one-shot move needs to know about time — a tween's
  * (`./tween.ts`), a `spring()`'s, and the part of an effect's `Curve` that
- * is not its swing. `Phase.once(start, seconds)` through `ease` is the move
+ * is not its swing. `WrapMode.once(start, seconds)` through `ease` is the move
  * on a timeline. [LAW:one-type-per-behavior] One shape, so a spring is handed
  * to a tween as it is, and a curve written for an effect times a tween.
  */
 export interface Timing {
     /** How the move is shaped, as progress in to progress out. */
-    readonly ease: Ease;
+    readonly ease: Easing;
     /** How long the move takes, in seconds. */
     readonly seconds: number;
 }
 /**
  * How close to its rest a spring must come to count as settled: one part in a
- * thousand of the way it moves, under a colour channel's step (1/255) and
+ * thousand of the way it moves, under a color channel's step (1/255) and
  * under any cell, so what rounds the spring's value to show it draws the rest
  * from there on.
  */
@@ -137,28 +137,28 @@ export declare function spring(options?: SpringOptions): Timing;
  * `seconds` are `DEFAULT_SPRING`'s; the rest are Penner's at his constants.
  */
 export declare const EASES: {
-    readonly linear: Ease;
-    readonly ease: Ease;
-    readonly "ease-in": Ease;
-    readonly "ease-out": Ease;
-    readonly "ease-in-out": Ease;
-    readonly "step-start": Ease;
-    readonly "step-end": Ease;
-    readonly step: Ease;
-    readonly sine: Ease;
-    readonly spring: Ease;
-    readonly bounce: Ease;
-    readonly "back-in": Ease;
-    readonly "back-out": Ease;
-    readonly elastic: Ease;
+    readonly linear: Easing;
+    readonly ease: Easing;
+    readonly "ease-in": Easing;
+    readonly "ease-out": Easing;
+    readonly "ease-in-out": Easing;
+    readonly "step-start": Easing;
+    readonly "step-end": Easing;
+    readonly step: Easing;
+    readonly sine: Easing;
+    readonly spring: Easing;
+    readonly bounce: Easing;
+    readonly "back-in": Easing;
+    readonly "back-out": Easing;
+    readonly elastic: Easing;
 };
-export type EaseName = keyof typeof EASES;
+export type EasingName = keyof typeof EASES;
 /**
  * The gate a spelled ease crosses. [LAW:parse-dont-validate] — a name in, the
  * function out, so nothing downstream holds a string it must check again.
  * Unknown names throw naming every legal one. [LAW:no-silent-failure]
  */
-export declare function parseEase(name: string): Ease;
+export declare function parseEasing(name: string): Easing;
 /** Throws, naming `what`, unless `seconds` is a positive, finite number of seconds. */
 export declare function positiveSeconds(what: string, seconds: number): void;
 /**
@@ -166,11 +166,11 @@ export declare function positiveSeconds(what: string, seconds: number): void;
  * way the frames of an animation are each held and then replaced. `at(t)` is
  * the index of the hold in progress at `t`, counted from the first hold at
  * `t = 0`, and the sequence wraps every `period` seconds, before zero too,
- * as `Phase.loop` wraps. With equal holds `at` is `steps(n)` read as an
+ * as `WrapMode.loop` wraps. With equal holds `at` is `steps(n)` read as an
  * index; the holds here may differ, which `steps` cannot say, so a frame
  * held for a second and the next for a quarter are one beat.
  */
-export interface Beat {
+export interface StepSequence {
     readonly holds: readonly number[];
     /** The sum of the holds: how long one pass takes, in seconds. */
     readonly period: number;
@@ -180,10 +180,10 @@ export interface Beat {
      * When the hold in progress at `t` began, in seconds on `t`'s own
      * timeline: what a sample-and-hold on this beat reads at `t`. Every `t`
      * inside one hold of one pass answers the same number, to the bit, so an
-     * effect handed it draws the same frame throughout. With `nextChange`,
+     * effect handed it draws the same frame throughout. With `validUntil`,
      * the two ends of the hold, as every `Animation` answers them.
      */
-    lastChange(t: number): number;
+    validFrom(t: number): number;
     /**
      * When the hold in progress at `t` ends, in seconds on `t`'s own timeline:
      * the start of the next hold, the first moment `at` places in it, so it is
@@ -191,9 +191,9 @@ export interface Beat {
      * With `at`, this makes a beat an `Animation` of the hold in progress
      * (`./animation.ts`).
      */
-    nextChange(t: number): number;
+    validUntil(t: number): number;
     /** The beat with its motion taken out: its first hold, held for good, as a loop holds its first value. */
-    reduced(): Beat;
+    reduced(): StepSequence;
 }
 /**
  * `t`, unless it is not a finite number of seconds, which throws naming
@@ -234,14 +234,14 @@ export declare function walkUp(sum: number, reached: (x: number) => boolean, fin
  * exact to the float and the cost is logarithmic in that distance.
  */
 export declare function firstReaching(near: number, reached: (x: number) => boolean): number;
-/** `holds` as a `Beat`; a beat with no hold, or a hold that is not a positive number of seconds, throws. */
-export declare function beat(holds: readonly number[]): Beat;
-/** The three phase shapes. Each takes seconds and returns a `Phase`. */
-export declare const Phase: {
+/** `holds` as a `StepSequence`; a beat with no hold, or a hold that is not a positive number of seconds, throws. */
+export declare function stepSequence(holds: readonly number[]): StepSequence;
+/** The three phase shapes. Each takes seconds and returns a `WrapMode`. */
+export declare const WrapMode: {
     /** 0 before `start`, rising to 1 over `duration` seconds, then held at 1. */
-    once(start: number, duration: number): Phase;
+    once(start: number, duration: number): WrapMode;
     /** 0 → 1 every `period` seconds, wrapping back to 0; negative `t` wraps too. */
-    loop(period: number): Phase;
+    loop(period: number): WrapMode;
     /** 0 → 1 → 0 every `period` seconds: there in the first half, back in the second. */
-    pingPong(period: number): Phase;
+    pingPong(period: number): WrapMode;
 };

package/dist/core/easing.js

@@ -22,7 +22,7 @@
  *   `elastic`, Robert Penner's curves at the constants every animation
  *   library since has shipped. An ease that leaves [0, 1] — a spring or a
  *   back curve overshooting its rest — is still an ease: a `ColorRamp` holds
- *   its end colours where it does, and an effect's `Curve` saturates at its
+ *   its end colors where it does, and an effect's `Curve` saturates at its
  *   swing, so the overshoot is read by what can show it (a position, a
  *   count) and clipped by what cannot.
  *
@@ -33,7 +33,7 @@
  * [LAW:one-type-per-behavior] An ease is a plain function value. CSS's named
  * curves are four instances of `cubicBezier`, not four implementations, the
  * spring in `EASES` is one `spring()`, and `ColorRamp` and every effect take
- * the same `Ease`.
+ * the same `Easing`.
  *
  * Tier 0 of `src/core/`: imports nothing, so `themes/` and every later
  * `core/` module reach it downhill. [LAW:one-way-deps]
@@ -91,7 +91,7 @@ export function cubicBezier(x1, y1, x2, y2) {
         }
         return s;
     };
-    return settled((p) => yAt(solve(p)));
+    return withSettlingTime((p) => yAt(solve(p)));
 }
 /**
  * CSS `steps(n, position)`: progress held flat in `n` equal intervals, jumping
@@ -115,12 +115,12 @@ export function steps(n, position = "jump-end") {
         "jump-none": n - 1,
     }[position];
     const lift = jumpsAtStart ? 1 : 0;
-    return settled((p) => Math.min(jumps, Math.floor(p * n) + lift) / jumps);
+    return withSettlingTime((p) => Math.min(jumps, Math.floor(p * n) + lift) / jumps);
 }
 /**
  * The curve `shape` over [0, 1) as an ease that has arrived: its argument
  * held to [0, 1], and exactly 1 at 1. Every built-in ease is one, so the two
- * halves of the `Ease` contract — an argument in [0, 1], the end landed on —
+ * halves of the `Easing` contract — an argument in [0, 1], the end landed on —
  * are enforced here and nowhere else. [LAW:single-enforcer] The end matters
  * because a curve is 1 at its end only in the limit or up to a rounding — a
  * spring settles to within `SPRING_REST`, the elastic's ringing never quite
@@ -128,19 +128,19 @@ export function steps(n, position = "jump-end") {
  * and a count or a width eased by it must land on its target, not a
  * thousandth or an ulp short.
  */
-export const settled = (shape) => (x) => {
+export const withSettlingTime = (shape) => (x) => {
     const p = Math.min(1, Math.max(0, x));
     return p === 1 ? 1 : shape(p);
 };
 /** The identity ease: progress unchanged. */
-const linear = settled((p) => p);
+const linear = withSettlingTime((p) => p);
 /** CSS `step-end`: 0 until the very end. */
 const stepEnd = steps(1, "jump-end");
 /** A half-cosine, flat at both ends: the curve a breathing pulse wants. */
-const sine = settled((p) => (1 - Math.cos(Math.PI * p)) / 2);
+const sine = withSettlingTime((p) => (1 - Math.cos(Math.PI * p)) / 2);
 /**
  * How close to its rest a spring must come to count as settled: one part in a
- * thousand of the way it moves, under a colour channel's step (1/255) and
+ * thousand of the way it moves, under a color channel's step (1/255) and
  * under any cell, so what rounds the spring's value to show it draws the rest
  * from there on.
  */
@@ -171,7 +171,7 @@ export function spring(options = {}) {
     const zeta = damping / (2 * Math.sqrt(stiffness * mass));
     const decay = zeta * w0;
     const { displacement, seconds } = zeta < 1 ? ringing(w0, zeta, decay) : creeping(w0, zeta, decay);
-    return { seconds, ease: settled((p) => 1 - displacement(p * seconds)) };
+    return { seconds, ease: withSettlingTime((p) => 1 - displacement(p * seconds)) };
 }
 /**
  * Where `|displacement|` falls through `SPRING_REST` between `lo` and `hi`,
@@ -258,7 +258,7 @@ const BOUNCE_ARCS = [
     { until: 2.5 / 2.75, centre: 2.25 / 2.75, floor: 0.9375 },
     { until: Number.POSITIVE_INFINITY, centre: 2.625 / 2.75, floor: 0.984375 },
 ];
-const bounce = settled((p) => {
+const bounce = withSettlingTime((p) => {
     // The last arc's `until` is unbounded, so an arc is always found.
     const arc = BOUNCE_ARCS.find(({ until }) => p < until);
     return 7.5625 * (p - arc.centre) ** 2 + arc.floor;
@@ -272,8 +272,8 @@ const bounce = settled((p) => {
  * and lands on 1 to the bit.
  */
 const BACK_OVERSHOOT = 1.70158;
-const backIn = settled((p) => p ** 3 + BACK_OVERSHOOT * p ** 2 * (p - 1));
-const backOut = settled((p) => {
+const backIn = withSettlingTime((p) => p ** 3 + BACK_OVERSHOOT * p ** 2 * (p - 1));
+const backOut = withSettlingTime((p) => {
     const q = p - 1;
     return 1 + q ** 3 + BACK_OVERSHOOT * q ** 2 * (q + 1);
 });
@@ -284,7 +284,7 @@ const backOut = settled((p) => {
  * last — `2^(−10x)·sin((10x − 0.75)·2π/3) + 1`.
  */
 const ELASTIC_PERIOD = (2 * Math.PI) / 3;
-const elastic = settled((p) => 2 ** (-10 * p) * Math.sin((10 * p - 0.75) * ELASTIC_PERIOD) + 1);
+const elastic = withSettlingTime((p) => 2 ** (-10 * p) * Math.sin((10 * p - 0.75) * ELASTIC_PERIOD) + 1);
 /**
  * Every built-in ease by the name a template spells it with — CSS's keyword
  * names, plus `sine`, plus `step`: the spelling `ColorRamp` used before this
@@ -314,7 +314,7 @@ export const EASES = {
  * function out, so nothing downstream holds a string it must check again.
  * Unknown names throw naming every legal one. [LAW:no-silent-failure]
  */
-export function parseEase(name) {
+export function parseEasing(name) {
     if (!Object.hasOwn(EASES, name)) {
         throw new RangeError(`unknown ease ${JSON.stringify(name)}; expected one of ` +
             Object.keys(EASES).map((n) => JSON.stringify(n)).join(", "));
@@ -335,8 +335,8 @@ const STILL = {
     holds: [Number.POSITIVE_INFINITY],
     period: Number.POSITIVE_INFINITY,
     at: () => 0,
-    lastChange: () => Number.NEGATIVE_INFINITY,
-    nextChange: () => Number.POSITIVE_INFINITY,
+    validFrom: () => Number.NEGATIVE_INFINITY,
+    validUntil: () => Number.POSITIVE_INFINITY,
     reduced: () => STILL,
 };
 /**
@@ -352,7 +352,7 @@ export function finiteTime(what, t) {
 /**
  * The seconds into the current pass of a `period` at `t`: `t` taken modulo
  * the period, into [0, period), before zero too. [LAW:single-enforcer] The
- * one wrap `Phase.loop` and `beat` both read time through, so a `t` that is
+ * one wrap `WrapMode.loop` and `beat` both read time through, so a `t` that is
  * not a finite number of seconds fails here, loudly, and nowhere else. A
  * `t` at or past zero is `t % period` alone, which is exact; only a negative
  * `t` is carried up by a period, so a boundary a host samples exactly lands
@@ -474,21 +474,21 @@ export function firstReaching(near, reached) {
             lo = mid;
     }
 }
-/** `holds` as a `Beat`; a beat with no hold, or a hold that is not a positive number of seconds, throws. */
-export function beat(holds) {
+/** `holds` as a `StepSequence`; a beat with no hold, or a hold that is not a positive number of seconds, throws. */
+export function stepSequence(holds) {
     if (holds.length === 0)
-        throw new RangeError("a beat needs at least one hold");
-    holds.forEach((hold, i) => positiveSeconds(`beat hold ${i}`, hold));
-    const period = holds.reduce((sum, hold) => sum + hold, 0);
+        throw new RangeError("a step sequence needs at least one step");
+    holds.forEach((validity, i) => positiveSeconds(`step ${i}`, validity));
+    const period = holds.reduce((sum, validity) => sum + validity, 0);
     // Where each hold begins, in seconds into the period: the unit
     // `wrapSeconds` answers in, so the sum a boundary sits at is the number
     // the wrap of a `t` on that boundary produces, and the hold that begins
     // there is the one in progress, at any rate the host samples.
     const starts = [];
     let elapsed = 0;
-    for (const hold of holds) {
+    for (const validity of holds) {
         starts.push(elapsed);
-        elapsed += hold;
+        elapsed += validity;
     }
     // A copy, and the one `at` walks: what `at` and `period` were built from
     // stays what `holds` says whatever the caller does to its array.
@@ -520,40 +520,40 @@ export function beat(holds) {
         holds: own,
         period,
         at(t) {
-            return index(wrapSeconds("Beat.at", t, period));
+            return index(wrapSeconds("StepSequence.at", t, period));
         },
-        lastChange(t) {
-            const { pass, into } = passAt("Beat.lastChange", t, period);
-            return boundary("Beat.lastChange", pass, index(into), t);
+        validFrom(t) {
+            const { pass, into } = passAt("StepSequence.validFrom", t, period);
+            return boundary("StepSequence.validFrom", pass, index(into), t);
         },
         // The next hold's start, in the next pass when this hold is the last.
-        nextChange(t) {
-            const { pass, into } = passAt("Beat.nextChange", t, period);
+        validUntil(t) {
+            const { pass, into } = passAt("StepSequence.validUntil", t, period);
             const i = index(into);
             const last = i === own.length - 1;
-            return boundary("Beat.nextChange", pass + (last ? 1 : 0), last ? 0 : i + 1, t);
+            return boundary("StepSequence.validUntil", pass + (last ? 1 : 0), last ? 0 : i + 1, t);
         },
         reduced: () => STILL,
     };
 }
-/** The three phase shapes. Each takes seconds and returns a `Phase`. */
-export const Phase = {
+/** The three phase shapes. Each takes seconds and returns a `WrapMode`. */
+export const WrapMode = {
     /** 0 before `start`, rising to 1 over `duration` seconds, then held at 1. */
     once(start, duration) {
         if (!Number.isFinite(start))
-            throw new RangeError(`Phase.once start must be finite, got ${start}`);
-        positiveSeconds("Phase.once duration", duration);
+            throw new RangeError(`WrapMode.once start must be finite, got ${start}`);
+        positiveSeconds("WrapMode.once duration", duration);
         return (t) => Math.min(1, Math.max(0, (t - start) / duration));
     },
     /** 0 → 1 every `period` seconds, wrapping back to 0; negative `t` wraps too. */
     loop(period) {
-        positiveSeconds("Phase.loop period", period);
-        return (t) => wrapSeconds("Phase.loop", t, period) / period;
+        positiveSeconds("WrapMode.loop period", period);
+        return (t) => wrapSeconds("WrapMode.loop", t, period) / period;
     },
     /** 0 → 1 → 0 every `period` seconds: there in the first half, back in the second. */
     pingPong(period) {
-        positiveSeconds("Phase.pingPong period", period);
-        const wrap = Phase.loop(period);
+        positiveSeconds("WrapMode.pingPong period", period);
+        const wrap = WrapMode.loop(period);
         return (t) => 1 - Math.abs(2 * wrap(t) - 1);
     },
 };

package/dist/core/env.d.ts

@@ -14,3 +14,9 @@
  * `NodeJS` namespace. `test/seam/browser-types.test.ts` holds that line.
  */
 export type Env = Readonly<Record<string, string | undefined>>;
+/**
+ * A terminal that says it cannot be drawn on: `TERM` is `dumb` or `unknown`,
+ * as Emacs' shell mode sets it. It takes no color and nothing that moves the
+ * cursor.
+ */
+export declare function isDumbTerminal(env: Env): boolean;

package/dist/core/env.js

@@ -13,4 +13,12 @@
  * without `@types/node` — the ordinary browser project — cannot resolve the
  * `NodeJS` namespace. `test/seam/browser-types.test.ts` holds that line.
  */
-export {};
+/**
+ * A terminal that says it cannot be drawn on: `TERM` is `dumb` or `unknown`,
+ * as Emacs' shell mode sets it. It takes no color and nothing that moves the
+ * cursor.
+ */
+export function isDumbTerminal(env) {
+    const term = env["TERM"];
+    return term === "dumb" || term === "unknown";
+}