@promptctl/rich-js 0.27.0 → 0.29.0

package/README.md

@@ -385,18 +385,19 @@ npm run demo
 | `npm run demo-inputs` | rich-config | The widgets — checkbox, toggle, slider, dropdown, text input, button — driving a theme and palette viewer. |
 | `npm run demo:dropdown` | dropdown-demo | Three `Dropdown` widgets: a plain one, one filtered as you type, and one whose options change every few seconds. |
 | `npm run template-bindings` | rich-template-bindings | Type a template on the left and watch it render on the right. |
-| `npm run themes-and-color-studio` | themes-and-color-studio | A printed tour of colours, palettes, bundled themes, and contrast. Prints once and exits; set any of `EXPORT_HTML=out.html`, `EXPORT_SVG=out.svg` and `EXPORT_TEXT=out.txt` to also save it to each file named. |
-| `npm run strip` | rich-strip | Every built-in `Joiner`, printed side by side. Prints once and exits. |
-| `npm run effects-feel` | effects-feel | Shimmer, a gentle pulse on chosen elements, sparkle, a hue wheel, fade-in and a dissolve-out that eddies back before it goes, on a powerline strip and a run of text, at a colour depth you choose, with keys to step the frame rate, the demo's pace and the theme while it runs. A demo for agreeing how the effects feel; `npm run effects-feel -- --help` lists the flags and keys. |
+| `npm run themes-and-color-studio` | themes-and-color-studio | A printed tour of colors, palettes, bundled themes, and contrast. Prints once and exits; set any of `EXPORT_HTML=out.html`, `EXPORT_SVG=out.svg` and `EXPORT_TEXT=out.txt` to also save it to each file named. |
+| `npm run strip` | rich-strip | Every built-in `Separator`, printed side by side. Prints once and exits. |
+| `npm run effects-feel` | effects-feel | Shimmer, a gentle pulse on chosen elements, sparkle, a hue wheel, fade-in and a dissolve-out that eddies back before it goes, on a powerline strip and a run of text, at a color depth you choose, with keys to step the frame rate, the demo's pace and the theme while it runs. A demo for agreeing how the effects feel; `npm run effects-feel -- --help` lists the flags and keys. |
 | `npm run glyph-effects` | glyph-effects | Text typed, scrambled until it resolves, crossed by a wave of capitals, and rained and snowed on, each glyph effect in the catalogue and a few made by hand, for twenty seconds. |
-| `npm run attribute-effects` | attribute-effects | A line that blinks, pulses bold, and blinks its underline and its italics on beats of its own: the attribute effects in the catalogue and two made by hand from `blink`, for twenty seconds. |
-| `npm run gradient-effects` | gradient-effects | A colour ramp laid across three rules and three panel borders, one scrolling, one turning its hues, one swaying and settling a quarter turn round, while the titles and the words inside keep their own colour, for twenty seconds. |
+| `npm run attribute-effects` | attribute-effects | A line that blinks, pulses bold, and blinks its underline and its italics on steps of its own: the attribute effects in the catalogue and two made by hand from `blink`, for twenty seconds. |
+| `npm run gradient-effects` | gradient-effects | A color ramp laid across three rules and three panel borders, one scrolling, one turning its hues, one swaying and settling a quarter turn round, while the titles and the words inside keep their own color, for twenty seconds. |
 | `npm run transitions` | transitions | A build status changing state every three seconds, crossfaded in one panel and wiped in the other, each cell passing through the terminal's ground and nothing beside it moving while it changes, for twenty seconds. |
 | `npm run lifecycle` | lifecycle | A build log whose lines type themselves in as they are appended and leave four seconds later, dissolved, backspaced or scrambled away in turn, each dropped from the log once it is gone, for twenty seconds. |
 | `npm run scroll` | scroll | A marquee crossing a fixed width, a log tail stepping a row a second, and a panel sliding in from the left and holding: one window moved three ways, for twenty seconds. |
