@tangle-network/sandbox-ui 0.113.6 → 0.114.0

package/dist/workflows.d.ts

@@ -1,7 +1,7 @@
-import * as React from 'react';
-export { M as ModelBrandIdentity, a as ModelBrandStack, m as modelBrandFor } from './model-brand-BNnaUKKZ.js';
-import '@tangle-network/agent-interface';
-
+import { a as modelBrandFor, n as ModelBrandStack, t as ModelBrandIdentity } from "./model-brand-B9A4H9pJ.js";
+import "@xyflow/react";
+import "@xyflow/react/dist/style.css";
+//#region src/workflows/model.d.ts
 /**
  * Turns a workflow YAML definition into a positioned node/edge graph for the
  * visualizer. Pure and React-Flow-agnostic so the parsing + layout is unit
@@ -35,23 +35,23 @@ type WfNodeStatus = "queued" | "running" | "waiting" | "succeeded" | "failed";
  * teach `sameRunState` to compare it.
  */
 interface WfNodeState {
-    status: WfNodeStatus;
-    /** Amount booked for this action, USD. */
-    costUsd?: number;
-    /** Wall-clock the action took, ms. */
-    durationMs?: number;
-    /** Model the action actually used (may differ from the requested model). */
-    model?: string;
-    /** Failure message, when the node failed. */
-    error?: string;
-    /** Short preview of the action's output (or a failure's partial text). */
-    outputPreview?: string;
-    /** Input/output token usage, when known. */
-    inputTokens?: number;
-    outputTokens?: number;
-    /** Agent iteration count (agent.run only) — the number of reasoning/tool
-     *  rounds the agent has taken, surfaced on the node's progress strip. */
-    rounds?: number;
+  status: WfNodeStatus;
+  /** Amount booked for this action, USD. */
+  costUsd?: number;
+  /** Wall-clock the action took, ms. */
+  durationMs?: number;
+  /** Model the action actually used (may differ from the requested model). */
+  model?: string;
+  /** Failure message, when the node failed. */
+  error?: string;
+  /** Short preview of the action's output (or a failure's partial text). */
+  outputPreview?: string;
+  /** Input/output token usage, when known. */
+  inputTokens?: number;
+  outputTokens?: number;
+  /** Agent iteration count (agent.run only) — the number of reasoning/tool
+   *  rounds the agent has taken, surfaced on the node's progress strip. */
+  rounds?: number;
 }
 /**
  * A node's card-facing content. Three tiers, so both densities can show the
@@ -69,67 +69,67 @@ interface WfNodeState {
  * {@link config} for the full-detail view.
  */
 interface WfNodeData extends Record<string, unknown> {
-    /** Human headline for the node, e.g. "GitHub", "AI Agent". */
-    title: string;
-    /** The action/trigger kind verbatim, e.g. "agent.run", "schedule". Set on every
-     *  node `buildWorkflowGraph` produces so a consumer can dispatch on the node's
-     *  type (icon, detail rendering) regardless of what its title says; optional on
-     *  the type so external consumers constructing `WfNodeData` directly aren't
-     *  forced to supply it (the render guards its usage). */
-    kind?: string;
-    /** The one-phrase qualifier under the title, e.g. "create: pulls.reviews". */
-    subtitle?: string;
-    /** Free-text detail (agent prompt, notify URL, trigger events) — shown only by
-     *  the expanded node, which has the room to clamp it to two lines. */
-    description?: string;
-    /** Requested model (agent.run). A live run's ACTUAL model (`state.model`)
-     *  supersedes it on the card. */
-    model?: string;
-    /** `integration.invoke` provider.method path. */
-    path?: string;
-    /** The raw, UNTRUNCATED config for this node — the action/trigger config from
-     *  the definition. The card shows the summary above; a full-detail view (e.g. a
-     *  node drawer) reads this to render every field — the complete prompt, all
-     *  profile/source/input keys — without the card-sized clamp. It is a JSON-safe
-     *  deep copy of the config (cycles and non-JSON values normalized), so a
-     *  consumer can serialize or render it freely. Omitted when the node has no
-     *  config. */
-    config?: Record<string, unknown>;
-    /** Connector slug (e.g. `github`) — drives the node's brand logo, so a provider
-     *  step is recognizable before any text is read. */
-    provider?: string;
-    /** Small corner tag, e.g. "×3" for a parallel fan-out. */
-    badge?: string;
-    /** Whether this node is the spine root (no incoming/target handle). */
-    isRoot: boolean;
-    tone: WfNodeTone;
-    /** Live run state, merged in by the host at render time (never from YAML). */
-    state?: WfNodeState;
+  /** Human headline for the node, e.g. "GitHub", "AI Agent". */
+  title: string;
+  /** The action/trigger kind verbatim, e.g. "agent.run", "schedule". Set on every
+   *  node `buildWorkflowGraph` produces so a consumer can dispatch on the node's
+   *  type (icon, detail rendering) regardless of what its title says; optional on
+   *  the type so external consumers constructing `WfNodeData` directly aren't
+   *  forced to supply it (the render guards its usage). */
+  kind?: string;
+  /** The one-phrase qualifier under the title, e.g. "create: pulls.reviews". */
+  subtitle?: string;
+  /** Free-text detail (agent prompt, notify URL, trigger events) — shown only by
+   *  the expanded node, which has the room to clamp it to two lines. */
+  description?: string;
+  /** Requested model (agent.run). A live run's ACTUAL model (`state.model`)
+   *  supersedes it on the card. */
+  model?: string;
+  /** `integration.invoke` provider.method path. */
+  path?: string;
+  /** The raw, UNTRUNCATED config for this node — the action/trigger config from
+   *  the definition. The card shows the summary above; a full-detail view (e.g. a
+   *  node drawer) reads this to render every field — the complete prompt, all
+   *  profile/source/input keys — without the card-sized clamp. It is a JSON-safe
+   *  deep copy of the config (cycles and non-JSON values normalized), so a
+   *  consumer can serialize or render it freely. Omitted when the node has no
+   *  config. */
+  config?: Record<string, unknown>;
+  /** Connector slug (e.g. `github`) — drives the node's brand logo, so a provider
+   *  step is recognizable before any text is read. */
+  provider?: string;
+  /** Small corner tag, e.g. "×3" for a parallel fan-out. */
+  badge?: string;
+  /** Whether this node is the spine root (no incoming/target handle). */
+  isRoot: boolean;
+  tone: WfNodeTone;
+  /** Live run state, merged in by the host at render time (never from YAML). */
+  state?: WfNodeState;
 }
 /** Which edge of a node box an edge attaches to. Named in plain compass terms
  *  rather than React Flow's `Position` so the layouter stays free of it. */
 type WfSide = "left" | "right" | "top" | "bottom";
 interface WfNode {
-    id: string;
-    position: {
-        x: number;
-        y: number;
-    };
-    /** Authoritative rendered size (px). The card renders at exactly this box
-     *  (`h-full`/`w-full`) so the layout — which spaces nodes by these dims — is
-     *  collision-free by construction, with no measure-then-reflow pass. */
-    width: number;
-    height: number;
-    data: WfNodeData;
-    /**
-     * Where this node's edges attach, when the LAYOUT decides rather than the
-     * flow direction. A straight layer flow has one answer for every node (edges
-     * enter the leading edge and leave the trailing one, per `direction`), so it
-     * sets neither and the renderer derives both. A folded layout does not — a row
-     * that runs right-to-left mirrors them. Absent ⇒ derive from `direction`.
-     */
-    sourceSide?: WfSide;
-    targetSide?: WfSide;
+  id: string;
+  position: {
+    x: number;
+    y: number;
+  };
+  /** Authoritative rendered size (px). The card renders at exactly this box
+   *  (`h-full`/`w-full`) so the layout — which spaces nodes by these dims — is
+   *  collision-free by construction, with no measure-then-reflow pass. */
+  width: number;
+  height: number;
+  data: WfNodeData;
+  /**
+   * Where this node's edges attach, when the LAYOUT decides rather than the
+   * flow direction. A straight layer flow has one answer for every node (edges
+   * enter the leading edge and leave the trailing one, per `direction`), so it
+   * sets neither and the renderer derives both. A folded layout does not — a row
+   * that runs right-to-left mirrors them. Absent ⇒ derive from `direction`.
+   */
+  sourceSide?: WfSide;
+  targetSide?: WfSide;
 }
 /**
  * Node ids are PUBLIC contract, not an internal detail. A host keys its live
@@ -141,7 +141,7 @@ interface WfNode {
  * and read everywhere else through them.
  */
 /** The workflow's first (or only) trigger. */
