@weasel-js/diagram 1.11.0 → 1.11.1

package/dist/{fromData-GKqRgPFs.d.ts → dataTypes-B-iEwKZp.d.ts}

@@ -1,32 +1,29 @@
-import { DerivedDep, PoseDescriptor, NodeShapeEntry, MarkerRef, AddNodeSpec, Stroke, RectPose } from '@weasel-js/core';
-import { P as PortAnchor, D as DiagramGroup, R as RowTextStyle, a as Row, O as Outline, b as PortSpec, B as BodySpec, L as LayoutPorts, c as LayoutFn, d as LayoutOptions, M as MeasureRowText, e as DiagramNode } from './body-2lC7IiIA.js';
+import { DerivedDep, PoseDescriptor, NodeShapeEntry, MarkerRef, Page, PageLayoutOptions, AddNodeSpec, Stroke, RectPose } from '@weasel-js/core';
 import { Vec2 } from '@weasel-js/core/math';
+import { E as EdgeHop, S as StyleField, P as PortAnchor, D as DiagramGroup, R as RowTextStyle, a as Row, O as Outline, b as PortSpec, B as BodySpec, c as DiagramLabel, L as LayoutPorts, d as LayoutFn, e as LayoutOptions, M as MeasureRowText, f as DiagramNode } from './types-BbHunLXm.js';
 
 /**
- * The label trait: where along its edge a label sits. Data only — placing the
- * label on the route is `label`'s job, so layout can read one without
- * reaching the scene.
+ * Off-page markers as data: what a connector cut at the page gap holds, and
+ * what each of its two tags holds. The pass that writes both is `install`.
  */
-
-/** Where along an edge a label sits. */
-interface DiagramLabel {
-    /** `'start'`, `'mid'` and `'end'` are 0, 0.5 and 1; a number is that
-     *  fraction of the route's length. `{ near }` is the point on the route
-     *  nearest `near`, in world coordinates — where `layered` leaves a label
-     *  room — so a bend added or removed elsewhere leaves the label on the
-     *  stretch it was on. */
-    at: 'start' | 'mid' | 'end' | number | {
-        near: Vec2;
-    };
-    /** World units between the route and the label's near side, to the **left
-     *  of the direction of travel** — above a left-to-right edge. Default 0,
-     *  which centers the label on the line. */
-    offset?: number;
+/** A connector whose ends sit on different pages: its reference letter, and
+ *  the pages its `from` and `to` ends are on. */
+interface OffPageSplit {
+    ref: string;
+    from: string;
+    to: string;
+}
+/** Which end of which connector a tag names the far page for. */
+interface OffPageTag {
+    edge: string;
+    end: 'from' | 'to';
 }
-/** The label trait on a node's data, or `null`. */
-declare function diagramLabelOf(node: {
+/** The id of the tag at end `end` of connector `edgeId`. */
+declare const offPageTagId: (edgeId: string, end: "from" | "to") => string;
+/** The off-page tag trait on a node's data (`data.diagram.offPageTag`), or `null`. */
+declare function offPageTagOf(node: {
     data: unknown;
-}): DiagramLabel | null;
+}): OffPageTag | null;
 
 /**
  * The edge trait: what an edge's `data` says about its ends and its route, and
@@ -61,10 +58,27 @@ interface DiagramEdge {
      *  them, layout owns the route and rewrites it on its next run; once anyone
      *  edits them, they are the author's and layout leaves them alone. */
     laidOut?: readonly Vec2[];
+    /** The bends between the ends that the obstacle-avoiding router last
+     *  computed, kept so the edge draws without rerouting. The router owns it,
+     *  and while it is here each end aims at its nearest bend. */
+    route?: readonly Vec2[];
+    /** Where it bows over the connectors drawn before it, as the line-jump
+     *  pass last computed. Literal, so any reader draws them. */
+    hops?: readonly EdgeHop[];
+    /** Set while its ends sit on different pages, when it draws as two stubs
+     *  ending at off-page tags. The off-page pass owns it (`installOffPageMarkers`). */
+    offPage?: OffPageSplit;
+    /** The theme role it is drawn in. Unset, the theme's own connector style. */
+    style?: string;
+    /** The colors the author set by hand, which a theme leaves as they are. */
+    ownStyle?: readonly StyleField[];
 }
 /** Whether layout may rewrite this edge's route: it has no waypoints, or only
  *  the ones layout last wrote. */
 declare function layoutOwnsRoute(edge: DiagramEdge): boolean;
