@promptctl/rich-js 0.26.0 → 0.28.0

package/dist/renderables/live.d.ts

@@ -26,7 +26,7 @@
  */
 import { type Clock } from "../core/clock.js";
 import { Console } from "../core/console.js";
-import { type FrameHost } from "../core/protocol.js";
+import { type HostFrame, type FrameHost } from "../core/protocol.js";
 import { Timeline } from "../core/timeline.js";
 import { type View } from "../core/view.js";
 export interface LiveOptions {
@@ -79,8 +79,8 @@ export declare class Live implements FrameHost {
     get clock(): Clock;
     /** The map from the clock to the time the view is drawn for. */
     get timeline(): Timeline;
-    /** The time a frame drawn now is drawn for: the clock's now, through the timeline. */
-    get frameTime(): number;
+    /** The frame this Live draws now (`FrameHost`): the clock's now, through the timeline, on a frame it is the host of. */
+    frameNow(): HostFrame;
     private _time;
     /**
      * Replace the timeline and draw the frame for the time it now maps the

package/dist/renderables/live.js

@@ -30,7 +30,7 @@ import { Segment } from "../core/segment.js";
 import { FinalFramePainter, SurfacePainter } from "../core/paint.js";
 import { fitHeight, render } from "../core/protocol.js";
 import { Timeline } from "../core/timeline.js";
-import { drawView, frameTime, hostView, undrawn } from "../core/view.js";
+import { drawView, frameNow, hostView, undrawn } from "../core/view.js";
 import { State } from "../core/state.js";
 // Nothing: what a Live made with no view draws until `update` gives it one.
 const NOTHING = { render: () => [] };
@@ -89,9 +89,9 @@ export class Live {
     get timeline() {
         return this._timeline.get();
     }
-    /** The time a frame drawn now is drawn for: the clock's now, through the timeline. */
-    get frameTime() {
-        return frameTime(this._time());
+    /** The frame this Live draws now (`FrameHost`): the clock's now, through the timeline, on a frame it is the host of. */
+    frameNow() {
+        return frameNow(this, this._time());
     }
     _time() {
         return { now: this._clock.now(), epoch: this._epoch, timeline: this._timeline.get() };

package/dist/renderables/markdown.js

@@ -8,6 +8,7 @@
  * followed: HTML, a block of it or a tag inline, is drawn as Rich draws it,
  * not at all.
  */
+import { withoutExplicit } from "../core/bidi.js";
 import { cellCount, cellLen } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
@@ -107,7 +108,8 @@ function appendInline(result, inlines, settings, options) {
     };
     const write = (text, styles) => {
         const start = result.length;
-        result.append(text);
+        // Each inline node is its own content, so what it holds open ends with it.
+        result.append(new RichText(text));
         paint(start, styles);
     };
     const enter = (styles) => {
@@ -156,7 +158,7 @@ function appendInline(result, inlines, settings, options) {
                 write("\n");
                 break;
             case "code":
-                write(inline.code, [groundedStyle(options, resolveStyle(options, settings.inlineCodeStyle))]);
+                write(withoutExplicit(inline.code), [groundedStyle(options, resolveStyle(options, settings.inlineCodeStyle))]);
                 break;
             case "html":
                 kbd(inline.content);

package/dist/renderables/panel.js

@@ -1,6 +1,7 @@
 /**
  * Panel — a bordered box that wraps content, with optional title and subtitle.
  */
+import { labelled } from "../core/orient.js";
 import { cellLen, setCellSize, asCellCol, cellCount } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
 import { NULL_STYLE } from "../core/style.js";
@@ -42,10 +43,11 @@ function borderTitle(label, options) {
  * its own laid over the border's, the one rule for "what colour is the title
  * text in". Laid over rather than in place of it, as Rich's `stylize_before`
  * does, because the border's style carries the panel's own: a title that
- * replaced it cut a hole in the panel's background on the top row.
+ * replaced it cut a hole in the panel's background on the top row. The text
+ * is set into the frame and is not of it.
  */
 function borderTextStyle(border, own) {
-    return own.isNull ? border : (border ?? NULL_STYLE).add(own);
+    return border.add(own).withBoxFrame(undefined);
 }
 /**
  * A border row: the opening corner, the rule across `span` cells with `label`
@@ -129,7 +131,7 @@ export class Panel {
         // and the content is rendered on top of it. Applied to the padding alone,
         // "white on dark_blue" drew a blue ring with a hole where the text was.
         const borderStyle = getStyle(options, this.style).add(getStyle(options, this.borderStyle));
-        const border = borderStyle.isNull ? undefined : borderStyle;
+        const border = box.frame(borderStyle);
         const geometry = layoutPanel(this._getPanelWidth(options));
         const bodyLines = this._renderBody(options, geometry.spanWidth);
         yield* this._renderTopBorder(options, box, geometry, border);
@@ -241,7 +243,7 @@ export class Panel {
         const corner = box.bottom.right.repeat(geometry.right);
         const [close, afterAccessory] = accessoryText === "" ? [corner, ""] : ["", corner];
         yield* borderRow(options, box.bottom, geometry, geometry.spanWidth - cellLen(accessoryText), this._subtitleLabel, subtitleStyle, border, close);
-        yield new Segment(accessoryText, borderTextStyle(border, accessoryOwn));
+        yield* labelled("", accessoryText, "", borderTextStyle(border, accessoryOwn), options.textOrder);
         yield new Segment(afterAccessory, border);
         yield Segment.line();
     }

package/dist/renderables/progress.d.ts

@@ -7,7 +7,7 @@ import { Console } from "../core/console.js";
 import type { Style } from "../core/style.js";
 import type { Clock } from "../core/clock.js";
 import { type ColumnOptions } from "./table.js";
-import type { FrameHost, Renderable, RenderOptions } from "../core/protocol.js";
+import type { HostFrame, FrameHost, Renderable, RenderOptions } from "../core/protocol.js";
 import { Animation } from "../core/animation.js";
 import type { Timing } from "../core/easing.js";
 export interface TaskOptions {
@@ -156,7 +156,7 @@ export declare class MofNCompleteColumn implements ProgressColumn {
 }
 /**
  * How a `Progress` is set up. It is drawn by one host, and every time it
- * keeps or draws at is that host's `frameTime`: by its own `Live`, which the
+ * keeps or draws at is that host's `frameNow()`: by its own `Live`, which the
  * options for that `Live` configure, or, given `drawnBy`, by another host —
  * which then does all the drawing, so none of them apply.
  */
@@ -185,7 +185,7 @@ interface OwnLiveOptions {
 interface DrawnByOptions {
     /**
      * The host — a `Live`, an `App` — whose frames this `Progress` is drawn in:
-     * tasks are timed by its `frameTime`, so they hold while its timeline is
+     * tasks are timed by its `frameNow()`, so they hold while its timeline is
      * paused and run back while it is reversed. Drawn in any other host's
      * frame, the `Progress` throws.
      */
@@ -207,6 +207,13 @@ export declare class Progress implements Renderable {
     constructor(...columns: (ProgressColumn | ProgressOptions)[]);
     /** The console its own `Live` prints above the bars through. */
     get console(): Console;
+    /**
+     * The frame its host draws now (`FrameHost.frameNow`): what a print of
+     * this display is drawn in — `console.print(progress, { frame:
+     * progress.frameNow() })` — so a still of it is drawn for a moment on the
+     * clock its tasks are timed on, the one the program asked at.
+     */
+    frameNow(): HostFrame;
     /** Rich's `Progress.finished`: every task finished, and so true with none. */
     get finished(): boolean;
     static getDefaultColumns(): ProgressColumn[];
@@ -224,7 +231,7 @@ export declare class Progress implements Renderable {
     refresh(): void;
     private _ownLive;
     render(options: RenderOptions): Iterable<Segment>;
-    private _framed;
+    private _ownFrame;
     private _table;
 }
 export declare function track<T>(iterable: Iterable<T>, options?: {

package/dist/renderables/progress.js

@@ -321,9 +321,20 @@ export class Progress {
     get console() {
         return this._ownLive("console").console;
     }
+    /**
+     * The frame its host draws now (`FrameHost.frameNow`): what a print of
+     * this display is drawn in — `console.print(progress, { frame:
+     * progress.frameNow() })` — so a still of it is drawn for a moment on the
+     * clock its tasks are timed on, the one the program asked at.
+     */
+    frameNow() {
+        return this._host.frameNow();
+    }
     /** Rich's `Progress.finished`: every task finished, and so true with none. */
     get finished() {
-        return this._tasks.get().every((task) => finished(taskAt(task.get(), this._host.frameTime)));
+        // [LAW:one-source-of-truth] One moment, so every task is judged at it.
+        const now = this._host.frameNow().time;
+        return this._tasks.get().every((task) => finished(taskAt(task.get(), now)));
     }
     static getDefaultColumns() {
         return [
@@ -342,7 +353,7 @@ export class Progress {
             completed: 0,
             fill: Animation.constant(0),
             visible: options?.visible !== false,
-            startTime: options?.start === false ? undefined : this._host.frameTime,
+            startTime: options?.start === false ? undefined : this._host.frameNow().time,
             finishedAt: undefined,
             samples: [],
         }));
@@ -364,7 +375,7 @@ export class Progress {
         const completed = options.completed === undefined
             ? finiteCount("completed + advance", task.completed + advance)
             : finiteCount("completed", options.completed);
-        const now = this._host.frameTime;
+        const now = this._host.frameNow().time;
         const reached = task.startTime !== undefined && task.total !== undefined && completed >= task.total;
         held.set({
             ...task,
@@ -385,7 +396,7 @@ export class Progress {
         const held = this._task(taskId);
         // Rich's `start_task`: a task already running keeps the time it started.
         if (held)
-            held.set({ ...held.get(), startTime: held.get().startTime ?? this._host.frameTime });
+            held.set({ ...held.get(), startTime: held.get().startTime ?? this._host.frameNow().time });
     }
     start() {
         this._ownLive("start").start();
@@ -410,23 +421,24 @@ export class Progress {
         return this._live;
     }
     *render(options) {
-        const framed = this._framed(options);
-        yield* render(this._table(framed.frame.time), framed);
+        yield* render(this._table(this._ownFrame(options).time), options);
     }
-    // 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) {
+    // The frame this display is drawn in, which is only ever its host's: the
+    // tasks were stamped on that host's time, and a frame of any other host is
+    // drawn for a moment on a different clock. A render reads no clock, so a
+    // print names its frame (`frameNow`, `PrintOptions.frame`): drawn for no
+    // moment — 0, as everything else is — every task would read as not yet
+    // started, so that print is refused with the call that draws it right.
+    // [LAW:parse-dont-validate] [LAW:no-silent-failure]
+    _ownFrame(options) {
         const { frame } = options;
-        if (frame !== undefined && frame.host !== this._host) {
+        if (frame === undefined) {
+            throw new Error("a Progress is drawn for a moment on its host's clock, and this print named none; print it in its frame: console.print(progress, { frame: progress.frameNow() })");
+        }
+        if (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 } };
+        return frame;
     }
     // Rich's `make_tasks_table`: each column laid out as it says, at `now` on
     // this display's clock.

package/dist/renderables/progressBar.d.ts

@@ -44,9 +44,9 @@ export declare class ProgressBar implements Renderable, Measurable {
     set finished(value: boolean | undefined);
     render(options: RenderOptions): Iterable<Segment>;
     /**
-     * The shimmer over this bar's back colour as `Effected` sees it drawn at
-     * `depth`, toward `bar.pulse`. A bar has no words to keep legible, so its
-     * back takes the whole of the light.
+     * The shimmer over this bar's back colour as `Effected` sees it drawn,
+     * toward `bar.pulse`. A bar has no words to keep legible, so its back takes
+     * the whole of the light.
      */
     private pulseEffect;
     /** Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and a total of zero is a bar already full. */

package/dist/renderables/progressBar.js

@@ -71,30 +71,33 @@ export class ProgressBar {
         }
         const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
         // Rich's pulse resolves its colours on the terminal a depth assumes, as
-        // `get_truecolor` does with no theme; so does this.
-        const theme = resolveTerminal(undefined, depth);
+        // `get_truecolor` does with no theme; so does this with none named.
+        const terminal = resolveTerminal(options.terminal, depth);
         // Rich writes the pulse's back as a colour of its own, black where the
         // back style names none, so the light always has the bar's colour to fall
         // on: one the terminal supplies takes no light.
         const style = getStyle(options, this.style);
-        const ink = style.color?.isDefault === false ? style.color : ColorSpec.fromRgba((style.color ?? PULSE_BACK).getTruecolor(theme, true));
+        const ink = style.color?.isDefault === false ? style.color : ColorSpec.fromRgba((style.color ?? PULSE_BACK).getTruecolor(terminal, true));
         const back = style.add(Style.fromColor(ink));
         // [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), { key: "progress-bar", theme }), options);
+        yield* render(new Effected(track, this.pulseEffect(options, back), { key: "progress-bar" }), options);
     }
     /**
-     * The shimmer over this bar's back colour as `Effected` sees it drawn at
-     * `depth`, toward `bar.pulse`. A bar has no words to keep legible, so its
-     * back takes the whole of the light.
+     * The shimmer over this bar's back colour as `Effected` sees it drawn,
+     * toward `bar.pulse`. A bar has no words to keep legible, so its back takes
+     * the whole of the light.
      */
-    pulseEffect(options, back, depth, theme) {
-        const ink = back.drawnColors(depth).color ?? ColorSpec.default();
-        const glow = getStyle(options, "bar.pulse").drawnColors(depth).color ?? ColorSpec.default();
-        const loop = shimmer(PULSE_CURVE, PULSE_REACH, glow.getTruecolor(theme, true), 0);
-        const whole = new Map([[ink.getTruecolor(theme, true).hex, 1]]);
-        return atShares(loop, () => whole);
+    pulseEffect(options, back) {
+        return (drawn) => {
+            const { depth, terminal } = drawn;
+            const ink = back.drawnColors(depth).color ?? ColorSpec.default();
+            const glow = getStyle(options, "bar.pulse").drawnColors(depth).color ?? ColorSpec.default();
+            const loop = shimmer(PULSE_CURVE, PULSE_REACH, glow.getTruecolor(terminal, true), 0);
+            const whole = new Map([[ink.getTruecolor(terminal, true).hex, 1]]);
+            return atShares(loop, () => whole)(drawn);
+        };
     }
     /** Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and a total of zero is a bar already full. */
     completeHalves(width) {

package/dist/renderables/syntax.js

@@ -7,7 +7,8 @@
  * other renderable here is restyled, and a second styling vocabulary on this
  * one class would be a second answer to "what colour is a keyword".
  */
-import { cellLen, expandTabs, parseTabSize } from "../core/cells.js";
+import { escaped } from "../core/bidi.js";
+import { cellLen, expandTabs, parseTabSize, unicodeEscape } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";
 import { drawable, groundedStyle, getStyle, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
@@ -89,7 +90,11 @@ export class Syntax {
         this.wordWrap = options?.wordWrap ?? false;
         const tabSize = parseTabSize(options?.tabSize ?? 4);
         this.tabSize = tabSize;
-        this._lines = expandTabs(code, tabSize).text.split("\n");
+        // Code on show: what the wire would drop is escaped, and an explicit bidi
+        // control with it. That is the Trojan Source attack: the order and the lines on
+        // screen differing from what the compiler reads. A joiner stays, since a Persian
+        // comment or an emoji string needs it. Only a CRLF's CR goes, with its line ending.
+        this._lines = expandTabs(escaped(code.replace(/\r\n/g, "\n"), unicodeEscape), tabSize).text.split("\n");
     }
     /**
      * The lines shown, as a 0-based half-open slice of `_lines`, and the number

package/dist/renderables/table.js

@@ -454,11 +454,12 @@ export class Table {
         // that is all it styles: the reference reads it as `table_style` for the
         // frame and nowhere else, so a cell is untouched by it.
         const borderStyle = getStyle(options, this.style).add(getStyle(options, this.borderStyle));
-        const border = borderStyle.isNull ? undefined : borderStyle;
         // The one division of the width every row below is measured against.
         const outerWidth = this._outerWidth(options);
         const geometry = this._geometry(options, outerWidth);
         const edge = geometry.edge === 1;
+        // Only an edge closes a frame: without one, a table's rules are not a border.
+        const border = box && edge ? box.frame(borderStyle) : borderStyle.isNull ? undefined : borderStyle;
         // Title
         if (this._title) {
             yield* this._renderTitle(options, this._title, geometry.totalWidth, this.titleStyle, this.titleJustify);

package/dist/template-bindings/animation-funcs.d.ts

@@ -20,7 +20,7 @@
  * number the time is turned into first: a frame's stamp says when it changes
  * on the host's clock, which only `Timeline.run` can carry it back onto —
  * paused, never; backwards, at the hold it is about to drop under.
- * [LAW:single-enforcer] `drawing` is the one place the time, the timeline
+ * [LAW:single-enforcer] `drawn` is the one place the time, the timeline
  * and the reader's preference for motion are read, for every function.
  *
  * `frames <seconds> <frame> <seconds> <frame> …` is a `FrameSequence`
@@ -57,31 +57,52 @@
  * exact arity of typed slots, so a slot of the wrong kind fails at the gate.
  *
  * Every function says when what it drew changes, so a host paints a
- * template while it moves and not after. `frames` and `glyphs` stamp the
- * fragment they draw (`textFrameAt`), covering its own glyphs. A number or a
- * colour carries no cells to stamp, so `tween`, `loop` and `stepped` tell
- * their hold to the frame instead (`TemplateFrame.onHold`), as a placed
- * animation of no cells does (`RenderOptions.onHold`). Nothing here claims
- * a moment it does not know.
+ * template while it moves and not after — and says it only for what the
+ * output depends on. A number or a colour has no cells to carry a hold, and
+ * a fragment's cells lose theirs the moment it is flattened (`printf "%s"`),
+ * so no function stamps cells or tells the frame itself. Each marks its
+ * return with the hold its value is in (`marked`, the engine's evaluation
+ * provenance), and the engine carries the mark beside the value into every
+ * variable, dot and function the value passes through, reporting it where
+ * the output depends on it. `emitted` is where a template's cells take a
+ * hold: every fragment the template emits, stamped with the holds of the
+ * marked values its action read. `decided` is the route for a hold no cell
+ * can carry, told to the frame (`TemplateFrame.onHold`): a mark an
+ * `if`/`with`/`range` consumed, whichever arm it took, because the frame may
+ * show cells for it later and must say when without a cell to say it on, as
+ * a placed animation of no cells does (`placed`) — and, by the same rule, a
+ * mark a writing function or a throwing action read; `EngineConfig.decided`
+ * is the authority on when it is called. A mark bound somewhere nobody reads
+ * is reported nowhere, so a value a template computes and never draws or
+ * decides on tells the frame nothing (rich-animation-27tq.0gd). Early, never
+ * late: an emission may carry a hold it did not strictly need, and a hold
+ * the output depends on is never dropped. [LAW:single-enforcer]
+ *
+ * The functions and the two hooks go into the host's engine config together,
+ * by `withAnimation`: the functions wired without the hooks would compile,
+ * draw and never say they move. [LAW:no-silent-failure]
  */
-import type { FuncMap } from "@promptctl/go-template-js";
+import { type EngineConfig } from "@promptctl/go-template-js";
 import type { RenderOptions } from "../core/protocol.js";
+import type { RichText } from "../core/text.js";
 import { Timeline } from "../core/timeline.js";
-/** What a registration is drawn on, beside the frame each evaluation is handed. */
-export interface AnimationFuncsOptions {
+/** What the animation functions are drawn on, beside the frame each evaluation is handed. */
+export interface AnimationOptions {
     /** The timeline to draw on, read once per call; the frame's own time when omitted. */
     readonly timeline?: () => Timeline;
 }
 /**
  * The frame a template is evaluated for, in the fields a render's options
- * carry under the same names: `time` in seconds, `onHold`, told when what a
- * function drew there changes, and the reader's preferences —
+ * carry under the same names: `time` in seconds, `onHold`, told the hold of
+ * an animated value the output may depend on with no cell to carry it — one
+ * a decision read, whichever arm it took, a writing function's input, a
+ * throwing action's (the engine's `decided`) — and the reader's preferences,
  * `reducedMotion`, and `asciiOnly`, which the glyphs an effect picks for
  * itself go through. They arrive with every frame and nowhere else, so a
  * template drawn in an `App` is drawn as the app's preferences say.
  * [LAW:one-source-of-truth]
  *
- * `time` is on the clock `AnimationFuncsOptions.timeline` maps from, and
+ * `time` is on the clock `AnimationOptions.timeline` maps from, and
  * `onHold` hears on that clock. A host outside rich-js hands its own clock's
  * time. Inside a rich-js frame the time is the frame's, which its host's
  * timeline has already mapped, so a template drawn there registers no
@@ -93,14 +114,24 @@ export interface TemplateFrame extends Pick<RenderOptions, "onHold" | "reducedMo
 /** The frame a renderable is drawn in, as the frame a template it evaluates there is drawn for. */
 export declare function templateFrame(options: RenderOptions): TemplateFrame;
 /**
- * Register `frames`, `stepped`, `tween`, `loop` and `glyphs`, each drawn for
- * the frame `frame` reports when the template is evaluated — its time in
- * seconds, from whatever zero the host counts from — through
- * `options.timeline`, and each telling that frame when what it drew changes.
+ * `config` with `frames`, `stepped`, `tween`, `loop` and `glyphs` registered
+ * beside its own functions, each drawn for the frame `frame` reports when
+ * the template is evaluated — its time in seconds, from whatever zero the
+ * host counts from — through `options.timeline`, and each marking its
+ * return with the hold it is in there; and with the two hooks that carry
+ * those holds to the cells (`emitted`) and the frame (`decided`) installed
+ * over any `config` already has, which still hear everything they did. One
+ * call, so the functions and the hooks that report for them cannot be wired
+ * apart: the functions alone would compile, draw, and never say they move.
+ * [LAW:types-are-the-program] [LAW:no-silent-failure] [LAW:composability]
+ * A `config` that already has one of the five names is refused, which is
+ * also what a second `withAnimation` over its own result meets: its template
+ * calls would otherwise reach these with no word said.
+ *
  * The functions exist whatever `frame` returns, so a template compiles once
  * and is evaluated at every moment the host draws. In a frame that says
  * `reducedMotion` each draws its animation reduced (`Animation.reduced`): a
  * loop at its start, a one-shot cut from where it starts to where it arrives
  * when it starts.
  */
-export declare function animationFuncs(frame: () => TemplateFrame, options?: AnimationFuncsOptions): FuncMap;
+export declare function withAnimation(config: EngineConfig<RichText>, frame: () => TemplateFrame, options?: AnimationOptions): EngineConfig<RichText>;