@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/console.d.ts

@@ -3,15 +3,26 @@
  */
 import { Style, Theme } from "./style.js";
 import { ColorDepth } from "./color.js";
-import type { Destination } from "./color.js";
+import type { ColorSystemName, Destination } from "./color.js";
+import type { Env } from "./env.js";
 import type { TerminalTheme } from "./color.js";
 import { type JSONOptions } from "./json.js";
 import type { Highlighter } from "./highlighter.js";
 import { type RuleOptions } from "../renderables/rule.js";
 import type { Height, OverflowMethod, RenderOptions, StyleErrorHandler } from "./protocol.js";
+import type { Unsubscribe } from "./subscription.js";
 export interface ConsoleSink {
     write(chunk: string | Uint8Array): unknown;
 }
+/**
+ * A frame standing on the terminal under the cursor — a running `Live` — that
+ * everything the console writes has to go above. `around` returns the bytes
+ * that take the frame off the terminal, write `text`, and paint the frame
+ * back under it; the console writes them in one piece.
+ */
+export interface LiveRegion {
+    around(text: string): string;
+}
 export interface ConsoleStream extends ConsoleSink {
     readonly isTTY?: boolean;
     readonly columns?: number;
@@ -23,18 +34,18 @@ export interface ConsoleStream extends ConsoleSink {
  * point — injecting a fake terminal needs no adapter at either end.
  */
 export interface ConsoleEnvironment {
-    readonly env: NodeJS.ProcessEnv;
+    readonly env: Env;
     readonly stdout?: ConsoleStream;
     readonly stderr?: ConsoleStream;
 }
 export interface ConsoleOptions {
     /**
-     * Color encoding. Accepts a string spec (`"auto"`, `"truecolor"`, `"256"`,
-     * `"ansi"`, `"none"`), a `ColorDepth` enum value (use this for `WINDOWS`,
-     * which has no string spec), or `null` for no color. Default `"auto"`.
+     * Color encoding. Accepts a `ColorSystemName` (`"auto"`, `"truecolor"`,
+     * `"256"`, `"ansi"`, `"none"`), a `ColorDepth` enum value (use this for
+     * `WINDOWS`, which has no name), or `null` for no color. Default `"auto"`.
      * Colour only: an explicit depth, `null` included, keeps hyperlinks.
      */
-    colorSystem?: string | ColorDepth | null;
+    colorSystem?: ColorSystemName | ColorDepth | null;
     /**
      * Whether OSC 8 hyperlinks are emitted. Default: what the destination takes
      * — true for an explicit `colorSystem`, detected under `"auto"` (no TTY or
@@ -72,6 +83,11 @@ export interface ConsoleOptions {
         width: number;
         height: number;
     };
+    /**
+     * The clock `log` stamps each row from, read once per call. Default: the
+     * wall clock. Pass a fixed one to make logged output repeatable.
+     */
+    getDatetime?: () => Date;
     style?: string | Style;
     forceTerminal?: boolean;
     forceInteractive?: boolean;
@@ -112,9 +128,11 @@ export interface PrintOptions {
 export declare class Console {
     private readonly _destination;
     private _getSize;
+    private readonly _getDatetime;
+    private _lastLogTime;
     private _style;
     private _isTerminal;
-    private _forceInteractive;
+    private readonly _interactive;
     private _file;
     private _stream;
     private _record;
@@ -126,6 +144,7 @@ export declare class Console {
     private _highlighter;
     private _recorded;
     private _capture;
+    private _liveRegion;
     constructor(options?: ConsoleOptions);
     get size(): {
         width: number;
@@ -148,9 +167,16 @@ export declare class Console {
         height: Height;
     };
     print(...args: unknown[]): void;
+    private _draw;
     log(...args: unknown[]): void;
     rule(title?: string, options?: RuleOptions): void;
     printJson(json: string | object, options?: JSONOptions): void;
+    /**
+     * Hold `region` under everything this console writes until the returned
+     * call lets it go. One region at a time: a second would be erased and
+     * painted over by the first, so claiming one while another is held throws.
+     */
+    claimLiveRegion(region: LiveRegion): Unsubscribe;
     beginCapture(): void;
     endCapture(): string;
     exportText({ clear }?: {
@@ -160,6 +186,11 @@ export declare class Console {
         theme?: TerminalTheme;
         clear?: boolean;
     }): string;
+    exportSvg({ theme, title, clear }?: {
+        theme?: TerminalTheme;
+        title?: string;
+        clear?: boolean;
+    }): string;
     private _writeSegments;
     private _write;
 }

package/dist/core/console.js

@@ -3,11 +3,12 @@
  */
 import { Segment } from "./segment.js";
 import { NULL_STYLE, DEFAULT_THEME } from "./style.js";
-import { resolveDestination } from "./color.js";
+import { isDumbTerminal, resolveDestination } from "./color.js";
 import { encodeHtml } from "./export-html.js";
+import { encodeSvg } from "./export-svg.js";
 import { RichText } from "./text.js";
-import { renderMarkup } from "./markup.js";
-import { Pretty } from "./pretty.js";
+import { activeHighlighter, renderStr } from "./markup.js";
+import { Pretty, UNSEEN_DATA_BOUNDS, isExpandable } from "./pretty.js";
 import { JSONRenderable } from "./json.js";
 import { ReprHighlighter, NullHighlighter } from "./highlighter.js";
 // [LAW:one-way-deps] exception: one of the two sanctioned upward edges out of
@@ -18,6 +19,29 @@ import { Rule } from "../renderables/rule.js";
 import { segmentsToString } from "./render.js";
 import { placeBlock } from "./place.js";
 import { isRenderable } from "./protocol.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 };
+// Rows as the bytes that reach the terminal. Every row but the last is closed
+// by a line break, and the last one when `closed` says so. Crop last, and crop
+// the line-end with the rest: in the reference `end` is the tail of the printed
+// line, so a line cut at the edge loses it too.
+function emit({ rows, closed, cropWidth }) {
+    const output = rows.flatMap((row, index) => closed || index < rows.length - 1 ? [...row, Segment.line()] : row);
+    return [...Segment.cropLines(output, cropWidth)];
+}
+// The time `log` stamps: local 24-hour `HH:MM:SS`, what the reference's `%X`
+// prints under the C locale a Python program runs in unless it asks for
+// another. The machine's locale never reaches it, so neither does the width
+// an AM/PM suffix would add, and one clock prints one stamp everywhere.
+function logTime(time) {
+    // [LAW:no-silent-failure] The clock is the caller's, and an invalid `Date`
+    // would otherwise print as `[NaN:NaN:NaN]`.
+    if (Number.isNaN(time.getTime()))
+        throw new RangeError("Console getDatetime returned an invalid Date");
+    const two = (n) => String(n).padStart(2, "0");
+    return `[${two(time.getHours())}:${two(time.getMinutes())}:${two(time.getSeconds())}] `;
+}
 // Three of the five justify methods place what a print draws as a block, the
 // way Rich's `print` wraps each renderable in `Align`. The other two leave it
 // where it was drawn: `"default"` asks for no placement, and `"full"` is a way
@@ -36,23 +60,18 @@ const PLACED_BY = {
 // `justify`, `overflow`, `noWrap` and `tabSize` stay behind, as they do in the
 // reference: the print's options set the whole run.
 class TextRun {
-    items;
     end;
+    text;
     constructor(items, end) {
-        this.items = items;
         this.end = end;
+        this.text = items.reduce((joined, item) => joined.append(item), new RichText("", { end: "" }));
     }
     *render(options) {
-        yield* this.text(options).render(options);
+        yield* this.text.render(options);
         yield this.end;
     }
     measure(options) {
-        return this.text(options).measure(options);
-    }
-    // A `Pretty` lays itself out for the width it is offered, so the run is
-    // joined per call rather than once.
-    text(options) {
-        return this.items.reduce((joined, item) => joined.append(item instanceof Pretty ? item.toText(options) : item), new RichText("", { end: "" }));
+        return this.text.measure(options);
     }
 }
 // A host with an environment but no streams — what a browser looks like from
@@ -146,25 +165,6 @@ function resolveGetSize(options, environment, stream) {
 // --- Console ---
 /** Shared because it is stateless: highlighting nothing has nothing to own. */
 const NO_HIGHLIGHT = new NullHighlighter();
-/**
- * What `print` bounds a data argument by when the caller said nothing.
- *
- * `print` formats whatever it is handed, so it is the one place that has to
- * assume nothing about the value's size, in any of the three ways a value can
- * be large. Unbounded, `print(buffer)` emits a line per byte,
- * `print(deeplyNested)` descends until the stack gives out, and a single
- * response body assigned to a field arrives in full — each of them a debug line
- * that costs megabytes or hangs the terminal. All three bounds announce
- * themselves in the output (`... +N`, `{...}`, `+N` after the closing quote),
- * so this truncates visibly and never silently. [LAW:no-silent-failure]
- *
- * `maxString` reaches only strings nested inside data; a string argument is
- * printed by the arm above, where the caller asked for that string by name.
- *
- * A caller constructing a `Pretty` has seen their data and gets no defaults;
- * these belong to the convenience path, not to the formatter.
- */
-const PRINT_DATA_BOUNDS = { maxLength: 100, maxDepth: 16, maxString: 1000 };
 export class Console {
     _destination;
     // [LAW:one-source-of-truth] Size flows through a single function. Static
@@ -172,9 +172,15 @@ export class Console {
     // caller-supplied `getSize` overrides. Every size read in this class goes
     // through `_getSize()` — no second path, no second source to drift.
     _getSize;
+    _getDatetime;
+    // The stamp the last `log` row was given, which the next row's stamp is
+    // 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;
     _style;
     _isTerminal;
-    _forceInteractive;
+    _interactive;
     _file;
     // [LAW:one-source-of-truth] The resolved output stream, not the `stderr`
     // flag that selected it. Storing the answer instead of the question is what
@@ -194,6 +200,7 @@ export class Console {
     // boolean+string would admit the impossible state "not capturing, buffer
     // non-empty" — `string | null` makes that unrepresentable.
     _capture;
+    _liveRegion;
     constructor(options) {
         const environment = options?.environment ?? ambientEnvironment();
         const stream = boundStream(environment, options?.stderr ?? false);
@@ -211,11 +218,13 @@ export class Console {
             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
         // style, because the console's own style may be one of the theme's names.
         this._theme = options?.theme ?? DEFAULT_THEME;
         this._style = this._theme.resolve(options?.style ?? NULL_STYLE);
-        this._forceInteractive = options?.forceInteractive;
+        // Rich's rule: a terminal is interactive unless it is a dumb one.
+        this._interactive = options?.forceInteractive ?? (this._isTerminal && !isDumbTerminal(environment.env));
         this._file = options?.file;
         this._record = options?.record ?? false;
         this._markup = options?.markup !== false;
@@ -225,6 +234,7 @@ export class Console {
         this._asciiOnly = options?.asciiOnly ?? false;
         this._recorded = [];
         this._capture = null;
+        this._liveRegion = NO_LIVE_REGION;
     }
     // --- Properties ---
     get size() {
@@ -240,9 +250,7 @@ export class Console {
         return this._isTerminal;
     }
     get isInteractive() {
-        if (this._forceInteractive !== undefined)
-            return this._forceInteractive;
-        return this.isTerminal;
+        return this._interactive;
     }
     get colorSystem() {
         return this._destination.colorSystem;
@@ -282,10 +290,17 @@ export class Console {
             theme: this._theme,
             onStyleError: this._onStyleError,
             colorSystem: this._destination.colorSystem,
+            markup: this._markup,
+            highlight: this._highlight,
+            highlighter: this._highlighter,
         };
     }
     // --- Print ---
     print(...args) {
+        this._writeSegments(emit(this._draw(args, this.options)));
+    }
+    // What `print` draws for `args` at `options.maxWidth`.
+    _draw(args, options) {
         // Extract options from last arg if it's a PrintOptions
         let opts = {};
         let items;
@@ -309,53 +324,56 @@ export class Console {
         else {
             items = args;
         }
-        const doMarkup = opts.markup ?? this._markup;
-        const doHighlight = opts.highlight ?? this._highlight;
+        // What a string is read as, wherever in this print it lands: an argument,
+        // or a cell or label inside a renderable argument. `print`'s own flags
+        // outrank the console's, as Rich's `options.update` has them.
+        const strings = {
+            markup: opts.markup ?? this._markup,
+            highlight: opts.highlight ?? this._highlight,
+            highlighter: this._highlighter,
+        };
         const sep = opts.sep ?? " ";
         const end = opts.end ?? "\n";
         const softWrap = opts.softWrap ?? false;
         const printStyle = this._theme.resolve(opts.style ?? NULL_STYLE);
         // A print is a column of blocks, and every argument joins one of two kinds.
-        // Text — a string, a `RichText`, or data — runs together: adjacent text
+        // Text — a string, a `RichText`, or a scalar — runs together: adjacent text
         // items are one block, joined by `sep` and ended by `end`. Any other
         // renderable is a block of its own that occupies whole lines, so neither
         // `sep` nor `end` ever touches it. That is the reference's split — `end`
         // belongs to text, not to the print — and it is what lets two printed panels
-        // stack with no blank line between them. The one place the reference cuts
-        // differently is data: it gives a container lines of its own, and here all
-        // data is text. The line is not closed by asking where the cursor sits:
-        // `print("a\n")` is a line and an empty one, here as in the reference and
-        // in every other `print`, and only the kind of the item can tell that
-        // trailing break from a `Panel`'s. A call with nothing to print is one
-        // empty text run, so it still ends the line.
+        // stack with no blank line between them. Data is cut where the reference
+        // cuts it: a container (`isExpandable`) is a block, a scalar is text. A
+        // container is laid out by `Pretty` across as many lines as it needs, and
+        // joined into a run it would start partway along a line and leave its
+        // closing bracket where the next item carries on. The line is not closed by
+        // asking where the cursor sits: `print("a\n")` is a line and an empty one,
+        // here as in the reference and in every other `print`, and only the kind of
+        // the item can tell that trailing break from a `Panel`'s. A call with
+        // nothing to print is one empty text run, so it still ends the line.
         const blocks = items.length === 0 ? [{ kind: "text", items: [] }] : [];
         for (const item of items) {
-            // Four arms, and they are the whole domain. A `RichText` is already text;
-            // it runs as a copy with its own `end` cleared, as a string's is, because
-            // the line end of a run is the print's. Any other renderable draws itself,
+            // Four arms, and they are the whole domain. A `RichText` is already text.
+            // No arm's own `end` reaches the line: `TextRun` joins the run with
+            // `append`, which leaves each part's behind, as Rich's `Text(sep).join`
+            // does, because the line end of a run is the print's. Any other renderable draws itself,
             // as a block. A string is the only kind of argument that can *contain*
             // markup, so it is the only kind the markup dialect is applied to.
-            // Everything else is data, and `Pretty` is the single authority on how a
+            // Everything else is data — a block when it is a container, text when it
+            // is not — and `Pretty` is the single authority on how a
             // JavaScript value displays — `String(value)` was a second, weaker one
             // that answered `[object Object]` for every object and let the markup
             // parser eat it. [LAW:one-source-of-truth]
             let text;
             if (item instanceof RichText) {
-                const richText = item.copy();
-                richText.end = "";
-                text = richText;
+                text = item;
             }
             else if (isRenderable(item)) {
                 blocks.push({ kind: "lines", renderable: item });
                 continue;
             }
             else if (typeof item === "string") {
-                const richText = doMarkup ? renderMarkup(item) : new RichText(item);
-                richText.end = "";
-                if (doHighlight) {
-                    this._highlighter.highlight(richText);
-                }
-                text = richText;
+                text = renderStr(item, strings);
             }
             else {
                 // The highlighter travels with the value. `highlight` and a custom
@@ -363,18 +381,21 @@ export class Console {
                 // formatted object the same way they reach a printed string; a `Pretty`
                 // left to its own default would outrank both. [LAW:dataflow-not-control-flow]
                 // the disabled case is an identity highlighter, not a skipped call.
-                // Indent guides are styling too, and travel with the same decision —
-                // the console owns what `highlight` means for everything it emits,
-                // rather than `Pretty` inferring it back out of the highlighter.
-                text = new Pretty(item, {
-                    ...PRINT_DATA_BOUNDS,
-                    highlighter: doHighlight ? this._highlighter : NO_HIGHLIGHT,
-                    indentGuides: doHighlight,
+                const pretty = new Pretty(item, {
+                    ...UNSEEN_DATA_BOUNDS,
+                    highlighter: activeHighlighter(strings) ?? NO_HIGHLIGHT,
                 });
+                // A scalar spells the same at every width, so it joins its run as the
+                // one text it is.
+                if (isExpandable(item)) {
+                    blocks.push({ kind: "lines", renderable: pretty });
+                    continue;
+                }
+                text = pretty.toText(options);
             }
             const run = blocks.at(-1);
             if (run?.kind === "text")
-                run.items.push(new RichText(sep, { end: "" }), text);
+                run.items.push(new RichText(sep), text);
             else
                 blocks.push({ kind: "text", items: [text] });
         }
@@ -384,7 +405,8 @@ export class Console {
         // at the width, as Rich's does. What `"ignore"` does to a line — no edge,
         // no justify — is `RichText`'s to apply, so it crosses as it was asked for.
         const renderOpts = {
-            ...this.options,
+            ...options,
+            ...strings,
             justify: opts.justify === "default" ? undefined : opts.justify,
             overflow: opts.overflow ?? (softWrap ? "ignore" : undefined),
             noWrap: softWrap,
@@ -404,10 +426,9 @@ export class Console {
         // block is closed line by line, as `Align` closes it. Unplaced, a text run
         // is closed exactly where its content — its `end` included — breaks; any
         // other block's lines are closed whether or not it closed them itself: a
-        // `Panel` ends in a line break and a bare `Spinner` or `ProgressBar` does
-        // not (they're line fragments, meant to be composed within a line —
-        // rich-flexstrip-5kf.4cq), and both leave the next print at the start of a
-        // line.
+        // `Panel` ends in a line break and a bare `ProgressBar` does not (a line
+        // fragment — test/seam/line-ends.ts), and both leave the next print at the
+        // start of a line.
         const drawBlock = (block) => {
             const renderable = block.kind === "text" ? new TextRun(block.items, terminator) : block.renderable;
             if (align)
@@ -422,31 +443,56 @@ export class Console {
         // Every line end goes through the same writeSegments funnel as the text it
         // ends, so it survives recording — otherwise `exportText` and `exportHtml`
         // would join consecutive prints onto a single line. [LAW:single-enforcer]
+        // A block left open carries on along the next block's first line, so the
+        // rows are read off the joined output rather than counted per block.
         const output = [];
+        let closed = true;
         for (const block of blocks) {
-            const { lines, closed } = drawBlock(block);
-            lines.forEach((line, index) => {
+            const drawn = drawBlock(block);
+            drawn.lines.forEach((line, index) => {
                 output.push(...styleContent(line));
-                if (closed || index < lines.length - 1)
+                if (drawn.closed || index < drawn.lines.length - 1)
                     output.push(Segment.line());
             });
+            closed = drawn.closed;
         }
-        // Crop last, and crop the line-end with the rest: in the reference `end` is
-        // the tail of the printed line, so a line cut at the edge loses it too.
         // Soft wrap turns cropping off whatever `crop` says, because a line it left
         // whole is meant to reach the terminal whole. [LAW:dataflow-not-control-flow]
         // Not cropping is an unbounded width rather than a skipped step — the same
         // spelling `RichText` uses for `"ignore"`.
-        const cropWidth = !softWrap && (opts.crop ?? true) ? this.width : Infinity;
-        this._writeSegments([...Segment.cropLines(output, cropWidth)]);
+        const cropWidth = !softWrap && (opts.crop ?? true) ? options.maxWidth : Infinity;
+        return { rows: Segment.splitLines(output), closed, cropWidth };
     }
+    // The reference's `LogRender`: a grid row of two cells, the time and beside it
+    // whatever `print` would draw for `args` in the width that is left. A grid row
+    // is at least one line tall and always closed, whatever `end` left open
+    // inside its cell. The time gives up cells before the content does, so a
+    // console narrower than the time still shows every argument. The time takes
+    // the console's style alone, as the reference styles only the renderables.
+    // A time that reads as the previous row's is left blank at its width, the
+    // reference's `omit_repeated_times`, so a burst of rows carries one stamp.
     log(...args) {
-        // Simple log implementation — adds timestamp
-        const now = new Date();
-        const time = now.toLocaleTimeString();
-        const timeText = new RichText(`[${time}] `, { end: "" });
-        timeText.stylize("log.time");
-        this.print(timeText, ...args);
+        const options = this.options;
+        const stamped = logTime(this._getDatetime());
+        const repeated = stamped === this._lastLogTime;
+        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 styled = (cell) => [...Segment.applyStyle(cell, this._style)];
+        const stamp = styled(Segment.adjustLineLength(stampLine, width));
+        const blank = styled([new Segment(" ".repeat(width))]);
+        const head = repeated ? blank : stamp;
+        const grid = Array.from({ length: Math.max(1, rows.length) }, (_, index) => [
+            ...(index === 0 ? head : blank),
+            ...(rows[index] ?? []),
+        ]);
+        // The row is the column wider than its cell; an uncropped cell stays so.
+        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;
     }
     // [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
@@ -466,6 +512,24 @@ export class Console {
             : JSONRenderable.fromData(json, options);
         this.print(renderable, { softWrap: true });
     }
+    // --- Live region ---
+    /**
+     * Hold `region` under everything this console writes until the returned
+     * call lets it go. One region at a time: a second would be erased and
+     * painted over by the first, so claiming one while another is held throws.
+     */
+    claimLiveRegion(region) {
+        if (this._liveRegion !== NO_LIVE_REGION) {
+            throw new Error("A live display is already running on this console; stop it before starting another.");
+        }
+        this._liveRegion = 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;
+        };
+    }
     // --- Capture ---
     // [LAW:one-source-of-truth] Redirect semantics match Python Rich's
     // `Console.capture()`: while a capture is active the underlying target
@@ -495,12 +559,17 @@ export class Console {
             this._recorded = [];
         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 });
+        if (clear)
+            this._recorded = [];
+        return svg;
+    }
     // --- Internal ---
     // [LAW:single-enforcer] One encode call per write batch routes through the
-    // same `segmentsToString` tree-coalescer used by `renderToString`. Adjacent
-    // same-style segments share one SGR open/close pair on the wire instead of
-    // one pair per segment. Recording captures every non-control segment for
-    // replay regardless of how the bytes coalesce.
+    // same `segmentsToString` used by `renderToString`. Recording captures every
+    // non-control segment for replay.
     _writeSegments(segments) {
         if (this._record) {
             for (const segment of segments) {
@@ -522,6 +591,6 @@ export class Console {
             return;
         }
         const target = this._file ?? defaultSink(this._stream);
-        target.write(text);
+        target.write(this._liveRegion.around(text));
     }
 }

package/dist/core/easing.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Easing and phase: the one vocabulary for "how far along" — every function
+ * here returns progress in [0, 1].
+ *
+ * Two kinds of curve, composed as `ease(phase(t))`:
+ *
+ * - A **phase** turns a time `t` (seconds) into raw progress: `once` runs
+ *   0 → 1 over a span and holds, `loop` wraps 0 → 1 every period,
+ *   `pingPong` goes 0 → 1 → 0 every period. A per-cell offset is added to `t`
+ *   before the phase sees it — `phase(t + offset)` — so the cells of one
+ *   effect run the same curve shifted in time.
+ * - An **ease** reshapes that progress: any `(x) => y` on [0, 1]. The
+ *   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.
+ *
+ * [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`.
+ *
+ * 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]. */
+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;
+/**
+ * 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
+ * [0, 1] — as in CSS — which keeps x monotonic in the curve parameter, so
+ * 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;
+/**
+ * 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
+ * `end` are CSS's older spellings of the first two.
+ */
+export type StepPosition = "jump-start" | "jump-end" | "jump-none" | "jump-both" | "start" | "end";
+/**
+ * CSS `steps(n, position)`: progress held flat in `n` equal intervals, jumping
+ * between them. The output takes `n` distinct values between the jumps
+ * `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;
+/**
+ * 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.
+ */
+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;
+};
+export type EaseName = 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;
+/** The three phase shapes. Each takes seconds and returns a `Phase`. */
+export declare const Phase: {
+    /** 0 before `start`, rising to 1 over `duration` seconds, then held at 1. */
+    once(start: number, duration: number): Phase;
+    /** 0 → 1 every `period` seconds, wrapping back to 0; negative `t` wraps too. */
+    loop(period: number): Phase;
+    /** 0 → 1 → 0 every `period` seconds: there in the first half, back in the second. */
+    pingPong(period: number): Phase;
+};