+/** Whether layout writes this edge's waypoints: it owns the route, and the
+ *  edge is not routed around obstacles, whose bends are never stops. */
+declare function layoutWritesRoute(edge: DiagramEdge): boolean;
 /** The edge trait on a node's data, or `null`. */
 declare function diagramEdgeOf(node: {
     data: unknown;
@@ -183,13 +197,86 @@ declare function registerMarkShape<TPose>(opts?: {
     geometry?: PoseDescriptor<TPose>;
 }): () => void;
 
+/** The face a diagram node's text is set in. */
+type DiagramTextStyle = {
+    fontFamily: string;
+    fontSize: number;
+    fontWeight?: number;
+    align?: 'center';
+};
+type Font = {
+    fontFamily: string;
+    fontSize: number;
+};
+/** The face a body row's text is set in. A label row's is centered in the row. */
+declare function rowTextStyle(row: Row | undefined, font: Font): DiagramTextStyle;
+
+/** The roles every shipped theme styles, with the name a picker shows. */
+declare const DIAGRAM_ROLES: readonly [{
+    readonly id: "default";
+    readonly label: "Default";
+}, {
+    readonly id: "accent";
+    readonly label: "Accent";
+}, {
+    readonly id: "muted";
+    readonly label: "Muted";
+}, {
+    readonly id: "positive";
+    readonly label: "Positive";
+}, {
+    readonly id: "warning";
+    readonly label: "Warning";
+}, {
+    readonly id: "negative";
+    readonly label: "Negative";
+}];
+/** The id of one of {@link DIAGRAM_ROLES}. A theme may style roles of its own besides. */
+type DiagramRole = (typeof DIAGRAM_ROLES)[number]['id'];
+
+/** The face a theme sets diagram text in. A text row keeps its own size. */
+interface DiagramFont {
+    family: string;
+    size: number;
+}
 /**
- * `diagramScene` — a laid-out diagram from plain `{ nodes, edges }`.
- *
- * Every box is a `buildBody` body, so a data node can say anything a body
- * can: outline, rows, padding, ports. Sizes are estimated from character
- * counts unless `measure` is given, so layout runs without a canvas and gives
- * the same answer in node and in a browser.
+ * A document's colors and face. Applying one writes literal colors into the
+ * scene, so nothing that reads the scene needs the theme to draw it.
+ */
+interface DiagramTheme {
+    id: string;
+    name: string;
+    /** A shape's fill, stroke and text by role id. A connector given a role takes that role's stroke. */
+    roles: Readonly<Record<string, NodeStyle>>;
+    /** The names a picker shows for roles beyond {@link DIAGRAM_ROLES}, or for a shipped role renamed. */
+    roleLabels?: Readonly<Record<string, string>>;
+    /** The role a shape or connector naming none, or naming one this theme lacks, is drawn in. */
+    defaultRole: string;
+    /** A connector naming no role. */
+    edge: EdgeStyle;
+    /** A connector's label, where the connector names no role. */
+    label: {
+        fill: string;
+        font?: DiagramFont;
+    };
+    /** A group's or a container's box, its `text` the title's color. */
+    container: NodeStyle;
+    /** A pool's header, and its lanes' bodies in turn. */
+    lane: {
+        header: NodeStyle;
+        bodies: readonly NodeStyle[];
+    };
+    /** The page a document is drawn on. */
+    page: string;
+    font: DiagramFont;
+    /** Colors for a series of things the theme cannot name in advance: an effect look's value types. */
+    series: readonly string[];
+}
+/** The document value a theme is saved under: a shipped theme's id, or a whole custom theme. */
+declare const DIAGRAM_THEME_KEY = "diagram:theme";
+
+/**
+ * The plain data `diagramScene` reads, and the options and styles it takes.
  */
 
 /** One node of a {@link DiagramData}: its rows of text, and optionally its outline, ports, size, and starting place. */
@@ -222,9 +309,18 @@ interface DataNode {
     /** Drawn over the box besides its rows: shapes in a unit square stretched
      *  over it, and text pinned to a point on it. */
     marks?: readonly DataMark[];
+    /** The theme role it is drawn in, under `DiagramSceneOptions.theme`. Kept on its trait. */
+    style?: string;
+    /** Colors of its own, over its role's. Each one set is listed in the trait's `ownStyle`, so a
+     *  theme change leaves it. */
+    colors?: Partial<NodeStyle>;
 }
 /** One edge of a {@link DiagramData}, between two nodes or groups by id. */
 interface DataEdge {
+    /** The scene node id this edge gets, for an editor that must find it again
+     *  after its ends, ports or label change. Unset, {@link edgeIdOf} derives
+     *  one from those. */
+    id?: string;
     /** A node's id, or a group's: an edge naming a group meets its box. */
     from: string;
     to: string;
@@ -248,6 +344,11 @@ interface DataEdge {
     /** Ports a layout run named, as `onMove` reports them: used like `routed`,
      *  and not part of the edge's id. `fromPort` and `toPort` win. */
     routedPorts?: LayoutPorts;
+    /** The theme role it is drawn in, under `DiagramSceneOptions.theme`: that role's stroke. Kept on its trait. */
+    style?: string;
+    /** Its stroke, markers, and label color of its own, over the theme's. `stroke` and `label` are
+     *  listed in the trait's `ownStyle` (as `stroke` and `text`), so a theme change leaves them. */
+    colors?: Partial<EdgeStyle>;
 }
 /** A box drawn around some nodes, which layout keeps together. */
 interface DataGroup {
@@ -262,16 +363,85 @@ interface DataGroup {
     /** Between the box and its members, and around the label. Default
      *  `DiagramSceneOptions.groupPadding`. */
     padding?: number;
+    /** The axis its members can be dragged along to change their order, in a
+     *  `DiagramView` given `onReorder`. A member that is a group carries
+     *  everything inside it. */
+    reorder?: 'x' | 'y';
 }
 /** A diagram as plain data, the input to `diagramScene`. */
 interface DiagramData {
     nodes: readonly DataNode[];
     edges: readonly DataEdge[];
-    /** A group may be a member of another. `layered`, `tree`, and `force` keep
-     *  each group's members together; `chain` and `'none'` ignore groups but
-     *  still draw them. */
+    /** A group may be a member of another. `layered`, `tree`, `force`, and `chain`
+     *  keep each group's members together; `'none'` ignores groups but still
+     *  draws them. */
     groups?: readonly DataGroup[];
+    /** Containers and pools: regions drawn as scene containers that hold their
+     *  members, which a `DiagramView` drags shapes into and out of. */
+    containers?: readonly DataContainer[];
+    /** The sheets the diagram is drawn on, in world space as `layoutPages` places them; a node
+     *  belongs to the page its box overlaps most (`pageOfBounds`). A connector whose ends belong
+     *  to different pages is split into two stubs, each with an off-page tag. A node in the gap
+     *  between pages belongs to none, and its connectors stay whole. */
+    pages?: readonly Page[];
+    /** How `pages` are laid out in world space. */
+    pageLayout?: PageLayoutOptions;
+}
+/**
+ * A container or a pool, drawn as a region that holds its members. Its id
+ * shares one namespace with node, group, and lane ids.
+ *
+ * With a `box` it is laid out as one node of that size, and its members ride
+ * along with it: a member with no `at` is seeded inside its body, in rows.
+ * With none, a container is laid out as a group and its box fits its members.
+ * A pool always has a box, {@link DEFAULT_POOL_ACROSS} across and
+ * {@link DEFAULT_LANE_SIZE} along per lane when none is given. An edge with
+ * an end inside a boxed region ranks against the outermost one holding it.
+ */
+interface DataContainer {
+    id: string;
+    role: 'container' | 'pool';
+    /** Its title, drawn in its header. */
+    label?: string;
+    /** A container's direct members: node ids and container ids. A member
+     *  already claimed by an earlier container, a pool, an unknown id, and one
+     *  that would put a container inside itself are ignored. */
+    members?: readonly string[];
+    /** A pool's lanes, in the order they stack. */
+    lanes?: readonly DataLane[];
+    /** The axis a pool stacks its lanes along: `'y'` for rows. Default `'y'`. */
+    axis?: 'x' | 'y';
+    /** Where it stands and how big it is, in world units. A pool's size along
+     *  its stack is shared by the lanes that give no `size`. */
+    box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Layout leaves its box where it is. */
+    pinned?: boolean;
+    /** The theme role it is drawn in. Unset, a container takes the theme's
+     *  `container` style, a pool its `lane.header`. */
+    style?: string;
+    /** Colors of its own, over its style's, listed in its trait's `ownStyle` as a node's are. */
+    colors?: Partial<NodeStyle>;
+}
+/** One lane of a pool. Its id shares the node id namespace. */
+interface DataLane {
+    id: string;
+    label?: string;
+    /** Its depth along the pool's stack, in world units. */
+    size?: number;
+    /** Node ids and container ids, claimed as a container's are. */
+    members?: readonly string[];
+    /** Colors of its own, as a container's. A lane draws no fill. */
+    colors?: Partial<NodeStyle>;
 }
+/** A pool's size across its stack when it gives no box. */
+declare const DEFAULT_POOL_ACROSS = 600;
+/** A lane's size along its pool's stack when neither it nor the pool's box gives one. */
+declare const DEFAULT_LANE_SIZE = 120;
 /** The colors and outline a node is drawn with. */
 interface NodeStyle {
     fill: string;
@@ -280,6 +450,12 @@ interface NodeStyle {
     strokeWidth?: number;
     dash?: number[];
 }
+/** A node's or region's outline width when its style gives none. */
+declare const NODE_STROKE_WIDTH = 2;
+/** A lane's outline width, which its style does not change. */
+declare const LANE_STROKE_WIDTH = 1;
+/** An edge's stroke width when its style gives none. */
+declare const EDGE_STROKE_WIDTH = 1.5;
 /** The stroke, markers, and label color an edge is drawn with. */
 interface EdgeStyle {
     stroke: string;
@@ -293,13 +469,7 @@ interface EdgeStyle {
     label?: string;
 }
 /** How an edge is drawn between its ends. */
-type DiagramRouter = 'straight' | 'bezier' | 'orthogonal';
-/** The face a diagram node's text is set in. */
-type DiagramTextStyle = {
-    fontFamily: string;
-    fontSize: number;
-    fontWeight?: number;
-};
+type DiagramRouter = 'straight' | 'bezier' | 'orthogonal' | 'avoid';
 /** The `data` of a scene node `diagramScene` makes: its diagram role, and what it paints. */
 interface DiagramSceneData {
     diagram?: DiagramNode | DiagramEdge | {
@@ -308,6 +478,8 @@ interface DiagramSceneData {
         anchor: DiagramAnchor;
     } | {
         mark: DiagramMark;
+    } | {
+        offPageTag: OffPageTag;
     };
     fill?: {
         paint: {
@@ -318,16 +490,28 @@ interface DiagramSceneData {
     stroke?: Stroke;
     text?: string;
     style?: DiagramTextStyle;
+    verticalAlign?: 'top' | 'center' | 'bottom';
     /** What a slot is filled with: an image the kit's image painter draws. */
     image?: {
         src: string;
         opacity?: number;
     };
+    /** A body's text row: its place among the body's rows (see `DiagramNode.body`). */
+    bodyRow?: number;
+    /** An off-page tag's box, behind its text, and the room between them. */
+    background?: {
+        paint: {
+            color: string;
+        };
+    };
+    padding?: number;
 }
 /** A scene node spec, as `diagramScene` returns them. */
-type DiagramSpec = AddNodeSpec<DiagramSceneData, 'main', RectPose>;
+type DiagramSpec<TLayer extends string = 'main'> = AddNodeSpec<DiagramSceneData, TLayer, RectPose>;
 /** How `diagramScene` lays out, routes, and styles a {@link DiagramData}. */
-interface DiagramSceneOptions {
+interface DiagramSceneOptions<TLayer extends string = 'main'> {
+    /** The layer every spec goes on. Default `'main'`. */
+    layer?: TLayer;
     /** A layout by name, or any `LayoutFn`. Default `'layered'`. `'none'`
      *  leaves every node at its `at`. */
     layout?: 'layered' | 'tree' | 'force' | 'chain' | 'none' | LayoutFn;
@@ -361,19 +545,9 @@ interface DiagramSceneOptions {
     /** A group's box and label. `text` colors the label. */
     groupStyle?: (group: DataGroup) => NodeStyle;
     edgeStyle?: (edge: DataEdge) => EdgeStyle;
+    /** Styles nodes by their `style` role, and edges, groups and text by the theme, where the
+     *  functions above leave them; and its face is the default `font`. */
+    theme?: DiagramTheme;
 }
-/** The scene node id `diagramScene` gives an edge, built from its ends, ports,
- *  and label. Two edges differing in any of those get different ids, an empty
- *  port or label included: a `.`, `>`, `:`, `/` or `\` in one of them is
- *  escaped with a backslash. */
-declare const edgeIdOf: (e: DataEdge) => string;
-/** Every spec carries an id — a node's own, `<id>/<k>` for its text,
- *  `<id>/mark:<i>` for its marks, `<edge id>/label`, a group's own and
- *  `<group id>/label` — so a later call's
- *  specs can be reconciled against this one's. Throws on a repeated id among
- *  nodes and groups, which names two things as one. An edge whose
- *  end is not a node is dropped, and so is a repeat of an earlier edge with
- *  the same ends, ports and label: it would draw exactly on top of the first. */
-declare function diagramScene(data: DiagramData, opts?: DiagramSceneOptions): DiagramSpec[];
 
-export { ANCHOR_DERIVE_POSE as A, edgeIdOf as B, groupDerivePose as C, type DiagramData as D, type EdgeStyle as E, layoutOwnsPort as F, GROUP_DERIVE_POSE as G, layoutOwnsRoute as H, markShape as I, registerMarkShape as J, type NodeStyle as N, type DiagramSceneOptions as a, type DataEdge as b, type DataNode as c, type DiagramRouter as d, type DiagramSpec as e, type EdgeEnd as f, DIAGRAM_ANCHOR as g, DIAGRAM_GROUP as h, type DataGroup as i, type DataMark as j, type DiagramAnchor as k, type DiagramDerivePose as l, type DiagramEdge as m, type DiagramLabel as n, type DiagramMark as o, type DiagramSceneData as p, type DiagramTextStyle as q, type GroupPoseOptions as r, anchorDerivePose as s, boxAround as t, diagramAnchorOf as u, diagramEdgeOf as v, diagramGroupOf as w, diagramLabelOf as x, diagramMarkOf as y, diagramScene as z };
+export { ANCHOR_DERIVE_POSE as A, type GroupPoseOptions as B, NODE_STROKE_WIDTH as C, type DiagramTheme as D, type EdgeStyle as E, type OffPageTag as F, GROUP_DERIVE_POSE as G, anchorDerivePose as H, boxAround as I, diagramAnchorOf as J, diagramEdgeOf as K, LANE_STROKE_WIDTH as L, diagramGroupOf as M, type NodeStyle as N, type OffPageSplit as O, diagramMarkOf as P, groupDerivePose as Q, layoutOwnsPort as R, layoutOwnsRoute as S, layoutWritesRoute as T, markShape as U, offPageTagId as V, offPageTagOf as W, registerMarkShape as X, rowTextStyle as Y, type DiagramData as a, type DiagramSceneOptions as b, type DataEdge as c, type DataNode as d, type DiagramRouter as e, type DiagramSpec as f, type EdgeEnd as g, type DiagramSceneData as h, type DiagramEdge as i, type DataContainer as j, DEFAULT_LANE_SIZE as k, DEFAULT_POOL_ACROSS as l, DIAGRAM_ANCHOR as m, DIAGRAM_GROUP as n, DIAGRAM_ROLES as o, DIAGRAM_THEME_KEY as p, type DataGroup as q, type DataLane as r, type DataMark as s, type DiagramAnchor as t, type DiagramDerivePose as u, type DiagramFont as v, type DiagramMark as w, type DiagramRole as x, type DiagramTextStyle as y, EDGE_STROKE_WIDTH as z };

package/dist/effect-audio.d.ts

@@ -0,0 +1,138 @@
+import { GraphNodeDef, GraphTarget, GraphPatch, AnalyserTap, AudioEngine } from '@weasel-js/audio';
+import { E as EffectPipeline, a as EffectRun, b as EffectStageType } from './stageTypes-DvnR8cKQ.js';
+import { VisibleRafOptions } from '@weasel-js/react';
+import '@weasel-js/core';
+import '@weasel-js/core/math';
+
+/** What a run supplies to its source stages. */
+interface AudioSources {
+    audio?: AudioBuffer;
+}
+type Values = Readonly<Record<string, unknown>>;
+/** How one stage type becomes a graph node: its settings, its levels, and the node it builds. */
+interface AudioStageNode {
+    /** The stage's discrete settings, from its param values and the run's sources. Throws to fail the stage. */
+    settings(params: Values, sources: AudioSources): Values;
+    /** The ids of its numeric params, each a `params` key of the def `build` returns. */
+    levels: readonly string[];
+    build(ctx: BaseAudioContext, settings: Values, levels: Readonly<Record<string, number>>): GraphNodeDef;
+}
+/** The graph node of each stage type, by `type`. */
+type AudioStageNodes = Readonly<Record<string, AudioStageNode>>;
+/** The graph node each stage type builds; `audio.output` has none. */
+declare const audioStageNodes: AudioStageNodes;
+
+/** A node the plan builds: its stage type, its discrete settings and its numeric levels. */
+interface PlanNode {
+    type: string;
+    settings: Readonly<Record<string, unknown>>;
+    levels: Readonly<Record<string, number>>;
+}
+/** A connection the plan makes, from a node to another node's port or to the graph's output. */
+interface PlanEdge {
+    from: string;
+    to: GraphTarget;
+}
+/** The graph an audio pipeline should play: what to build, how it connects, and which stages it left out. */
+interface LivePlan {
+    nodes: Readonly<Record<string, PlanNode>>;
+    /** Sorted by `edgeKey`, so equal plans compare equal. */
+    edges: readonly PlanEdge[];
+    /** Why a stage is not in `nodes`, by stage id. A stage left out for want of input has none. */
+    errors: Readonly<Record<string, string>>;
+}
+/** The plan of a graph holding nothing. */
+declare const EMPTY_PLAN: LivePlan;
+/** Compiles the audio stages of `pipeline`; stages of other types are ignored. */
+declare function livePlan(pipeline: EffectPipeline, nodes: AudioStageNodes, sources: AudioSources): LivePlan;
+
+/** Makes the def for a node that is added or replaced. */
+type BuildNode = (id: string, node: PlanNode) => GraphNodeDef;
+/** The patches that turn the graph `prev` describes into the one `next` describes. */
+declare function diffPlans(prev: LivePlan, next: LivePlan, build: BuildNode): GraphPatch[];
+
+/** What a stage's preview slot shows while its graph plays. */
+type AudioPreview = 'off' | 'scope' | 'spectrum';
+type Size = {
+    width: number;
+    height: number;
+};
+/** The waveform as a line across the bitmap, silence at mid-height. */
+declare function drawScope(tap: AnalyserTap, size: Size): ImageBitmap;
+/** The spectrum as filled bars rising from the bottom, low frequencies on the left. */
+declare function drawSpectrum(tap: AnalyserTap, size: Size): ImageBitmap;
+
+/** What a live runner last published: its run, and whether it plays. */
+interface LiveAudioRunnerState {
+    run: EffectRun | undefined;
+    playing: boolean;
+}
+/** What a live runner plays, and through which engine. */
+interface LiveAudioRunnerOptions {
+    engine: AudioEngine;
+    pipeline: EffectPipeline;
+    nodes?: AudioStageNodes;
+    sources?: AudioSources;
+    /** The engine bus the graph plays through. */
+    bus?: string;
+}
+/** Plays an audio pipeline through a patchable graph, editing the graph as the pipeline changes. */
+interface LiveAudioRunner {
+    readonly state: LiveAudioRunnerState;
+    /** The graph follows `pipeline` while it plays, or while it does not. */
+    setPipeline(pipeline: EffectPipeline): void;
+    /** A new buffer replaces each file node. */
+    setSources(sources: AudioSources): void;
+    /** Unlocks the engine, then starts the graph. */
+    play(): Promise<void>;
+    pause(): void;
+    /** Which stages draw into their `out` preview: a scope, a spectrum, or none. Takes effect on the next `frame`. */
+    setPreviews(mode: AudioPreview): void;
+    /** Publishes a run with each tapped stage's preview drawn from its tap's current window. */
+    frame(): void;
+    /** Call after the render that shows `run`: the bitmaps of earlier runs are closed. */
+    drawn(run: EffectRun | undefined): void;
+    /** A fresh graph holding the current plan, not playing: files start again from 0. */
+    reset(): void;
+    subscribe(listener: () => void): () => void;
+    /** Disposes the graph; the runner does nothing after. The engine is the caller's. */
+    dispose(): void;
+}
+/** A runner over `opts.pipeline` holding a fresh graph on `opts.engine`, not playing. */
+declare function createLiveAudioRunner(opts: LiveAudioRunnerOptions): LiveAudioRunner;
+
+/** Stage types over audio, each with a graph node in `audioStageNodes` except
+ *  `audio.output`, which is the graph's own output. Every `type` is prefixed
+ *  because `IMAGE_STAGE_TYPES` already has an `oscillator`. */
+declare const AUDIO_STAGE_TYPES: readonly EffectStageType[];
+
+/** What `useFollowAudioRunner` keeps a runner following, and how its preview loop is gated. */
+interface FollowAudioRunnerOptions extends Pick<VisibleRafOptions, 'target' | 'requestFrame' | 'cancelFrame'> {
+    pipeline: EffectPipeline;
+    sources?: AudioSources;
+    previews: AudioPreview;
+    /** The nodes the plan is read with while there is no runner. */
+    nodes?: AudioStageNodes;
+}
+/**
+ * Keeps a caller-owned `runner` following `pipeline`, `sources` and `previews`, draws its previews every
+ * visible frame while it plays, and closes the bitmaps of runs no render shows. While `runner` is null,
+ * the run holds the plan's errors, so a stage that cannot play says why before any engine exists.
+ */
+declare function useFollowAudioRunner(runner: LiveAudioRunner | null, opts: FollowAudioRunnerOptions): LiveAudioRunnerState;
+
+/** Options for `useLiveAudioRunner`: the runner's, which it follows as they change, and how its preview loop is gated. */
+interface UseLiveAudioRunnerOptions extends LiveAudioRunnerOptions, Pick<FollowAudioRunnerOptions, 'previews' | 'target' | 'requestFrame' | 'cancelFrame'> {
+}
+/** What `useLiveAudioRunner` returns: the runner's state, and the runner to drive, null until it mounts. */
+interface LiveAudioRunnerHandle extends LiveAudioRunnerState {
+    runner: LiveAudioRunner | null;
+}
+/**
+ * A runner made on mount and remade when `engine`, `bus` or `nodes` change, following `pipeline`,
+ * `sources` and `previews` through `useFollowAudioRunner`, and disposed on unmount. Before the first
+ * mount the runner is null and the run holds the plan's errors. The engine is the caller's.
+ */
+declare function useLiveAudioRunner(opts: UseLiveAudioRunnerOptions): LiveAudioRunnerHandle;
+
+export { AUDIO_STAGE_TYPES, type AudioPreview, type AudioSources, type AudioStageNode, type AudioStageNodes, type BuildNode, EMPTY_PLAN, type FollowAudioRunnerOptions, type LiveAudioRunner, type LiveAudioRunnerHandle, type LiveAudioRunnerOptions, type LiveAudioRunnerState, type LivePlan, type PlanEdge, type PlanNode, type UseLiveAudioRunnerOptions, audioStageNodes, createLiveAudioRunner, diffPlans, drawScope, drawSpectrum, livePlan, useFollowAudioRunner, useLiveAudioRunner };