@weasel-js/diagram 1.11.0 → 1.12.0

package/dist/effect.d.ts

@@ -1,100 +1,38 @@
-import { D as DiagramData, a as DiagramSceneOptions, N as NodeStyle, b as DataEdge, E as EdgeStyle, c as DataNode, d as DiagramRouter, e as DiagramSpec } from './fromData-GKqRgPFs.js';
-import { a as Row, M as MeasureRowText } from './body-2lC7IiIA.js';
+import { c as EffectDoc, E as EffectPipeline, d as EffectWire, e as EffectStage, f as EffectPort, g as EffectGroup, a as EffectRun, b as EffectStageType, L as LookRoutes, h as EffectParamControl, i as EffectBox } from './stageTypes-DvnR8cKQ.js';
+export { j as EffectParam, k as EffectPlaces, l as EffectStageRun, m as EffectType, n as LookRoute, o as formatParam, s as stageFromType } from './stageTypes-DvnR8cKQ.js';
+import { D as DiagramTheme, a as DiagramData, b as DiagramSceneOptions, N as NodeStyle, c as DataEdge, E as EdgeStyle, d as DataNode, e as DiagramRouter, f as DiagramSpec } from './dataTypes-DHdkzCL8.js';
+import { a as Row, M as MeasureRowText } from './types-M_ccNAlk.js';
 import * as react from 'react';
 import { Paint } from '@weasel-js/core';
-import '@weasel-js/core/math';
+import { Vec2 } from '@weasel-js/core/math';
+import { VisibleRafOptions } from '@weasel-js/react';
 import '@weasel-js/geom';
 