-declare const TRIGGER_NODE_ID = "trigger";
+export declare const TRIGGER_NODE_ID = "trigger";
 /** The node for the `index`th entry of a list-form `on:`. Entry 0 IS
  *  {@link TRIGGER_NODE_ID}, so a single-trigger graph — the overwhelmingly
  *  common one — keeps the plain id a host may already have persisted.
@@ -151,38 +151,38 @@ declare const TRIGGER_NODE_ID = "trigger";
  *  topology then rejects by name ("…names "trigger:NaN", which this definition
  *  has no step for") — reported there rather than thrown from here, because
  *  {@link buildWorkflowGraph} calls this and must never throw. */
-declare function triggerNodeId(index: number): string;
+export declare function triggerNodeId(index: number): string;
 /** The `on:` entry a trigger node stands for, or null when the id names
  *  anything else — so a host can tell a trigger from an action without
  *  matching the id format itself. */
-declare function triggerNodeIndex(nodeId: string): number | null;
+export declare function triggerNodeIndex(nodeId: string): number | null;
 /** The node for the `do` entry at `index`. */
-declare function actionNodeId(index: number): string;
+export declare function actionNodeId(index: number): string;
 /** The node for the `branchIndex`th fan-out leaf of the `do` entry at
  *  `actionIndex` — a `parallel` branch or a `foreach` template. */
