@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/core/console.d.ts

@@ -59,6 +59,15 @@ export interface ConsoleOptions {
      * renderable this console draws. Default false.
      */
     asciiOnly?: boolean;
+    /**
+     * The reader asked for reduced motion: every animation this console draws
+     * — through `print`, a `Live` or an `App` — is drawn with its motion taken
+     * out, waking its host only where content changes
+     * (`RenderOptions.reducedMotion`). A preference of the
+     * person at the terminal, which no terminal reports, so the program hands
+     * it in; nothing here reads the environment for it. Default false.
+     */
+    reducedMotion?: boolean;
     /**
      * Static width (cells). Ignored when `getSize` is provided. Falls back to
      * the `COLUMNS` env var / the bound stream's `columns` / 80.
@@ -127,24 +136,25 @@ export interface PrintOptions {
 }
 export declare class Console {
     private readonly _destination;
-    private _getSize;
+    private readonly _getSize;
     private readonly _getDatetime;
-    private _lastLogTime;
-    private _style;
-    private _isTerminal;
+    private readonly _lastLogTime;
+    private readonly _style;
+    private readonly _isTerminal;
     private readonly _interactive;
-    private _file;
-    private _stream;
-    private _record;
-    private _markup;
-    private _highlight;
-    private _theme;
-    private _onStyleError;
+    private readonly _file;
+    private readonly _stream;
+    private readonly _record;
+    private readonly _markup;
+    private readonly _highlight;
+    private readonly _theme;
+    private readonly _onStyleError;
     private readonly _asciiOnly;
-    private _highlighter;
-    private _recorded;
-    private _capture;
-    private _liveRegion;
+    private readonly _highlighter;
+    private readonly _recorded;
+    private readonly _capture;
+    private readonly _liveRegion;
+    private readonly _madeIn;
     constructor(options?: ConsoleOptions);
     get size(): {
         width: number;
@@ -156,8 +166,9 @@ export declare class Console {
     get isInteractive(): boolean;
     get colorSystem(): ColorDepth | null;
     /**
-     * Where this console writes: the colour depth it draws at and whether it
-     * emits OSC 8 hyperlinks, overrides applied — the value its output is
+     * Where this console writes: the colour depth it draws at, whether it
+     * emits OSC 8 hyperlinks, and whether its reader asked for reduced motion,
+     * overrides applied — the value its output is
      * encoded for, for anything that encodes on its behalf (`Live`).
      */
     get destination(): Destination;

package/dist/core/console.js

@@ -16,9 +16,10 @@ import { ReprHighlighter, NullHighlighter } from "./highlighter.js";
 // orchestrator reaching down for `Rule`. `RuleOptions` rides the same edge
 // rather than being restated here; see `rule()`.
 import { Rule } from "../renderables/rule.js";
-import { segmentsToString } from "./render.js";
+import { segmentsToString, shownOn } from "./render.js";
 import { placeBlock } from "./place.js";
-import { isRenderable } from "./protocol.js";
+import { activePass, isRenderable, measure, render } from "./protocol.js";
+import { ListState, State, refuseRenderWrite } from "./state.js";
 // [LAW:dataflow-not-control-flow] With no live region claimed, stepping around
 // it is the text itself: every write takes the same path.
 const NO_LIVE_REGION = { around: (text) => text };
@@ -67,11 +68,11 @@ class TextRun {
         this.text = items.reduce((joined, item) => joined.append(item), new RichText("", { end: "" }));
     }
     *render(options) {
-        yield* this.text.render(options);
+        yield* render(this.text, options);
         yield this.end;
     }
     measure(options) {
-        return this.text.measure(options);
+        return measure(this.text, options);
     }
 }
 // A host with an environment but no streams — what a browser looks like from
