@promptctl/rich-js 0.24.0 → 0.24.1

package/dist/renderables/embed.js

@@ -23,6 +23,7 @@
  */
 import { cellCount, cellLen, setCellSize } from "../core/cells.js";
 import { activeHighlighter, readStr } from "../core/markup.js";
+import { render } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";
 /**
@@ -71,7 +72,7 @@ export class EmbeddedText {
         return text;
     }
     render(options) {
-        return this.text(options).render(options);
+        return render(this.text(options), options);
     }
     /**
      * Measured unhighlighted, as Rich's `Measurement.get` reads a string with
@@ -163,7 +164,7 @@ export function present(content) {
  */
 export function drawLabel(text, options, base) {
     text.overflow = "ignore";
-    return [...Segment.applyStyle(text.render(options), base)];
+    return [...Segment.applyStyle(render(text, options), base)];
 }
 /**
  * Caller content as a label, or no label at all: content that is not

package/dist/renderables/flexStrip.d.ts

@@ -16,7 +16,7 @@
  * FlexStrip reuses it verbatim. There is no second concept of "join."
  */
 import { Segment } from "../core/segment.js";
-import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Composite, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 import { type Joiner, type StyledRenderable } from "../core/strip.js";
 export type FlexAlign = "left" | "center" | "right" | "justify";
 export interface FlexStripOptions<T extends StyledRenderable> {
@@ -27,12 +27,13 @@ export interface FlexStripOptions<T extends StyledRenderable> {
     /** Line alignment when packed items don't fill the available width (default "left"). */
     align?: FlexAlign;
 }
-export declare class FlexStrip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable {
+export declare class FlexStrip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable, Composite {
     readonly items: readonly T[];
     readonly joiner: Joiner<T> | undefined;
     readonly gap: number;
     readonly align: FlexAlign;
     constructor(items: readonly T[], options?: FlexStripOptions<T>);
+    contents(): Iterable<Renderable>;
     render(options: RenderOptions): Iterable<Segment>;
     measure(options: RenderOptions): {
         minimum: number;

package/dist/renderables/flexStrip.js

@@ -16,9 +16,10 @@
  * FlexStrip reuses it verbatim. There is no second concept of "join."
  */
 import { Segment } from "../core/segment.js";
+import { render } from "../core/protocol.js";
 import { drawItem, drawJoin } from "../core/strip.js";
 function renderToBlock(r, options) {
-    const segments = [...r.render(options)];
+    const segments = [...render(r, options)];
     let width = 0;
     for (const s of segments)
         width += s.cellLength;
@@ -55,6 +56,10 @@ export class FlexStrip {
         this.gap = options?.gap ?? 0;
         this.align = options?.align ?? "left";
     }
+    // The items; a join is drawn from what the joiner emits for it, not held.
+    contents() {
+        return this.items;
+    }
     *render(options) {
         const items = this.items;
         if (items.length === 0)

package/dist/renderables/frames.d.ts

@@ -21,18 +21,23 @@
  *
  * The sequence and the moment are two values, because only one of them
  * changes from frame to frame. A `FrameSequence` is the frames prepared once
- * — the beat, the one width, each frame set into a line and padded — and a
- * `Frames` is that sequence at a `t`, whose work is one frame's — finding
- * which, and copying it: a host holds the sequence and asks it for a frame,
- * as `Spinner` holds its two, so a draw costs the same over ninety frames as
- * over one. The sequence is a value the host keeps, not a memo here: nothing
- * is looked up by key.
+ * — the beat, the one width, each frame set into a line and padded — and an
+ * `Animation` of the frame shown (`core/animation.ts`); a `Frames` is that
+ * sequence at a `t`, whose work is one frame's — finding which, and copying
+ * it: a host holds the sequence and asks it for a frame, as `Spinner` holds
+ * its two, so a draw costs the same over ninety frames as over one. The
+ * sequence is a value the host keeps, not a memo here: nothing is looked up
+ * by key.
  *
  * The frame drawn is drawn until the next begins, and its cells say so: they
- * are stamped with that moment (`Style.nextChange`), which rides up through
- * every container to whoever holds the composed frame (`Segment.nextChange`),
- * so a host drawing at `t` knows when to draw again, and one drawing slower
- * than the frames turn can see that it is skipping them.
+ * are stamped with the sequence's `nextChange` (`Style.nextChange`), which
+ * rides up through every container to whoever holds the composed frame
+ * (`Segment.nextChange`), so a host drawing at `t` knows when to draw again,
+ * and one drawing slower than the frames turn can see that it is skipping
+ * them. The stamp is put on by whoever draws the frame at a host time
+ * (`frameAt`) — a `Frames`, a `Spinner`, the template `frames` function —
+ * and the sequence's `at` hands over the frame alone, because the time a
+ * sequence is asked for may be one a `Timeline` mapped from the host's.
  *
  * Every frame is drawn at one width, the widest frame's, each padded on the
  * right to it, so whatever sits beside the frames never moves as they turn;
@@ -43,6 +48,7 @@
  * binding has no console for, so the frame arrives read, as a `Group`'s
  * children do.
  */
+import type { Animation } from "../core/animation.js";
 import { type Beat } from "../core/easing.js";
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import type { Segment } from "../core/segment.js";
@@ -53,7 +59,7 @@ export interface Frame {
     readonly seconds: number;
 }
 /** A sequence of frames prepared to be drawn: built once, asked for the frame at a time. */
-export declare class FrameSequence {
+export declare class FrameSequence implements Animation<RichText> {
     /** Which frame is in progress when: the holds are the frames' seconds, in order. */
     readonly beat: Beat;
     /** The width every frame draws at: the widest frame's, in cells. */
@@ -62,16 +68,31 @@ export declare class FrameSequence {
     constructor(frames: readonly Frame[]);
     /**
      * The frame in progress at `t`, at `width` cells, ending no line: a copy,
-     * the caller's to change, its every cell — padding included — stamped with
-     * when it gives way to the next, `beat.end(t)`, so a blank frame among
-     * drawn ones still turns. [LAW:one-source-of-truth] The stamp is the one
-     * answer to when the frame changes, read off the cells
-     * (`Segment.nextChange`): a sequence of nothing has no cell to carry one,
-     * and a field saying a time would disagree with cells saying never.
-     * `beat.at` refuses a `t` that is not finite.
+     * the caller's to change, carrying no word on when it changes — that is
+     * `frameAt`'s, stamped by whoever draws it at a host time. `beat.at`
+     * refuses a `t` that is not finite.
      */
-    text(t: number): RichText;
+    at(t: number): RichText;
+    /** When the frame in progress at `t` gives way to the next: the beat's answer, its holds being the frames'. */
+    nextChange(t: number): number;
+    /** When the frame in progress at `t` began: the beat's answer. */
+    lastChange(t: number): number;
 }
+/**
+ * The frame `animation` shows at host time `t`, its every cell — padding
+ * included, so a blank frame among drawn ones still turns — stamped with when
+ * it gives way to the next, `animation.nextChange(t)`. [LAW:one-source-of-truth]
+ * The stamp is that one answer carried on the cells (`Segment.nextChange`),
+ * so a container holding the frame passes it up without asking the
+ * animation; and it is put on here, where the host's time is known, and not
+ * in the animation's `at`, whose own time a `Timeline` or an
+ * `Animation.sequence` may have mapped from the host's — a stamp made there
+ * would be a moment on a clock the host cannot read. A copy is stamped, the
+ * caller's to change: an animation may hand back the one `RichText` it
+ * holds, as `Animation.constant` does, and a stamp on that would outlive
+ * the draw it was true for.
+ */
+export declare function frameAt(animation: Animation<RichText>, t: number): RichText;
 export interface FramesOptions {
     /** The moment to draw, in seconds. */
     readonly t: number;

package/dist/renderables/frames.js

@@ -21,18 +21,23 @@
  *
  * The sequence and the moment are two values, because only one of them
  * changes from frame to frame. A `FrameSequence` is the frames prepared once
- * — the beat, the one width, each frame set into a line and padded — and a
- * `Frames` is that sequence at a `t`, whose work is one frame's — finding
- * which, and copying it: a host holds the sequence and asks it for a frame,
- * as `Spinner` holds its two, so a draw costs the same over ninety frames as
- * over one. The sequence is a value the host keeps, not a memo here: nothing
- * is looked up by key.
+ * — the beat, the one width, each frame set into a line and padded — and an
+ * `Animation` of the frame shown (`core/animation.ts`); a `Frames` is that
+ * sequence at a `t`, whose work is one frame's — finding which, and copying
+ * it: a host holds the sequence and asks it for a frame, as `Spinner` holds
+ * its two, so a draw costs the same over ninety frames as over one. The
+ * sequence is a value the host keeps, not a memo here: nothing is looked up
+ * by key.
  *
  * The frame drawn is drawn until the next begins, and its cells say so: they
- * are stamped with that moment (`Style.nextChange`), which rides up through
- * every container to whoever holds the composed frame (`Segment.nextChange`),
- * so a host drawing at `t` knows when to draw again, and one drawing slower
- * than the frames turn can see that it is skipping them.
+ * are stamped with the sequence's `nextChange` (`Style.nextChange`), which
+ * rides up through every container to whoever holds the composed frame
+ * (`Segment.nextChange`), so a host drawing at `t` knows when to draw again,
+ * and one drawing slower than the frames turn can see that it is skipping
+ * them. The stamp is put on by whoever draws the frame at a host time
+ * (`frameAt`) — a `Frames`, a `Spinner`, the template `frames` function —
+ * and the sequence's `at` hands over the frame alone, because the time a
+ * sequence is asked for may be one a `Timeline` mapped from the host's.
  *
  * Every frame is drawn at one width, the widest frame's, each padded on the
  * right to it, so whatever sits beside the frames never moves as they turn;
@@ -44,6 +49,7 @@
  * children do.
  */
 import { beat } from "../core/easing.js";
+import { render } from "../core/protocol.js";
 import { Style } from "../core/style.js";
 import { setIntoLine } from "./embed.js";
 /** A sequence of frames prepared to be drawn: built once, asked for the frame at a time. */
@@ -69,17 +75,38 @@ export class FrameSequence {
     }
     /**
      * The frame in progress at `t`, at `width` cells, ending no line: a copy,
-     * the caller's to change, its every cell — padding included — stamped with
-     * when it gives way to the next, `beat.end(t)`, so a blank frame among
-     * drawn ones still turns. [LAW:one-source-of-truth] The stamp is the one
-     * answer to when the frame changes, read off the cells
-     * (`Segment.nextChange`): a sequence of nothing has no cell to carry one,
-     * and a field saying a time would disagree with cells saying never.
-     * `beat.at` refuses a `t` that is not finite.
+     * the caller's to change, carrying no word on when it changes — that is
+     * `frameAt`'s, stamped by whoever draws it at a host time. `beat.at`
+     * refuses a `t` that is not finite.
      */
-    text(t) {
-        return this._shown[this.beat.at(t)].copy().stylize(new Style({ nextChange: this.beat.end(t) }));
+    at(t) {
+        return this._shown[this.beat.at(t)].copy();
     }
+    /** When the frame in progress at `t` gives way to the next: the beat's answer, its holds being the frames'. */
+    nextChange(t) {
+        return this.beat.nextChange(t);
+    }
+    /** When the frame in progress at `t` began: the beat's answer. */
+    lastChange(t) {
+        return this.beat.lastChange(t);
+    }
+}
+/**
+ * The frame `animation` shows at host time `t`, its every cell — padding
+ * included, so a blank frame among drawn ones still turns — stamped with when
+ * it gives way to the next, `animation.nextChange(t)`. [LAW:one-source-of-truth]
+ * The stamp is that one answer carried on the cells (`Segment.nextChange`),
+ * so a container holding the frame passes it up without asking the
+ * animation; and it is put on here, where the host's time is known, and not
+ * in the animation's `at`, whose own time a `Timeline` or an
+ * `Animation.sequence` may have mapped from the host's — a stamp made there
+ * would be a moment on a clock the host cannot read. A copy is stamped, the
+ * caller's to change: an animation may hand back the one `RichText` it
+ * holds, as `Animation.constant` does, and a stamp on that would outlive
+ * the draw it was true for.
+ */
+export function frameAt(animation, t) {
+    return animation.at(t).copy().stylize(new Style({ nextChange: animation.nextChange(t) }));
 }
 /** A sequence's frame in progress at one moment, as a renderable. */
 export class Frames {
@@ -90,10 +117,10 @@ export class Frames {
     constructor(sequence, options) {
         this.sequence = sequence;
         this.t = options.t;
-        this._shown = sequence.text(options.t);
+        this._shown = frameAt(sequence, options.t);
     }
     render(options) {
-        return this._shown.render(options);
+        return render(this._shown, options);
     }
     /**
      * One width both ways: a frame is one picture, never wrapped apart at a

package/dist/renderables/group.d.ts

@@ -4,11 +4,12 @@
  */
 import type { Segment } from "../core/segment.js";
 import { type Measurement } from "../core/measure.js";
-import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
-export declare class Group implements Renderable, Measurable {
+import type { Composite, Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+export declare class Group implements Renderable, Measurable, Composite {
     readonly renderables: Renderable[];
     constructor(...renderables: Renderable[]);
     render(options: RenderOptions): Iterable<Segment>;
     /** As wide as its widest member: the reference's `measure_renderables`. */
     measure(options: RenderOptions): Measurement;
+    contents(): Iterable<Renderable>;
 }

package/dist/renderables/group.js

@@ -3,7 +3,7 @@
  * No visual chrome — purely a container.
  */
 import { measureRenderables } from "../core/measure.js";
-import { stackedHeight } from "../core/protocol.js";
+import { render, stackedHeight } from "../core/protocol.js";
 export class Group {
     renderables;
     constructor(...renderables) {
@@ -12,11 +12,14 @@ export class Group {
     *render(options) {
         const memberOptions = { ...options, height: stackedHeight(options.height) };
         for (const renderable of this.renderables) {
-            yield* renderable.render(memberOptions);
+            yield* render(renderable, memberOptions);
         }
     }
     /** As wide as its widest member: the reference's `measure_renderables`. */
     measure(options) {
         return measureRenderables(options, this.renderables);
     }
+    contents() {
+        return this.renderables;
+    }
 }

package/dist/renderables/html-entities.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTML's named character references, each name without its `;`, to the
+ * characters it stands for — the table markdown-it-py, Rich's parser, decodes
+ * with. Generated by scripts/html-entities.py from Python's
+ * `html.entities.html5`; regenerate rather than edit.
+ */
+/** The characters `name`, a reference's name without its `&` and `;`, stands for, if it names any. */
+export declare function namedReference(name: string): string | undefined;