-declare function branchNodeId(actionIndex: number, branchIndex: number): string;
+export declare function branchNodeId(actionIndex: number, branchIndex: number): string;
 type WfEdgeKind = "spine" | "fork" | "join";
 interface WfEdge {
-    id: string;
-    source: string;
-    target: string;
-    /** Spine = trigger→action→action; fork = fan-out into a branch leaf; join =
-     *  a branch leaf reconverging onto the next spine node. Drives edge styling.
-     *
-     *  A DECLARED edge ({@link BuildWorkflowGraphOptions.edges}) is a `spine`
-     *  edge: it is the flow. Fork edges survive a declared topology unchanged (a
-     *  branch leaf is this module's own node, which no declared spec addresses);
-     *  join edges do not exist under one, because what follows a fan-out is then
-     *  declared rather than inferred from list position. */
-    kind: WfEdgeKind;
-    /** Short, already-human summary of the edge's guard, when it carries one.
-     *  Supplied by {@link WfEdgeSpec.whenLabel} — this module never interprets a
-     *  condition, it only places the label its host wrote. */
-    whenLabel?: string;
-    /** True when this edge closes a cycle: it points back at a node that is
-     *  already on the path reaching it. Rendered distinctly (dashed, with the
-     *  visit budget) because such an edge is the one that can run a node twice. */
-    backEdge?: boolean;
+  id: string;
+  source: string;
+  target: string;
+  /** Spine = trigger→action→action; fork = fan-out into a branch leaf; join =
+   *  a branch leaf reconverging onto the next spine node. Drives edge styling.
+   *
+   *  A DECLARED edge ({@link BuildWorkflowGraphOptions.edges}) is a `spine`
+   *  edge: it is the flow. Fork edges survive a declared topology unchanged (a
+   *  branch leaf is this module's own node, which no declared spec addresses);
+   *  join edges do not exist under one, because what follows a fan-out is then
+   *  declared rather than inferred from list position. */
+  kind: WfEdgeKind;
+  /** Short, already-human summary of the edge's guard, when it carries one.
+   *  Supplied by {@link WfEdgeSpec.whenLabel} — this module never interprets a
+   *  condition, it only places the label its host wrote. */
+  whenLabel?: string;
+  /** True when this edge closes a cycle: it points back at a node that is
+   *  already on the path reaching it. Rendered distinctly (dashed, with the
+   *  visit budget) because such an edge is the one that can run a node twice. */
+  backEdge?: boolean;
 }
 /**
  * One edge of a DECLARED topology — the caller's answer to "what actually
@@ -202,9 +202,9 @@ interface WfEdge {
  * step's row), which is what keeps the two readings identical.
  */
 interface WfEdgeSpec {
-    from: string;
-    to: string;
-    whenLabel?: string;
+  from: string;
+  to: string;
+  whenLabel?: string;
 }
 /** How serious an authoring problem is. An `error` stops the definition from
  *  compiling; a `warning` compiles but is worth saying out loud. */