@@ -177,7 +178,7 @@ export class Console {
     // compared with: the reference's `LogRender._last_time`, one per console.
     // [LAW:no-ambient-temporal-coupling] "same as the previous row" is a fact
     // about an earlier call, so it is state this console owns, not order luck.
-    _lastLogTime = null;
+    _lastLogTime = new State(null);
     _style;
     _isTerminal;
     _interactive;
@@ -193,14 +194,15 @@ export class Console {
     _onStyleError;
     _asciiOnly;
     _highlighter;
-    _recorded;
+    _recorded = new ListState();
     // [LAW:types-are-the-program] The capture state is carried in the *type*
     // of this field, not in a sentinel value. `null` = not capturing; any
     // string (including "") = capturing, this is the buffer. A paired
     // boolean+string would admit the impossible state "not capturing, buffer
     // non-empty" — `string | null` makes that unrepresentable.
-    _capture;
-    _liveRegion;
+    _capture = new State(null);
+    _liveRegion = new State(NO_LIVE_REGION);
+    _madeIn = activePass();
     constructor(options) {
         const environment = options?.environment ?? ambientEnvironment();
         const stream = boundStream(environment, options?.stderr ?? false);
@@ -209,14 +211,13 @@ export class Console {
         // [LAW:dataflow-not-control-flow] `isTTY` and `env` are forwarded
         // unconditionally, so detection stays inside the console's injected
         // environment rather than the ambient process's.
-        const resolved = resolveDestination(options?.colorSystem === undefined ? "auto" : options.colorSystem, { isTTY: this._isTerminal, env: environment.env });
+        const resolved = resolveDestination(options?.colorSystem === undefined ? "auto" : options.colorSystem, { isTTY: this._isTerminal, env: environment.env, reducedMotion: options?.reducedMotion });
         // [LAW:single-enforcer] The console's one override, an explicit
         // `hyperlinks`, is applied here and nowhere else; every write encodes for
-        // this value whole.
-        this._destination = {
-            colorSystem: resolved.colorSystem,
-            hyperlinks: options?.hyperlinks ?? resolved.hyperlinks,
-        };
+        // this value whole. [LAW:one-source-of-truth] The reader's motion
+        // preference lives here too, and `options` reads it back from here, so
+        // what is drawn and how it is encoded take one preference.
+        this._destination = { ...resolved, hyperlinks: options?.hyperlinks ?? resolved.hyperlinks };
         this._getSize = resolveGetSize(options, environment, stream);
         this._getDatetime = options?.getDatetime ?? (() => new Date());
         // [LAW:no-ambient-temporal-coupling] The theme is assigned before the
@@ -232,9 +233,6 @@ export class Console {
         this._highlighter = options?.highlighter ?? new ReprHighlighter();
         this._onStyleError = options?.onStyleError;
         this._asciiOnly = options?.asciiOnly ?? false;
-        this._recorded = [];
-        this._capture = null;
-        this._liveRegion = NO_LIVE_REGION;
     }
     // --- Properties ---
     get size() {
@@ -256,8 +254,9 @@ export class Console {
         return this._destination.colorSystem;
     }
     /**
-     * Where this console writes: the colour depth it draws at and whether it
-     * emits OSC 8 hyperlinks, overrides applied — the value its output is
+     * Where this console writes: the colour depth it draws at, whether it
+     * emits OSC 8 hyperlinks, and whether its reader asked for reduced motion,
+     * overrides applied — the value its output is
      * encoded for, for anything that encodes on its behalf (`Live`).
      */
     get destination() {
@@ -287,6 +286,7 @@ export class Console {
             height: { rows: height, exact: false },
             isTerminal: this.isTerminal,
             asciiOnly: this._asciiOnly,
+            reducedMotion: this._destination.reducedMotion,
             theme: this._theme,
             onStyleError: this._onStyleError,
             colorSystem: this._destination.colorSystem,
@@ -433,7 +433,7 @@ export class Console {
             const renderable = block.kind === "text" ? new TextRun(block.items, terminator) : block.renderable;
             if (align)
                 return { lines: placeBlock(renderable, align, renderOpts), closed: true };
-            const drawn = [...renderable.render(renderOpts)];
+            const drawn = [...render(renderable, renderOpts)];
             // A text run's last segment is always its `end`, yielded even when
             // empty, and `splitLines` drops the empty line after a final break only
             // when nothing follows it — so the run is closed exactly when `end` is.
@@ -474,12 +474,12 @@ export class Console {
     log(...args) {
         const options = this.options;
         const stamped = logTime(this._getDatetime());
-        const repeated = stamped === this._lastLogTime;
+        const repeated = stamped === this._lastLogTime.get();
         const time = new RichText(stamped, { end: "" });
         time.stylize("log.time");
         const width = Math.min(time.cellLength, options.maxWidth - 1);
         const { rows, cropWidth } = this._draw(args, { ...options, maxWidth: options.maxWidth - width });
-        const [stampLine = []] = Segment.splitLines(time.render({ ...options, maxWidth: time.cellLength }));
+        const [stampLine = []] = Segment.splitLines(render(time, { ...options, maxWidth: time.cellLength }));
         const styled = (cell) => [...Segment.applyStyle(cell, this._style)];
         const stamp = styled(Segment.adjustLineLength(stampLine, width));
         const blank = styled([new Segment(" ".repeat(width))]);
@@ -492,14 +492,14 @@ export class Console {
         this._writeSegments(emit({ rows: grid, closed: true, cropWidth: cropWidth + width }));
         // Remembered only once the row is written: a log that threw printed no
         // stamp, so the next row's must show.
-        this._lastLogTime = stamped;
+        this._lastLogTime.set(stamped);
     }
     // [LAW:one-source-of-truth] `RuleOptions` is `Rule`'s, not a restatement of
     // it. `console.ts` used to declare its own copy and field-by-field forward
     // into this constructor, which made a second map of one shape — identical
     // then, free to drift the moment `Rule` grew an option.
     rule(title, options) {
-        const segments = [...new Rule(title, options).render(this.options)];
+        const segments = [...render(new Rule(title, options), this.options)];
         this._writeSegments(segments);
     }
     // [LAW:one-source-of-truth] `JSONRenderable` is the one formatter for JSON and
@@ -519,15 +519,15 @@ export class Console {
      * painted over by the first, so claiming one while another is held throws.
      */
     claimLiveRegion(region) {
-        if (this._liveRegion !== NO_LIVE_REGION) {
+        if (this._liveRegion.get() !== NO_LIVE_REGION) {
             throw new Error("A live display is already running on this console; stop it before starting another.");
         }
-        this._liveRegion = region;
+        this._liveRegion.set(region);
         // Letting go of a region no longer held — a second call, or after another
         // was claimed — leaves the one that is.
         return () => {
-            if (this._liveRegion === region)
-                this._liveRegion = NO_LIVE_REGION;
+            if (this._liveRegion.get() === region)
+                this._liveRegion.set(NO_LIVE_REGION);
         };
     }
     // --- Capture ---
@@ -537,60 +537,65 @@ export class Console {
     // the full text that would otherwise have been written. This is not a
     // tee — callers wanting both must compose explicitly.
     beginCapture() {
-        this._capture = "";
+        this._capture.set("");
     }
     endCapture() {
-        const result = this._capture ?? "";
-        this._capture = null;
+        const result = this._capture.get() ?? "";
+        this._capture.set(null);
         return result;
     }
     // --- Export (when record:true) ---
     exportText({ clear = true } = {}) {
-        const text = this._recorded.map((s) => s.text).join("");
+        const text = this._recorded.get().map((s) => s.text).join("");
         if (clear)
-            this._recorded = [];
+            this._recorded.set([]);
         return text;
     }
     // [LAW:single-enforcer] `encodeHtml` draws the picture `exportLines`
     // resolves; nothing here interprets a `Style`.
     exportHtml({ theme, clear = true } = {}) {
-        const html = encodeHtml(this._recorded, theme);
+        const html = encodeHtml(this._recorded.get(), theme);
         if (clear)
-            this._recorded = [];
+            this._recorded.set([]);
         return html;
     }
     // [LAW:single-enforcer] As `exportHtml`: `encodeSvg` draws, this clears.
     exportSvg({ theme, title = "Rich", clear = true } = {}) {
-        const svg = encodeSvg(this._recorded, { theme, title, width: this.width });
+        const svg = encodeSvg(this._recorded.get(), { theme, title, width: this.width });
         if (clear)
-            this._recorded = [];
+            this._recorded.set([]);
         return svg;
     }
     // --- Internal ---
     // [LAW:single-enforcer] One encode call per write batch routes through the
     // same `segmentsToString` used by `renderToString`. Recording captures every
-    // non-control segment for replay.
+    // non-control segment for replay, as its destination shows it.
     _writeSegments(segments) {
+        const shown = segments.map((segment) => shownOn(segment, this._destination));
         if (this._record) {
-            for (const segment of segments) {
+            for (const segment of shown) {
                 if (!segment.isControl)
                     this._recorded.push(segment);
             }
         }
-        const encoded = segmentsToString(segments, this._destination);
+        const encoded = segmentsToString(shown, this._destination);
         if (encoded.length > 0)
             this._write(encoded);
     }
     _write(text) {
+        // [LAW:single-enforcer] Every write is refused during a render this console was not made in, whatever
+        // the console records or captures: output is an effect, and one made mid-frame lands inside the frame.
+        refuseRenderWrite(this._madeIn);
         // [LAW:types-are-the-program] `_capture !== null` is a discriminator
         // narrow on `string | null`, not a sentinel comparison — the type
         // carries the active/inactive state. The early return is what makes
         // this a redirect (not a tee); see beginCapture for semantics.
-        if (this._capture !== null) {
-            this._capture += text;
+        const captured = this._capture.get();
+        if (captured !== null) {
+            this._capture.set(captured + text);
             return;
         }
         const target = this._file ?? defaultSink(this._stream);
-        target.write(this._liveRegion.around(text));
+        target.write(this._liveRegion.get().around(text));
     }
 }

package/dist/core/easing.d.ts

@@ -1,6 +1,7 @@
 /**
- * Easing and phase: the one vocabulary for "how far along" — every function
- * here returns progress in [0, 1].
+ * Easing and phase: the one vocabulary for "how far along" — a time in
+ * seconds becomes progress in [0, 1], and an ease reshapes that progress,
+ * usually but not always within [0, 1].
  *
  * Two kinds of curve, composed as `ease(phase(t))`:
  *
@@ -13,20 +14,31 @@
  *   built-ins are CSS's easing functions (CSS Easing Functions Level 1):
  *   `linear`, `cubic-bezier()` with its named curves, and `steps()` with its
  *   jump terms, plus `sine` for pulses — a half-cosine, so a `pingPong`
- *   through it brightens and dims with no corner at either end.
+ *   through it brightens and dims with no corner at either end — and the
+ *   physics-flavoured curves a cursor snapping, a counter settling or a
+ *   panel sliding in want: `spring`, a damped harmonic oscillator released
+ *   toward its rest, which is the one of them with parameters and so the one
+ *   that also says how long it takes; `bounce`, `back-in`, `back-out` and
+ *   `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
+ *   swing, so the overshoot is read by what can show it (a position, a
+ *   count) and clipped by what cannot.
  *
  * [LAW:no-ambient-temporal-coupling] Nothing here reads a clock. `t` is an
  * argument; whoever draws frames owns the clock and samples these at
  * whatever rate it likes, so the same `t` always gives the same progress.
  *
  * [LAW:one-type-per-behavior] An ease is a plain function value. CSS's named
- * curves are four instances of `cubicBezier`, not four implementations, and
- * `ColorRamp` and every effect take the same `Ease`.
+ * 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`.
  *
  * Tier 0 of `src/core/`: imports nothing, so `themes/` and every later
  * `core/` module reach it downhill. [LAW:one-way-deps]
  */
-/** Progress in, progress out: a reshaping of [0, 1]. */
+/** 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;
 /** Time in seconds (plus any per-cell offset) in, progress in [0, 1] out. */
 export type Phase = (t: number) => number;
@@ -51,11 +63,78 @@ export type StepPosition = "jump-start" | "jump-end" | "jump-none" | "jump-both"
  * the very end.
  */
 export declare function steps(n: number, position?: StepPosition): Ease;
+/**
+ * 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 —
+ * 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
+ * stops, a back curve's cubic or a bezier's Newton step lands an ulp off —
+ * 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;
+/**
+ * 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
+ * in (React Spring, Framer Motion), whose defaults these are — a spring that
+ * overshoots once and settles in about a second and a quarter.
+ */
+export interface SpringOptions {
+    /** The restoring force per unit of displacement; stiffer swings faster and settles in about the same time, since the decay is the damping's over the mass's. Positive. Defaults to 100. */
+    readonly stiffness?: number;
+    /** The force against the motion per unit of velocity; more settles sooner and overshoots less. Positive. Defaults to 10. */
+    readonly damping?: number;
+    /** What the spring moves; heavier is slower and overshoots further. Positive. Defaults to 1. */
+    readonly mass?: number;
+}
+/**
+ * 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
+ * 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;
+    /** 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
+ * under any cell, so what rounds the spring's value to show it draws the rest
+ * from there on.
+ */
+export declare const SPRING_REST = 0.001;
+/**
+ * A damped harmonic oscillator, `m·x″ = −k·x − c·x′`, released at rest one
+ * unit from its equilibrium: the spring every animation library means. Its
+ * progress at `s` seconds is `1 − displacement(s)`, the closed-form solution
+ * of that equation in the regime its damping ratio `ζ = c / 2√(k·m)` puts it
+ * in — ringing past its rest for `ζ < 1`, creeping up to it for `ζ ≥ 1` — and
+ * its `seconds` is its settling time: the first moment after which the
+ * displacement stays within `SPRING_REST`, found once here by `crossing` on
+ * the bracket each regime knows its last crossing lies in, so a sample costs
+ * an exponential and a cosine whatever `x` is. [LAW:no-ambient-temporal-coupling]
+ *
+ * The ease is exactly 1 at `x = 1` (`settled`): settled means at rest. The
+ * `seconds` are the spring's to say, not the caller's: how long it rings is
+ * a fact about its physics, which is why this is the one ease that comes as
+ * a `Timing` — released at rest a unit from where it is going, at 1 when it
+ * has settled there.
+ */
+export declare function spring(options?: SpringOptions): Timing;
 /**
  * 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
  * vocabulary existed, kept so every template written against it renders the
- * same. It is CSS's `step-end`, the same function value.
+ * same. It is CSS's `step-end`, the same function value. Then the
+ * physics-flavoured curves: `spring` is the default `spring()`, whose
+ * `seconds` are `DEFAULT_SPRING`'s; the rest are Penner's at his constants.
  */
 export declare const EASES: {
     readonly linear: Ease;
@@ -67,6 +146,11 @@ export declare const EASES: {
     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;
 };
 export type EaseName = keyof typeof EASES;
 /**
@@ -75,6 +159,8 @@ export type EaseName = keyof typeof EASES;
  * Unknown names throw naming every legal one. [LAW:no-silent-failure]
  */
 export declare function parseEase(name: string): Ease;
+/** Throws, naming `what`, unless `seconds` is a positive, finite number of seconds. */
+export declare function positiveSeconds(what: string, seconds: number): void;
 /**
  * A beat: holds of given lengths in seconds, played in order and looped, the
  * way the frames of an animation are each held and then replaced. `at(t)` is
@@ -94,16 +180,60 @@ 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.
+     * effect handed it draws the same frame throughout. With `nextChange`,
+     * the two ends of the hold, as every `Animation` answers them.
      */
-    start(t: number): number;
+    lastChange(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
      * always after `t`. What is drawn on this beat at `t` is drawn until then.
+     * With `at`, this makes a beat an `Animation` of the hold in progress
+     * (`./animation.ts`).
      */
-    end(t: number): number;
+    nextChange(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;
 }
+/**
+ * `t`, unless it is not a finite number of seconds, which throws naming
+ * `what`. [LAW:single-enforcer] The one refusal of a moment to draw at, for
+ * every loop and beat that reads time and every renderable drawn at a time.
+ */
+export declare function finiteTime(what: string, t: number): number;
+/**
+ * Which pass of a `period` `t` is in, as a whole number of either sign, and
+ * the seconds into it, read through the one wrap: what a `beat` and an
+ * `Animation.repeat` (`./animation.ts`) both ask, so the two agree on the
+ * pass of every float, a boundary included.
+ */
+export declare function passAt(what: string, t: number, period: number): {
+    readonly pass: number;
+    readonly into: number;
+};
+/**
+ * The first float from `sum` up at which `reached` holds: a time built as a
+ * sum to land on a boundary — where a hold begins, where an animation's next
+ * part changes — that rounding put an ulp or two under it, walked up to the
+ * first moment on the far side. [LAW:single-enforcer] The one walk, so every
+ * boundary a time is carried onto is the moment the change shows, to the
+ * float. A walk longer than rounding can cost throws `finer()`'s message: the
+ * boundary is narrower than the floats around it are apart.
+ */
+export declare function walkUp(sum: number, reached: (x: number) => boolean, finer: () => string): number;
+/**
+ * The least float at which `reached` holds, `reached` being false up to some
+ * float and true from it on, found from `near`, a guess at it on either
+ * side. Where `walkUp` carries a sum onto a boundary on its own clock, and
+ * an ulp or two is all rounding can cost, this carries a moment across
+ * clocks (`./timeline.ts`): a host float is a step of `rate` on the
+ * animation's clock, so the host floats between the guess and the first one
+ * past the boundary are as many as the two clocks' resolutions are apart,
+ * which no cap bounds and is no error. The bracket is found by doubling the
+ * step out from `near`, and halved to two adjacent floats, so the answer is
+ * 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`. */