-| `npm run animation-playground` | animation-playground | Every kind of motion — tweens, moving ramps, a marching border, glyph and attribute effects, transitions, a list that comes and goes, a marquee, staggers and a blinking caret — on one timeline, with buttons to pause, reverse, scrub, change speed, reduce motion, drop to sixteen colours or none, and paint at one frame a second or sixty. |
+| `npm run animation-playground` | animation-playground | Every kind of motion — tweens, moving ramps, a marching border, glyph and attribute effects, transitions, a list that comes and goes, a marquee, staggers and a blinking caret — on one timeline, with buttons to pause, reverse, scrub, change speed, reduce motion, drop to sixteen colors or none, and paint at one frame a second or sixty. |
 | `npm run markup-plugins` | rich-markup-plugins | Custom markup tags registered through `MarkupRegistry`. Prints once and exits. |
 | `npm run viewport` | rich-viewport | A selection you move through a list taller than its window with the arrow keys, `j`/`k`, PgUp/PgDn and Home/End, kept in view by `Viewport.ensureVisible`; the mouse wheel scrolls the window, and `q` quits. |
+| `npm run terminal-colors` | terminal-colors | Your terminal asked for its own foreground and background with OSC 10 and OSC 11, shown as swatches, and whether it answered or the colors are assumed. |
 | `npm run terminal-host` | terminal-host | Each key you press printed as the bytes the terminal sends for it, and each resize as the new size — a program written against `TerminalHost` alone. `examples/terminal-host/embed.ts` runs the same program on an xterm.js terminal in your own page. |
 
 `Ctrl-C` quits any demo that stays running.

package/THIRD-PARTY-NOTICES

@@ -107,3 +107,45 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+src/core/bidi-data.ts holds data derived from the Unicode Character Database.
+
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright (c) 1991-2026 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY DOWNLOADING,
+INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR SOFTWARE, YOU
+UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE TERMS AND CONDITIONS
+OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT DOWNLOAD, INSTALL, COPY,
+DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+data files and any associated documentation (the "Data Files") or software and
+any associated documentation (the "Software") to deal in the Data Files or
+Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, and/or sell copies of the Data Files
+or Software, and to permit persons to whom the Data Files or Software are
+furnished to do so, provided that either (a) this copyright and permission
+notice appear with all copies of the Data Files or Software, or (b) this
+copyright and permission notice appear in associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD
+PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE
+LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall not be
+used in advertising or otherwise to promote the sale, use or other dealings in
+these Data Files or Software without prior written authorization of the
+copyright holder.

package/dist/core/animation.d.ts

@@ -2,23 +2,24 @@
  * Animation — a value for a time, and when it next changes: the one type
  * anything in rich-js that changes with time is an instance of.
  *
- * `at(t)` is the value at `t` seconds. `nextChange(t)` is the first moment,
+ * `at(t)` is the value at `t` seconds. `validUntil(t)` is the first moment,
  * on `t`'s own timeline, at which the value may stop being `at(t)`: never
  * before `t`. A later time says the value is held until then, `Infinity`
  * that it never changes again, and `t` itself that it is moving at `t` — it
  * changes every frame, however close together they are drawn. An early
  * answer costs a host a frame that draws what the last one did; a late one
  * skips a change. So an animation that cannot say answers `t`, as
- * `continuous` does. A value drawn as cells carries this answer on every
+ * `continuous` does. An answer that depends on what the frame drew, an
+ * effect's, is told by that drawing (`Reads`). A value drawn as cells carries this answer on every
  * cell (`Style.hold`, both ends of the hold below), so a host holding
- * the composed frame reads it there (`Segment.nextChange`); a value that is
- * not drawn — a number, a colour — has `nextChange` as its only way to say
+ * the composed frame reads it there (`Segment.validUntil`); a value that is
+ * not drawn — a number, a color — has `validUntil` as its only way to say
  * when to look again.
  *
- * `lastChange(t)` is the other end of the same hold: the last moment, never
+ * `validFrom(t)` is the other end of the same hold: the last moment, never
  * after `t`, at which the value may have become `at(t)` — `-Infinity` if it
- * always was, `t` while it moves. Together they bound the hold, `[lastChange(t),
- * nextChange(t))`, and the answer may be narrower than the truth and never
+ * always was, `t` while it moves. Together they bound the hold, `[validFrom(t),
+ * validUntil(t))`, and the answer may be narrower than the truth and never
  * wider. It is what a host running the animation backwards reads
  * (`./timeline.ts`): run down the timeline, the value next changes where it
  * began. An animation that cannot say answers `t` here too.