@@ -235,75 +235,75 @@ type WfProblemSeverity = "error" | "warning";
  * be handed over with the definition it was computed from.
  */
 type WfProblem = {
-    anchor: "node";
-    /** The node the problem sits on. */
-    node: string;
-    severity: WfProblemSeverity;
-    message: string;
+  anchor: "node";
+  /** The node the problem sits on. */
+  node: string;
+  severity: WfProblemSeverity;
+  message: string;
 } | {
-    anchor: "edge";
-    /** The edge's endpoints, as {@link WfEdgeSpec} names them. */
-    from: string;
-    to: string;
-    severity: WfProblemSeverity;
-    message: string;
+  anchor: "edge";
+  /** The edge's endpoints, as {@link WfEdgeSpec} names them. */
+  from: string;
+  to: string;
+  severity: WfProblemSeverity;
+  message: string;
 };
 interface WfGraph {
-    nodes: WfNode[];
-    edges: WfEdge[];
-    /** Set when the YAML couldn't be parsed into a renderable graph. */
-    error: string | null;
+  nodes: WfNode[];
+  edges: WfEdge[];
+  /** Set when the YAML couldn't be parsed into a renderable graph. */
+  error: string | null;
 }
 /** Main-axis flow direction: "LR" (left-to-right, default) suits the wide/short
  *  run-detail panel; "TB" (top-to-bottom) suits a narrow column. */
 type WfDirection = "LR" | "TB";
 /** Options for {@link buildWorkflowGraph}. */
 interface BuildWorkflowGraphOptions {
-    /**
-     * Reserve space for the rows live run state adds to a node (the metrics line,
-     * the output/error preview, the status footer), so the RUN view never overlaps
-     * once a node starts or terminates. The static/preview layout (no run overlay)
-     * leaves this off to stay compact. Defaults to `false`.
-     */
-    reserveRunState?: boolean;
-    /** Flow direction. Defaults to "LR". */
-    direction?: WfDirection;
-    /** Collapse every node to the fixed icon-tile size, and pitch the layers for
-     *  it. Defaults to `false` (the full, expanded card). */
-    compact?: boolean;
-    /**
-     * Fold a long single-file pipeline into rows instead of one unbounded line,
-     * so it occupies both axes of the panel rather than running off one edge.
-     * Only a straight chain folds — a graph with any fan-out keeps its layered
-     * flow, whose branches need the cross axis. "LR" only. Defaults to `false`.
-     */
-    wrap?: boolean;
-    /**
-     * The graph's DECLARED topology. Omit — the default — and edges are inferred
-     * from `do`-list order: a linear spine, which is exactly right for a workflow
-     * that runs as one, and wrong for any workflow whose definition declares its
-     * own edges (`needs`, guards, cycles). Supply it and the inferred spine is
-     * replaced wholesale by these edges, the layout is re-ranked to the shape they
-     * describe (so a diamond reads as a diamond rather than a chain drawn over
-     * one), and cycle-closing edges are marked {@link WfEdge.backEdge}.
-     *
-     * An edge naming a node this graph has no slot for is an ERROR
-     * ({@link WfGraph.error}), never a quiet fall back to the positional spine:
-     * the two disagreeing means the topology and the definition came from
-     * different places, and a graph that draws edges the run will not take is
-     * worse than one that says it cannot be drawn.
-     */
-    edges?: readonly WfEdgeSpec[];
-    /**
-     * Widen the gap between layers so an edge has room for an in-line control at
-     * its midpoint — the insert affordance an EDITING canvas draws there. The
-     * compact densities pitch their layers at 20-34px, which is the whole button,
-     * so a canvas that renders one without asking for the lane puts it on top of
-     * the nodes either side. Reserved by the layout for the same reason run rows
-     * are: what a node or an edge renders is spaced for before it is drawn, never
-     * measured afterwards. Defaults to `false`.
-     */
-    reserveEdgeInsert?: boolean;
+  /**
+   * Reserve space for the rows live run state adds to a node (the metrics line,
+   * the output/error preview, the status footer), so the RUN view never overlaps
+   * once a node starts or terminates. The static/preview layout (no run overlay)
+   * leaves this off to stay compact. Defaults to `false`.
+   */
+  reserveRunState?: boolean;
+  /** Flow direction. Defaults to "LR". */
+  direction?: WfDirection;
+  /** Collapse every node to the fixed icon-tile size, and pitch the layers for
+   *  it. Defaults to `false` (the full, expanded card). */
+  compact?: boolean;
+  /**
+   * Fold a long single-file pipeline into rows instead of one unbounded line,
+   * so it occupies both axes of the panel rather than running off one edge.
+   * Only a straight chain folds — a graph with any fan-out keeps its layered
+   * flow, whose branches need the cross axis. "LR" only. Defaults to `false`.
+   */
+  wrap?: boolean;
+  /**
+   * The graph's DECLARED topology. Omit — the default — and edges are inferred
+   * from `do`-list order: a linear spine, which is exactly right for a workflow
+   * that runs as one, and wrong for any workflow whose definition declares its
+   * own edges (`needs`, guards, cycles). Supply it and the inferred spine is
+   * replaced wholesale by these edges, the layout is re-ranked to the shape they
+   * describe (so a diamond reads as a diamond rather than a chain drawn over
+   * one), and cycle-closing edges are marked {@link WfEdge.backEdge}.
+   *
+   * An edge naming a node this graph has no slot for is an ERROR
+   * ({@link WfGraph.error}), never a quiet fall back to the positional spine:
+   * the two disagreeing means the topology and the definition came from
+   * different places, and a graph that draws edges the run will not take is
+   * worse than one that says it cannot be drawn.
+   */
+  edges?: readonly WfEdgeSpec[];
+  /**
+   * Widen the gap between layers so an edge has room for an in-line control at
+   * its midpoint — the insert affordance an EDITING canvas draws there. The
+   * compact densities pitch their layers at 20-34px, which is the whole button,
+   * so a canvas that renders one without asking for the lane puts it on top of
+   * the nodes either side. Reserved by the layout for the same reason run rows
+   * are: what a node or an edge renders is spaced for before it is drawn, never
+   * measured afterwards. Defaults to `false`.
+   */
+  reserveEdgeInsert?: boolean;
 }
 /** Build a positioned graph from a workflow YAML string. Never throws —
  *  malformed YAML or an empty definition returns an `error` the UI can fall
@@ -311,179 +311,181 @@ interface BuildWorkflowGraphOptions {
  *  room for the rows live run state adds (see {@link nodeHeight}); `direction`
  *  picks the flow axis (default "LR"); `compact` collapses nodes to icon tiles;
  *  `edges` replaces the inferred positional spine with a declared topology. */
