@promptctl/rich-js 0.25.0 → 0.25.1

package/dist/core/color.js

@@ -2,6 +2,10 @@
  * Terminal color representation, parsing, downgrading, and ANSI code generation.
  */
 import { Memo, WeakMemo } from "./memo.js";
+import { pattern } from "./pattern.js";
+// Runtime-importing `Palette` from `themes/palette.ts` is safe: that module
+// only `import type`s from `core/color.ts`, so there is no runtime cycle.
+import { Palette } from "../themes/palette.js";
 // --- ColorRgba ---
 function hex2(byte) {
     return byte.toString(16).padStart(2, "0");
@@ -950,11 +954,6 @@ export const WINDOWS_TABLE = new ColorTable(buildWindowsTable());
 // terminal a colour's depth assumes, built from that depth's own sixteen with
 // an empty Palette — sufficient for the lookups it serves, which never read
 // `palette`.
-//
-// Runtime-importing `Palette` from `themes/palette.ts` is safe: that module
-// only `import type`s from `core/color.ts`, so there is no runtime cycle.
-import { Palette } from "../themes/palette.js";
-import { pattern } from "./pattern.js";
 const INTERNAL_DEFAULT_THEME = new TerminalTheme(new ColorRgba(0, 0, 0), new ColorRgba(255, 255, 255), STANDARD_TABLE, new Palette("default", true, new Map()));
 /** The Windows console in its default Campbell scheme: a WINDOWS colour's terminal. */
 const WINDOWS_CONSOLE_THEME = new TerminalTheme(WINDOWS_TABLE.get(0), WINDOWS_TABLE.get(7), WINDOWS_TABLE, new Palette("windows", true, new Map()));

package/dist/core/strip.d.ts

@@ -28,6 +28,7 @@
 import type { Anchor } from "./anchor.js";
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
+import { ColorDepth, ColorSpec } from "./color.js";
 import { type Measurable, type Renderable, type RenderOptions } from "./protocol.js";
 /**
  * Items in a `Strip` expose their per-edge style so joiners can paint the
@@ -70,21 +71,11 @@ export interface Joiner<T extends StyledRenderable = StyledRenderable> {
  * not draw at all. An effect reads it to leave a seam out of the words it
  * keeps legible (`drawnOf`, `../renderables/effect.ts`).
  *
- * Inside it, every cell a `CellJoiner` draws names whose colour each of its
- * two sides shows (`colorsOwnedBy`). One seam cell can show two neighbours —
- * a powerline arrow is inked in the fill it points out of, over the fill it
- * points into — so a cell has no single owner; each side has one.
+ * Inside it, every cell a `CellJoiner` draws is stamped with what it was
+ * resolved from (`JoinedCell`), so a cell whose neighbours an effect moves is
+ * resolved again from where they moved to.
  */
 export declare const JOIN: object;
-/**
- * Which of a cell's two colours on screen are one of `owners`': both, for a
- * cell one of them drew, itself or through an owner nested in its output; for
- * a cell a `CellJoiner` drew, the sides shown in one of their colours.
- */
-export declare function colorsOwnedBy(anchor: Anchor | undefined, owners: ReadonlySet<object>): {
-    readonly fg: boolean;
-    readonly bg: boolean;
-};
 /**
  * [LAW:single-enforcer] What `joiner` draws at one join, every cell stamped
  * as `JOIN`'s: the one way `Strip` and `FlexStrip` draw a join.
@@ -203,6 +194,86 @@ export interface JoinCaps {
  * difference, because a seam is one cell wide.
  */
 export declare const SEAM_MIN_DELTA_E = 0.04;
+/** The parts of each neighbour's edge a join cell paints with. */
+interface CellParts {
+    readonly left: ReadonlySet<"fg" | "bg">;
+    readonly right: ReadonlySet<"fg" | "bg">;
+}
+/** A neighbour a join cell paints with, and its edge as the cell was resolved from it. */
+export interface JoinSide {
+    readonly owner: object;
+    readonly edge: Style;
+}
+interface Edges {
+    readonly left: Style | undefined;
+    readonly right: Style | undefined;
+}
+/**
+ * Where an effect moved one slot or both of a neighbour's edge cell to, each
+ * the spec the depth writes the slot in, a palette slot as that slot:
+ * `color` for its text, `bgcolor` for its ground. A slot left unset did not
+ * move.
+ */
+export interface EdgeMove {
+    readonly color?: ColorSpec;
+    readonly bgcolor?: ColorSpec;
+}
+/**
+ * A cell a `CellJoiner` drew, as what it is: one function of its two
+ * neighbours' edges. It holds the cell's paints, the neighbour each side of
+ * them reads, and the edges and render it was resolved from, and it is stamped
+ * on the cell as the owner of its innermost anchor level.
+ *
+ * [LAW:one-source-of-truth] A seam's colours are its neighbours', so nothing
+ * paints them but this resolution. An effect paints a strip's items and never
+ * a join cell that `follows` them; once the items are painted, each such cell
+ * is handed what moved at the item cells beside it and resolved again through
+ * `cellStyle`, the path the join was drawn by, lift included
+ * (`../renderables/effect.ts`). A seam then follows its neighbours wherever an
+ * effect takes them, a mix of the two included, and an effect that paints
+ * both one colour leaves the seam's ink lifted off it. A cell painted from
+ * roles and the terminal's ground alone, as `plain`'s separator is, follows
+ * nobody, and an effect paints it as it paints any cell.
+ */
+export declare class JoinedCell {
+    private readonly cell;
+    private readonly parts;
+    private readonly neighbours;
+    private readonly edges;
+    private readonly options;
+    /** What the cell's paints read on each side: that neighbour and its edge as the cell was resolved from it, or `null` for a side they read nothing of. */
+    readonly reads: {
+        readonly left: JoinSide | null;
+        readonly right: JoinSide | null;
+    };
+    /** Whether the cell's paints read either neighbour, so it follows them under an effect. */
+    readonly follows: boolean;
+    /** The cell as drawn from its edges: the one resolution, at join time and after an effect alike. */
+    readonly style: Style;
+    constructor(cell: JoinCell, parts: CellParts, neighbours: {
+        readonly left: object | null;
+        readonly right: object | null;
+    }, edges: Edges, options: RenderOptions);
+    /**
+     * The cell resolved again once each side's edge has moved as `moves` says:
+     * its `colors`, as `cellStyle` draws them, and `style`, the cell's own, with
+     * the record of that stamped where this one was, so an effect drawn over
+     * this one moves on from these edges. Resolved, lift included, at `depth`,
+     * the depth the effect writes the frame at. None when nothing moved of what
+     * the cell paints with: a seam of arrows in two grounds is as it was drawn
+     * while an effect moves only the lettering beside it, and its lift is not
+     * walked again for a frame that cannot change it.
+     */
+    rederived(moves: {
+        readonly left?: EdgeMove;
+        readonly right?: EdgeMove;
+    }, style: Style, depth: ColorDepth): {
+        readonly colors: Style;
+        readonly style: Style;
+    } | undefined;
+}
+/** The record a `CellJoiner` stamped on the cell `anchor` names, or none for a cell no `CellJoiner` drew. */
+export declare function joinedCell(anchor: Anchor | undefined): JoinedCell | undefined;
 /**
  * The one joiner: what it draws is a `JoinSeam` between neighbours and a
  * `JoinCaps` at the ends of each run, picked independently, so a new joiner is
@@ -308,3 +379,4 @@ export declare function joinerNamed(spec: JoinerSpec): CellJoiner;
  * draws the caps the ramp is ended in.
  */
 export declare function gradientSeam(steps?: number): JoinSeam;
+export {};

package/dist/core/strip.js

@@ -39,41 +39,11 @@ import { drawable, getStyle, isAscii, render } from "./protocol.js";
  * not draw at all. An effect reads it to leave a seam out of the words it
  * keeps legible (`drawnOf`, `../renderables/effect.ts`).
  *
- * Inside it, every cell a `CellJoiner` draws names whose colour each of its
- * two sides shows (`colorsOwnedBy`). One seam cell can show two neighbours —
- * a powerline arrow is inked in the fill it points out of, over the fill it
- * points into — so a cell has no single owner; each side has one.
+ * Inside it, every cell a `CellJoiner` draws is stamped with what it was
+ * resolved from (`JoinedCell`), so a cell whose neighbours an effect moves is
+ * resolved again from where they moved to.
  */
 export const JOIN = Object.freeze({ name: "join" });
-/**
- * Whose colour each side of a join cell shows on screen, its ink and its
- * ground: the neighbour whose edge a `Paint` names, or `null` for a role, a
- * mix or the terminal's ground, which are no neighbour's.
- */
-class ColorOwners {
-    fg;
-    bg;
-    constructor(fg, bg) {
-        this.fg = fg;
-        this.bg = bg;
-    }
-}
-/**
- * Which of a cell's two colours on screen are one of `owners`': both, for a
- * cell one of them drew, itself or through an owner nested in its output; for
- * a cell a `CellJoiner` drew, the sides shown in one of their colours.
- */
-export function colorsOwnedBy(anchor, owners) {
-    for (let level = anchor; level; level = level.inner) {
-        if (owners.has(level.owner))
-            return { fg: true, bg: true };
-        if (level.owner instanceof ColorOwners) {
-            const { fg, bg } = level.owner;
-            return { fg: fg !== null && owners.has(fg), bg: bg !== null && owners.has(bg) };
-        }
-    }
-    return { fg: false, bg: false };
-}
 /**
  * [LAW:single-enforcer] What `joiner` draws at one join, every cell stamped
  * as `JOIN`'s: the one way `Strip` and `FlexStrip` draw a join.
@@ -262,9 +232,12 @@ function parseCaps(raw) {
 function joinForms(seam, caps) {
     return { seam: seam.seam.flatMap((cell) => ("cap" in cell ? caps[cell.cap] : [cell])), lead: caps.lead, tail: caps.tail };
 }
+// The parts of `side`'s edge `cell` paints with: its ground (`bg`), its text (`fg`).
+const partsRead = (cell, side) => new Set([cell.fg, cell.bg].flatMap((color) => (color === "ground" ? [] : [...paintsIn(color)].flatMap((p) => ("edge" in p && p.edge === side ? [p.part] : [])))));
 // Whether any of `cells` paints with `side`'s ground.
 const readsGround = (cells, side) => cells.some((cell) => [cell.fg, cell.bg].some((color) => color !== "ground" && [...paintsIn(color)].some((p) => "edge" in p && p.edge === side && p.part === "bg")));
 function formOf(shape) {
+    const cells = (part) => shape[part].map((cell) => ({ cell, parts: { left: partsRead(cell, "left"), right: partsRead(cell, "right") } }));
     return {
         shape,
         reads: {
@@ -272,6 +245,7 @@ function formOf(shape) {
             lead: readsGround(shape.lead, "right"),
             tail: readsGround(shape.tail, "left"),
         },
+        cells: { seam: cells("seam"), lead: cells("lead"), tail: cells("tail") },
     };
 }
 // A bg with a real colour to paint. `undefined` (no bg) and the terminal
@@ -380,6 +354,9 @@ function resolvePaint(paint, edges, options) {
     // A mix with no colour at one end has nothing to blend toward.
     return a && b && ColorSpec.blend(a, b, t);
 }
+// [LAW:single-enforcer] The one resolution of a join cell's paints: at join
+// time, and again whenever an effect moves the neighbours it reads
+// (`JoinedCell`).
 function cellStyle(cell, edges, options) {
     // [LAW:dataflow-not-control-flow] "ground" is the absence of a colour on its
     // side; as the fg it is reverse video over the bg colour, so the glyph's ink
@@ -391,6 +368,84 @@ function cellStyle(cell, edges, options) {
     // the gap measured between them decides how far it moves, usually not at all.
     return new Style({ color: standOff(resolvePaint(cell.fg, edges, options), bgcolor, options.colorSystem ?? ColorDepth.TRUECOLOR), bgcolor });
 }
+/**
+ * A cell a `CellJoiner` drew, as what it is: one function of its two
+ * neighbours' edges. It holds the cell's paints, the neighbour each side of
+ * them reads, and the edges and render it was resolved from, and it is stamped
+ * on the cell as the owner of its innermost anchor level.
+ *
+ * [LAW:one-source-of-truth] A seam's colours are its neighbours', so nothing
+ * paints them but this resolution. An effect paints a strip's items and never
+ * a join cell that `follows` them; once the items are painted, each such cell
+ * is handed what moved at the item cells beside it and resolved again through
+ * `cellStyle`, the path the join was drawn by, lift included
+ * (`../renderables/effect.ts`). A seam then follows its neighbours wherever an
+ * effect takes them, a mix of the two included, and an effect that paints
+ * both one colour leaves the seam's ink lifted off it. A cell painted from
+ * roles and the terminal's ground alone, as `plain`'s separator is, follows
+ * nobody, and an effect paints it as it paints any cell.
+ */
+export class JoinedCell {
+    cell;
+    parts;
+    neighbours;
+    edges;
+    options;
+    /** What the cell's paints read on each side: that neighbour and its edge as the cell was resolved from it, or `null` for a side they read nothing of. */
+    reads;
+    /** Whether the cell's paints read either neighbour, so it follows them under an effect. */
+    follows;
+    /** The cell as drawn from its edges: the one resolution, at join time and after an effect alike. */
+    style;
+    constructor(cell, parts, neighbours, edges, options) {
+        this.cell = cell;
+        this.parts = parts;
+        this.neighbours = neighbours;
+        this.edges = edges;
+        this.options = options;
+        const read = (side) => {
+            if (parts[side].size === 0)
+                return null;
+            const [owner, edge] = [neighbours[side], edges[side]];
+            // [LAW:no-silent-failure] Unreachable: a join draws a part only beside
+            // the neighbours its cells may name: a cap naming the one it is drawn
+            // without is refused when parsed (`parsePaint`).
+            if (owner === null || edge === undefined)
+                throw new Error(`a join cell paints with its ${side} neighbour's edge, and the join has no ${side} neighbour`);
+            return { owner, edge };
+        };
+        this.reads = { left: read("left"), right: read("right") };
+        this.follows = this.reads.left !== null || this.reads.right !== null;
+        this.style = cellStyle(cell, edges, options);
+    }
+    /**
+     * The cell resolved again once each side's edge has moved as `moves` says:
+     * its `colors`, as `cellStyle` draws them, and `style`, the cell's own, with
+     * the record of that stamped where this one was, so an effect drawn over
+     * this one moves on from these edges. Resolved, lift included, at `depth`,
+     * the depth the effect writes the frame at. None when nothing moved of what
+     * the cell paints with: a seam of arrows in two grounds is as it was drawn
+     * while an effect moves only the lettering beside it, and its lift is not
+     * walked again for a frame that cannot change it.
+     */
+    rederived(moves, style, depth) {
+        const reaches = (side) => (moves[side]?.color !== undefined && this.parts[side].has("fg")) || (moves[side]?.bgcolor !== undefined && this.parts[side].has("bg"));
+        if (!reaches("left") && !reaches("right"))
+            return undefined;
+        const moved = (edge, move) => move === undefined ? edge : new Style({ color: move.color ?? edge?.color, bgcolor: move.bgcolor ?? edge?.bgcolor });
+        const edges = { left: moved(this.edges.left, moves.left), right: moved(this.edges.right, moves.right) };
+        const next = new JoinedCell(this.cell, this.parts, this.neighbours, edges, { ...this.options, colorSystem: depth });
+        const restamp = (level) => ({ ...level, owner: level.owner === this ? next : level.owner, inner: level.inner && restamp(level.inner) });
+        return { colors: next.style, style: style.withAnchor(style.anchor && restamp(style.anchor)) };
+    }
+}
+/** The record a `CellJoiner` stamped on the cell `anchor` names, or none for a cell no `CellJoiner` drew. */
+export function joinedCell(anchor) {
+    for (let level = anchor; level; level = level.inner)
+        if (level.owner instanceof JoinedCell)
+            return level.owner;
+    return undefined;
+}
 const shapeGlyphs = (shape) => PARTS.flatMap((part) => shape[part].flatMap(glyphsOf)).join("");
 /**
  * The one joiner: what it draws is a `JoinSeam` between neighbours and a
@@ -422,7 +477,7 @@ export class CellJoiner {
         const forms = this._forms;
         return {
             *render(options) {
-                const { shape: drawn, reads } = drawable(options, forms.glyph, forms.ascii, (form) => shapeGlyphs(form.shape));
+                const { cells, reads } = drawable(options, forms.glyph, forms.ascii, (form) => shapeGlyphs(form.shape));
                 const edges = { left: left?.edgeStyle("right", options), right: right?.edgeStyle("left", options) };
                 const leftBg = paintableBg(edges.left?.bgcolor);
                 const rightBg = paintableBg(edges.right?.bgcolor);
@@ -431,12 +486,9 @@ export class CellJoiner {
                 const leads = hasRight && (!reads.lead || rightBg !== undefined);
                 const tails = hasLeft && (!reads.tail || leftBg !== undefined);
                 const neighbours = { left, right };
-                // On screen a cell's ink is its `fg` paint and its ground its `bg`,
-                // reverse video or not (`cellStyle`).
-                const ownerOf = (color) => (color !== "ground" && "edge" in color ? neighbours[color.edge] : null);
-                const styled = (part) => drawn[part].map((cell, at) => {
-                    const owners = new ColorOwners(ownerOf(cell.fg), ownerOf(cell.bg));
-                    return new Segment(pickGlyph(cell, part, index, at), cellStyle(cell, edges, options).withAnchor({ owner: owners, row: 0, col: 0, inner: undefined }));
+                const styled = (part) => cells[part].map(({ cell, parts }, at) => {
+                    const joined = new JoinedCell(cell, parts, neighbours, edges, options);
+                    return new Segment(pickGlyph(cell, part, index, at), joined.style.withAnchor({ owner: joined, row: 0, col: 0, inner: undefined }));
                 });
                 if (!hasLeft || !hasRight) {
                     if (leads || tails)

package/dist/renderables/effect.d.ts

@@ -8,11 +8,16 @@
  * (`EffectFrame`), and it says when that next changes as every
  * animation does. Whatever holds for the whole frame is worked out once, in
  * the effect and its `at(t)`, and every cell of the frame is handed to the
- * function `at(t)` returns, but for those a wrapper keeps back: `confined`
+ * function `at(t)` returns, but for those a wrapper keeps back — `confined`
  * hands over only the cells its owners drew, so an effect never counts on
- * seeing them all. Shimmer, pulse, fade, dissolve and a blinking attribute
- * 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
+ * seeing them all — and for a strip's join cells painted from the items beside
+ * them, which are no one's to paint: a seam's colours are its neighbours'
+ * edges, so once the effect has painted every other cell, each such cell is
+ * resolved again from the cells beside it as the effect left them
+ * (`JoinedCell`, `../core/strip.ts`), the way the joiner drew it. Shimmer,
+ * pulse, fade, dissolve and a blinking attribute 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.
  *
@@ -149,9 +154,12 @@ export interface Drawn {
      * sits and who drew it, listed before the effect is handed any: what
      * an effect spread over the element — a transition, which has its last cell
      * settle as it ends — is spread over. A blank cell on the terminal's ground
-     * that draws no line is handed but not listed, since nothing in it shows.
-     * `confined` narrows it to the cells its owners drew. A call, so a frame
-     * whose effect does not ask lists none.
+     * that draws no line is handed but not listed, since nothing in it shows,
+     * and a strip's join cell painted from the items beside it is listed but
+     * never handed its own look, since it follows them: it is handed only a
+     * neighbour's edge the frame does not show, to be painted where the seam
+     * shows it. `confined` narrows it to the cells its owners drew. A call, so a
+     * frame whose effect does not ask lists none.
      */
     cells(): readonly Placed[];
     /** Every distinct ink and ground of a word cell. */
@@ -220,6 +228,16 @@ export declare class Recolored implements Renderable, Measurable {
     /** The frame the effect draws at `t`, and the hold it says that is in. */
     moved(options: RenderOptions): Moved;
     private _recolored;
+    /** `segment`'s cells drawn in the looks the effect painted them. */
+    private _repainted;
+    /**
+     * A join cell's `segment` resolved again from the edges beside it, as the
+     * effect left them: each neighbour's nearest cell to the join on its row,
+     * its slots as the depth writes them. A side whose neighbour the effect moved
+     * nothing of keeps the edge the cell was drawn from, so with neither moved
+     * the cell is as it was drawn.
+     */
+    private _rejoined;
     measure(options: RenderOptions): {
         minimum: number;
         maximum: number;
@@ -297,13 +315,12 @@ export declare function walkGlyphs(segments: readonly Segment[]): (readonly Walk
  */
 export declare function inked(text: string): boolean;
 /**
- * `effect` on the colours any of `owners` drew, itself or through an owner
- * nested in its output, and every other colour left as it is: one item of a
+ * `effect` on the cells any of `owners` drew, itself or through an owner
+ * nested in its output, and every other cell left as it is: one item of a
  * strip whose items share a fill, the items of a row one other item stands
- * apart from, 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`). A cell none of them drew is never handed to the
+ * apart from, one widget of a screen. A strip's join cell is no item's, so it
+ * is never handed; one painted from the items beside it follows them, the
+ * moved ones included (`Recolored`). A cell none of them drew is never handed to the
  * effect, so confining one effect to many owners costs one call a cell, not
  * one for each owner.
  */

package/dist/renderables/effect.js

@@ -8,11 +8,16 @@
  * (`EffectFrame`), and it says when that next changes as every
  * animation does. Whatever holds for the whole frame is worked out once, in
  * the effect and its `at(t)`, and every cell of the frame is handed to the
- * function `at(t)` returns, but for those a wrapper keeps back: `confined`
+ * function `at(t)` returns, but for those a wrapper keeps back — `confined`
  * hands over only the cells its owners drew, so an effect never counts on
- * seeing them all. Shimmer, pulse, fade, dissolve and a blinking attribute
- * 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
+ * seeing them all — and for a strip's join cells painted from the items beside
+ * them, which are no one's to paint: a seam's colours are its neighbours'
+ * edges, so once the effect has painted every other cell, each such cell is
+ * resolved again from the cells beside it as the effect left them
+ * (`JoinedCell`, `../core/strip.ts`), the way the joiner drew it. Shimmer,
+ * pulse, fade, dissolve and a blinking attribute 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.
  *
@@ -71,7 +76,7 @@ import { fnv1a } from "../core/fnv1a.js";
 import { Measurement } from "../core/measure.js";
 import { render } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
-import { JOIN, colorsOwnedBy } from "../core/strip.js";
+import { JOIN, joinedCell } from "../core/strip.js";
 import { ATTRIBUTE_NAMES, Style } from "../core/style.js";
 import { finiteTime } from "../core/easing.js";
 /** What drew nothing the effect can change: held forever, as far as the effect says. */
@@ -118,48 +123,154 @@ export class Recolored {
         return { segments: this._recolored(walked, shown.value, depth), hold: holdOf(shown, this.t) };
     }
     *_recolored(walked, frame, depth) {
-        for (const { segment, look, glyphs } of walked) {
-            if (look === undefined) {
-                yield segment;
-                continue;
-            }
-            const { style: base, wire, slots, pair, attributes } = look;
-            const { terminal } = pair;
-            const from = { fg: pair.fg, bg: pair.bg, attributes };
-            // [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 and on its attributes, so two truecolors landing on one index
-            // stay one run. A cell the effect gave its neighbour's look is drawn as
-            // that neighbour was.
-            const runs = [];
-            for (const { glyph, cell } of glyphs) {
-                const moved = cell === undefined ? from : returned(frame(from, { ...cell, seed: cellSeed(this.key, cell.row, cell.col), terminal, reverse: pair.reverse }));
-                // Back from the screen to the style's slots: the same swap undoes itself.
-                const colors = onScreen(moved, pair.reverse);
-                const last = runs[runs.length - 1];
-                const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
-                if (last !== undefined && writesAlike(last.drawn, writes) && sameAttributes(last.attributes, moved.attributes)) {
-                    last.text += glyph;
-                    last.cells += cellLen(glyph);
-                    last.colors = colors;
-                }
-                else {
-                    runs.push({ text: glyph, cells: cellLen(glyph), colors, attributes: moved.attributes, drawn: writes });
-                }
-            }
-            if (runs.every((run) => writesAlike(run.drawn, wire) && sameAttributes(run.attributes, attributes))) {
+        // [LAW:one-source-of-truth] Every cell but a join cell that follows its
+        // neighbours is painted first, so that cell is resolved from the cells
+        // beside it as the effect left them, wherever in the frame they fall.
+        const drawings = walked.map(({ look, glyphs }) => {
+            if (look === undefined)
+                return undefined;
+            const joined = joinedCell(look.style.anchor);
+            if (joined?.follows === true)
+                return { joined };
+            const from = { fg: look.pair.fg, bg: look.pair.bg, attributes: look.attributes };
+            const { terminal, reverse } = look.pair;
+            return { painted: glyphs.map(({ cell }) => (cell === undefined ? from : returned(frame(from, { ...cell, seed: cellSeed(this.key, cell.row, cell.col), terminal, reverse })))) };
+        });
+        const beside = edgesBeside(walked, drawings);
+        for (const [i, { segment, look, glyphs }] of walked.entries()) {
+            const drawing = drawings[i];
+            if (look === undefined || drawing === undefined)
                 yield segment;
-                continue;
+            else if ("joined" in drawing)
+                yield this._rejoined(segment, look, drawing.joined, glyphs, beside, frame, depth);
+            else
+                yield* this._repainted(segment, look, glyphs, drawing.painted, depth);
+        }
+    }
+    /** `segment`'s cells drawn in the looks the effect painted them. */
+    *_repainted(segment, look, glyphs, moved, depth) {
+        const { style: base, wire, slots, pair, attributes } = look;
+        // [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 and on its attributes, so two truecolors landing on one index
+        // stay one run. A cell the effect gave its neighbour's look is drawn as
+        // that neighbour was.
+        const runs = [];
+        for (const [k, { glyph }] of glyphs.entries()) {
+            const now = moved[k];
+            // Back from the screen to the style's slots: the same swap undoes itself.
+            const colors = onScreen(now, pair.reverse);
+            const last = runs[runs.length - 1];
+            const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
+            if (last !== undefined && writesAlike(last.drawn, writes) && sameAttributes(last.attributes, now.attributes)) {
+                last.text += glyph;
+                last.cells += cellLen(glyph);
+                last.colors = colors;
             }
-            let offset = 0;
-            for (const run of runs) {
-                const placed = base.shiftedBy(offset);
-                const shifted = sameAttributes(run.attributes, attributes) ? placed : placed.withAttributes(cellAttributes(run.attributes));
-                const style = writesAlike(run.drawn, wire) ? shifted : shifted.add(Style.fromColor(run.drawn.color, run.drawn.bgcolor));
-                yield new Segment(run.text, style);
-                offset += run.cells;
+            else {
+                runs.push({ text: glyph, cells: cellLen(glyph), colors, attributes: now.attributes, drawn: writes });
             }
         }
+        if (runs.every((run) => writesAlike(run.drawn, wire) && sameAttributes(run.attributes, attributes))) {
+            yield segment;
+            return;
+        }
+        let offset = 0;
+        for (const run of runs) {
+            const placed = base.shiftedBy(offset);
+            const shifted = sameAttributes(run.attributes, attributes) ? placed : placed.withAttributes(cellAttributes(run.attributes));
+            const style = writesAlike(run.drawn, wire) ? shifted : shifted.add(Style.fromColor(run.drawn.color, run.drawn.bgcolor));
+            yield new Segment(run.text, style);
+            offset += run.cells;
+        }
+    }
+    /**
+     * A join cell's `segment` resolved again from the edges beside it, as the
+     * effect left them: each neighbour's nearest cell to the join on its row,
+     * its slots as the depth writes them. A side whose neighbour the effect moved
+     * nothing of keeps the edge the cell was drawn from, so with neither moved
+     * the cell is as it was drawn.
+     */
+    _rejoined(segment, look, joined, glyphs, beside, frame, depth) {
+        const cells = glyphs.flatMap(({ cell }) => (cell === undefined ? [] : [cell]));
+        // A join cell that draws no cell shows nothing an effect could move.
+        const [at] = cells;
+        if (at === undefined)
+            return segment;
+        const { theme } = this;
+        // [LAW:one-source-of-truth] A moved edge is the spec the depth writes its
+        // slot in, the spec the joiner reads of an item drawn so: a palette slot
+        // stays that slot, which the lift tells apart by number, never an RGB read
+        // back through a palette the writer did not use. Only the terminal's own
+        // colour names none, and the terminal the effect draws on says what it is.
+        // Each such spec is kept, so the writer below knows it by identity: an
+        // RGB a blend or another colour lands on is not the terminal's own.
+        const terminals = new Set();
+        const edgeOf = (spec, foreground) => {
+            if (!spec?.isDefault)
+                return spec;
+            const own = ColorSpec.fromRgba(spec.getTruecolor(theme, foreground));
+            terminals.add(own);
+            return own;
+        };
+        const moved = (from, to) => {
+            const specs = movedSpecs(from, to, depth, theme);
+            return specs.fg === undefined && specs.bg === undefined ? undefined : { color: edgeOf(specs.fg, true), bgcolor: edgeOf(specs.bg, false) };
+        };
+        // [LAW:one-source-of-truth] A neighbour the frame shows no cell of beside
+        // the join (cut off by a narrower container, scrolled out of a `Viewport`,
+        // covered, or an item that draws nothing) is painted by the effect where
+        // the seam shows it: its edge, as the seam drew it, handed to the frame at
+        // the seam's own cell. An effect over the whole element moves it as it
+        // moves everything there; one confined to some owners leaves it, since no
+        // owner drew the seam. Where the frame is whole and every item draws, each
+        // neighbour a seam reads has a cell on its row, so only a partial frame
+        // comes here [LAW:no-silent-failure].
+        const unseen = (edge) => {
+            const wire = edge.drawnColors(depth);
+            const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(theme, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(theme, false) };
+            const terminal = { fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true };
+            return moved(slots, returned(frame({ ...slots, attributes: cellAttributes(edge) }, { ...at, seed: cellSeed(this.key, at.row, at.col), terminal, reverse: false })));
+        };
+        const moveOf = (side) => {
+            const read = joined.reads[side];
+            if (read === null)
+                return undefined;
+            const cell = beside(cells, side, read.owner);
+            return cell === undefined ? unseen(read.edge) : moved(cell.look.slots, onScreen(cell.moved, cell.look.pair.reverse));
+        };
+        const rederived = joined.rederived({ left: moveOf("left"), right: moveOf("right") }, look.style, depth);
+        if (rederived === undefined)
+            return segment;
+        const { colors, style } = rederived;
+        // [LAW:one-source-of-truth] Each slot is written as the depth writes what
+        // it resolved to, by the writer the lift measured it with
+        // (`Style.drawnColors`), so a lifted ink stands off its ground in the bytes
+        // as it did when measured. A slot resolved to the colour it was before
+        // keeps the spec it was written in, as a painted cell's unmoved slot does.
+        // The terminal's own colours, which stand in a moved edge as the spec of
+        // the RGB the effect's terminal gives them and reach a slot unchanged or
+        // not at all, are written by the writer that wrote them on the item
+        // beside, on that terminal, which writes its own ground below truecolor as
+        // `default`.
+        const was = joined.style;
+        const drawn = colors.drawnColors(depth);
+        const { wire, slots } = look;
+        const rounded = this.respec(wire, slots, { fg: colors.color?.getTruecolor(theme, true) ?? slots.fg, bg: colors.bgcolor?.getTruecolor(theme, false) ?? slots.bg }, depth);
+        const written = (now, before, wrote, drew, round) => {
+            if (sameSpec(now, before))
+                return wrote;
+            // [LAW:no-silent-failure] Unreachable: a move only fills an edge in, so
+            // a slot that resolved to a colour when drawn resolves to one after.
+            if (now === undefined)
+                throw new Error(`a seam cell resolved to ${before?.name ?? "nothing"} when drawn and to nothing after an effect moved its neighbours`);
+            return terminals.has(now) ? round : drew;
+        };
+        const writes = {
+            color: written(colors.color, was.color, wire.color, drawn.color, rounded.color),
+            bgcolor: written(colors.bgcolor, was.bgcolor, wire.bgcolor, drawn.bgcolor, rounded.bgcolor),
+        };
+        return new Segment(segment.text, writesAlike(writes, wire) ? style : style.add(Style.fromColor(writes.color, writes.bgcolor)));
     }
     measure(options) {
         return Measurement.get(options, this.renderable);
@@ -293,6 +404,45 @@ function walk(looked) {
     const placed = walkGlyphs(looked.map(({ segment }) => segment));
     return looked.map((item, i) => ({ ...item, glyphs: placed[i] }));
 }
+/**
+ * Where to find the cells beside a join in `walked`, painted as `painted` says.
+ * Read by owner, never by column alone: a `FlexStrip` can set a gap or a
+ * justified fill between a seam and the items it joins.
+ */
+function edgesBeside(walked, drawings) {
+    let rows;
+    const index = () => {
+        const byRow = new Map();
+        walked.forEach(({ look, glyphs }, i) => {
+            const drawing = drawings[i];
+            if (look === undefined || drawing === undefined || !("painted" in drawing))
+                return;
+            const moved = drawing.painted;
+            glyphs.forEach(({ cell }, k) => {
+                if (cell === undefined)
+                    return;
+                const row = byRow.get(cell.row) ?? [];
+                row.push({ col: cell.col, anchor: cell.anchor, look, moved: moved[k] });
+                byRow.set(cell.row, row);
+            });
+        });
+        return byRow;
+    };
+    return (cells, side, owner) => {
+        // Cells on a row are listed left to right, as the walk places them.
+        const row = (rows ??= index()).get(cells[0].row) ?? [];
+        const first = cells[0].col;
+        const last = cells[cells.length - 1].col;
+        if (side === "right")
+            return row.find((cell) => cell.col > last && drawnBy(cell.anchor, owner));
+        for (let k = row.length - 1; k >= 0; k--) {
+            const cell = row[k];
+            if (cell.col < first && drawnBy(cell.anchor, owner))
+                return cell;
+        }
+        return undefined;
+    };
+}
 /** Whether `style` draws in its ink on a blank glyph: a line under, through or over it, or a frame round it. */
 function drawsLines(style) {
     return [style.underline, style.underline2, style.strike, style.overline, style.frame, style.encircle].some((on) => on === true);
@@ -327,32 +477,28 @@ function measured(looked, walked, depth, theme) {
     };
 }
 /**
- * `effect` on the colours any of `owners` drew, itself or through an owner
- * nested in its output, and every other colour left as it is: one item of a
+ * `effect` on the cells any of `owners` drew, itself or through an owner
+ * nested in its output, and every other cell left as it is: one item of a
  * strip whose items share a fill, the items of a row one other item stands
- * apart from, 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`). A cell none of them drew is never handed to the
+ * apart from, one widget of a screen. A strip's join cell is no item's, so it
+ * is never handed; one painted from the items beside it follows them, the
+ * moved ones included (`Recolored`). A cell none of them drew is never handed to the
  * effect, so confining one effect to many owners costs one call a cell, not
  * one for each owner.
  */
 export function confined(effect, ...owners) {
     const confinedTo = new Set(owners);
-    // [LAW:single-enforcer] One reading of which slots are owned, for the cells listed and the cells handed alike.
-    const ownedOf = (cell) => colorsOwnedBy(cell.anchor, confinedTo);
-    const any = ({ fg, bg }) => fg || bg;
+    // [LAW:single-enforcer] One reading of whose a cell is, for the cells listed and the cells handed alike.
+    const owned = (cell) => {
+        for (let level = cell.anchor; level; level = level.inner)
+            if (confinedTo.has(level.owner))
+                return true;
+        return false;
+    };
     // The frame as the effect sees it: the owners' cells alone. [LAW:one-source-of-truth] One narrowing, handed to both stages.
-    const owned = (drawn) => ({ ...drawn, cells: () => drawn.cells().filter((cell) => any(ownedOf(cell))) });
+    const narrowed = (drawn) => ({ ...drawn, cells: () => drawn.cells().filter(owned) });
     // The owners' cells change when the effect's frame does.
-    return (drawn) => Animation.map(effect(owned(drawn)), (frame) => (look, cell) => {
-        const owns = ownedOf(cell);
-        if (!any(owns))
-            return look;
-        const moved = frame(look, cell);
-        // An attribute is drawn on the glyph, in its ink, so it moves with whoever owns the ink.
-        return { fg: owns.fg ? moved.fg : look.fg, bg: owns.bg ? moved.bg : look.bg, attributes: owns.fg ? moved.attributes : look.attributes };
-    });
+    return (drawn) => Animation.map(effect(narrowed(drawn)), (frame) => (look, cell) => (owned(cell) ? frame(look, cell) : look));
 }
 /**
  * What `segments`, drawn at `depth` on `theme`, draw their words in, measured
@@ -424,6 +570,10 @@ export function cellAttributes(of) {
 function sameAttributes(a, b) {
     return a === b || MOVED.every((name) => a[name] === b[name]);
 }
+/** Whether two specs are one colour as written: the same kind, naming the same colour. */
+function sameSpec(a, b) {
+    return a === b || (a !== undefined && b !== undefined && a.type === b.type && a.name === b.name);
+}
 function sameColors(a, b) {
     return sameColor(a.fg, b.fg) && sameColor(a.bg, b.bg);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",