@weasel-js/diagram 1.10.1 → 1.11.1

package/dist/effect.d.ts

@@ -0,0 +1,782 @@
+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-B-iEwKZp.js';
+import { a as Row, M as MeasureRowText } from './types-BbHunLXm.js';
+import * as react from 'react';
+import { Paint } from '@weasel-js/core';
+import { Vec2 } from '@weasel-js/core/math';
+import { VisibleRafOptions } from '@weasel-js/react';
+import '@weasel-js/geom';
+
+/** 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 {
+    kind: 'missing-stage' | 'missing-port' | 'wrong-direction' | 'type-mismatch' | 'duplicate-stage' | 'duplicate-port' | 'duplicate-group' | 'missing-member' | 'bad-split';
+    message: string;
+    stage?: string;
+    port?: string;
+    /** Index into `pipeline.wires`. */
+    wire?: number;
+    group?: string;
+}
+/** Everything wrong with `pipeline`. Never throws. */
+declare function checkPipeline(pipeline: EffectPipeline): EffectProblem[];
+
+/** What every look shares: how a type is colored, how a stage and a wire are
+ *  styled, and the lookups a look does over a pipeline. */
+
+/** The color of a value type, for a port or a wire. Answers `undefined`, a
+ *  port with no type, with a neutral color. */
+type TypeColor = (type: string | undefined) => string;
+/** What a look hands back: `diagramScene`'s two arguments, and its colors. */
+interface EffectLookResult {
+    data: DiagramData;
+    scene: DiagramSceneOptions;
+    color: TypeColor;
+    /** Edges standing in for a decision's exits where the look draws no
+     *  decision, keyed by edge id: which stage chose, and by which output. A
+     *  run reads that stage's `taken` for them. */
+    exits?: ReadonlyMap<string, {
+        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 `series` in the order
+ *  types first appear on the pipeline's ports. */
+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: 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;
+/** Stages with the repeats dropped, first one kept. `diagramScene` throws on
+ *  a repeated id, so a look builds its nodes from these. */
+declare function uniqueStages(pipeline: EffectPipeline): EffectStage[];
+/** Groups with the repeats dropped, first one kept, and none that has the id
+ *  of a stage: `diagramScene` throws on an id that names two things. */
+declare function uniqueGroups(pipeline: EffectPipeline): EffectGroup[];
+/** The port called `id` among a stage's inputs and outputs, inputs first. */
+declare function portOn(stage: EffectStage | undefined, id: string): EffectPort | undefined;
+/** A stage's `kind` as the shipped looks read it: any value they do not know is `'stage'`. */
+declare function kindOf(stage: EffectStage): 'stage' | 'decision' | 'source' | 'sink';
+/** A wire with both ends present, and what a look needs to draw it. */
+interface DrawableWire {
+    wire: EffectWire;
+    /** Index into `pipeline.wires`. */
+    index: number;
+    /** The value type of the port the wire leaves. */
+    type: string | undefined;
+    /** `checkPipeline` reported it. */
+    problem: boolean;
+    fromStage: EffectStage;
+    toStage: EffectStage;
+}
+/** The wires a look can draw: each one whose two stages and two ports exist,
+ *  in the pipeline's order. A wire `checkPipeline` reported and that still has
+ *  both ends is kept, with `problem` set. */
+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. */
+declare const previewRowId: (port: string) => string;
+/** `RunRowOptions.previewSize`'s default: a 48-unit square. */
+declare const PREVIEW_SIZE = 48;
+/** The rows a look keeps on each stage for what an `EffectRun` shows there.
+ *  Kept from the start, so a run fills them in without the chart laying out
+ *  again. A decision's symbol keeps neither. */
+interface RunRowOptions {
+    /** A row per output for its value. Default false. */
+    showValues?: boolean;
+    /** A slot per output for its preview, after its value row. Default false. */
+    showPreviews?: boolean;
+    /** The preview slot's size: a square's side, or a width and height. A
+     *  preview is stretched to fill it. Default `PREVIEW_SIZE`. */
+    previewSize?: number | {
+        width: number;
+        height: number;
+    };
+}
+/** The body rows of an ordinary stage: its title, a row of its ports when
+ *  `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;
+    withPorts: boolean;
+} & RunRowOptions): Row[];
+/** What a wire is called: its own label, or for a wire leaving a decision the
+ *  exit's label, which defaults to the exit's id. Any other wire has no name. */
+declare function exitLabel(d: DrawableWire): string | undefined;
+/** One edge per drawable wire, from port to port, named by `exitLabel` and
+ *  styled by `wireStyle` in its type's color. */
+declare function wireEdges(pipeline: EffectPipeline, color: TypeColor): {
+    edge: DataEdge;
+    style: EdgeStyle;
+}[];
+
+/** What every branch symbol is built from: its types, where its ports go, and
+ *  the diamond each one falls back to. */
+
+/** What a branch symbol draws: a data node without its id or style, which the look adds. */
+type BranchNode = Pick<DataNode, 'outline' | 'lines' | 'rows' | 'ports' | 'marks' | 'width' | 'height' | 'padding'>;
+/** How a look wants a branch symbol drawn. */
+interface BranchOptions {
+    /** The edge control inputs enter by: the side the stages driving them sit
+     *  on. Default `'top'`. */
+    controlSide?: 'top' | 'bottom';
+    /** The style the look draws the stage's node in: lines, dots and ticks
+     *  take its `text` color. Default `stageStyle(stage)`. */
+    style?: NodeStyle;
+    /** The colors of a `bar`'s bands and a `crossover`'s curves, lowest
+     *  first, repeating. Default a palette of four, or for a bypassed stage
+     *  `style.stroke` for every band. */
+    tints?: readonly string[];
+}
+/** Draws one decision stage, with a port for each of its inputs and outputs. */
+type BranchSymbol = (stage: EffectStage, pipeline: EffectPipeline, options?: BranchOptions) => BranchNode;
+
+/** Which symbol a decision draws as: one by name, or `'auto'` for a bar when
+ *  the stage has a sound `split` and a diamond otherwise. */
+type BranchChoice = 'auto' | 'diamond' | 'bar' | 'demux' | 'switch' | 'hexagon' | 'step' | 'comparator' | 'crossover' | 'fork';
+/** Each branch symbol by name. One called on a stage it cannot draw draws
+ *  the `diamond` instead: a `bar`, `step` or `crossover` with no sound split,
+ *  or a `switch` or `comparator` without exactly two exits. */
+declare const BRANCH_SYMBOLS: Readonly<Record<Exclude<BranchChoice, 'auto'>, BranchSymbol>>;
+/** The symbol `choice` comes to for `stage`: `'auto'` a bar for a sound
+ *  split, and any symbol that cannot draw the stage the diamond. */
+declare function symbolNameFor(stage: EffectStage, choice?: BranchChoice): Exclude<BranchChoice, 'auto'>;
+/** The node a decision stage draws as, by the symbol `choice` comes to. */
+declare function branchNode(stage: EffectStage, pipeline: EffectPipeline, choice?: BranchChoice, options?: BranchOptions): BranchNode;
+
+/** Options for the `compact` look. */
+interface CompactOptions extends LookThemeOptions {
+    /** Default `'bezier'`. */
+    router?: DiagramRouter;
+    /** Default 16. */
+    nodeGap?: number;
+    /** Default 48. */
+    rankGap?: number;
+    /** A color per value type, over the palette's own. */
+    colors?: Readonly<Record<string, string>>;
+    /** Default `'hexagon'`, the one symbol that keeps a decision one row tall. */
+    branch?: BranchChoice;
+}
+/** Between a compact stage's outline and its title. */
+declare const COMPACT_PADDING = 4;
+/** The compact look: each stage one line, its title alone, and no ports
+ *  drawn; the wires between two stages one line between them. For a
+ *  pipeline too big to read as a node graph. */
+declare const compact: EffectLook<CompactOptions>;
+
+/** Props for `EffectChart`. */
+interface EffectChartProps<TOptions = never> {
+    /** Compared by its JSON, so it may be rebuilt on every render: the chart
+     *  lays out again only when that changes. A value JSON drops or flattens
+     *  in a stage's `data` (a function, a `Map`) is not seen changing. */
+    pipeline: EffectPipeline;
+    /** One run of the pipeline, drawn over it: stages it never reached and
+     *  branches it did not take faded, each stage's cost above its corner, and
+     *  each output's value and preview in the rows a look keeps for them
+     *  (`showValues`, `showPreviews`). It may change every frame: the chart
+     *  neither lays out again nor refits, and repaints only what changed. A
+     *  preview the next run no longer shows has its texture freed then. */
+    run?: EffectRun;
+    /** How the pipeline is drawn. Default `nodeGraph`. */
+    look?: EffectLook<TOptions>;
+    /** The look's options. Keep the object's identity steady between renders,
+     *  or the chart lays out again on each one. */
+    options?: TOptions;
+    /** CSS pixels. Omit both to fill the parent, which then needs a size of
+     *  its own. The chart refits when its size changes, until the user pans or
+     *  zooms. */
+    width?: number;
+    height?: number;
+    /** The smallest scale the chart opens at. A chart that does not fit whole
+     *  at it opens at it anyway, anchored at its start, and the rest is a pan
+     *  away. Default `EFFECT_MIN_SCALE`. */
+    minScale?: number;
+    /** What the canvas paints behind the chart. Unset, it is transparent; the
+     *  shipped looks are drawn for a dark ground. */
+    background?: Paint;
+    /** A stage id, or null for none. */
+    selected?: string | null;
+    /** Hears each pick: a stage's id, or `null` for anything else. Only a
+     *  stage can be picked: a click on a group box or a lane lands on the
+     *  canvas behind it. The canvas keeps its own highlight on the stage picked;
+     *  only a change to `selected` moves it. */
+    onSelect?: (stage: string | null) => void;
+    /** What `checkPipeline` found. Called once on mount, and again each time
+     *  the pipeline's content changes. */
+    onProblems?: (problems: readonly EffectProblem[]) => void;
+    /** A class for the canvas element. */
+    className?: string;
+}
+/** `EffectChart`'s default `minScale`: the shipped looks' 12px titles at 6px, the smallest still legible. */
+declare const EFFECT_MIN_SCALE = 0.5;
+/** A chart of an effects pipeline: pan, zoom, and pick a stage. Text paints
+ *  only in a registered font family, so call `registerCanvasFont('sans-serif')`
+ *  once before mounting one. */
+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, 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[];
+    /** The least height of a lane. A lane grows past it until what stands in
+     *  it fits. Default 48. */
+    laneHeight?: number;
+    /** Between one column of stages and the next. Default 40. */
+    rankGap?: number;
+    /** Default `'bezier'`. */
+    router?: DiagramRouter;
+    /** A color per value type, over the palette's own. */
+    colors?: Readonly<Record<string, string>>;
+    /** Whether a stage lists its `params`. Default true. */
+    showParams?: boolean;
+    /** Default `'auto'`. */
+    branch?: BranchChoice;
+    /** Measures text, as `diagramScene` takes it, for sizing stages before
+     *  the lanes are cut to fit them. It is handed on in the look's `scene`. */
+    measure?: MeasureRowText;
+}
+/** How far a stage stands inside the first and last lane it touches, at
+ *  least: more beside a lane edge that wires run along on several tracks. */
+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,
+ *  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, 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'`. */
+    side?: 'below' | 'above';
+    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;
+    /** Draw a decision that only skips ahead as an arc over what it skips. Default true. */
+    collapseSkips?: boolean;
+}
+/** The rack look: the main signal on one straight line with its stages in
+ *  order, and whatever feeds a stage from the side hung beside it. */
+declare const rack: EffectLook<RackOptions>;
+
+/** 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;
+}
+/** 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<{
+    nodeGraph: EffectLook<NodeGraphOptions>;
+    rack: EffectLook<RackOptions>;
+    lanes: EffectLook<LanesOptions>;
+    compact: EffectLook<CompactOptions>;
+}>;
+
+/** Which stages a pipeline's main signal runs through, and which decisions on
+ *  that run only choose between going on and skipping ahead. */
+
+/** 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; 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;
+
+/** 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 };