@promptctl/rich-js 0.20.0 → 0.21.0

package/dist/host/input.js

@@ -16,8 +16,9 @@
  *
  * Lone-ESC handling: a bare `\x1b` is ambiguous (escape key vs. start of a
  * CSI sequence). When the buffer is drained but ends with a lone ESC, the
- * parser defers emission via setTimeout(0). The next chunk cancels the timer
- * if it extends the sequence. `flush()` drains it synchronously.
+ * parser defers emission via setTimeout(0). A next chunk opening with `[` or
+ * `O` extends the sequence; any other next chunk emits the ESC as Escape
+ * first. `flush()` drains it synchronously.
  */
 /**
  * The one name a key goes by — what a keymap is keyed by and what
@@ -164,12 +165,26 @@ export class InputParser {
     /** Feed a chunk of bytes (or a string of them) into the parser. */
     feed(chunk) {
         const next = typeof chunk === "string" ? UTF8_ENCODER.encode(chunk) : chunk;
-        this.buffer = concatBytes(this.buffer, next);
+        // A held lone ESC waits only for the rest of a split CSI/SS3 introducer.
+        // Any other next chunk means Escape was its own key, even when the hold
+        // timer has not run yet: a busy worker can queue the next key ahead of it,
+        // and joining them would read Escape then G as Alt+G (rich-host-input-0c4f).
+        const escaped = this.holdingEscape() && next.length > 0 && next[0] !== LBRACKET && next[0] !== O_BYTE;
         this.cancelEscape();
-        this.drain();
+        // The buffer is settled before the sink hears Escape, so a sink that
+        // resets the parser on it (an app stopping) leaves nothing to drain.
+        this.buffer = concatBytes(escaped ? EMPTY_BYTES : this.buffer, next);
+        try {
+            if (escaped)
+                this.sink.key(ESCAPE);
+        }
+        finally {
+            this.drain();
+        }
         // [LAW:dataflow-not-control-flow] If a lone ESC remains, defer emission
-        // until the next macrotask so a follow-up chunk can extend it.
-        if (this.buffer.length === 1 && this.buffer[0] === ESC) {
+        // until the next macrotask so a follow-up chunk can extend it. Only a lone
+        // one: a sequence split after `ESC [` waits for its rest, however late.
+        if (this.holdingEscape()) {
             this.escTimer = setTimeout(() => {
                 this.escTimer = undefined;
                 this.flush();
@@ -179,9 +194,9 @@ export class InputParser {
     /** Force any pending lone ESC out of the buffer. */
     flush() {
         this.cancelEscape();
-        if (this.buffer.length === 1 && this.buffer[0] === ESC) {
+        if (this.holdingEscape()) {
             this.buffer = EMPTY_BYTES;
-            this.sink.key(({ key: "escape", character: "", shift: false, ctrl: false, meta: false }));
+            this.sink.key(ESCAPE);
         }
     }
     /** Drop what is buffered and any pending lone ESC: the parser as constructed. */
@@ -189,6 +204,10 @@ export class InputParser {
         this.cancelEscape();
         this.buffer = EMPTY_BYTES;
     }
+    /** The parser's one hold: a lone ESC that may yet open a sequence. */
+    holdingEscape() {
+        return this.buffer.length === 1 && this.buffer[0] === ESC;
+    }
     cancelEscape() {
         clearTimeout(this.escTimer);
         this.escTimer = undefined;
@@ -294,7 +313,7 @@ export class InputParser {
             return {
                 kind: "key",
                 bytes: 2,
-                event: ({ key: "escape", character: "", shift: false, ctrl: false, meta: false }),
+                event: ESCAPE,
             };
         }
         // ESC <named> / ESC <printable> → Alt-modified key.
@@ -347,7 +366,7 @@ export class InputParser {
         return {
             kind: "key",
             bytes: 1,
-            event: ({ key: "escape", character: "", shift: false, ctrl: false, meta: false }),
+            event: ESCAPE,
         };
     }
     consumeSS3(buf) {

package/dist/index.d.ts

@@ -33,8 +33,8 @@ export type { Unsubscribe } from "./core/subscription.js";
 export { Measurement, measureRenderables } from "./core/measure.js";
 export { Span, RichText } from "./core/text.js";
 export type { RichTextOptions } from "./core/text.js";
-export { Strip, CellJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER, CAPSULE_JOINER, PLAIN_JOINER, gradientJoiner, } from "./core/strip.js";
-export type { StyledRenderable, Joiner, JoinShape, JoinCell, CellColor, Paint } from "./core/strip.js";
+export { Strip, CellJoiner, SEAM_MIN_DELTA_E, JOINERS, joinerNamed, gradientJoiner, } from "./core/strip.js";
+export type { StyledRenderable, Joiner, JoinContext, JoinShape, JoinCell, CellColor, Paint } from "./core/strip.js";
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 export type { RenderToStringOptions } from "./core/render.js";
 export { OSC8, osc8Sequences } from "./core/osc8.js";
@@ -55,10 +55,10 @@ export { Console } from "./core/console.js";
 export type { ConsoleOptions, ConsoleSink, ConsoleStream, ConsoleEnvironment, LiveRegion, PrintOptions, } from "./core/console.js";
 export type { Env } from "./core/env.js";
 export { Constrain } from "./renderables/constrain.js";
-export { Effected } from "./renderables/effect.js";
-export type { CellColors, Effect, EffectCell, EffectedOptions } from "./renderables/effect.js";
-export { EFFECT_CURVES, EFFECT_LIGHTS, SHIMMER_WIDTH, dissolveOut, fadeIn, onColors, pulse, shares, shimmer, sparkle, wheel, } from "./renderables/effects.js";
-export type { Curve, Field, Loop, Pair, Touch, Transition } from "./renderables/effects.js";
+export { Effected, confined, drawnOf } from "./renderables/effect.js";
+export type { CellColors, Drawn, Effect, EffectCell, EffectedOptions, Pair } from "./renderables/effect.js";
+export { EFFECT_CURVES, EFFECT_LIGHTS, SHIMMER_WIDTH, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.js";
+export type { Curve, Field, Loop, Touch, Transition } from "./renderables/effects.js";
 export { Align } from "./renderables/align.js";
 export type { Alignment } from "./core/place.js";
 export { Padding } from "./renderables/padding.js";

package/dist/index.js

@@ -44,7 +44,7 @@ export { Measurement, measureRenderables } from "./core/measure.js";
 // Text
 export { Span, RichText } from "./core/text.js";
 // Strip + Joiner
-export { Strip, CellJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER, CAPSULE_JOINER, PLAIN_JOINER, gradientJoiner, } from "./core/strip.js";
+export { Strip, CellJoiner, SEAM_MIN_DELTA_E, JOINERS, joinerNamed, gradientJoiner, } from "./core/strip.js";
 // renderToString — stateless one-shot emission
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 // OSC 8 hyperlink wire grammar — for consumers that read rendered bytes back
@@ -69,8 +69,8 @@ export { SPINNERS, DEFAULT_SPINNER } from "./core/spinnerData.js";
 export { Console } from "./core/console.js";
 // Renderables
 export { Constrain } from "./renderables/constrain.js";
-export { Effected } from "./renderables/effect.js";
-export { EFFECT_CURVES, EFFECT_LIGHTS, SHIMMER_WIDTH, dissolveOut, fadeIn, onColors, pulse, shares, shimmer, sparkle, wheel, } from "./renderables/effects.js";
+export { Effected, confined, drawnOf } from "./renderables/effect.js";
+export { EFFECT_CURVES, EFFECT_LIGHTS, SHIMMER_WIDTH, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.js";
 export { Align } from "./renderables/align.js";
 export { Padding } from "./renderables/padding.js";
 export { Viewport, ViewportPerKey, SCROLLBAR } from "./renderables/viewport.js";

package/dist/renderables/effect.d.ts

@@ -2,11 +2,18 @@
  * Effected — a renderable whose finished cells' colours pass through an
  * effect at a moment `t`.
  *
- * An effect is one pure function: a cell's colours, where the cell is, and a
- * time in, the cell's new colours out. Shimmer, pulse, fade and dissolve are
- * all this one shape, differing by what the function does with its inputs
- * [LAW:one-type-per-behavior]; two effects stack by nesting one wrapper in
- * another, which is the same as calling one after the other.
+ * An effect is one pure function: a cell's colours, where the cell is, a time,
+ * and what the element draws in that frame in, the cell's new colours out.
+ * Shimmer, pulse, fade and dissolve are all this one shape, differing by what
+ * the function does with its inputs [LAW:one-type-per-behavior]; two effects
+ * stack by nesting one wrapper in another, which is the same as calling one
+ * after the other but for what the outer one measures: the inner one's output.
+ *
+ * What the element draws (`Drawn`) is measured here, in the render, off the
+ * same reading of each segment its cells are drawn from, and handed to every
+ * cell of the frame alike. It is what an effect keeping words legible is
+ * settled against (`onColors`, `./effects.ts`), so no caller derives it a
+ * second time from a render of its own.
  *
  * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
  * clock read. Whoever draws frames builds the view for each frame's `t`, so
@@ -33,7 +40,8 @@
  * Positions are the child's own: row and column count from the top-left of
  * what the child drew, so a sweep crosses the element, not the screen.
  */
-import { type ColorRgba, type TerminalTheme } from "../core/color.js";
+import { type Anchor } from "../core/anchor.js";
+import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js";
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 /**
@@ -65,9 +73,44 @@ export interface EffectCell {
         readonly fg: boolean;
         readonly bg: boolean;
     };
+    /**
+     * Who drew the cell, and where it sits in their output, as
+     * `Segment.anchorAt` reads it off a frame: what tells one owner's cells
+     * from another's when their colours are alike (`confined`).
+     */
+    readonly anchor: Anchor | undefined;
+}
+/**
+ * A cell's ink and ground as the screen shows them, and which of the two are
+ * the terminal's: what an `Effect` is handed for that cell.
+ */
+export interface Pair extends CellColors {
+    readonly terminal: EffectCell["terminal"];
+}
+/**
+ * The colours the element an effect wraps draws its words in, in one frame,
+ * as the screen shows them: what an effect that must keep the words legible
+ * is measured against. A word cell is one whose glyph is not blank and that a
+ * strip's joiner did not draw (`JOIN`): a seam's ink is the fill beside it,
+ * not words.
+ */
+export interface Drawn {
+    /** Every distinct ink and ground of a word cell. */
+    readonly pairs: readonly Pair[];
+    /** The colours the element sets itself in its word cells, by hex: never the terminal's, whatever its hex. */
+    readonly colors: ReadonlySet<string>;
+    /** Of `colors`, the ones a word cell has for its ground. */
+    readonly fills: ReadonlySet<string>;
+    /** The depth the frame is written at: below truecolor a moved colour lands on a palette colour. */
+    readonly depth: ColorDepth;
+    /** The terminal the frame is drawn on. */
+    readonly theme: TerminalTheme;
 }
-/** A cell's colours at time `t`, in seconds. Return `colors` to leave it be. */
-export type Effect = (colors: CellColors, cell: EffectCell, t: number) => CellColors;
+/**
+ * A cell's colours at time `t`, in seconds, in a frame whose element draws
+ * `drawn`. Return `colors` to leave it be.
+ */
+export type Effect = (colors: CellColors, cell: EffectCell, t: number, drawn: Drawn) => CellColors;
 export interface EffectedOptions {
     /** The moment to draw, in seconds. */
     readonly t: number;
@@ -111,3 +154,18 @@ export declare class Effected implements Renderable, Measurable {
     /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
     private seed;
 }
+/**
+ * `effect` on the colours `owner` drew, itself or through an owner nested in
+ * its output, and every other colour left as it is: one item of a strip whose
+ * items share a fill, one widget of a screen. A seam cell shows its two
+ * neighbours side by side, a powerline arrow in the fill it points out of
+ * over the fill it points into, so each side moves with its own item
+ * (`colorsOwnedBy`, `../core/strip.ts`).
+ */
+export declare function confined(effect: Effect, owner: object): Effect;
+/**
+ * What `segments`, drawn at `depth` on `theme`, draw their words in, measured
+ * as `Effected` measures its child for every frame. Measure an element's
+ * output under an effect to read the contrast its words are left at.
+ */
+export declare function drawnOf(segments: Iterable<Segment>, depth: ColorDepth, theme: TerminalTheme): Drawn;

package/dist/renderables/effect.js

@@ -2,11 +2,18 @@
  * Effected — a renderable whose finished cells' colours pass through an
  * effect at a moment `t`.
  *
- * An effect is one pure function: a cell's colours, where the cell is, and a
- * time in, the cell's new colours out. Shimmer, pulse, fade and dissolve are
- * all this one shape, differing by what the function does with its inputs
- * [LAW:one-type-per-behavior]; two effects stack by nesting one wrapper in
- * another, which is the same as calling one after the other.
+ * An effect is one pure function: a cell's colours, where the cell is, a time,
+ * and what the element draws in that frame in, the cell's new colours out.
+ * Shimmer, pulse, fade and dissolve are all this one shape, differing by what
+ * the function does with its inputs [LAW:one-type-per-behavior]; two effects
+ * stack by nesting one wrapper in another, which is the same as calling one
+ * after the other but for what the outer one measures: the inner one's output.
+ *
+ * What the element draws (`Drawn`) is measured here, in the render, off the
+ * same reading of each segment its cells are drawn from, and handed to every
+ * cell of the frame alike. It is what an effect keeping words legible is
+ * settled against (`onColors`, `./effects.ts`), so no caller derives it a
+ * second time from a render of its own.
  *
  * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
  * clock read. Whoever draws frames builds the view for each frame's `t`, so
@@ -33,11 +40,13 @@
  * Positions are the child's own: row and column count from the top-left of
  * what the child drew, so a sweep crosses the element, not the screen.
  */
+import { drawnBy, shiftAnchor } from "../core/anchor.js";
 import { cellLen, graphemes } from "../core/cells.js";
 import { ColorDepth, ColorSpec, SURFACE_BLACK, rgbDistance } from "../core/color.js";
 import { fnv1a } from "../core/fnv1a.js";
 import { Measurement } from "../core/measure.js";
 import { Segment } from "../core/segment.js";
+import { JOIN, colorsOwnedBy } from "../core/strip.js";
 import { Style } from "../core/style.js";
 export class Effected {
     renderable;
@@ -63,30 +72,27 @@ export class Effected {
         }
         // No depth named is no downgrade, as `drawnColors` reads it.
         const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
+        // [LAW:one-source-of-truth] The frame is measured before any cell is
+        // handed to the effect, off the same looks its cells are drawn from.
+        const looked = looks(segments, depth, this.theme);
+        const drawn = measured(looked, depth, this.theme);
         let row = 0;
         let col = 0;
-        for (const segment of segments) {
-            if (segment.isControl) {
+        for (const { segment, look } of looked) {
+            if (look === undefined) {
                 yield segment;
                 continue;
             }
-            const base = segment.style ?? Style.null();
-            // [LAW:single-enforcer] `drawnColors` is what the wire writes at this
-            // depth — alpha flattened, downgraded — and the theme resolves what it
-            // leaves to the terminal. A slot the effect leaves alone keeps the
-            // written spec, so it stays what the screen showed whatever moves
-            // beside it.
-            const wire = base.drawnColors(options.colorSystem ?? undefined);
-            const ink = (wire.color ?? DEFAULT).getTruecolor(this.theme, true);
-            const paper = (wire.bgcolor ?? DEFAULT).getTruecolor(this.theme, false);
-            const slots = { fg: ink, bg: paper };
-            const from = onScreen(slots, base);
-            const terminal = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, base);
+            const { style: base, wire, slots, pair } = look;
+            const { terminal } = pair;
+            const from = { fg: pair.fg, bg: pair.bg };
             // [LAW:one-source-of-truth] A run is cells the wire writes alike: each
             // cell is drawn at the output depth first and merged on the colours that
             // writes, so two truecolors landing on one index stay one run. A cell
             // the effect gave its neighbour's colours is drawn as that neighbour was.
             const runs = [];
+            // Cells into the segment, as `base.shiftedBy` counts them below.
+            let into = 0;
             for (const glyph of graphemes(segment.text)) {
                 let colors = slots;
                 if (glyph === "\n") {
@@ -94,19 +100,21 @@ export class Effected {
                     col = 0;
                 }
                 else {
+                    const anchor = base.anchor && shiftAnchor(base.anchor, into);
                     // Back from the screen to the style's slots: the same swap undoes itself.
-                    colors = onScreen(this.effect(from, { row, col, seed: this.seed(row, col), terminal }, this.t), base);
+                    colors = onScreen(this.effect(from, { row, col, seed: this.seed(row, col), terminal, anchor }, this.t, drawn), base);
                     col += cellLen(glyph);
                 }
+                into += cellLen(glyph);
                 const last = runs[runs.length - 1];
-                const drawn = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
-                if (last !== undefined && writesAlike(last.drawn, drawn)) {
+                const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
+                if (last !== undefined && writesAlike(last.drawn, writes)) {
                     last.text += glyph;
                     last.cells += cellLen(glyph);
                     last.colors = colors;
                 }
                 else {
-                    runs.push({ text: glyph, cells: cellLen(glyph), colors, drawn });
+                    runs.push({ text: glyph, cells: cellLen(glyph), colors, drawn: writes });
                 }
             }
             if (runs.every((run) => writesAlike(run.drawn, wire))) {
@@ -153,6 +161,49 @@ export class Effected {
     }
 }
 const DEFAULT = ColorSpec.default();
+/** Each of `segments` with how it is drawn at `depth` on `theme`; a control segment draws nothing. */
+function looks(segments, depth, theme) {
+    return [...segments].map((segment) => {
+        if (segment.isControl)
+            return { segment, look: undefined };
+        const style = segment.style ?? Style.null();
+        const wire = style.drawnColors(depth);
+        const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(theme, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(theme, false) };
+        const terminal = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, style);
+        return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, style), terminal } } };
+    });
+}
+/** What `looked` draws its words in: `Drawn`'s measure, taken once per frame. */
+function measured(looked, depth, theme) {
+    const words = looked.flatMap(({ segment, look }) => (look !== undefined && segment.text.trim() !== "" && !drawnBy(look.style.anchor, JOIN) ? [look.pair] : []));
+    const pairs = [...new Map(words.map((pair) => [`${pair.fg.hex}/${pair.bg.hex}/${pair.terminal.fg}/${pair.terminal.bg}`, pair])).values()];
+    // [LAW:one-source-of-truth] A slot the terminal fills is no colour of the element's, whatever its hex.
+    const own = (slot) => pairs.flatMap((pair) => (pair.terminal[slot] ? [] : [pair[slot].hex]));
+    return { pairs, colors: new Set([...own("fg"), ...own("bg")]), fills: new Set(own("bg")), depth, theme };
+}
+/**
+ * `effect` on the colours `owner` drew, itself or through an owner nested in
+ * its output, and every other colour left as it is: one item of a strip whose
+ * items share a fill, one widget of a screen. A seam cell shows its two
+ * neighbours side by side, a powerline arrow in the fill it points out of
+ * over the fill it points into, so each side moves with its own item
+ * (`colorsOwnedBy`, `../core/strip.ts`).
+ */
+export function confined(effect, owner) {
+    return (colors, cell, t, drawn) => {
+        const owned = colorsOwnedBy(cell.anchor, owner);
+        const moved = effect(colors, cell, t, drawn);
+        return { fg: owned.fg ? moved.fg : colors.fg, bg: owned.bg ? moved.bg : colors.bg };
+    };
+}
+/**
+ * What `segments`, drawn at `depth` on `theme`, draw their words in, measured
+ * as `Effected` measures its child for every frame. Measure an element's
+ * output under an effect to read the contrast its words are left at.
+ */
+export function drawnOf(segments, depth, theme) {
+    return measured(looks(segments, depth, theme), depth, theme);
+}
 /**
  * A style's colour slots as the screen shows them, or the reverse: `reverse`
  * swaps glyph and ground, and swapping twice is where you started.

package/dist/renderables/effects.d.ts

@@ -36,14 +36,14 @@
  * [LAW:no-ambient-temporal-coupling] No curve reads a clock; `t` is the
  * effect's argument, so the frame owner decides when to sample.
  *
- * Every import below names something the package exports, but for `noise`,
- * which the docs' effects playground page supplies itself: each of its
+ * Every import below names something the package exports, but for `noise`
+ * and `Memo`, which the docs' effects playground page supplies itself: each of its
  * cards runs this file's own declarations as the program a visitor edits
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
 import { ColorRgba } from "../core/color.js";
 import { type Ease } from "../core/easing.js";
-import type { CellColors, Effect, EffectCell } from "./effect.js";
+import type { Drawn, Effect, EffectCell, Pair } from "./effect.js";
 /** What a loop does to one colour at strength `w` in [0, 1]: at 0, nothing. */
 export type Touch = (color: ColorRgba, w: number) => ColorRgba;
 /** How strongly a loop acts on a cell at a moment, in [0, 1]; `onColors` holds a field outside it to it. */
@@ -53,20 +53,13 @@ export interface Loop {
     readonly touch: Touch;
     readonly field: Field;
 }
-/**
- * A cell's ink and ground as the screen shows them, and which of the two are
- * the terminal's: what an `Effect` is handed for that cell.
- */
-export interface Pair extends CellColors {
-    readonly terminal: EffectCell["terminal"];
-}
 /**
  * How much of `touch` each of `colors` (hex) can take: the largest share in
  * [0, 1] at which every pair in `pairs` that shows it, touched at the same
  * strength, still reads at its resting contrast or `LEGIBLE`, whichever is
  * lower. A colour in a pair but not in `colors` takes none, and so does one
  * the terminal supplies, whatever its hex, as in `onColors`. One of `colors`
- * no pair writes has nothing to be measured against, and throws.
+ * no pair writes has nothing to be measured against, and takes it all.
  *
  * Colours are settled lightest first, each against every partner: one
  * already settled at its share, one not yet settled as it is. So the lighter
@@ -77,14 +70,28 @@ export interface Pair extends CellColors {
  */
 export declare function shares(pairs: readonly Pair[], colors: ReadonlySet<string>, touch: Touch): Map<string, number>;
 /**
- * A loop as an `Effect` on a subject's own colours, by hex, wherever a cell
- * shows them, each touched at its share of the cell's strength. A powerline
- * strip's fill is the ground of its cells and the ink of the seam glyphs
- * between them, so the arrow moves with the cell it points out of. A colour
- * the terminal supplies (`EffectCell.terminal`) is not the subject's, whatever
- * its hex, and takes no share.
+ * A loop as an `Effect` on the element's own colours, by hex, wherever a cell
+ * shows them, each touched at its share of the cell's strength: the share
+ * `shares` settles for it against the pairs the element draws its words in
+ * (`Drawn`), touched as the frame's depth writes them — at 256 colours a
+ * touched colour lands on the cube, and the contrast it spends is the cube
+ * colour's. `colors` are the ones lit, by default every colour the element
+ * sets itself. A powerline strip's fill is the ground of its cells and the
+ * ink of the seam glyphs between them, so the arrow moves with the cell it
+ * points out of. A colour the terminal supplies (`EffectCell.terminal`) is
+ * not the element's, whatever its hex, and takes no share.
+ *
+ * Settling shares is costly, so it is done once for each set of colours an
+ * element draws: make the effect once and draw it in every frame, and a frame
+ * drawing what an earlier one drew costs no settling.
+ */
+export declare function onColors(loop: Loop, colors?: ReadonlySet<string>): Effect;
+/**
+ * A loop as an `Effect` on colours by hex, each touched at the share
+ * `share` gives it of the cell's strength in a frame drawing what `Drawn`
+ * says; a colour it gives none, and one the terminal supplies, stays as it is.
  */
-export declare function onColors(share: ReadonlyMap<string, number>, loop: Loop): Effect;
+export declare function atShares(loop: Loop, share: (drawn: Drawn) => ReadonlyMap<string, number>): Effect;
 /** How the curves below are tuned: one period (or duration), ease and swing. */
 export interface Curve {
     /** Seconds: a looping effect's period, a transition's duration. */
@@ -247,6 +254,7 @@ export declare function dissolveOut(curve: Curve, start: number, z: number, grou
  * its own. A segment's stray is slow noise of its own, at `STRAY_PERIODS`,
  * so no two keep step, and the row never shows one spread of hues twice.
  * Lightness and chroma are kept, so the words read as they did; the turn
- * only happens to `colors`, the element's own, never the terminal's.
+ * only happens to the element's own colours (`Drawn.colors`), never the
+ * terminal's.
  */
-export declare function wheel(curve: Curve, colors: ReadonlySet<string>, fills: ReadonlySet<string>, z: number): Effect;
+export declare function wheel(curve: Curve, z: number): Effect;

package/dist/renderables/effects.js

@@ -36,14 +36,15 @@
  * [LAW:no-ambient-temporal-coupling] No curve reads a clock; `t` is the
  * effect's argument, so the frame owner decides when to sample.
  *
- * Every import below names something the package exports, but for `noise`,
- * which the docs' effects playground page supplies itself: each of its
+ * Every import below names something the package exports, but for `noise`
+ * and `Memo`, which the docs' effects playground page supplies itself: each of its
  * cards runs this file's own declarations as the program a visitor edits
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
-import { ColorRgba, contrastRatio } from "../core/color.js";
+import { ColorRgba, ColorSpec, contrastRatio } from "../core/color.js";
 import { EASES, Phase } from "../core/easing.js";
 import { fbm, hash, noise, smoothstep } from "../core/noise.js";
+import { Memo } from "../core/memo.js";
 import { IDENTITY, Oklch } from "../core/oklch.js";
 /** The contrast no touch takes a cell below, unless it rested below it: WCAG AA for body text. */
 const LEGIBLE = 4.5;
@@ -64,7 +65,7 @@ const ROUNDING = 0.01;
  * strength, still reads at its resting contrast or `LEGIBLE`, whichever is
  * lower. A colour in a pair but not in `colors` takes none, and so does one
  * the terminal supplies, whatever its hex, as in `onColors`. One of `colors`
- * no pair writes has nothing to be measured against, and throws.
+ * no pair writes has nothing to be measured against, and takes it all.
  *
  * Colours are settled lightest first, each against every partner: one
  * already settled at its share, one not yet settled as it is. So the lighter
@@ -81,12 +82,12 @@ export function shares(pairs, colors, touch) {
         { color: bg, own: terminal.bg ? undefined : bg.hex },
     ]);
     const rgba = new Map(sides.flat().flatMap(({ color, own }) => (own === undefined ? [] : [[own, color]])));
-    const unpaired = [...colors].filter((hex) => !rgba.has(hex));
-    if (unpaired.length > 0)
-        throw new RangeError(`shares: ${unpaired.join(", ")} written in no pair, so nothing to keep legible against`);
+    // A colour no pair writes keeps no word legible, so nothing bounds its share:
+    // a frame drawing a lit colour only under blanks and seams, or not at all,
+    // is a frame like any other.
+    const settled = new Map([...colors].filter((hex) => !rgba.has(hex)).map((hex) => [hex, 1]));
     const lightness = (hex) => Oklch.fromRgba(rgba.get(hex)).l;
-    const settled = new Map();
-    for (const hex of [...colors].sort((a, b) => lightness(b) - lightness(a))) {
+    for (const hex of [...colors].filter((hex) => rgba.has(hex)).sort((a, b) => lightness(b) - lightness(a))) {
         const partners = sides.flatMap(([fg, bg]) => {
             const partner = fg.own === hex ? bg : bg.own === hex ? fg : undefined;
             return partner === undefined ? [] : [[partner.color, partner.own === undefined ? 0 : (settled.get(partner.own) ?? 0)]];
@@ -106,17 +107,46 @@ export function shares(pairs, colors, touch) {
     return settled;
 }
 /**
- * A loop as an `Effect` on a subject's own colours, by hex, wherever a cell
- * shows them, each touched at its share of the cell's strength. A powerline
- * strip's fill is the ground of its cells and the ink of the seam glyphs
- * between them, so the arrow moves with the cell it points out of. A colour
- * the terminal supplies (`EffectCell.terminal`) is not the subject's, whatever
- * its hex, and takes no share.
+ * A loop as an `Effect` on the element's own colours, by hex, wherever a cell
+ * shows them, each touched at its share of the cell's strength: the share
+ * `shares` settles for it against the pairs the element draws its words in
+ * (`Drawn`), touched as the frame's depth writes them — at 256 colours a
+ * touched colour lands on the cube, and the contrast it spends is the cube
+ * colour's. `colors` are the ones lit, by default every colour the element
+ * sets itself. A powerline strip's fill is the ground of its cells and the
+ * ink of the seam glyphs between them, so the arrow moves with the cell it
+ * points out of. A colour the terminal supplies (`EffectCell.terminal`) is
+ * not the element's, whatever its hex, and takes no share.
+ *
+ * Settling shares is costly, so it is done once for each set of colours an
+ * element draws: make the effect once and draw it in every frame, and a frame
+ * drawing what an earlier one drew costs no settling.
+ */
+export function onColors(loop, colors) {
+    const settled = new WeakMap();
+    const settle = (drawn) => {
+        const lit = colors ?? drawn.colors;
+        const key = [drawn.depth, ...drawn.pairs.map(({ fg, bg, terminal }) => `${fg.hex}/${bg.hex}/${terminal.fg}/${terminal.bg}`), "|", ...lit].join(" ");
+        const memo = settled.get(drawn.theme) ?? new Memo();
+        settled.set(drawn.theme, memo);
+        const asWritten = (color, w) => ColorSpec.fromRgba(loop.touch(color, w)).downgrade(drawn.depth).getTruecolor(drawn.theme);
+        return memo.get(key, () => shares(drawn.pairs, lit, asWritten));
+    };
+    return atShares(loop, settle);
+}
+/**
+ * A loop as an `Effect` on colours by hex, each touched at the share
+ * `share` gives it of the cell's strength in a frame drawing what `Drawn`
+ * says; a colour it gives none, and one the terminal supplies, stays as it is.
  */
-export function onColors(share, loop) {
-    return ({ fg, bg }, cell, t) => {
+export function atShares(loop, share) {
+    // Every cell of a frame is handed the same `Drawn`, so its shares are looked up once a frame.
+    let frame = { drawn: undefined, share: new Map() };
+    return ({ fg, bg }, cell, t, drawn) => {
+        if (frame.drawn !== drawn)
+            frame = { drawn, share: share(drawn) };
         const w = Math.round(clamp01(loop.field(cell, t)) * LEVELS) / LEVELS;
-        const moved = (color, terminal) => touchedAt(loop.touch, color, (terminal ? 0 : (share.get(color.hex) ?? 0)) * w);
+        const moved = (color, terminal) => touchedAt(loop.touch, color, (terminal ? 0 : (frame.share.get(color.hex) ?? 0)) * w);
         return { fg: moved(fg, cell.terminal.fg), bg: moved(bg, cell.terminal.bg) };
     };
 }
@@ -541,9 +571,10 @@ const STRAY = 180;
  * its own. A segment's stray is slow noise of its own, at `STRAY_PERIODS`,
  * so no two keep step, and the row never shows one spread of hues twice.
  * Lightness and chroma are kept, so the words read as they did; the turn
- * only happens to `colors`, the element's own, never the terminal's.
+ * only happens to the element's own colours (`Drawn.colors`), never the
+ * terminal's.
  */
-export function wheel(curve, colors, fills, z) {
+export function wheel(curve, z) {
     requireCurve(curve);
     const P = curve.seconds;
     // A segment's seed, from the colour it is.
@@ -555,11 +586,11 @@ export function wheel(curve, colors, fills, z) {
         const s = seed(hex);
         return (360 * t) / P + curve.swing * STRAY * ((stray(s, t) - stray(s, 0)) / 1.5);
     };
-    return (drawn, cell, t) => {
+    return (shown, cell, t, { colors, fills }) => {
         // Whether a slot shows one of the element's colours: never the terminal's, whatever its hex.
-        const own = { fg: !cell.terminal.fg && colors.has(drawn.fg.hex), bg: !cell.terminal.bg && colors.has(drawn.bg.hex) };
+        const own = { fg: !cell.terminal.fg && colors.has(shown.fg.hex), bg: !cell.terminal.bg && colors.has(shown.bg.hex) };
         // An own colour turns with its segment: itself if a fill or beside no own colour, else the one beside it.
         const turn = (color, mine, other, theirs) => !mine ? color : Oklch.fromRgba(color).applyKey({ ...IDENTITY, hueShift: turned(fills.has(color.hex) || !theirs ? color.hex : other.hex, t) }).toRgba();
-        return { fg: turn(drawn.fg, own.fg, drawn.bg, own.bg), bg: turn(drawn.bg, own.bg, drawn.fg, own.fg) };
+        return { fg: turn(shown.fg, own.fg, shown.bg, own.bg), bg: turn(shown.bg, own.bg, shown.fg, own.fg) };
     };
 }

package/dist/renderables/flexStrip.d.ts

@@ -17,7 +17,7 @@
  */
 import { Segment } from "../core/segment.js";
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
-import type { Joiner, StyledRenderable } from "../core/strip.js";
+import { type Joiner, type StyledRenderable } from "../core/strip.js";
 export type FlexAlign = "left" | "center" | "right" | "justify";
 export interface FlexStripOptions<T extends StyledRenderable> {
     /** Joiner used between items within a line, and at line endpoints. */