-declare function buildWorkflowGraph(yaml: string, options?: BuildWorkflowGraphOptions): WfGraph;
-
+export declare function buildWorkflowGraph(yaml: string, options?: BuildWorkflowGraphOptions): WfGraph;
+//#endregion
+//#region src/workflows/WorkflowGraph.d.ts
 interface WorkflowGraphProps {
-    /** Workflow YAML to render. */
-    yaml: string;
-    /** "full" = interactive (pan/zoom/drag + controls); "preview" = static fit. */
-    variant?: "full" | "preview";
-    /** Flow direction: "LR" (default) reads left-to-right — best for the wide/short
-     *  run-detail panel; "TB" is a vertical column. */
-    direction?: WfDirection;
-    /**
-     * Start collapsed (compact icon tiles) rather than expanded.
-     *
-     * Defaults to whether the graph has a RUN: a definition is read
-     * structure-first, so it opens as tiles, while a run is read result-first and
-     * opens as cards — the answers are the reason the reader opened it. Passing
-     * the prop pins the density either way; the full variant still exposes the
-     * toggle, and the preview variant is always compact.
-     */
-    defaultCompact?: boolean;
-    /**
-     * Called when the reader moves the density toggle, with the density they
-     * chose.
-     *
-     * `defaultCompact` seeds the graph; this reports back out of it, which is
-     * what a host needs to REMEMBER the choice. Without it a host can set an
-     * opening density but never learn that the reader wanted the other one, so
-     * every navigation puts them back where they started and the toggle has to
-     * be found again.
-     */
-    onCompactChange?: (compact: boolean) => void;
-    /** Sizing for the wrapper; the caller controls height. */
-    className?: string;
-    /**
-     * Fold a long single-file pipeline into rows instead of one unbounded line,
-     * so it uses both axes of the panel rather than running off one edge. Only a
-     * straight chain folds; anything with fan-out keeps its layered flow. "LR"
-     * only. Defaults to `false`.
-     */
-    wrap?: boolean;
-    /**
-     * Live per-node run state, keyed by graph node id (`trigger`, `a0`, `a0-b1`).
-     * Absent ⇒ the static definition view (the proposal-card preview passes
-     * nothing). When present, each node shows its status/cost/duration/output and
-     * the running node pulses.
-     *
-     * Immutability contract: the node memo keys on this object's reference, so the
-     * host MUST pass a NEW top-level `nodeState` object whenever any node's state
-     * changes (mutating a nested entry in place will not re-render). Building a
-     * fresh record each update — e.g. from a poll/SSE tick — satisfies this.
-     */
-    nodeState?: Record<string, WfNodeState>;
-    /**
-     * The graph's DECLARED topology, replacing the spine inferred from `do`-list
-     * order — see {@link WfEdgeSpec}. Name endpoints with the exported id helpers
-     * (`actionNodeId`, `branchNodeId`, `TRIGGER_NODE_ID`).
-     *
-     * Immutability contract, as for `nodeState`: the layout memo keys on this
-     * array's reference, so pass a stable one (a `useMemo`, or a value derived
-     * once per fetch) rather than a fresh literal each render.
-     */
-    edges?: readonly WfEdgeSpec[];
-    /** Per-node visit budget for a cyclic graph, shown on cycle-closing edges.
-     *  Meaningless without `edges` (an inferred spine cannot loop). */
-    maxNodeVisits?: number;
-    /** The node to ring as selected — e.g. the one whose detail panel is open.
-     *  Selection is the host's state; the graph only reflects it. */
-    selectedNodeId?: string;
-    /** Click handler for a node (e.g. open a detail drawer). Absent ⇒ nodes are
-     *  non-interactive on click. */
-    onNodeClick?: (nodeId: string, data: WfNodeData) => void;
-    /**
-     * Editing gestures. Supplying `onEdgeConnect` turns the canvas from a diagram
-     * into an EDITOR: node handles become visible and draggable, an edge can be
-     * selected and removed with Delete/Backspace, and clicking one asks to edit
-     * its guard. Omit it — the default — and the graph stays the read-only
-     * visualisation it has always been.
-     *
-     * `onEdgeConnect` is the ONE prop that decides it. Every other editing
-     * callback below (`onEdgeDelete`, `onEdgeClick`, `onEdgeInsert`,
-     * `onNodeInsert`, `onTriggerAdd`, `onTriggerDelete`) refines an editor and is
-     * inert without it — a canvas that cannot accept a new connection has no
-     * business drawing an add control either.
-     *
-     * Every callback speaks node ids (`actionNodeId`, `branchNodeId`), never
-     * positions: this component reports the gesture, and turning it into a
-     * definition edit is the host's job — it owns the YAML, and only it knows
-     * what a `needs` row is. Fan-out and trigger edges never fire any of these
-     * ({@link isEditableEdge}), because neither is a row in anyone's topology.
-     *
-     * The canvas holds no pending state: an accepted edit comes back as new
-     * `yaml` + `edges`, and a rejected one simply never arrives.
-     */
-    onEdgeConnect?: (sourceId: string, targetId: string) => void;
-    onEdgeDelete?: (sourceId: string, targetId: string) => void;
-    onEdgeClick?: (sourceId: string, targetId: string) => void;
-    /**
-     * Add a step ON an edge: the edge draws a "+" at its midpoint, and pressing it
-     * reports the pair it sits between. The layout widens the corridor between
-     * layers to hold the control, so arming this RELAYS OUT the graph — a compact
-     * canvas pitches its layers at 20px, which is the whole button.
-     *
-     * Offered on exactly the edges the other three gestures are ({@link
-     * isEditableEdge}): inserting on a fan-out or trigger edge would name a pair
-     * that exists in no definition. "Add a step at the very start" is the
-     * {@link onNodeInsert} drop instead — dragged from the first step's inbound
-     * handle onto empty canvas, which names one node rather than a synthesized
-     * edge. (A definition with no `on:` at all has no inbound handle on its first
-     * step, because nothing points at it; there the step list is the only way in.)
-     */
-    onEdgeInsert?: (sourceId: string, targetId: string) => void;
-    /**
-     * Add a step at the loose end of a connection dragged from a node's handle and
-     * released over empty canvas — the canvas's answer to "and then what?".
-     * `side` is which handle it left from: `"after"` for the outbound one (the new
-     * step follows `nodeId`), `"before"` for the inbound one (it precedes it).
-     *
-     * Reported for ANY node, including a trigger and a fan-out branch leaf: unlike
-     * an edge gesture, this names a node that certainly exists, and whether a step
-     * may go beside it is a question about the definition's schema — which this
-     * library does not model and the host already answers.
-     */
-    onNodeInsert?: (nodeId: string, side: "before" | "after") => void;
-    /**
-     * The `on:` list gains an entry. Drawn as a canvas control rather than a
-     * per-node one, because the workflow that most needs it is the one with NO
-     * trigger — which has no trigger node to hang a "+" on.
-     *
-     * Offered whenever it is supplied, including on a definition that ALREADY has
-     * a trigger: `on:` is a list with OR semantics, and a second subscription is a
-     * normal thing to want. Whether THIS workflow may take another one is a
-     * question about the definition's schema and the provider behind it, which
-     * this library does not model — a host that must cap the list withholds the
-     * callback.
-     */
-    onTriggerAdd?: () => void;
-    /** Remove the `on:` entry a trigger node stands for — the one node deletion
-     *  that IS a canvas gesture (every other node is a `do` entry, reordered and
-     *  removed in the list the host owns). Read the entry's position back with
-     *  `triggerNodeIndex`. */
-    onTriggerDelete?: (nodeId: string) => void;
-    /**
-     * AUTHORING problems anchored to the nodes and edges that carry them, so a
-     * compile error is visible on the canvas rather than only in a list beside it.
-     * See {@link WfProblem} — and note it is a separate channel from `nodeState`,
-     * which is what a node DID rather than what is wrong with what it says.
-     *
-     * A problem tints the node's border in either density, and states itself on a
-     * mark in the card's identity row (a corner of the compact tile). A graph
-     * showing a RUN is not an authoring surface — its cards and edges state the
-     * run instead, which takes precedence over a problem's colour on both, and the
-     * problem's mark and chip still render beside it.
-     *
-     * What the canvas gives is a LOCATOR: which step or dependency is at fault,
-     * with the messages on the mark's `title` and in the accessibility tree. It is
-     * deliberately not a reader for them — at the zoom a whole pipeline is viewed
-     * at, a panel of message text on the canvas is unreadable, and the host
-     * already owns the problem list that the messages are read and acted on in.
-     *
-     * Pairing contract: anchors are positional node ids, so a problem list must be
-     * derived from the SAME definition passed as `yaml`. Hand over a list computed
-     * against an older draft and an id that still exists may now name a different
-     * step, which puts the diagnostic on an innocent one — the graph cannot tell
-     * the two apart, any more than it can for a run's `nodeState`. A host that
-     * validates asynchronously therefore holds each result against the text it was
-     * computed from, and passes neither until they agree.
-     *
-     * Immutability contract, as for `edges`: the index is memoized on this array's
-     * reference, so pass a stable one.
-     */
-    problems?: readonly WfProblem[];
+  /** Workflow YAML to render. */
+  yaml: string;
+  /** "full" = interactive (pan/zoom/drag + controls); "preview" = static fit. */
+  variant?: "full" | "preview";
+  /** Flow direction: "LR" (default) reads left-to-right — best for the wide/short
+   *  run-detail panel; "TB" is a vertical column. */
+  direction?: WfDirection;
+  /**
+   * Start collapsed (compact icon tiles) rather than expanded.
+   *
+   * Defaults to whether the graph has a RUN: a definition is read
+   * structure-first, so it opens as tiles, while a run is read result-first and
+   * opens as cards — the answers are the reason the reader opened it. Passing
+   * the prop pins the density either way; the full variant still exposes the
+   * toggle, and the preview variant is always compact.
+   */
+  defaultCompact?: boolean;
+  /**
+   * Called when the reader moves the density toggle, with the density they
+   * chose.
+   *
+   * `defaultCompact` seeds the graph; this reports back out of it, which is
+   * what a host needs to REMEMBER the choice. Without it a host can set an
+   * opening density but never learn that the reader wanted the other one, so
+   * every navigation puts them back where they started and the toggle has to
+   * be found again.
+   */
+  onCompactChange?: (compact: boolean) => void;
+  /** Sizing for the wrapper; the caller controls height. */
+  className?: string;
+  /**
+   * Fold a long single-file pipeline into rows instead of one unbounded line,
+   * so it uses both axes of the panel rather than running off one edge. Only a
+   * straight chain folds; anything with fan-out keeps its layered flow. "LR"
+   * only. Defaults to `false`.
+   */
+  wrap?: boolean;
+  /**
+   * Live per-node run state, keyed by graph node id (`trigger`, `a0`, `a0-b1`).
+   * Absent ⇒ the static definition view (the proposal-card preview passes
+   * nothing). When present, each node shows its status/cost/duration/output and
+   * the running node pulses.
+   *
+   * Immutability contract: the node memo keys on this object's reference, so the
+   * host MUST pass a NEW top-level `nodeState` object whenever any node's state
+   * changes (mutating a nested entry in place will not re-render). Building a
+   * fresh record each update — e.g. from a poll/SSE tick — satisfies this.
+   */
+  nodeState?: Record<string, WfNodeState>;
+  /**
+   * The graph's DECLARED topology, replacing the spine inferred from `do`-list
+   * order — see {@link WfEdgeSpec}. Name endpoints with the exported id helpers
+   * (`actionNodeId`, `branchNodeId`, `TRIGGER_NODE_ID`).
+   *
+   * Immutability contract, as for `nodeState`: the layout memo keys on this
+   * array's reference, so pass a stable one (a `useMemo`, or a value derived
+   * once per fetch) rather than a fresh literal each render.
+   */
+  edges?: readonly WfEdgeSpec[];
+  /** Per-node visit budget for a cyclic graph, shown on cycle-closing edges.
+   *  Meaningless without `edges` (an inferred spine cannot loop). */
+  maxNodeVisits?: number;
+  /** The node to ring as selected — e.g. the one whose detail panel is open.
+   *  Selection is the host's state; the graph only reflects it. */
+  selectedNodeId?: string;
+  /** Click handler for a node (e.g. open a detail drawer). Absent ⇒ nodes are
+   *  non-interactive on click. */
+  onNodeClick?: (nodeId: string, data: WfNodeData) => void;
+  /**
+   * Editing gestures. Supplying `onEdgeConnect` turns the canvas from a diagram
+   * into an EDITOR: node handles become visible and draggable, an edge can be
+   * selected and removed with Delete/Backspace, and clicking one asks to edit
+   * its guard. Omit it — the default — and the graph stays the read-only
+   * visualisation it has always been.
+   *
+   * `onEdgeConnect` is the ONE prop that decides it. Every other editing
+   * callback below (`onEdgeDelete`, `onEdgeClick`, `onEdgeInsert`,
+   * `onNodeInsert`, `onTriggerAdd`, `onTriggerDelete`) refines an editor and is
+   * inert without it — a canvas that cannot accept a new connection has no
+   * business drawing an add control either.
+   *
+   * Every callback speaks node ids (`actionNodeId`, `branchNodeId`), never
+   * positions: this component reports the gesture, and turning it into a
+   * definition edit is the host's job — it owns the YAML, and only it knows
+   * what a `needs` row is. Fan-out and trigger edges never fire any of these
+   * ({@link isEditableEdge}), because neither is a row in anyone's topology.
+   *
+   * The canvas holds no pending state: an accepted edit comes back as new
+   * `yaml` + `edges`, and a rejected one simply never arrives.
+   */
+  onEdgeConnect?: (sourceId: string, targetId: string) => void;
+  onEdgeDelete?: (sourceId: string, targetId: string) => void;
+  onEdgeClick?: (sourceId: string, targetId: string) => void;
+  /**
+   * Add a step ON an edge: the edge draws a "+" at its midpoint, and pressing it
+   * reports the pair it sits between. The layout widens the corridor between
+   * layers to hold the control, so arming this RELAYS OUT the graph — a compact
+   * canvas pitches its layers at 20px, which is the whole button.
+   *
+   * Offered on exactly the edges the other three gestures are ({@link
+   * isEditableEdge}): inserting on a fan-out or trigger edge would name a pair
+   * that exists in no definition. "Add a step at the very start" is the
+   * {@link onNodeInsert} drop instead — dragged from the first step's inbound
+   * handle onto empty canvas, which names one node rather than a synthesized
+   * edge. (A definition with no `on:` at all has no inbound handle on its first
+   * step, because nothing points at it; there the step list is the only way in.)
+   */
+  onEdgeInsert?: (sourceId: string, targetId: string) => void;
+  /**
+   * Add a step at the loose end of a connection dragged from a node's handle and
+   * released over empty canvas — the canvas's answer to "and then what?".
+   * `side` is which handle it left from: `"after"` for the outbound one (the new
+   * step follows `nodeId`), `"before"` for the inbound one (it precedes it).
+   *
+   * Reported for ANY node, including a trigger and a fan-out branch leaf: unlike
+   * an edge gesture, this names a node that certainly exists, and whether a step
+   * may go beside it is a question about the definition's schema — which this
+   * library does not model and the host already answers.
+   */
+  onNodeInsert?: (nodeId: string, side: "before" | "after") => void;
+  /**
+   * The `on:` list gains an entry. Drawn as a canvas control rather than a
+   * per-node one, because the workflow that most needs it is the one with NO
+   * trigger — which has no trigger node to hang a "+" on.
+   *
+   * Offered whenever it is supplied, including on a definition that ALREADY has
+   * a trigger: `on:` is a list with OR semantics, and a second subscription is a
+   * normal thing to want. Whether THIS workflow may take another one is a
+   * question about the definition's schema and the provider behind it, which
+   * this library does not model — a host that must cap the list withholds the
+   * callback.
+   */
+  onTriggerAdd?: () => void;
+  /** Remove the `on:` entry a trigger node stands for — the one node deletion
+   *  that IS a canvas gesture (every other node is a `do` entry, reordered and
+   *  removed in the list the host owns). Read the entry's position back with
+   *  `triggerNodeIndex`. */
+  onTriggerDelete?: (nodeId: string) => void;
+  /**
+   * AUTHORING problems anchored to the nodes and edges that carry them, so a
+   * compile error is visible on the canvas rather than only in a list beside it.
+   * See {@link WfProblem} — and note it is a separate channel from `nodeState`,
+   * which is what a node DID rather than what is wrong with what it says.
+   *
+   * A problem tints the node's border in either density, and states itself on a
+   * mark in the card's identity row (a corner of the compact tile). A graph
+   * showing a RUN is not an authoring surface — its cards and edges state the
+   * run instead, which takes precedence over a problem's colour on both, and the
+   * problem's mark and chip still render beside it.
+   *
+   * What the canvas gives is a LOCATOR: which step or dependency is at fault,
+   * with the messages on the mark's `title` and in the accessibility tree. It is
+   * deliberately not a reader for them — at the zoom a whole pipeline is viewed
+   * at, a panel of message text on the canvas is unreadable, and the host
+   * already owns the problem list that the messages are read and acted on in.
+   *
+   * Pairing contract: anchors are positional node ids, so a problem list must be
+   * derived from the SAME definition passed as `yaml`. Hand over a list computed
+   * against an older draft and an id that still exists may now name a different
+   * step, which puts the diagnostic on an innocent one — the graph cannot tell
+   * the two apart, any more than it can for a run's `nodeState`. A host that
+   * validates asynchronously therefore holds each result against the text it was
+   * computed from, and passes neither until they agree.
+   *
+   * Immutability contract, as for `edges`: the index is memoized on this array's
+   * reference, so pass a stable one.
+   */
+  problems?: readonly WfProblem[];
 }
-
-declare function WorkflowGraph(props: WorkflowGraphProps): React.JSX.Element;
-
-export { type BuildWorkflowGraphOptions, TRIGGER_NODE_ID, type WfEdge, type WfEdgeKind, type WfEdgeSpec, type WfGraph, type WfNode, type WfNodeData, type WfNodeState, type WfNodeStatus, type WfNodeTone, type WfProblem, type WfProblemSeverity, WorkflowGraph as WorkflowGraphLazy, type WorkflowGraphProps, actionNodeId, branchNodeId, buildWorkflowGraph, triggerNodeId, triggerNodeIndex };
+//#endregion
+//#region src/workflows/WorkflowGraphLazy.d.ts
+declare function WorkflowGraph(props: WorkflowGraphProps): import("react").JSX.Element;
+//#endregion
+export { type BuildWorkflowGraphOptions, type ModelBrandIdentity, ModelBrandStack, type WfEdge, type WfEdgeKind, type WfEdgeSpec, type WfGraph, type WfNode, type WfNodeData, type WfNodeState, type WfNodeStatus, type WfNodeTone, type WfProblem, type WfProblemSeverity, WorkflowGraph as WorkflowGraphLazy, type WorkflowGraphProps, modelBrandFor };