-/** An effects pipeline as plain data. It says what is wired to what and
- *  nothing about how any of it is drawn. */
-interface EffectPipeline {
-    stages: readonly EffectStage[];
-    wires: readonly EffectWire[];
-    groups?: readonly EffectGroup[];
-    /** What the value types mean. A type no entry names is plain data. */
-    types?: Readonly<Record<string, EffectType>>;
-}
-/** One step of a pipeline: what it reads and writes, and what its box shows. */
-interface EffectStage {
-    id: string;
-    title: string;
-    /** What sort of stage this is, for a look to read. The shipped looks know
-     *  'stage' (default), 'decision', 'source' and 'sink', and draw any other
-     *  value as 'stage'. */
-    kind?: string;
-    inputs?: readonly EffectPort[];
-    outputs?: readonly EffectPort[];
-    /** Settings worth showing, in order. */
-    params?: readonly {
-        label: string;
-        value: string;
-    }[];
-    /** For a decision that splits on a number: the input it compares, and the
-     *  cut points in ascending order. N cuts need N + 1 outputs, the lowest
-     *  band first. */
-    split?: {
-        input: string;
-        at: readonly number[];
-    };
-    /** The stage is in the pipeline and switched off. */
-    bypassed?: boolean;
-    /** Anything else a look wants. No shipped look reads it. */
-    data?: Readonly<Record<string, unknown>>;
-}
-/** One input or output of a stage, carrying a value of one type. */
-interface EffectPort {
-    /** Unique among the stage's inputs and outputs together. */
-    id: string;
-    /** Default the id. */
-    label?: string;
-    type: string;
-}
-/** A connection from one stage's output to another stage's input. */
-interface EffectWire {
-    from: {
-        stage: string;
-        port: string;
-    };
-    to: {
-        stage: string;
-        port: string;
-    };
-    /** Drawn on the wire. */
-    label?: string;
-}
-/** A box drawn around some stages, and around other groups. */
-interface EffectGroup {
-    id: string;
-    label?: string;
-    /** Stage ids and group ids. */
-    members: readonly string[];
-}
-/** One run of a pipeline: what happened, beside the pipeline rather than in
- *  it, so it can change every frame while the pipeline and its layout stay
- *  put. A stage the run has no entry for is one it never reached. */
-interface EffectRun {
-    stages: Readonly<Record<string, EffectStageRun>>;
-}
-/** What one stage did in a run. */
-interface EffectStageRun {
-    /** How long it took, in milliseconds. */
-    cost?: number;
-    /** For a decision: the output it chose. */
-    taken?: string;
-    /** What each output carried, by port id, as text to show. */
-    values?: Readonly<Record<string, string>>;
-    /** What each output carried, by port id, as a picture, drawn in the slot a
-     *  look keeps for it (`showPreviews`). A bitmap rather than a canvas
-     *  because its pixels cannot change: hand back the same one and nothing is
-     *  uploaded again; draw new pixels into a new one. */
-    previews?: Readonly<Record<string, ImageBitmap>>;
-}
-/** What a value type means, as `EffectPipeline.types` records it. */
-interface EffectType {
-    /** A control value: a condition, a gate, a modulation source. Looks draw
-     *  its wires apart from data wires. */
-    control?: boolean;
+/** How the stages of a chain are joined. */
+interface ChainLinks {
+    /** By stage id: the input the main signal arrives on. */
+    mainIn: ReadonlyMap<string, string>;
+    /** By stage id: the output the main signal leaves by. */
+    mainOut: ReadonlyMap<string, string>;
+    /** By `k`: the index into `pipeline.wires` of the wire from `chain[k]` to
+     *  `chain[k + 1]`, or `undefined` where no data wire joins them. */
+    between: readonly (number | undefined)[];
 }
+/** The first data wire from each chain stage to the next, and the ports it joins. */
+declare function chainLinks(pipeline: EffectPipeline, chain: readonly string[]): ChainLinks;
+/**
+ * The doc with `stage`, which must be on `mainChain`, moved to gap `to` of
+ * that chain: 0 before its first stage, `chain.length` after its last. Its
+ * main input and output wires come off and its old neighbors are wired to
+ * each other; the wire between its new neighbors comes off and it is wired
+ * between them. Side wires, control wires, and params stay with it. `null`
+ * where a new wire would join unlike types or a fed input, where `to` leaves
+ * it where it is, or where the rewired pipeline's main line would not read
+ * in the new order.
+ */
+declare function moveInChain(doc: EffectDoc, stage: string, to: number): EffectDoc | null;
+/** Whether `moveInChain` would make the move. */
+declare function canMoveInChain(doc: EffectDoc, stage: string, to: number): boolean;
 
 /** One thing wrong with a pipeline, and where. */
 interface EffectProblem {
@@ -127,19 +65,49 @@ interface EffectLookResult {
         stage: string;
         port: string;
     }>;
+    /** The stages on the main line, in the order the look draws them, for a
+     *  reorder to drag along. Looks that place stages freely leave it out. */
+    order?: LookOrder;
+    /** The lanes, top down, where the look draws lanes. */
+    laneOrder?: LookOrder;
+}
+/** A sequence a look draws: the scene node ids of its items in order along
+ *  `axis`. `reorder`'s `sequenceSlots` turns it into slots once the items
+ *  have drawn boxes. */
+interface LookOrder {
+    axis: 'x' | 'y';
+    /** `grip` is where a press picks the item up, in world units; default its drawn box. */
+    items: readonly {
+        id: string;
+        grip?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }[];
 }
 /** One way of drawing a pipeline. Unparameterized, a look whose options are
  *  not known: any look fits it, and it is called with none. */
 type EffectLook<TOptions = never> = (pipeline: EffectPipeline, options?: TOptions) => EffectLookResult;
+/** The theme the shipped looks draw in when their options name none. */
+declare const LOOK_THEME: DiagramTheme;
+/** The option every shipped look takes for its colors. */
+interface LookThemeOptions {
+    /** Stages take its default role, bypassed ones its muted role; value types its `series` in
+     *  turn; groups its container; lanes its lane bodies. Default `night`. */
+    theme?: DiagramTheme;
+}
 /** The color `wireStyle` draws a wire in when `checkPipeline` reported it. */
 declare const PROBLEM_COLOR = "#ff5d5d";
-/** A color per type: the one given, or the next in the palette in the order
+/** A color per type: the one given, or the next in `series` in the order
  *  types first appear on the pipeline's ports. */
-declare function typeColors(pipeline: EffectPipeline, given?: Readonly<Record<string, string>>): TypeColor;
+declare function typeColors(pipeline: EffectPipeline, given?: Readonly<Record<string, string>>, series?: readonly string[]): TypeColor;
 /** Whether `type` is one the pipeline's `types` mark as `control`. */
 declare function isControl(pipeline: EffectPipeline, type: string | undefined): boolean;
-/** The node style the shipped looks give a stage: dashed and dim when it is bypassed. */
-declare function stageStyle(stage: EffectStage): NodeStyle;
+/** The node style the shipped looks give a stage: the theme's default role, or dashed in its
+ *  muted role when the stage is bypassed. */
+declare function stageStyle(stage: EffectStage, theme?: DiagramTheme): NodeStyle;
 /** The edge style the shipped looks give a wire: `color`, dashed for a
  *  control wire, and `PROBLEM_COLOR` in place of `color` for a flagged one. */
 declare function wireStyle(color: string, control: boolean, problem: boolean): EdgeStyle;
@@ -171,6 +139,10 @@ interface DrawableWire {
 declare function drawableWires(pipeline: EffectPipeline): DrawableWire[];
 /** What a value row shows before a run fills it in. */
 declare const NO_VALUE = "\u2013";
+/** The ports a run shows values and previews on: a stage's outputs, or for a
+ *  stage with none, such as a sink, its inputs, so the end of a pipeline
+ *  shows what reached it. */
+declare function shownPorts(stage: EffectStage): readonly EffectPort[];
 /** The row id of the value row for an output, under its stage's body. */
 declare const valueRowId: (port: string) => string;
 /** The row id of the preview slot for an output, under its stage's body. */
@@ -193,8 +165,9 @@ interface RunRowOptions {
     };
 }
 /** The body rows of an ordinary stage: its title, a row of its ports when
- *  `withPorts` (inputs left, outputs right), then for each output its value
- *  row when `showValues` and its preview slot when `showPreviews`, then its
+ *  `withPorts` (inputs left, outputs right), then for each of its
+ *  `shownPorts` its value row when `showValues` and its preview slot when
+ *  `showPreviews`, then its
  *  params when `showParams`. */
 declare function stageRows(stage: EffectStage, opts: {
     showParams: boolean;
@@ -245,7 +218,7 @@ declare function symbolNameFor(stage: EffectStage, choice?: BranchChoice): Exclu
 declare function branchNode(stage: EffectStage, pipeline: EffectPipeline, choice?: BranchChoice, options?: BranchOptions): BranchNode;
 
 /** Options for the `compact` look. */
-interface CompactOptions {
+interface CompactOptions extends LookThemeOptions {
     /** Default `'bezier'`. */
     router?: DiagramRouter;
     /** Default 16. */
@@ -315,7 +288,7 @@ declare const EFFECT_MIN_SCALE = 0.5;
 declare function EffectChart<TOptions = never>({ pipeline: given, run, look, options, width, height, minScale, background, selected, onSelect, onProblems, className, }: EffectChartProps<TOptions>): react.JSX.Element;
 
 /** Options for the `lanes` look. */
-interface LanesOptions extends RunRowOptions {
+interface LanesOptions extends RunRowOptions, LookThemeOptions {
     /** The value types whose lanes come first, top down. The rest follow in
      *  the order their types first appear on the pipeline's ports. */
     lanes?: readonly string[];
@@ -341,16 +314,36 @@ interface LanesOptions extends RunRowOptions {
 declare const LANE_INSET = 6;
 /** The node id of the lane for a value type. */
 declare const laneId: (type: string) => string;
+/** The value type of the lane `laneId` named, or `undefined` for any other id. */
+declare const laneTypeOf: (id: string) => string | undefined;
 /** The lanes look: a horizontal lane per value type, and each stage standing
  *  across the lanes of the types it reads and writes, as tall as they are,
  *  its ports in their own lanes. A decision keeps its symbol's size, centered
- *  across its lanes. Columns run left to right in the order the signal flows.
- *  A wire runs around the stages between its ends along the lane edges, each
+ *  across its lanes. Columns run left to right in the order the signal flows,
+ *  and a group's members hold columns no other stage stands in. A wire runs around the stages between its ends along the lane edges, each
  *  sharing one on a track of its own. */
 declare const lanes: EffectLook<LanesOptions>;
 
+/** Options for the `nodeGraph` look. */
+interface NodeGraphOptions extends RunRowOptions, LookThemeOptions {
+    /** Default `'bezier'`. */
+    router?: DiagramRouter;
+    nodeGap?: number;
+    rankGap?: number;
+    /** A color per value type, over the palette's own. */
+    colors?: Readonly<Record<string, string>>;
+    /** Whether a stage lists its `params`. Default true. A decision's symbol
+     *  does not show params either way. */
+    showParams?: boolean;
+    /** Default `'auto'`. */
+    branch?: BranchChoice;
+}
+/** The node-graph look: every port a named row on its stage, a wire from port
+ *  to port in the color of what it carries, flowing left to right. */
+declare const nodeGraph: EffectLook<NodeGraphOptions>;
+
 /** Options for the `rack` look. */
-interface RackOptions extends RunRowOptions {
+interface RackOptions extends RunRowOptions, LookThemeOptions {
     /** The stage ids on the line, in order. Default the longest path over data wires. */
     chain?: readonly string[];
     /** Where what feeds the chain from the side sits. Default `'below'`. */
@@ -371,23 +364,277 @@ interface RackOptions extends RunRowOptions {
  *  order, and whatever feeds a stage from the side hung beside it. */
 declare const rack: EffectLook<RackOptions>;
 
-/** Options for the `nodeGraph` look. */
-interface NodeGraphOptions extends RunRowOptions {
-    /** Default `'bezier'`. */
-    router?: DiagramRouter;
-    nodeGap?: number;
-    rankGap?: number;
-    /** A color per value type, over the palette's own. */
-    colors?: Readonly<Record<string, string>>;
-    /** Whether a stage lists its `params`. Default true. A decision's symbol
-     *  does not show params either way. */
-    showParams?: boolean;
-    /** Default `'auto'`. */
-    branch?: BranchChoice;
+/** The looks an editor draws a doc in. */
+type EditorLook = 'nodeGraph' | 'rack' | 'lanes';
+/** Each editor look's options. Rack's `chain` is left out: a reorder follows
+ *  the wiring, and a chain given here would draw some other order. */
+interface EditorLookOptions {
+    nodeGraph: NodeGraphOptions;
+    rack: Omit<RackOptions, 'chain'>;
+    lanes: LanesOptions;
 }
-/** The node-graph look: every port a named row on its stage, a wire from port
- *  to port in the color of what it carries, flowing left to right. */
-declare const nodeGraph: EffectLook<NodeGraphOptions>;
+/** A look's drawing of a doc, and the way back from what the drawing reports
+ *  to the doc. A port id needs no mapping: box stages and decision symbols
+ *  both give each port its `EffectPort` id. */
+interface EditorScene extends EffectLookResult {
+    /** The stage a scene node is, or `undefined` for a group box, a lane, or anything else. */
+    stageOf(node: string): string | undefined;
+    /** The group a scene node is: a container under `nodeGraph`, a group box under the others. */
+    groupOf(node: string): string | undefined;
+    /** The wire a data edge id (`edgeIdOf`) draws, by its id in
+     *  `ensureWireIds(doc)`, so an id-less wire is found by the id it will get.
+     *  `undefined` for an edge standing in for more than one wire, such as
+     *  rack's arc over a skip. */
+    wireOf(edge: string): string | undefined;
+}
+/** The look's drawing of the doc's pipeline. Under `nodeGraph` every placed
+ *  stage is pinned at its place, so layered layout places only the stages
+ *  that have none, and each group is a container, at its `groupBoxes` box or
+ *  fitting its members; the other looks place every stage themselves and draw
+ *  groups as boxes around their members. `lanes` takes the doc's `laneOrder`
+ *  over its options' `lanes`. */
+declare function editorScene<L extends EditorLook = 'nodeGraph'>(doc: EffectDoc, look?: L, options?: EditorLookOptions[L]): EditorScene;
+
+/** Which look `EffectEditor` draws in, and that look's options. Keep the
+ *  options object's identity steady between renders. */
+type EffectEditorLookProps = {
+    look?: 'nodeGraph';
+    options?: NodeGraphOptions;
+} | {
+    look: 'rack';
+    options?: EditorLookOptions['rack'];
+} | {
+    look: 'lanes';
+    options?: LanesOptions;
+};
+/** Props for `EffectEditor`. */
+type EffectEditorProps = EffectEditorBaseProps & EffectEditorLookProps;
+/** `EffectEditor`'s props apart from its look. */
+interface EffectEditorBaseProps {
+    /** The pipeline and where its stages sit. The editor keeps none of it:
+     *  every edit comes back through `onChange` and shows once `doc` follows. */
+    doc: EffectDoc;
+    /** Hears each edit as the doc it makes, and a name for it fit for an undo
+     *  entry: 'Move', 'Connect', 'Delete', 'Reconnect', 'Edit route', 'Add stage',
+     *  'Reorder', 'Reorder lanes', 'Resize group', 'Group', 'Ungroup' or 'Rename group'. */
+    onChange: (next: EffectDoc, label: string) => void;
+    /** One run of the pipeline, drawn over it as `EffectChart` draws its
+     *  `run`, with the stage it is `at` outlined. */
+    run?: EffectRun;
+    /** A stage id, or null for none. */
+    selected?: string | null;
+    /** Hears each pick: a stage's id, or `null` for anything else, a wire included. */
+    onSelect?: (stage: string | null) => void;
+    /** A group id, or null for none: drawn picked while no stage is. */
+    selectedGroup?: string | null;
+    /** Hears each pick: a group's id, or `null` for anything else. */
+    onSelectGroup?: (group: string | null) => void;
+    /** CSS pixels. Omit both to fill the parent. */
+    width?: number;
+    height?: number;
+    background?: Paint;
+    className?: string;
+}
+/** What a `ref` on `EffectEditor` holds. */
+interface EffectEditorApi {
+    /** Adds a stage of type `type`. Under `nodeGraph` its top-left goes at the
+     *  world point under `client` when given, or in the first free spot in view
+     *  (`freeSpot`), and like a drag it pins every stage layout placed where it
+     *  shows, so nothing moves under it; the other looks place it themselves.
+     *  Returns the new stage's id. */
+    addStage(type: EffectStageType, client?: {
+        x: number;
+        y: number;
+    }): string;
+    /** Groups stages and groups, as `groupStages` does, and reports it as 'Group'.
+     *  Under `nodeGraph` it first pins every stage where it shows, as a drag
+     *  does. Returns the new group's id, or `null` for no ids. */
+    group(ids: readonly string[]): string | null;
+    /** Dissolves a group, as `ungroup` does, and reports it as 'Ungroup'. */
+    ungroup(id: string): void;
+    /** Opens the field a group's title is renamed in, over its title, or above
+     *  its box where it has none; a double-click on the title does
+     *  the same. Renaming reports 'Rename group'. */
+    renameGroup(id: string): void;
+}
+/** The pipeline-mode editor: a look's drawing of an effect pipeline, whose
+ *  ports wire output to input, and whose wires and stages reconnect and
+ *  delete. Under `nodeGraph` stages drag freely, and each group is a titled
+ *  box: drag a stage into or out of it, drag the box to carry what it holds,
+ *  resize it, or double-click its title to rename it; under `rack` and `lanes` a
+ *  stage on the main line drags along it to another place, rewiring the
+ *  pipeline, a group drags along it by its title, and a double-click on that
+ *  title renames it; under `lanes` a lane drags by its header. A selected
+ *  wire's route drags under every look: into `routes` under `nodeGraph`, and
+ *  into `lookRoutes` under the others, where it holds only while the wire's
+ *  ends stay put. Every edit is a doc handed to `onChange`. Text paints only in a registered font family,
+ *  as with `EffectChart`. */
+declare const EffectEditor: react.ForwardRefExoticComponent<EffectEditorProps & react.RefAttributes<EffectEditorApi>>;
+
+/** The reorders an editor installs under a look that places stages itself:
+ *  a main-line stage dragged along the line, a lane dragged by its header,
+ *  and a group dragged along the line by its title. */
+
+/** The action that drags a lane to another place among the lanes. */
+declare const REORDER_LANES_ACTION_ID = "diagram.reorderLanes";
+
+/** Routes a person drew under `rack` and `lanes`, which place every stage
+ *  themselves: each holds only while its wire's ends are where they were
+ *  drawn from. */
+
+/** The looks whose routes `lookRoutes` keeps. */
+type RoutedLook = keyof LookRoutes;
+/** Routes wire `wire` through `waypoints` under `look`, for as long as its
+ *  ends stay at `ends`, its from end first. No waypoints gives the wire back
+ *  to the look. */
+declare function setLookRoute(doc: EffectDoc, look: RoutedLook, wire: string, waypoints: readonly Vec2[], ends: readonly [Vec2, Vec2]): EffectDoc;
+/** `doc` without the look routes of wires it no longer has, or of the
+ *  `rewired` ones, whose ends now join other ports. */
+declare function pruneLookRoutes(doc: EffectDoc, rewired?: Iterable<string>): EffectDoc;
+/** The points of the ports edge `edge` joins as `specs` draw it, from end
+ *  first, or `undefined` when either end names no port. */
+declare function wireEnds(specs: readonly DiagramSpec[], edge: string): [Vec2, Vec2] | undefined;
+/** `specs`, drawn from `built`, with each wire `doc` routed under `look`
+ *  drawn through its waypoints where its ends are still where they were. An
+ *  edge's own waypoints win over the route a look worked out (`routed`), as
+ *  for any `DataEdge`. `specs` itself when no route holds. */
+declare function applyLookRoutes(specs: readonly DiagramSpec[], doc: EffectDoc, look: EditorLook, built: EditorScene): readonly DiagramSpec[];
+
+type Ref = {
+    stage: string;
+    port: string;
+};
+/** `base` if no stage has it, else `base-2`, `base-3`, … */
+declare function nextStageId(p: EffectPipeline, base: string): string;
+/** The first of `w1`, `w2`, … no wire has. */
+declare function nextWireId(p: EffectPipeline): string;
+/** Appends the stage, pinning it at `at` when given. */
+declare function addStage(doc: EffectDoc, stage: EffectStage, at?: Vec2): EffectDoc;
+/** Drops the stages with their wires, places, routes and group memberships,
+ *  and any group that leaves empty, with its box. */
+declare function removeStages(doc: EffectDoc, ids: readonly string[]): EffectDoc;
+/** Routes wire `wire` through `points`; none clears its route. */
+declare function setWireRoute(doc: EffectDoc, wire: string, points: readonly Vec2[]): EffectDoc;
+/** Mints an id when the wire has none. */
+declare function addWire(doc: EffectDoc, wire: EffectWire): EffectDoc;
+/** An id-less wire is never matched: run `ensureWireIds` first. */
+declare function removeWires(doc: EffectDoc, ids: readonly string[]): EffectDoc;
+/** An id-less wire is never matched: run `ensureWireIds` first. */
+declare function reconnectWire(doc: EffectDoc, id: string, end: 'from' | 'to', to: Ref): EffectDoc;
+/** Replaces a param's control and re-formats its display value. */
+declare function setParam(doc: EffectDoc, stage: string, param: string, control: EffectParamControl): EffectDoc;
+/** Pins each stage at its new position. */
+declare function moveStages(doc: EffectDoc, moves: readonly {
+    id: string;
+    x: number;
+    y: number;
+}[]): EffectDoc;
+/** Sets the value types whose lanes `lanes` draws first, top down. */
+declare function setLaneOrder(doc: EffectDoc, order: readonly string[]): EffectDoc;
+/** Mints ids for id-less wires; returns `doc` itself when none lacks one. */
+declare function ensureWireIds(doc: EffectDoc): EffectDoc;
+/** An output into an input of the same type, both existing, on different stages. */
+declare function canWire(p: EffectPipeline, from: Ref, to: Ref): boolean;
+
+/** Edits to a pipeline's groups: what each holds, its label, and its box under `nodeGraph`. */
+
+/** `group` if no stage or group has it, else `group-2`, `group-3`, … */
+declare function nextGroupId(p: EffectPipeline): string;
+/**
+ * Groups `ids`, stages or groups, in a new group whose id is
+ * {@link nextGroupId}'s. It nests inside the group all of them share, where
+ * the first of them was; otherwise it goes at the top level, taking them out
+ * of the groups they were in.
+ */
+declare function groupStages(doc: EffectDoc, ids: readonly string[], label?: string): EffectDoc;
+/** Dissolves group `id`: its members go to its parent group, in its place, or to the top level. */
+declare function ungroup(doc: EffectDoc, id: string): EffectDoc;
+/** Sets group `id`'s label; an empty one removes it. */
+declare function renameGroup(doc: EffectDoc, id: string, label: string): EffectDoc;
+/**
+ * Moves `ids`, stages or groups, into group `group`, or to the top level for
+ * `null`, out of the groups they were in. A group left empty goes too unless
+ * it has a box. `doc` itself when `group` is unknown or inside one of `ids`.
+ */
+declare function moveToGroup(doc: EffectDoc, ids: readonly string[], group: string | null): EffectDoc;
+/** Sets group `id`'s box under `nodeGraph`; `null` has it fit its members again. */
+declare function setGroupBox(doc: EffectDoc, id: string, box: EffectBox | null): EffectDoc;
+/** Group `id` and every stage and group inside it. */
+declare function groupContents(doc: EffectDoc, id: string): {
+    stages: Set<string>;
+    groups: Set<string>;
+};
+/**
+ * Moves group `id` by `offset`: the places of the stages inside it, its box
+ * and the boxes inside it, and the routes of wires with both ends inside it.
+ * A stage with no place stays where layout puts it.
+ */
+declare function moveGroup(doc: EffectDoc, id: string, offset: Vec2): EffectDoc;
+
+/** What an evaluator is handed for one stage of one run. */
+interface EffectEvalContext {
+    stage: EffectStage;
+    /** The value on each input a wire feeds, by port id. An input no reached
+     *  wire feeds is absent. */
+    inputs: Readonly<Record<string, unknown>>;
+    /** Each param's control value (its display string when it has no
+     *  control), by param id, or by label for a param without one. */
+    params: Readonly<Record<string, unknown>>;
+    /** The values the run was handed (`RunPipelineOptions.sources`), for a
+     *  source stage to read. */
+    sources: Readonly<Record<string, unknown>>;
+    /** Seconds of play time. */
+    time: number;
+    /** Aborted when the run is abandoned. */
+    signal: AbortSignal;
+}
+/** What one stage produced: a value per output it fed, by port id, and for a
+ *  decision the output it chose. An output left out feeds nothing. */
+interface EffectEvalResult {
+    outputs: Readonly<Record<string, unknown>>;
+    taken?: string;
+}
+/** Evaluates one stage. Throw to fail it: the run records the message as the
+ *  stage's `error` and leaves what it feeds unreached. */
+type EffectEvaluator = (ctx: EffectEvalContext) => EffectEvalResult | Promise<EffectEvalResult>;
+/** Evaluators by stage `type`. */
+type EffectEvaluators = Readonly<Record<string, EffectEvaluator>>;
+/** How a run shows, previews, and lets go of the values of one value type. */
+interface EffectValueKind {
+    /** The value as text for a value row. Default `String(value)` for a
+     *  number, string, or boolean, and nothing for anything else. */
+    show?(value: unknown): string;
+    /** The value as a picture of `size`, for a preview slot. */
+    preview?(value: unknown, size: {
+        width: number;
+        height: number;
+    }): ImageBitmap | Promise<ImageBitmap> | undefined;
+    /** Frees what the value holds, once nothing reads it again. */
+    dispose?(value: unknown): void;
+}
+/** Value kinds by value type. */
+type EffectValueKinds = Readonly<Record<string, EffectValueKind>>;
+
+/** Evaluators for `IMAGE_STAGE_TYPES`, drawing on `OffscreenCanvas` 2D. An
+ *  image or mask is an `ImageBitmap`; a source puts out `sources.image`. */
+declare const imageEvaluators: EffectEvaluators;
+
+/** Stage types over images, each with an evaluator in `imageEvaluators`.
+ *  Ports carry `image`, `number`, or `mask`, and a wire joins only like to
+ *  like. Mark `number` as control in a pipeline's `types`. */
+declare const IMAGE_STAGE_TYPES: readonly EffectStageType[];
+
+/** A test card of `size` (a square's side, or a width and height): color bars
+ *  over a gray ramp, with a white ring in the middle, so every stage has edges,
+ *  hues, and levels to work on. */
+declare function testCard(size: number | {
+    width: number;
+    height: number;
+}): ImageBitmap;
+
+/** Value kinds for `IMAGE_STAGE_TYPES`: an image or mask shows as its size and
+ *  previews as a copy scaled to the slot; a number shows to three places. */
+declare const imageValueKinds: EffectValueKinds;
 
 /** The looks that ship, by name. */
 declare const EFFECT_LOOKS: Readonly<{
@@ -403,15 +650,133 @@ declare const EFFECT_LOOKS: Readonly<{
 /** Stage ids of the longest path over data wires, sources first. */
 declare function mainChain(pipeline: EffectPipeline): string[];
 
+/** The outline of the stage a run taken a step at a time is `at`. */
+declare const AT_COLOR = "#ffc94d";
 /**
  * `specs` as `run` leaves them: a stage the run never reached faded, with its
  * wires; a decision's wires to the outputs it did not take faded; each value
  * row a look kept filled in; a `switch` thrown to the output its decision
- * took; and each stage's cost written above its corner.
+ * took; each stage's cost, or its error in `PROBLEM_COLOR`, written above
+ * its corner; and the stage the run is `at` outlined in `AT_COLOR`.
  * No run, no change.
  */
 declare function paintRun(pipeline: EffectPipeline, specs: readonly DiagramSpec[], run: EffectRun | undefined, exits?: EffectLookResult['exits']): DiagramSpec[];
 /** A cost in milliseconds, to three figures. */
 declare function costText(ms: number): string;
 
-export { BRANCH_SYMBOLS, type BranchChoice, type BranchNode, type BranchOptions, type BranchSymbol, COMPACT_PADDING, type CompactOptions, type DrawableWire, EFFECT_LOOKS, EFFECT_MIN_SCALE, EffectChart, type EffectChartProps, type EffectGroup, type EffectLook, type EffectLookResult, type EffectPipeline, type EffectPort, type EffectProblem, type EffectRun, type EffectStage, type EffectStageRun, type EffectType, type EffectWire, LANE_INSET, type LanesOptions, NO_VALUE, type NodeGraphOptions, PREVIEW_SIZE, PROBLEM_COLOR, type RackOptions, type RunRowOptions, type TypeColor, branchNode, checkPipeline, compact, costText, drawableWires, exitLabel, isControl, kindOf, laneId, lanes, mainChain, nodeGraph, paintRun, portOn, previewRowId, rack, stageRows, stageStyle, symbolNameFor, typeColors, uniqueGroups, uniqueStages, valueRowId, wireEdges, wireStyle };
+/** The order a run evaluates stages in, and the stages it never can. */
+interface RunOrder {
+    /** Every stage outside a cycle, each after every stage that feeds it. */
+    order: string[];
+    /** The stages on a cycle of wires, in stage order. */
+    cyclic: string[];
+}
+/** The stages topologically over data and control wires alike, stable by
+ *  stage order: of the stages ready to go, the earliest goes first. A stage on
+ *  a cycle is left out, and so are its wires. */
+declare function runOrder(pipeline: EffectPipeline): RunOrder;
+
+/** Options for `runPipeline` and `createEffectRunner`. */
+interface RunPipelineOptions {
+    /** By stage `type`. A stage whose type has none fails. */
+    evaluators: EffectEvaluators;
+    /** By value type. A value whose type has none shows as text when it is a
+     *  number, string, or boolean, and has no preview. */
+    kinds?: EffectValueKinds;
+    /** Handed to every evaluator, for source stages. The run never disposes them. */
+    sources?: Readonly<Record<string, unknown>>;
+    /** Seconds of play time. Default 0. */
+    time?: number;
+    signal?: AbortSignal;
+    /** Make a preview of each output whose kind can. Default true. */
+    previews?: boolean;
+    /** The size previews are made at: `RunRowOptions.previewSize`. Default `PREVIEW_SIZE`. */
+    previewSize?: number | {
+        width: number;
+        height: number;
+    };
+}
+/** A run taken a stage at a time. */
+interface EffectPass {
+    /** Evaluates the next stage the run reaches, passing over those it does
+     *  not, and returns its id; `undefined` once none is left. */
+    step(): Promise<string | undefined>;
+    /** The run so far: a new object after each step. */
+    readonly run: EffectRun;
+    /** Disposes every value the pass made. Its previews are the caller's. */
+    dispose(): void;
+}
+/** A pass over `pipeline` that has evaluated nothing yet. */
+declare function createPass(pipeline: EffectPipeline, opts: RunPipelineOptions): EffectPass;
+
+/**
+ * One whole run of `pipeline`, stage by stage in `runOrder`. A stage with
+ * inputs none of which a value reaches is skipped; a bypassed stage passes its
+ * first input of each output's type through; a throwing evaluator sets the
+ * stage's `error` and leaves what it feeds unreached; stages on a cycle never
+ * run. Every value the run made is disposed before it resolves; the previews
+ * in the run are the caller's to close. Rejects once `signal` aborts.
+ */
+declare function runPipeline(pipeline: EffectPipeline, opts: RunPipelineOptions): Promise<EffectRun>;
+
+/** What `createEffectRunner` is made with. */
+interface EffectRunnerOptions extends Omit<RunPipelineOptions, 'time' | 'signal'> {
+    pipeline: EffectPipeline;
+}
+/** What a runner shows now. A new object whenever any of it changes. */
+interface EffectRunnerState {
+    /** The run to draw: the last whole run, or the step run so far. */
+    run: EffectRun | undefined;
+    playing: boolean;
+    /** Seconds of play time. */
+    time: number;
+}
+/** Runs one pipeline over and over: whole, a stage at a time, or every frame
+ *  while playing. It owns the values its runs make and the previews in them. */
+interface EffectRunner {
+    readonly state: EffectRunnerState;
+    /** One whole run at the current play time. */
+    run(): Promise<void>;
+    /** Evaluates the next stage the run reaches and makes it the run's `at`;
+     *  after the last stage, starts over. */
+    step(): Promise<void>;
+    play(): void;
+    pause(): void;
+    /** Pauses, drops the run, and sets the clock back to zero. */
+    reset(): void;
+    /** Moves the play clock on by `seconds` while playing, and starts a run
+     *  unless one is still going. A frame source calls it once a frame. */
+    advance(seconds: number): void;
+    /** The next run, step, or played frame follows `pipeline`. A step run under
+     *  way starts over. */
+    setPipeline(pipeline: EffectPipeline): void;
+    setSources(sources: Readonly<Record<string, unknown>>): void;
+    setOptions(opts: Partial<Omit<EffectRunnerOptions, 'pipeline' | 'sources'>>): void;
+    /** Says `run` is on screen: every preview of an older run that `run` does
+     *  not show is closed. */
+    drawn(run: EffectRun | undefined): void;
+    subscribe(listener: () => void): () => void;
+    /** Resets and closes every preview it still holds. The runner stays usable. */
+    dispose(): void;
+}
+/** A runner over `opts.pipeline`, with nothing run yet. */
+declare function createEffectRunner(opts: EffectRunnerOptions): EffectRunner;
+
+/** Options for `useEffectRunner`: the runner's, which it follows as they
+ *  change, and how its play loop is gated and clocked. */
+interface UseEffectRunnerOptions extends EffectRunnerOptions, Pick<VisibleRafOptions, 'target' | 'requestFrame' | 'cancelFrame'> {
+}
+/** What `useEffectRunner` returns: the runner's state, and the runner to drive. */
+interface EffectRunnerHandle extends EffectRunnerState {
+    runner: EffectRunner;
+}
+/**
+ * A runner for the life of the component. While it plays, every visible frame
+ * advances its clock by the time since the last and starts a run once the last
+ * has finished; time spent hidden does not count. Each run it hands back is
+ * taken as drawn after the render that shows it, so the previews of the runs
+ * before it are closed then.
+ */
+declare function useEffectRunner(opts: UseEffectRunnerOptions): EffectRunnerHandle;
+
+export { AT_COLOR, BRANCH_SYMBOLS, type BranchChoice, type BranchNode, type BranchOptions, type BranchSymbol, COMPACT_PADDING, type ChainLinks, type CompactOptions, type DrawableWire, EFFECT_LOOKS, EFFECT_MIN_SCALE, type EditorLook, type EditorLookOptions, type EditorScene, EffectBox, EffectChart, type EffectChartProps, EffectDoc, EffectEditor, type EffectEditorApi, type EffectEditorBaseProps, type EffectEditorLookProps, type EffectEditorProps, type EffectEvalContext, type EffectEvalResult, type EffectEvaluator, type EffectEvaluators, EffectGroup, type EffectLook, type EffectLookResult, EffectParamControl, type EffectPass, EffectPipeline, EffectPort, type EffectProblem, EffectRun, type EffectRunner, type EffectRunnerHandle, type EffectRunnerOptions, type EffectRunnerState, EffectStage, EffectStageType, type EffectValueKind, type EffectValueKinds, EffectWire, IMAGE_STAGE_TYPES, LANE_INSET, LOOK_THEME, type LanesOptions, type LookOrder, LookRoutes, type LookThemeOptions, NO_VALUE, type NodeGraphOptions, PREVIEW_SIZE, PROBLEM_COLOR, REORDER_LANES_ACTION_ID, type RackOptions, type RoutedLook, type RunOrder, type RunPipelineOptions, type RunRowOptions, type TypeColor, type UseEffectRunnerOptions, addStage, addWire, applyLookRoutes, branchNode, canMoveInChain, canWire, chainLinks, checkPipeline, compact, costText, createEffectRunner, createPass, drawableWires, editorScene, ensureWireIds, exitLabel, groupContents, groupStages, imageEvaluators, imageValueKinds, isControl, kindOf, laneId, laneTypeOf, lanes, mainChain, moveGroup, moveInChain, moveStages, moveToGroup, nextGroupId, nextStageId, nextWireId, nodeGraph, paintRun, portOn, previewRowId, pruneLookRoutes, rack, reconnectWire, removeStages, removeWires, renameGroup, runOrder, runPipeline, setGroupBox, setLaneOrder, setLookRoute, setParam, setWireRoute, shownPorts, stageRows, stageStyle, symbolNameFor, testCard, typeColors, ungroup, uniqueGroups, uniqueStages, useEffectRunner, valueRowId, wireEdges, wireEnds, wireStyle };