@@ -37,10 +38,10 @@
  * which content shows is a fact about time that motion is not: a value with
  * no time could only show a scheduled exit as already gone.
  *
- * The instances already in the tree: a `Beat` is an animation of which hold
+ * The instances already in the tree: a `StepSequence` is an animation of which hold
  * is in progress (`./easing.ts`), a `FrameSequence` of the frame shown and a
  * `Spinner` of the spinner drawn (`../renderables/`), and an `Effect` is, for
- * what an element draws in a frame, an animation of how its cells' colours
+ * what an element draws in a frame, an animation of how its cells' colors
  * move (`../renderables/effect.ts`). Every kind of motion is one more.
  *
  * An animation of renderables is a renderable — its face, `placedRender`:
@@ -66,24 +67,41 @@
  * of motion is built from — a constant, a value moving every moment, a map
  * over the value, several at once, one animation after another, and one
  * played again every period — and each says how
- * `nextChange` composes, so an animation built from them answers it without
+ * `validUntil` composes, so an animation built from them answers it without
  * its author doing anything.
  *
  * Tier 5 of `src/core/`: `./easing.ts`, `./measure.ts`, `./protocol.ts`,
  * `./segment.ts` and `./style.ts`, nothing else. [LAW:one-way-deps]
  */
-import { type Beat } from "./easing.js";
+import { type StepSequence } from "./easing.js";
 import { type Measurable, type Motion, type Renderable, type RenderOptions } from "./protocol.js";
 import { Segment } from "./segment.js";
-import { Style, type Hold } from "./style.js";
+import { Style, type ValidityInterval } from "./style.js";
+/**
+ * What a frame's drawing said of the hold the element named `key`, drawn at
+ * `t`, is in, or nothing if the frame heard of no such drawing: handed to an
+ * animation asked about a frame already drawn, so an answer only a drawing
+ * knows goes up through the combinators that remapped the time. It reads by
+ * `key` and not by the effect, which `reduced()` and a `repeat`'s `nth` build
+ * anew at each asking, and by `t`, since one element may be drawn at two
+ * moments. Parts sharing both share the intersection of what was drawn:
+ * narrower and never wider. A drawing a container hid, by not handing on its
+ * options, reads as none and stays early, unless a part sharing its key and
+ * `t` told. A measurement, which draws nothing, answers held for good for
+ * every part (`UNLAID`). An animation that does not read it ignores it, and
+ * one that forwards it to no part stays early. [LAW:one-source-of-truth] The
+ * frame's one drawing says it, so the answer cannot disagree with what the
+ * frame shows.
+ */
+export type Reads = (t: number, key: string) => ValidityInterval | undefined;
 /** A value of `T` at a time in seconds, and the hold it is in: what every animation answers, whatever its values. */
