@promptctl/rich-js 0.24.1 → 0.25.1

package/dist/renderables/progress.js

@@ -2,14 +2,16 @@
  * Progress — displays continuously updated progress bars.
  */
 import { RichText } from "../core/text.js";
-import { Console } from "../core/console.js";
 import { escape as escapeMarkup, readStr, renderStr } from "../core/markup.js";
 import { ProgressBar } from "./progressBar.js";
 import { Spinner } from "./spinner.js";
 import { Live } from "./live.js";
-import { systemClock } from "../core/clock.js";
 import { Table } from "./table.js";
 import { render } from "../core/protocol.js";
+import { Animation } from "../core/animation.js";
+import { Timeline } from "../core/timeline.js";
+import { tween } from "../core/tween.js";
+import { ListState, State } from "../core/state.js";
 /**
  * Rich's defaults for `speed_estimate_period` and its sample deque's
  * `maxlen`: an update forgets samples older than the period, and the newest
@@ -18,28 +20,32 @@ import { render } from "../core/protocol.js";
 const SPEED_ESTIMATE_PERIOD = 30;
 const MAX_SAMPLES = 1000;
 /**
- * Rich's `Progress.update` bookkeeping on its sample deque, in place: drop the
- * samples older than the period as of `now`, then add this update's if it
- * moved the task forward, keeping the newest `MAX_SAMPLES`. The samples are in
- * time order, so the stale ones are a prefix.
+ * Rich's `Progress.update` bookkeeping on its sample deque, as the samples it
+ * leaves: drop the samples older than the period as of `now`, then add this
+ * update's if it moved the task forward, keeping the newest `MAX_SAMPLES`. The samples are in
+ * the order the updates came, which is time order unless the host's timeline
+ * ran back between them, so the stale ones are found by time, not position.
  */
 function recordSample(samples, now, moved) {
-    const firstFresh = samples.findIndex((sample) => sample.timestamp >= now - SPEED_ESTIMATE_PERIOD);
-    samples.splice(0, firstFresh === -1 ? samples.length : firstFresh);
-    if (moved > 0)
-        samples.push({ timestamp: now, completed: moved });
-    samples.splice(0, samples.length - MAX_SAMPLES);
+    const fresh = samples.filter((sample) => sample.timestamp >= now - SPEED_ESTIMATE_PERIOD);
+    return [...fresh, ...(moved > 0 ? [{ timestamp: now, completed: moved }] : [])].slice(-MAX_SAMPLES);
 }
 /**
  * Rich's `Task.speed` over a started task's samples: everything moved after
- * the first sample, over the time from the first to the last. No samples, or
- * none apart in time, is no speed.
+ * the earliest sample, over the time from the earliest to the latest — Rich's
+ * first and last, when time only ran forward, and never negative when it ran
+ * back. No samples, or none apart in time, is no speed.
  */
 function sampleSpeed(samples) {
-    const span = (samples.at(-1)?.timestamp ?? 0) - (samples[0]?.timestamp ?? 0);
+    if (samples.length === 0)
+        return undefined;
+    const times = samples.map((sample) => sample.timestamp);
+    const earliest = Math.min(...times);
+    const span = Math.max(...times) - earliest;
     if (span === 0)
         return undefined;
-    return samples.slice(1).reduce((sum, sample) => sum + sample.completed, 0) / span;
+    const moved = samples.reduce((sum, sample) => sum + sample.completed, 0) - samples[times.indexOf(earliest)].completed;
+    return moved / span;
 }
 /**
  * A count as a task takes it in. [LAW:single-enforcer] `addTask` and
@@ -52,6 +58,25 @@ function finiteCount(field, value) {
         throw new RangeError(`progress task ${field} must be a finite number, got ${value}`);
     return value;
 }
+/**
+ * `state` as of `now`, the moment a frame is drawn for: a host whose timeline
+ * runs back draws moments before what was stamped later, so a task drawn
+ * before its start has not started, one drawn before it reached its total
+ * has not finished — and finishes no sooner than it started — and its speed
+ * is taken over the updates that had come by then.
+ */
+function taskAt({ samples, finishedAt, ...state }, now) {
+    const startTime = state.startTime !== undefined && now >= state.startTime ? state.startTime : undefined;
+    const finishedTime = startTime !== undefined && finishedAt !== undefined && now >= finishedAt ? Math.max(0, finishedAt - startTime) : undefined;
+    const started = startTime !== undefined;
+    return {
+        ...state,
+        startTime,
+        elapsed: started ? now - startTime : undefined,
+        finishedTime,
+        speed: started ? sampleSpeed(samples.filter((sample) => sample.timestamp <= now)) : undefined,
+    };
+}
 /** Rich's `Task.finished`. [LAW:one-source-of-truth] The one predicate every reader of "finished" asks. */
 function finished(task) {
     return task.finishedTime !== undefined;
@@ -83,15 +108,22 @@ export class BarColumn {
     constructor(barWidth) {
         this.barWidth = barWidth ?? 40;
     }
-    /** Rich's `BarColumn`: a task not yet started, or with no total to fill toward, pulses. */
+    /**
+     * Rich's `BarColumn`: a task not yet started, or with no total to fill
+     * toward, pulses, and a pulse draws no fill. Otherwise the bar is the
+     * task's `fill` drawn at the frame's time, every cell stamped with when the
+     * fill next moves, so a host draws while it eases and the bar asks for
+     * nothing once it lands. Its colour is the task's: an ease that overshoots
+     * the total does not finish the bar, and one that dips back does not
+     * unfinish it.
+     */
     render(task) {
-        const pulsing = task.startTime === undefined || task.total === undefined;
-        return new ProgressBar({
-            total: task.total ?? 100,
-            completed: task.completed,
-            width: this.barWidth,
-            pulse: pulsing ? { t: task.time } : undefined,
-        });
+        const total = task.total ?? 100;
+        if (task.startTime === undefined || task.total === undefined) {
+            return new ProgressBar({ total, completed: task.completed, width: this.barWidth, pulse: true });
+        }
+        const done = task.completed >= total;
+        return Animation.map(task.fill, (completed) => new ProgressBar({ total, completed, width: this.barWidth, finished: done }));
     }
 }
 /**
@@ -151,11 +183,21 @@ export class TimeElapsedColumn {
     tableColumn = {};
     render(task) {
         // Rich's `finished_time if finished else elapsed`: a finished task's clock
-        // holds where it stopped, and one never started has no time to show.
-        const time = finished(task) ? task.finishedTime : task.elapsed;
-        return new RichText(clockFace(time), { style: "progress.elapsed" });
+        // holds where it stopped, and one never started has no time to show. A
+        // running one is a clock placed in the cell, so the frame says when its
+        // next second turns and a host paints it then. [LAW:one-source-of-truth]
+        if (finished(task))
+            return elapsedFace(task.finishedTime);
+        return task.startTime === undefined ? elapsedFace(undefined) : runningClock(task.startTime);
     }
 }
+const elapsedFace = (seconds) => new RichText(clockFace(seconds), { style: "progress.elapsed" });
+/**
+ * The seconds since `startTime` at the frame's time, turning over on each
+ * whole one. A clock is information and not motion, so reduced it still
+ * keeps the time: `Animation.repeat` keeps its turns.
+ */
+const runningClock = (startTime) => Timeline.run(Timeline.play(startTime), Animation.repeat(1, (second) => Animation.constant(elapsedFace(second))));
 /** A time as the time columns draw it, `-:--:--` when there is none to draw. */
 function clockFace(seconds) {
     return seconds === undefined ? "-:--:--" : formatTime(seconds);
@@ -174,10 +216,10 @@ export class SpinnerColumn {
         const finishedText = options?.finishedText ?? " ";
         this._finishedText = typeof finishedText === "string" ? readStr(finishedText, true) : finishedText.copy();
     }
-    // Rich's `self.spinner.render(task.get_time())`: the frame for the time the
-    // task is drawn at, which `Progress` read off its clock once for the frame.
+    // Rich's `self.spinner.render(task.get_time())`: placed, the spinner draws
+    // at the frame's time, which is the time the task is drawn at.
     render(task) {
-        return finished(task) ? this._finishedText : this._spinner.at(task.time);
+        return finished(task) ? this._finishedText : this._spinner;
     }
 }
 /**
@@ -220,11 +262,20 @@ function formatTime(seconds) {
 }
 export class Progress {
     _columns;
-    _tasks;
-    _nextId;
+    // Rich's Progress adds and updates tasks between frames: each task is a
+    // record replaced whole on update, so a frame reads one task as it stood.
+    // A task's id is its place in the list, from 1, so an update finds it
+    // without copying the others.
+    _tasks = new ListState();
+    // [LAW:types-are-the-program] Its own Live, or none: a Progress another
+    // host draws has nothing of its own to start.
     _live;
-    _console;
-    _clock;
+    // [LAW:one-source-of-truth] The one source of every time this display
+    // keeps or draws at, so a task's stamps and the frames it is drawn in are
+    // readings of one host.
+    _host;
+    /** A task's fill after its count changes at `now`, from the value it shows then. */
+    _refill;
     expand;
     constructor(...columns) {
         // Last arg might be options
@@ -242,25 +293,37 @@ export class Progress {
             cols.push(new TextColumn("[progress.description]{task.description}"), new BarColumn(), new TaskProgressColumn(), new TimeRemainingColumn());
         }
         this._columns = cols;
-        this._tasks = new Map();
-        this._nextId = 1;
-        this._console = opts.console ?? new Console();
         this.expand = opts.expand ?? false;
-        this._clock = opts.clock ?? systemClock();
-        this._live = new Live(this, {
-            console: this._console,
-            clock: this._clock,
-            refreshPerSecond: opts.refreshPerSecond ?? 10,
-            autoRefresh: opts.autoRefresh,
-            transient: opts.transient,
-        });
+        // [LAW:dataflow-not-control-flow] The option picks the rule once; an
+        // update always refills through it. Eased, the tween starts at the
+        // update's moment, and the fill it replaces is never asked for again, so
+        // a task keeps one animation, not its history: a frame drawn for a
+        // moment before the update — a timeline run back — finds the new tween
+        // not yet begun, at the value the old one showed.
+        const timing = opts.fill;
+        this._refill = timing === undefined ? (_from, to) => Animation.constant(to) : (from, to, now) => Timeline.run(Timeline.play(now), tween(from, to, timing));
+        if (opts.drawnBy === undefined) {
+            this._live = new Live(this, {
+                console: opts.console,
+                clock: opts.clock,
+                refreshPerSecond: opts.refreshPerSecond ?? 10,
+                autoRefresh: opts.autoRefresh,
+                transient: opts.transient,
+            });
+            this._host = this._live;
+        }
+        else {
+            this._live = undefined;
+            this._host = opts.drawnBy;
+        }
     }
+    /** The console its own `Live` prints above the bars through. */
     get console() {
-        return this._console;
+        return this._ownLive("console").console;
     }
     /** Rich's `Progress.finished`: every task finished, and so true with none. */
     get finished() {
-        return [...this._tasks.values()].every(finished);
+        return this._tasks.get().every((task) => finished(taskAt(task.get(), this._host.frameTime)));
     }
     static getDefaultColumns() {
         return [
@@ -271,91 +334,115 @@ export class Progress {
         ];
     }
     addTask(description, options) {
-        const id = this._nextId++;
-        const task = {
+        const id = this._tasks.get().length + 1;
+        this._tasks.push(new State({
             id,
             description,
             total: options?.total === undefined ? undefined : finiteCount("total", options.total),
             completed: 0,
+            fill: Animation.constant(0),
             visible: options?.visible !== false,
-            startTime: options?.start === false ? undefined : this._clock.now(),
-            finishedTime: undefined,
+            startTime: options?.start === false ? undefined : this._host.frameTime,
+            finishedAt: undefined,
             samples: [],
-        };
-        this._tasks.set(id, task);
+        }));
         return id;
     }
+    _task(taskId) {
+        return this._tasks.get()[taskId - 1];
+    }
     updateTask(taskId, options) {
-        const task = this._tasks.get(taskId);
-        if (!task)
+        const held = this._task(taskId);
+        if (!held)
             return;
+        const task = held.get();
         // Rich's order: `advance` is added, then a given `completed` overwrites it,
         // so `completed` wins when both come. Checked whole before any field is
         // written, so a refused update leaves the task as it was.
+        const live = options.refresh ? this._ownLive("refresh") : undefined;
         const advance = finiteCount("advance", options.advance ?? 0);
         const completed = options.completed === undefined
             ? finiteCount("completed + advance", task.completed + advance)
             : finiteCount("completed", options.completed);
-        const now = this._clock.now();
-        recordSample(task.samples, now, completed - task.completed);
-        task.completed = completed;
-        if (options.description !== undefined)
-            task.description = options.description;
-        if (options.visible !== undefined)
-            task.visible = options.visible;
-        if (!finished(task) &&
-            task.startTime !== undefined &&
-            task.total !== undefined &&
-            task.completed >= task.total) {
-            task.finishedTime = now - task.startTime;
-        }
-        if (options.refresh) {
-            this._live.update(this, { refresh: true });
-        }
+        const now = this._host.frameTime;
+        const reached = task.startTime !== undefined && task.total !== undefined && completed >= task.total;
+        held.set({
+            ...task,
+            completed,
+            // A retarget is a change of count: an update that leaves it alone leaves
+            // the ease running as it was, rather than restarting it from where it is.
+            fill: completed === task.completed ? task.fill : this._refill(task.fill.at(now), completed, now),
+            description: options.description ?? task.description,
+            visible: options.visible ?? task.visible,
+            samples: recordSample(task.samples, now, completed - task.completed),
+            // Rich's `finished_time`, kept as the moment it was reached, so a frame
+            // drawn before it — a timeline run back — finds the task not yet finished.
+            finishedAt: task.finishedAt ?? (reached ? now : undefined),
+        });
+        live?.refresh();
     }
     startTask(taskId) {
-        const task = this._tasks.get(taskId);
+        const held = this._task(taskId);
         // Rich's `start_task`: a task already running keeps the time it started.
-        if (task)
-            task.startTime ??= this._clock.now();
+        if (held)
+            held.set({ ...held.get(), startTime: held.get().startTime ?? this._host.frameTime });
     }
     start() {
-        this._live.start();
+        this._ownLive("start").start();
     }
+    /**
+     * Every bar settles at its count, so the frame drawn next — its own `Live`'s
+     * final one, handed back here, or the next of the host that draws it —
+     * shows where the work got to, not a bar caught mid-ease.
+     */
     stop() {
-        this._live.stop();
+        for (const task of this._tasks.get())
+            task.set({ ...task.get(), fill: Animation.constant(task.get().completed) });
+        this._live?.stop();
     }
     refresh() {
-        this._live.refresh();
+        this._ownLive("refresh").refresh();
+    }
+    _ownLive(asked) {
+        if (this._live === undefined) {
+            throw new Error(`Progress.${asked}: this Progress has no Live of its own; it is drawn by the host it was given as drawnBy, so use that host's ${asked}`);
+        }
+        return this._live;
     }
     *render(options) {
-        yield* render(this._table(), options);
+        const framed = this._framed(options);
+        yield* render(this._table(framed.frame.time), framed);
     }
-    // What each column renders for each task is what the table holds, and so is
-    // all a progress display holds.
-    *contents() {
-        yield this._table();
+    // Inside a frame, the time its host read for it: a second read here would
+    // land a moving bar's stamp a hair after the frame, a moment the host takes
+    // for one still to come. A frame is only ever this display's host's,
+    // because the tasks were stamped on that host's time and a frame of any
+    // other is drawn for a moment on a different clock. A print is drawn for no
+    // moment, so it is drawn in a frame for the one the program asks at, read
+    // as `updateTask` reads it, and every bar and spinner placed in the table
+    // draws at that moment too. [LAW:one-source-of-truth]
+    _framed(options) {
+        const { frame } = options;
+        if (frame !== undefined && frame.host !== this._host) {
+            throw new Error("a Progress was drawn in a frame of a host other than its own; give it that host as `drawnBy`");
+        }
+        return { ...options, frame: frame ?? { time: this._host.frameTime, host: this._host } };
     }
-    // Rich's `make_tasks_table`: each column laid out as it says.
-    _table() {
+    // Rich's `make_tasks_table`: each column laid out as it says, at `now` on
+    // this display's clock.
+    _table(now) {
         const table = Table.grid({ expand: this.expand });
         for (const col of this._columns) {
             table.addColumn(undefined, col.tableColumn);
         }
-        // [LAW:effects-at-boundaries] One read of the clock a frame, handed to
-        // every column as the task's `time` and `elapsed`.
-        const now = this._clock.now();
-        for (const { samples, ...state } of this._tasks.values()) {
+        // [LAW:effects-at-boundaries] One moment a frame, handed to every column
+        // as the task's `elapsed`; a column that moves places an animation, which
+        // draws at that same moment, the frame's.
+        for (const held of this._tasks.get()) {
+            const state = held.get();
             if (!state.visible)
                 continue;
-            const { startTime } = state;
-            const started = startTime !== undefined;
-            const task = {
-                ...state,
-                time: now,
-                elapsed: started ? now - startTime : undefined,
-                speed: started ? sampleSpeed(samples) : undefined,
-            };
+            const task = taskAt(state, now);
             table.addRow(...this._columns.map((col) => col.render(task)));
         }
         return table;

package/dist/renderables/progressBar.d.ts

@@ -9,29 +9,39 @@ export interface ProgressBarOptions {
     completed?: number;
     width?: number;
     /**
-     * Rich's pulse, for work whose end is not known, drawn as it is `t` seconds
-     * into whoever draws the frames' clock: the whole bar in its back style,
-     * with the library's `shimmer` carrying `bar.pulse` light along it. Without
-     * it, the bar shows `completed` of `total`.
+     * Rich's pulse, for work whose end is not known: the whole bar in its back
+     * style, with the library's `shimmer` carrying `bar.pulse` light along it,
+     * drawn at the time of the frame it is drawn in. Without it, the bar shows
+     * `completed` of `total`.
      */
-    pulse?: {
-        readonly t: number;
-    };
+    pulse?: boolean;
+    /**
+     * Whether the work is done, which picks `finishedStyle` over
+     * `completeStyle`: `completed` reaching `total`, unless said. A bar drawing
+     * an eased fill says it, since the fill it draws is not the count.
+     */
+    finished?: boolean;
     style?: string | Style;
     completeStyle?: string | Style;
     finishedStyle?: string | Style;
 }
 export declare class ProgressBar implements Renderable, Measurable {
-    total: number;
-    completed: number;
+    private readonly _total;
+    private readonly _completed;
+    private readonly _finished;
     readonly width: number | undefined;
-    readonly pulse: {
-        readonly t: number;
-    } | undefined;
+    readonly pulse: boolean;
     readonly style: string | Style;
     readonly completeStyle: string | Style;
     readonly finishedStyle: string | Style;
     constructor(options?: ProgressBarOptions);
+    get total(): number;
+    set total(value: number);
+    get completed(): number;
+    set completed(value: number);
+    /** Whether the work is done, as given; unset, `completed` reaching `total` at the moment the bar is drawn. */
+    get finished(): boolean | undefined;
+    set finished(value: boolean | undefined);
     render(options: RenderOptions): Iterable<Segment>;
     /**
      * The shimmer over this bar's back colour as `Effected` sees it drawn at

package/dist/renderables/progressBar.js

@@ -8,6 +8,7 @@ import { Style } from "../core/style.js";
 import { drawable, getStyle, render } from "../core/protocol.js";
 import { Effected } from "./effect.js";
 import { EFFECT_CURVES, atShares, shimmer } from "./effects.js";
+import { State } from "../core/state.js";
 const BAR = "━";
 const ASCII_BAR = "-";
 const HALF_BAR_RIGHT = "╸";
@@ -22,27 +23,49 @@ const PULSE_REACH = 10;
 /** Rich's pulse back where the back style names no colour. */
 const PULSE_BACK = ColorSpec.fromRgba(new ColorRgba(0, 0, 0));
 export class ProgressBar {
-    total;
-    completed;
+    // Rich's ProgressBar is updated after it is built: `bar.completed = n`.
+    _total;
+    _completed;
+    _finished;
     width;
     pulse;
     style;
     completeStyle;
     finishedStyle;
     constructor(options) {
-        this.total = options?.total ?? 100;
-        this.completed = options?.completed ?? 0;
+        this._total = new State(options?.total ?? 100);
+        this._completed = new State(options?.completed ?? 0);
         this.width = options?.width;
-        this.pulse = options?.pulse;
+        this.pulse = options?.pulse ?? false;
+        this._finished = new State(options?.finished);
         this.style = options?.style ?? "bar.back";
         this.completeStyle = options?.completeStyle ?? "bar.complete";
         this.finishedStyle = options?.finishedStyle ?? "bar.finished";
     }
+    get total() {
+        return this._total.get();
+    }
+    set total(value) {
+        this._total.set(value);
+    }
+    get completed() {
+        return this._completed.get();
+    }
+    set completed(value) {
+        this._completed.set(value);
+    }
+    /** Whether the work is done, as given; unset, `completed` reaching `total` at the moment the bar is drawn. */
+    get finished() {
+        return this._finished.get();
+    }
+    set finished(value) {
+        this._finished.set(value);
+    }
     *render(options) {
         // Never wider than offered, as Rich's `min(self.width or max_width, max_width)`.
         // [LAW:parse-dont-validate] parsed as a cell count, so a negative width draws nothing, as Python's `"━" * -2` is "".
         const width = cellCount(Math.min(this.width || options.maxWidth, options.maxWidth));
-        if (this.pulse === undefined) {
+        if (!this.pulse) {
             yield* this.track(options, width, this.completeHalves(width), getStyle(options, this.style));
             return;
         }
@@ -56,10 +79,10 @@ export class ProgressBar {
         const style = getStyle(options, this.style);
         const ink = style.color?.isDefault === false ? style.color : ColorSpec.fromRgba((style.color ?? PULSE_BACK).getTruecolor(theme, true));
         const back = style.add(Style.fromColor(ink));
-        // [LAW:no-ambient-temporal-coupling] The moment is the caller's; the bar
+        // [LAW:no-ambient-temporal-coupling] The moment is the frame's; the bar
         // only says what it looks like then. An empty track, lit by the shimmer.
         const track = { render: (o) => this.track(o, width, 0, back) };
-        yield* render(new Effected(track, this.pulseEffect(options, back, depth, theme), { t: this.pulse.t, key: "progress-bar", theme }), options);
+        yield* render(new Effected(track, this.pulseEffect(options, back, depth, theme), { key: "progress-bar", theme }), options);
     }
     /**
      * The shimmer over this bar's back colour as `Effected` sees it drawn at
@@ -82,7 +105,7 @@ export class ProgressBar {
     *track(options, width, completeHalves, back) {
         const barCount = Math.floor(completeHalves / 2);
         const halfBarCount = completeHalves % 2;
-        const isFinished = this.completed >= this.total;
+        const isFinished = this.finished ?? this.completed >= this.total;
         const fill = getStyle(options, isFinished ? this.finishedStyle : this.completeStyle);
         const fillStyle = fill.isNull ? undefined : fill;
         const backStyle = back.isNull ? undefined : back;

package/dist/renderables/prompt.js

@@ -24,6 +24,7 @@
 import { Console } from "../core/console.js";
 import { renderMarkup } from "../core/markup.js";
 import { RichText } from "../core/text.js";
+import { pattern } from "../core/pattern.js";
 /** An answer the prompt refused, and the markup it prints before asking again — Rich's `InvalidResponse`. */
 class InvalidResponse {
     message;
@@ -104,10 +105,10 @@ function responseKind(convert, invalid, options) {
     };
 }
 /** Python's `int()` over a string: a sign, then digits, any two of which may have one `_` between them. */
-const INTEGER = /^[+-]?\d(?:_?\d)*$/;
+const INTEGER = pattern(/^[+-]?\d(?:_?\d)*$/);
 const DIGITS = String.raw `\d(?:_?\d)*`;
 /** Python's `float()` over a string: a decimal with an optional exponent, or `inf`, `infinity` or `nan`, in any case. */
-const FLOAT = new RegExp(String.raw `^[+-]?(?:(?:${DIGITS}(?:\.(?:${DIGITS})?)?|\.${DIGITS})(?:e[+-]?${DIGITS})?|inf(?:inity)?|nan)$`, "i");
+const FLOAT = pattern(new RegExp(String.raw `^[+-]?(?:(?:${DIGITS}(?:\.(?:${DIGITS})?)?|\.${DIGITS})(?:e[+-]?${DIGITS})?|inf(?:inity)?|nan)$`, "i"));
 /**
  * The integer an answer spells, as Python's `int()` reads it, or none. One a
  * `number` cannot hold exactly is none: Python's int is unbounded and a

package/dist/renderables/python-space.js

@@ -5,9 +5,10 @@
  * JavaScript's: `\s` and `trim` take U+FEFF, which Python does not, and leave
  * U+001C–U+001F and U+0085, which Python takes.
  */
+import { pattern } from "../core/pattern.js";
 /** The set as a regex character class, every member of it a single UTF-16 unit, for composing into a pattern where markdown-it-py's has `\s`. */
 export const PY_WHITESPACE = String.raw `[\t-\r\x1c-\x20\x85\xa0  - 

  　]`;
-const PY_SPACE = new RegExp(`^${PY_WHITESPACE}$`);
+const PY_SPACE = pattern(new RegExp(`^${PY_WHITESPACE}$`));
 /** Python's `str.strip`, a scan in from each end, so a run of interior whitespace costs one pass, as it does there. */
 export function pyStrip(text) {
     let start = 0;

package/dist/renderables/scroll.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Scroll — a slot of fixed size over content wider or taller than it, the
+ * content's offset in the slot moving with time: a long line panning as a
+ * marquee, a log tail scrolling, a panel sliding into its place.
+ *
+ * [LAW:one-type-per-behavior] A marquee, a scroll and a slide are one window
+ * and differ only in the motion handed in: the offset along each axis is an
+ * `Animation<number>`, so a marquee is a looping `Phase` scaled to the span
+ * it crosses and a slide-in is a `tween` to 0, and when the window next
+ * changes is `Animation.all`'s answer over the two. Nothing here knows which
+ * one it is drawing.
+ *
+ * The slot is what the window is. It measures as its width whatever the
+ * content, and draws exactly its rows of its width at every offset — cropped
+ * only to a narrower room it is given — so what sits beside it never moves.
+ * An offset before or past the content shows blank cells rather than stopping
+ * at an edge: that is what lets a marquee enter from the right and a slide-in
+ * arrive from outside the slot.
+ *
+ * The content is drawn at its own natural width and no height, its own
+ * length, because the content wider and taller than the slot is the thing
+ * being windowed. Content that should wrap to the slot instead, or that has
+ * no natural width because it fills whatever it is given, is
+ * `new Constrain(content, width)`, composed rather than asked for.
+ *
+ * [LAW:single-enforcer] A row is cut at the window's edges by
+ * `Segment.divide`, the one place a line is cut at a column: a wide glyph a
+ * cut falls in is blanked, never halved, and each cell's anchor still names
+ * its column in the content, so hit-testing finds the owner through a moving
+ * window.
+ *
+ * [LAW:no-ambient-temporal-coupling] Pure in `t`, nothing kept between
+ * frames; `at` hands over the frame alone, and placed, the scroll stamps
+ * the hold it is in at the frame's time (`placedRender`).
+ */
+import { Animation } from "../core/animation.js";
+import type { Renderable } from "../core/protocol.js";
+/** The slot a scroll draws, and how far the content is moved in it. */
+export interface ScrollOptions {
+    /** The slot's width in cells. */
+    readonly width: number;
+    /** The slot's height in rows. */
+    readonly height: number;
+    /** Columns of content left of the slot's first, rounded to the nearest cell: negative moves the content right. Absent, 0. */
+    readonly col?: Animation<number>;
+    /** Rows of content above the slot's first, rounded to the nearest row: negative moves the content down. Absent, 0. */
+    readonly row?: Animation<number>;
+}
+/** `content` seen through a slot of `width` by `height` cells, moved in it by `col` and `row` at each moment. */
+export declare function scroll(content: Renderable, options: ScrollOptions): Animation<Renderable>;