@promptctl/rich-js 0.24.1 → 0.25.1

package/dist/core/strip.d.ts

@@ -28,7 +28,8 @@
 import type { Anchor } from "./anchor.js";
 import { Segment } from "./segment.js";
 import { Style } from "./style.js";
-import { type Composite, type Measurable, type Renderable, type RenderOptions } from "./protocol.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
  * transition glyph at each boundary.
@@ -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.
@@ -97,12 +88,11 @@ export declare function drawJoin<T extends StyledRenderable>(joiner: Joiner<T>,
  * item.
  */
 export declare function drawItem(item: StyledRenderable): Renderable;
-export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable, Composite {
+export declare class Strip<T extends StyledRenderable = StyledRenderable> implements Renderable, Measurable {
     readonly items: readonly T[];
     readonly joiner: Joiner<T>;
     constructor(items: readonly T[], joiner: Joiner<T>);
     render(options: RenderOptions): Iterable<Segment>;
-    contents(): Iterable<Renderable>;
     /**
      * [LAW:one-source-of-truth] The width of the one row it draws, and that is
      * both bounds: the row never wraps and no item is offered less than the whole
@@ -167,15 +157,12 @@ export type SeamCell = JoinCell | {
     readonly cap: "lead" | "tail";
 };
 /**
- * What a joiner draws between two neighbours, in one form:
- *   • `seam` — the cells between them;
- *   • `divider` — in the seam's place where every seam cell's ink is drawn
- *     indistinct from its own ground (see `SEAM_MIN_DELTA_E`), so the seam
- *     would vanish; the same width as `seam`.
+ * What a joiner draws between two neighbours, in one form: `seam`, the cells
+ * between them. Each is drawn with its ink held off its own ground
+ * (`SEAM_MIN_DELTA_E`, `standOff`).
  */
 export interface SeamForm {
     readonly seam: readonly SeamCell[];
-    readonly divider: readonly SeamCell[];
 }
 /**
  * What a joiner draws at the ends of a run, in one form:
@@ -201,12 +188,92 @@ export interface JoinCaps {
     readonly ascii: CapsForm;
 }
 /**
- * The least ΔE_OK a seam cell's ink must differ from its own ground by for the
- * seam to be seen. Below it the eye cannot tell the ink from the ground,
- * so the joiner draws the divider instead. Twice the ~.02 threshold of a visible difference, because a seam is
- * one cell wide.
+ * The least ΔE_OK a join cell's ink must stand off its own ground by to be
+ * seen. Below it the eye cannot tell the ink from the ground, so the joiner
+ * lifts the ink to it (`standOff`). Twice the ~.02 threshold of a visible
+ * 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
@@ -215,9 +282,10 @@ export declare const SEAM_MIN_DELTA_E = 0.04;
  * Which part a join draws is read off its two neighbours. A neighbour is
  * missing at the strip's ends, and counts as missing — an endpoint — when the
  * seam paints with its ground anywhere and it has none to paint. With both
- * present the join is the seam, or the divider where every seam cell's ink is
- * drawn indistinct from its ground at `options.colorSystem`; with only the
- * right, the lead; with only the left, the tail; with neither, nothing. A cap
+ * present the join is the seam; with only the right, the lead; with only the
+ * left, the tail; with neither, nothing. Every cell is drawn with its ink held
+ * off its ground at `options.colorSystem` (`standOff`), measured per cell, so a
+ * seam stepping in thirds shows every step however close its grounds. A cap
  * that paints with its neighbour's ground is drawn only beside a neighbour
  * with one, so caps that need grounds never stop a seam that needs none.
  *
@@ -311,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 {};