-export interface Timed<T> {
+export interface Behavior<T> {
     /** The value at `t` seconds. */
     at(t: number): T;
     /** The first moment, never before `t`, at which the value may stop being `at(t)`: `t` while it moves, `Infinity` once it never will. */
-    nextChange(t: number): number;
+    validUntil(t: number, moves?: Reads): number;
     /** The last moment, never after `t`, at which the value may have become `at(t)`: `t` while it moves, `-Infinity` if it always was. */
-    lastChange(t: number): number;
+    validFrom(t: number, moves?: Reads): number;
     /** This animation with its motion taken out — a loop at its first value, a one-shot cut to its end — drawn in its place under reduced motion. */
     reduced(): Animation<T>;
 }
@@ -95,14 +113,12 @@ export interface Timed<T> {
  * number is no renderable and a `Panel` refuses it; a tween mapped to a
  * `RichText` is one, and a `Panel` holds it.
  */
-export type Animation<T> = Timed<T> & ([T] extends [Renderable] ? Renderable & Measurable : unknown);
+export type Animation<T> = Behavior<T> & ([T] extends [Renderable] ? Renderable & Measurable : unknown);
 /** What a frame drawn at a time shows of an animation, and what that says. */
 export interface Shown<T> {
     readonly value: T;
-    /** The first moment, never before the time drawn at, the value may stop being this. */
-    readonly nextChange: number;
     /** The animation the value is drawn from: the one handed in, or under reduced motion its reduced form. */
-    readonly drawn: Timed<T>;
+    readonly drawn: Behavior<T>;
     /** Whether it is the animation reduced: drawn under reduced motion, changing only where content does. */
     readonly reduced: boolean;
 }
@@ -114,19 +130,19 @@ export interface Shown<T> {
  * the template functions choose here, so a host told once
  * reduces every one.
  */
-export declare function shownAt<T>(animation: Timed<T>, t: number, motion: Motion): Shown<T>;
-/** The hold `shown`, drawn at `t`, is in: its animation's two answers there. */
-export declare function holdOf(shown: Shown<unknown>, t: number): Hold;
+export declare function shownAt<T>(animation: Behavior<T>, t: number, motion: Motion): Shown<T>;
+/** The hold `shown`, drawn at `t`, is in: its animation's two answers there, given what its drawing said. */
+export declare function validityOf(shown: Shown<unknown>, t: number, moves?: Reads): ValidityInterval;
 /** The style saying a cell is in `hold`. */
-export declare function stamp(hold: Hold): Style;
+export declare function stampValidity(validity: ValidityInterval): Style;
 /**
  * `segments`, every one carrying `hold` under whatever it already said: the
- * later `lastChange` and the sooner `nextChange` win (`Style.add`), so a
+ * later `validFrom` and the sooner `validUntil` win (`Style.add`), so a
  * frame's hold is the intersection of its cells', narrower than the truth
  * and never wider. [LAW:single-enforcer] The one way a time is put on drawn
  * cells, by whatever draws for a time it knows.
  */
-export declare function stampFrame(segments: Iterable<Segment>, hold: Hold): Iterable<Segment>;
+export declare function stampValidityFrame(segments: Iterable<Segment>, validity: ValidityInterval): Iterable<Segment>;
 /**
  * The moment a frame drawn under `options` is drawn for: the frame's time,
  * which the host writes once a frame (`RenderOptions.frame`), or with no
@@ -138,35 +154,38 @@ export declare function stampFrame(segments: Iterable<Segment>, hold: Hold): Ite
 export declare function frameTimeOf(options: RenderOptions): number;
 /**
  * An animation placed in the frame `options` draws: its value at the frame's
- * time (`frameTimeOf`, `shownAt`), drawn by `draw`, every segment stamped
- * with its hold there under whatever its own cells say, and the hold told to
- * the frame (`RenderOptions.onHold`), because a frame of no cells — an
- * element not yet entered — may have cells later, and must say when without
- * taking a row to say it in. [LAW:single-enforcer] The one placement: an
- * animation of renderables (`placedRender`) and a widget drawing one cell
- * from an animation of its own (a caret's blink) place through it, so how a
- * time reaches an animation and how its hold reaches the frame is written
- * once.
+ * time (`frameTimeOf`, `shownAt`), drawn whole by `draw` under the options it
+ * is handed, every segment then stamped with its hold there under whatever
+ * its own cells say, and the hold told to the frame (`RenderOptions.onValidity`),
+ * because a frame of no cells — an element not yet entered — may have cells
+ * later, and must say when without taking a row to say it in. Drawn first,
+ * because the hold is asked with what the drawing said (`Reads`); each report
+ * goes on outward too, since a value drawn inside a placement in this value
+ * may be a part of an animation placed further out. [LAW:single-enforcer]
+ * The one placement: an animation of renderables (`placedRender`), an effect
+ * and a widget drawing one cell from an animation of its own (a caret's
+ * blink) place through it, so how a time reaches an animation and how its
+ * hold reaches the frame is written once.
  */
-export declare function placed<T>(animation: Timed<T>, options: RenderOptions, draw: (value: T) => Iterable<Segment>): Iterable<Segment>;
+export declare function placed<T>(animation: Behavior<T>, options: RenderOptions, draw: (value: T, options: RenderOptions) => Iterable<Segment>): Iterable<Segment>;
 /**
  * An animation's face, `render`: `placed`, its value drawn as the renderable
  * it is. A container — the library's or a user's — that draws its children
  * through `render` draws an animation among them with no word about time:
  * the hold goes back the way the time came in. [LAW:composability]
  */
-export declare function placedRender(animation: Timed<unknown>, options: RenderOptions): Iterable<Segment>;
+export declare function placedRender(animation: Behavior<unknown>, options: RenderOptions): Iterable<Segment>;
 /**
  * An animation's face, `measure`: what it shows at the frame's time, measured,
- * and its hold there told (`RenderOptions.onHold`), because a container lays
+ * and its hold there told (`RenderOptions.onValidity`), because a container lays
  * out from the measurement and must lay out again when it changes.
  */
-export declare function placedMeasure(animation: Timed<unknown>, options: RenderOptions): {
+export declare function placedMeasure(animation: Behavior<unknown>, options: RenderOptions): {
     minimum: number;
     maximum: number;
 };
 /** What `Animation.of` makes of `X`: `X`, with the face its values call for. */
-export type Faced<X extends Timed<unknown>> = X & Animation<X extends Timed<infer T> ? T : never>;
+export type Faced<X extends Behavior<unknown>> = X & Animation<X extends Behavior<infer T> ? T : never>;
 export declare const Animation: {
     /**
      * `timed` as an animation: every member it carries kept (`membersOf`),
@@ -177,7 +196,7 @@ export declare const Animation: {
      * animation made here has the face, and one whose values are not
      * renderables throws when it is drawn.
      */
-    of<X extends Timed<unknown>>(timed: X): Faced<NoInfer<X>>;
+    of<X extends Behavior<unknown>>(timed: X): Faced<NoInfer<X>>;
     /**
      * Whether `animation` never changes again from `t`: a one-shot that has
      * run, a loop at a depth that shows no motion. [LAW:single-enforcer] The
@@ -186,7 +205,7 @@ export declare const Animation: {
      * once. An early answer the contract allows is a finite one, so `Infinity`
      * is only ever a true never.
      */
-    done(animation: Timed<unknown>, t: number): boolean;
+    done(animation: Behavior<unknown>, t: number): boolean;
     /** `value` at every time, never changing. */
     constant<T>(value: T): Animation<T>;
     /**
@@ -214,14 +233,14 @@ export declare const Animation: {
      * `animation`'s value through `f`, changing when it does. Two values `f`
      * maps alike make an early answer, which the contract allows.
      */
-    map<T, U>(animation: Timed<T>, f: (value: T) => U): Animation<U>;
+    map<T, U>(animation: Behavior<T>, f: (value: T) => U): Animation<U>;
     /**
      * Every one of `animations` at once, their values in order, changing when
      * the soonest of them does — so a stack of effects drawn together holds
      * still exactly while each of them does, and reduced each reduced — a
      * stagger with every child arrived. None never changes.
      */
-    all<const T extends readonly unknown[]>(animations: { readonly [K in keyof T]: Timed<T[K]>; }): Animation<T>;
+    all<const T extends readonly unknown[]>(animations: { readonly [K in keyof T]: Behavior<T[K]>; }): Animation<T>;
     /**
      * `animation` sampled once a hold of `beat`: within a hold, its value at
      * the hold's start, and at each hold's start it moves on. It changes at the
@@ -234,7 +253,7 @@ export declare const Animation: {
      * [LAW:one-source-of-truth] The one stepping rule, for an effect's frames
      * and a transition's schedule alike.
      */
-    onBeat<T>(animation: Timed<T>, beat: Beat): Animation<T>;
+    sampleAndHold<T>(animation: Behavior<T>, stepSequence: StepSequence): Animation<T>;
     /**
      * `first` until `seconds`, then `then`, handed the time since it began —
      * each part on its own clock from 0, as every effect is. Before the switch
@@ -244,7 +263,7 @@ export declare const Animation: {
      * shows on time; a one-shot that is the motion into what follows says its
      * own end (`transition`, `../renderables/effects.ts`).
      */
-    sequence<T>(first: Timed<T>, seconds: number, then: Timed<T>): Animation<T>;
+    sequence<T>(first: Behavior<T>, seconds: number, then: Behavior<T>): Animation<T>;
     /**
      * `nth(n)` for every time in the `n`th turn, `[n·period, (n+1)·period)`,
      * handed the time since that turn began — a one-shot played again every
@@ -257,5 +276,5 @@ export declare const Animation: {
      * something new still shows it on time and a one-shot inside cuts to its
      * end there. Nothing is walked through: a call reads only its turn.
      */
-    repeat<T>(period: number, nth: (n: number) => Timed<T>): Animation<T>;
+    repeat<T>(period: number, nth: (n: number) => Behavior<T>): Animation<T>;
 };