@w6w/ui 0.2.11 → 0.2.54

package/dist/flow-loop.d.ts

@@ -0,0 +1,98 @@
+import { Edge } from '@xyflow/react';
+import { FlowEdge, FlowStep, FlowWorkflow } from './flow-types.ts';
+import { StepNode } from './flow-utils.ts';
+type UsesLike = {
+    uses?: {
+        app?: string;
+        action?: string;
+    };
+};
+/** A step is a foreach iff it is `@w6w/control` · `foreach` (P1). */
+export declare function isForeachStep(step: UsesLike | undefined): boolean;
+/**
+ * The step ids a control step owns — engine `controlOwnedIds`, arm for arm
+ * (foreach `body`, parallel `branches`, if `then`/`else`; strings at any array depth).
+ */
+export declare function controlOwnedIds(step: FlowStep): string[];
+/** Every step id owned by some control step (engine `ownedByControl`). */
+export declare function ownedStepIds(steps: readonly FlowStep[]): Set<string>;
+/** A canvas each-lane edge in the ONE shape load, bridge and `applyConnect` share (P3). */
+export declare function eachLaneEdge(from: string, to: string, fromIsForeach: boolean, route?: string): Edge;
+/**
+ * The body drawn from `foreachId`: every step reachable from its Each-item port
+ * over each-lane edges, as a topological order (Kahn over the body's own each-lane
+ * edges, ties broken by discovery order) so the Each-item target is first and every
+ * edge goes from an earlier id to a later one. A plain chain comes out exactly as
+ * the chain. Never includes `foreachId` or a repeat — so it terminates on a cycle
+ * (steps stuck in one are appended in discovery order). `claimed` (internal) stops
+ * the walk BEFORE a step an earlier foreach already owns.
+ */
+export declare function loopBody(foreachId: string, nodes: readonly StepNode[], edges: readonly Edge[], claimed?: ReadonlySet<string>): string[];
+/** The each-lane edges with both ends inside `body` (the For each → body[0] link is not one). */
+export declare function bodyInternalEdges(body: readonly string[], edges: readonly Edge[]): Edge[];
+/**
+ * A body is plain iff it is a chain the ordered `with.body` list already says: every
+ * body node has at most one outgoing each-lane edge and none carries a route. Plain
+ * bodies serialize as the list alone; anything else also emits its body edges.
+ */
+export declare function isPlainBody(body: readonly string[], edges: readonly Edge[]): boolean;
+/** The definition edges a canvas's non-plain loop bodies need (empty for plain chains). */
+export declare function loopBodyDefinitionEdges(nodes: readonly StepNode[], edges: readonly Edge[]): FlowEdge[];
+/** Every foreach's body, handled in `nodes` order so emitted bodies are disjoint (P6). */
+export declare function loopBodies(nodes: readonly StepNode[], edges: readonly Edge[]): Map<string, string[]>;
+/** `bodyStepId → foreachId` over the whole canvas. */
+export declare function loopMembership(nodes: readonly StepNode[], edges: readonly Edge[]): Record<string, string>;
+/**
+ * The edge set after deleting step `id` (D-A4). A body step with exactly one inbound
+ * and one outbound each-lane edge is bridged (`prev → next`, each lane, keeping the
+ * inbound edge's route when `prev` is an If/Router, `out-each` iff `prev` is the
+ * foreach); any other body step just loses its incident edges; deleting the foreach
+ * also removes the each-lane edges of its whole body (the body steps stay, as
+ * ordinary unconnected nodes). A non-body step is the plain incident-edge filter.
+ */
+export declare function bridgeDeletedBodyStep(id: string, nodes: readonly StepNode[], edges: readonly Edge[]): Edge[];
+/** `with.body` is the derived view of the each lane — drop it from a foreach (P1); other steps untouched. */
+export declare function stripBody<T extends UsesLike & {
+    with?: Record<string, unknown>;
+}>(step: T): T;
+/** Why a connection would break the v1 linear-body rule (exhaustive; see {@link loopRefusal}). */
+export type LoopRefusalReason = "error_lane_in_body" | "outside_inbound" | "loop_cycle" | "already_in_loop" | "control_in_body" | "body_branch" | "body_exit";
+/**
+ * The loop rule for drawing `source → target` in `lane` (already promoted: a success
+ * connect from a body node arrives as `"each"`). First match wins. Pure; run on the
+ * INPUT edges, never a post-eviction set.
+ */
+export declare function loopRefusal(source: string, target: string, lane: "success" | "error" | "each", nodes: StepNode[], edges: Edge[]): LoopRefusalReason | null;
+export declare function loopRefusalMessage(reason: LoopRefusalReason): string;
+/**
+ * Set or clear `data.loopOf` from {@link loopMembership}. Same array reference when
+ * nothing changed, and the same node object for every unchanged node.
+ */
+export declare function stampLoopOf(nodes: StepNode[], edges: Edge[]): StepNode[];
+/** The delete-confirm text. Byte-identical to the plain message unless a For each owns a body. */
+export declare function deleteStepMessage(id: string, nodes: StepNode[], edges: Edge[]): string;
+export type LoopInvalidReason = "body_not_literal" | "body_unknown_step" | "body_self" | "body_duplicate" | "body_claimed_twice" | "body_contains_control" | "body_step_has_edges" | "legacy_not_linear";
+export type LoopInvalid = {
+    reason: LoopInvalidReason;
+    stepId?: string;
+};
+export type LoopResult = {
+    body: string[];
+    source: "body" | "legacy";
+    edges?: FlowEdge[];
+} | {
+    invalid: LoopInvalid;
+};
+/** The edges the engine would run: declared, else the implicit chain over main-graph (non-owned) steps. */
+export declare function effectiveEdges(wf: FlowWorkflow): FlowEdge[];
+/** A saved For each → `body[0]` link ({@link FOREACH_EACH_ROUTE}); the canvas draws it from `with.body`. */
+export declare const isEachLink: (e: FlowEdge) => boolean;
+/**
+ * What each foreach's loop is, in a stored definition — the ONE place that knows
+ * the legacy-chain rule (D-A3). A foreach carrying a `body` key is judged on it;
+ * one without is a legacy loop iff its success-lane successors form a valid linear
+ * chain (every node a non-control step owned by no control, whose only inbound edge
+ * is from its predecessor and whose only outbound edge is a success edge onward).
+ */
+export declare function definitionLoops(wf: FlowWorkflow): Record<string, LoopResult>;
+export {};

package/dist/flow-node-flags.d.ts

@@ -0,0 +1,14 @@
+import { FlowStep } from './flow-types.ts';
+export declare const PAUSED_LABEL = "Paused \u2014 test runs stop before this node";
+export declare const DISABLED_LABEL = "Disabled \u2014 skipped in every run";
+export declare function isPausedStep(step: FlowStep): boolean;
+export declare function isDisabledStep(step: FlowStep): boolean;
+/** `step` with `ui.paused` set (on) or removed (off); an emptied `ui` is dropped. */
+export declare function withPaused(step: FlowStep, on: boolean): FlowStep;
+/** `step` with `disabled: true` (on) or without the key (off). */
+export declare function withDisabled(step: FlowStep, on: boolean): FlowStep;
+/**
+ * The `stopAt` of a run started from `startId`'s ▶: every paused node except the start itself
+ * (pressing ▶ on a paused node runs it — the pause stops runs that ARRIVE at it).
+ */
+export declare function pausedStopAt(steps: readonly FlowStep[], startId: string): string[];

package/dist/flow-problems.d.ts

@@ -0,0 +1,69 @@
+import { Edge } from '@xyflow/react';
+import { LoopRefusalReason } from './flow-loop.ts';
+import { CanvasLane, FlowStep, FlowWorkflowInput } from './flow-types.ts';
+import { StepNode } from './flow-utils.ts';
+import { StepProblem, StepProblems } from './step-problems.ts';
+/**
+ * THE matcher: is `ref` a reference to foreach `foreachId`'s output, and what
+ * does it become inside the loop. `R.F.output` → `foreach.item`, `R.F.output.<rest>`
+ * → `foreach.item.<rest>`, `R.F.output[<rest>` → `foreach.item[<rest>`. Segment
+ * boundary only: `…outputs` and `for_each_10` never match.
+ */
+export declare function loopOutputRef(ref: string, foreachId: string): string | null;
+/**
+ * The loop problems of a stored definition, keyed by step id. Never throws and
+ * never mutates: any input `workflowToFlow` would reject gives `{}` (it runs in a
+ * host memo with no error boundary).
+ */
+export declare function findLoopProblems(input: FlowWorkflowInput): StepProblems;
+/** One editor-side parallel-write warning — the engine's `StateWriteWarning`, this code only. */
+export interface StateParallelWrite {
+    code: "state_parallel_write";
+    nodes: string[];
+    path: string[];
+}
+/**
+ * The editor mirror of the engine's plan-time parallel-write warning (R16, plan
+ * §2.3; proven equal on `core/packages/expr/tests/fixtures/state-write-conflicts.json`).
+ * Two writers are concurrent iff they sit in different branches of one
+ * `@w6w/control` `parallel`; else never when they share an anchor (outermost
+ * owning control, else the step) or one anchor reaches the other; else iff one
+ * `fanOut: "parallel"` step has two distinct outgoing edges in the SAME lane
+ * whose targets reach the two anchors. Each overlapping pair of static write
+ * paths gives one warning on the shorter path; deduped, sorted by the engine's
+ * order (`code`, then `nodes`, then `path`). Never throws (→ `[]`), never mutates.
+ */
+export declare function stateWriteConflicts(input: FlowWorkflowInput): StateParallelWrite[];
+/**
+ * `stateWriteConflicts` as canvas problems: each warning lands on both of its
+ * steps, naming the other one (`with`). Never throws (→ `{}`), never mutates.
+ */
+export declare function findStateWriteProblems(input: FlowWorkflowInput): StepProblems;
+/**
+ * Apply a problem's fix to `step`, returning a new step. Re-scans the step it is
+ * given (never trusts the problem's `refs` snapshot); the SAME reference comes
+ * back for a problem with no fix or nothing left to fix. Never mutates.
+ */
+export declare function applyStepProblemFix(step: FlowStep, problem: StepProblem): FlowStep;
+/**
+ * The lane of a drag, read from the handle the pointer went down on. xyflow's
+ * `connectionState.fromHandle` resolves an id-less handle (the Done port) to the
+ * node's FIRST handle (`out-each`), so it cannot tell Done from Each item;
+ * `onConnectStart` reports the real `handleId` (null for Done). Falls back to
+ * `fromHandle.id` when no matching start was recorded.
+ */
+export declare function dragLane(start: {
+    nodeId: string | null;
+    handleId: string | null;
+    handleType: string | null;
+} | null, fromNodeId: string, fromHandle: {
+    id?: string | null;
+    type?: string;
+} | null | undefined): CanvasLane;
+/**
+ * The loop reason a source-handle drag dropped ON an existing node is refused for
+ * (`null` when the loop rule has nothing to say). `onConnectEnd` shows it as the
+ * node-anchored notice instead of opening the step builder. The lane is promoted the
+ * way `planConnect` does: a success drag from a body node extends the body.
+ */
+export declare function connectDropRefusal(source: string, target: string, lane: "success" | "error" | "each", nodes: StepNode[], edges: Edge[]): LoopRefusalReason | null;

package/dist/flow-state.d.ts

@@ -0,0 +1,20 @@
+import { StateWriteConfig } from '@w6w/expr';
+import { FlowStep } from './flow-types.ts';
+export type StateMode = StateWriteConfig["mode"];
+/** The five modes, in the order the control lists them. */
+export declare const STATE_MODES: readonly StateMode[];
+export declare const STATE_MODE_LABELS: Record<StateMode, string>;
+type StepLike = Pick<FlowStep, "id" | "uses" | "state">;
+/** What the step writes, the default applied (R14: Set data merges at root, every other step is Off). */
+export declare function stateWriteFor(step: StepLike): StateWriteConfig;
+/**
+ * The step with `config` as its state write. The default is the key's ABSENCE
+ * (Off on an ordinary step, Merge at root on Set data), so writing the default
+ * removes `state`. Never mutates; every other key passes through.
+ */
+export declare function setStateWrite<S extends StepLike>(step: S, config: StateWriteConfig): S;
+/** The config written when the author picks `mode`: named after the step so it is valid at once. */
+export declare function seedStateWrite(step: Pick<FlowStep, "id">, mode: StateMode): StateWriteConfig;
+/** The control shows for app steps and triggers; every control-flow step (If, For each, Parallel, Race) hides it. */
+export declare function stateWriteVisible(step: Pick<FlowStep, "uses">): boolean;
+export {};

package/dist/flow-types.d.ts

@@ -1,3 +1,4 @@
+import { StateWriteConfig } from '@w6w/expr';
 import { FlowCanvas } from './canvas-types.ts';
 import { EdgeRunState } from './run-visuals.ts';
 import { ActionParam } from './types.ts';
@@ -7,13 +8,16 @@ export interface FlowStep {
         app: string;
         action: string;
         connection?: string | null;
+        connectionRef?: string;
+        /** An app TRIGGER node (`action` is the trigger key): behaves like a built-in trigger on the canvas. */
+        trigger?: true;
     };
     /**
      * Declared connection-port cardinality for this step (see core
      * `rfcs/node-types.md` · Ports & cardinality). Omitted fields fall through field-wise to the catalog action, the internal def, then `{ in: 1, out: "many" }`.
-     * A persisted value wins over the node's default — `in > 1` opts the step into
-     * accepting multiple inbound edges (e.g. a flow-control aggregator joining
-     * several upstream branches).
+     * A persisted value wins over the node's default. Only `in: 0` binds (no entry
+     * port); any `in >= 1` accepts any number of inbound edges (core node-types ·
+     * Alternate entries).
      */
     ports?: PortsDecl;
     with?: Record<string, unknown>;
@@ -37,6 +41,8 @@ export interface FlowStep {
      * runs them one after another.
      */
     fanOut?: "sequential" | "parallel";
+    /** Write to state (`Node.state`, core/rfcs/workflow.md). Absent = the default: Off, or Merge at root for `@w6w/data` set. */
+    state?: StateWriteConfig;
     /**
      * Authoring-time canvas coordinate for this step, in this editor's own
      * coordinate space (core `rfcs/workflow.md` · "Amendment — 2026-07-29:
@@ -60,10 +66,26 @@ export interface FlowStep {
         x: number;
         y: number;
     };
+    /**
+     * Disabled: skipped in EVERY run, published and triggered included — the node does not
+     * execute and its outgoing edges are skipped, so a node that depends only on it does not run
+     * either. An engine semantic (mirrors `Node.disabled` in `@w6w/workflow-types`). Written as
+     * `true` or absent, never `false`.
+     */
+    disabled?: true;
+    /**
+     * Editor-only metadata; the engine ignores it. `paused`: a test run started from a node's ▶
+     * stops BEFORE this node (it does not execute). Never affects a published or triggered run.
+     * Absent when empty, never `{}`.
+     */
+    ui?: {
+        paused?: true;
+    };
 }
 export interface FlowEdge {
     from: string;
     to: string;
+    route?: string;
     /**
      * Which outcome of the `from` step this edge carries (core
      * `rfcs/workflow.md` · "Amendment — 2026-07-29: failure-conditioned edges
@@ -111,7 +133,7 @@ export interface FlowEdge {
  * leaves the class in place, so `setEdgeWhen` assigns both keys explicitly
  * rather than spreading.
  */
-export declare function edgeVisuals(when: "success" | "error" | undefined, runState?: EdgeRunState): {
+export declare function edgeVisuals(when: CanvasLane | undefined, runState?: EdgeRunState): {
     className?: string;
     label?: string;
 };
@@ -121,6 +143,25 @@ export declare function edgeVisuals(when: "success" | "error" | undefined, runSt
  * (D-P2), since no consumer outside this package needs it.
  */
 export declare const ERROR_SOURCE_HANDLE = "out-error";
+/**
+ * The handle id of a For each's **Each item** exit port. The `each` lane derives
+ * `with.body` on save; its link to the first body step is also saved as a
+ * {@link FOREACH_EACH_ROUTE} edge so a reader sees which port it leaves.
+ */
+export declare const EACH_SOURCE_HANDLE = "out-each";
+/**
+ * `Edge.route` of a For each's **Done** port (the engine's `FOREACH_DONE_ROUTE`): the
+ * success edge that runs once, after every iteration. An unrouted For each success
+ * edge — the shape saved before the port had an id — is read as Done.
+ */
+export declare const FOREACH_DONE_ROUTE = "done";
+/** `Edge.route` of a For each's Each item link to `with.body[0]` (engine `FOREACH_EACH_ROUTE`). */
+export declare const FOREACH_EACH_ROUTE = "each";
+/**
+ * A lane on the CANVAS. `"each"` is canvas-only (a For each → body-step edge);
+ * the persisted {@link FlowEdge}`["when"]` deliberately stays `"success" | "error"`.
+ */
+export type CanvasLane = "success" | "error" | "each";
 /**
  * The `sourceHandle` a minted/re-laned/loaded edge carries for a given lane —
  * the inverse of {@link laneForSourceHandle}. `undefined` for `"success"`/
@@ -129,7 +170,7 @@ export declare const ERROR_SOURCE_HANDLE = "out-error";
  * already-saved workflow's edges implicitly use. An empty string would not do
  * this — an empty string is a real, if degenerate, handle id.
  */
-export declare function sourceHandleForLane(when: "success" | "error" | undefined): string | undefined;
+export declare function sourceHandleForLane(when: CanvasLane | undefined): string | undefined;
 /**
  * The lane a drag started from, read off the handle id React Flow reports.
  * **The one canonicalisation point** every minting/re-laning site calls
@@ -139,7 +180,7 @@ export declare function sourceHandleForLane(when: "success" | "error" | undefine
  * `"error"`; everything else — a near-miss id, `null`, `undefined` — is
  * `"success"`.
  */
-export declare function laneForSourceHandle(handleId: string | null | undefined): "success" | "error";
+export declare function laneForSourceHandle(handleId: string | null | undefined): CanvasLane;
 export interface FlowWorkflow {
     manifestVersion: string;
     id: string;
@@ -152,7 +193,13 @@ export interface FlowWorkflow {
         required?: boolean;
         default?: unknown;
     }>;
+    /** Starting data (`Workflow.initialState`): a literal JSON object that seeds the run's state tree. */
+    initialState?: Record<string, unknown>;
     nodes: FlowStep[];
+    connections?: Record<string, {
+        app: string;
+        connection: string | null;
+    }>;
     edges?: FlowEdge[];
     canvas?: FlowCanvas;
     /**
@@ -259,7 +306,7 @@ export declare const DOCUMENT_APP = "@w6w/document";
  */
 export declare const MODEL_APP = "@w6w/model";
 /**
- * Compile a Handlebars `template` string against a resolved `values` object
+ * Render Handlebars text or JSON string values against a resolved `values` object
  * (core rfcs/node-types.md · F-3 amendment, "the `@w6w/template` host node").
  * Host node: `runInternalNode` short-circuits this id before the registry
  * loads a module — it needs no privileged host resource (no DB, no
@@ -267,6 +314,74 @@ export declare const MODEL_APP = "@w6w/model";
  * compiles to a JS function, the same risk shape `@w6w/script` has.
  */
 export declare const TEMPLATE_APP = "@w6w/template";
+/** Host-run regular-expression operations. */
+export declare const REGEX_APP = "@w6w/regex";
+/**
+ * Read, write, count, list and query the entries of a named data store (core
+ * rfcs/node-types.md, the `@w6w/store` amendment). Host node, like
+ * {@link DOCUMENT_APP}: the run's own account and project are bound host-side, so
+ * there is no scope param — a store is addressed by NAME. The params mirror the
+ * `@w6w/store` internal-app manifest (pinned by `store-node-parity.test.ts`).
+ */
+export declare const STORE_APP = "@w6w/store";
+/** End the whole workflow successfully when its optional condition matches. */
+export declare const STOP_APP = "@w6w/stop";
+export declare const ROUTER_APP = "@w6w/router";
+export declare const RACE_APP = "@w6w/race";
+export declare const RACE_DESCRIPTION = "Continue once with the first arriving path\u2019s output. Later arrivals are ignored for this run. Other paths keep running.";
+export interface RouterRoute {
+    id: string;
+    label?: string;
+    condition?: unknown;
+    default?: boolean;
+}
+export declare function routesForStep(step: FlowStep): RouterRoute[];
+export declare const routeHandle: (id: string) => string;
+export declare const routeFromHandle: (handle: string | null | undefined) => string | undefined;
+/** Route ports the Router card's right edge holds at its natural height. */
+export declare const ROUTER_PORTS_AT_BASE_HEIGHT = 3;
+/** Card height (px, border-box) added per route port past the third. */
+export declare const ROUTER_PORT_STEP = 16;
+export interface RouterPort {
+    id: string;
+    /** Absent for an If's True port: the unnamed handle a route-less edge anchors to. */
+    handleId?: string;
+    label: string;
+    /** Handle position along its edge, as a CSS `top` (right-edge ports only). */
+    top?: string;
+}
+/**
+ * Where a Router's ports sit (human report, 2026-10-31: "they need to be
+ * attached to the router"). Condition routes go on the card's right edge,
+ * evenly spaced; the fallback route takes the bottom edge, the slot every
+ * other node gives its error port. Up to three right-edge ports fit the
+ * card's natural height; each one past that adds a fixed step, so five
+ * routes make a slightly taller card. Handle ids stay `route:<id>`, so
+ * saved edges keep resolving.
+ */
+export interface PortLayout {
+    right: RouterPort[];
+    bottom?: RouterPort;
+    minHeight?: number;
+}
+export declare function routerPortLayout(routes: RouterRoute[]): PortLayout;
+/**
+ * `Edge.route` of an If's false branch (the engine's `IF_FALSE_ROUTE`). The true
+ * branch is an edge with no route, which is what every If edge saved before the
+ * False port existed already is.
+ */
+export declare const IF_FALSE_ROUTE = "false";
+export declare function isIfStep(step: FlowStep): boolean;
+/**
+ * An If's ports, laid out the way {@link routerPortLayout} lays out a Router's
+ * (human report, 2026-10-31: "should not have error, it should have: true port
+ * and false port"). True takes the right edge; False takes the bottom edge, the
+ * slot every other node gives its error port, so an If has no error port. True
+ * keeps the unnamed handle, so saved If edges stay on it; False is `route:false`.
+ */
+export declare function ifPortLayout(): PortLayout & {
+    bottom: RouterPort;
+};
 /** True when `app` is a reserved internal pseudo-app id (`@w6w/*`). */
 export declare function isInternalApp(app: string): boolean;
 /** True when a node is an engine-native flow-control node (can't run standalone). */
@@ -278,6 +393,16 @@ export declare function isControlApp(app: string): boolean;
  * and send the filled values as `{ input }` rather than running the raw config.
  */
 export declare function isTriggerApp(app: string): boolean;
+/**
+ * Whether a step is a trigger NODE: one of the built-in triggers, or an app
+ * trigger node (`uses.trigger === true`). Canvas chrome, wiring and editing key
+ * on this; {@link isTriggerApp} stays for readers that mean the built-in
+ * `@w6w/*` triggers only (a callable workflow's input fields).
+ */
+export declare function isTriggerStep(uses: {
+    app: string;
+    trigger?: true;
+}): boolean;
 /** A palette entry for an internal node: its id, label, group, and config schema. */
 export interface InternalNodeDef {
     app: string;
@@ -289,6 +414,8 @@ export interface InternalNodeDef {
      * does. Shown wherever an app's name would be.
      */
     displayName: string;
+    /** Show one app entry in the palette and choose its action in configuration. */
+    groupActions?: boolean;
     group: "trigger" | "control" | "compute" | "request";
     /**
      * Inline SVG *inner* markup (paths / circles / polylines) for this primitive's
@@ -303,8 +430,9 @@ export interface InternalNodeDef {
      */
     hidden?: boolean;
     /**
-     * Connection ports: how many inbound (entry) and outbound (exit) connections
-     * this node accepts. A port is the ability to receive/emit a connection —
+     * Connection ports: whether this node has an entry (`in >= 1` takes any number
+     * of inbound edges; `in: 0` takes none) and how many outbound (exit) connections
+     * it allows. A port is the ability to receive/emit a connection —
      * rendered as a React Flow Handle. Defaults to one of each (`{ in: 1, out: 1 }`)
      * when omitted; a trigger overrides to `{ in: 0, out: 1 }` (nothing flows into
      * the entry node). Fixed for now — not user-editable.

package/dist/flow-utils.d.ts

@@ -1,5 +1,5 @@
 import { Edge, Node } from '@xyflow/react';
-import { FlowEdge, FlowStep, FlowWorkflow, FlowWorkflowInput } from './flow-types.ts';
+import { CanvasLane, FlowStep, FlowWorkflow, FlowWorkflowInput } from './flow-types.ts';
 import { RunStatus, StepVisualState } from './run-visuals.ts';
 import { StepProblem } from './step-problems.ts';
 export interface StepNodeData extends Record<string, unknown> {
@@ -23,11 +23,18 @@ export interface StepNodeData extends Record<string, unknown> {
      */
     runStatus?: RunStatus;
     /**
-     * A host-supplied problem with this step (e.g. a dangling connection).
+     * Host-supplied problems with this step (a dangling connection, loop problems).
      * Patched in by `WorkflowFlowEditor.tsx`'s `stepProblems` effect — never set
-     * here and never read by {@link flowToWorkflow} (not persisted).
+     * here, absent (never `[]`) when there are none, and never read by {@link flowToWorkflow} (not persisted).
      */
-    stepProblem?: StepProblem;
+    stepProblems?: StepProblem[];
+    /**
+     * The For each this step is a loop-body member of (canvas-only; derived on load
+     * and by the editor, never read by {@link flowToWorkflow}).
+     */
+    loopOf?: string;
+    /** This For each was converted from a legacy (no-`body`) loop on load. Canvas-only. */
+    legacyLoop?: boolean;
 }
 export type StepNode = Node<StepNodeData>;
 /**
@@ -46,13 +53,19 @@ export type StepNode = Node<StepNodeData>;
  * rewrite) in `flow-connect.ts`. A second hand-rolled copy of the template is
  * exactly how the rename path came to drop the qualifier.
  */
-export declare function flowEdgeId(from: string, to: string, when?: FlowEdge["when"]): string;
+export declare function flowEdgeId(from: string, to: string, when?: CanvasLane, route?: string): string;
 /**
  * Why a step id may not be saved from the editor, or `null` when it may. The one
  * rule here is "no `.`" (a dotted id cannot be addressed by `steps.<id>.output`);
  * duplicates and the edge-time `->` / `:error` checks are NOT this function's job.
  */
 export declare function stepIdError(id: string): string | null;
+/**
+ * {@link stepIdError} plus uniqueness: why `id` may not name a node of a graph whose other
+ * nodes are `taken`, or `null`. The rename in the step editor and the name in the add flow
+ * both validate through this.
+ */
+export declare function stepNameError(id: string, taken: Iterable<string>): string | null;
 /**
  * The one wording for a refused edge id, shared by both routes into the collision —
  * drawing a wire whose minted id is taken (`applyConnect` / `connectConflict`) and
@@ -108,6 +121,8 @@ export declare function stepIdError(id: string): string | null;
  * vague-but-true message beats a confident false one.
  */
 export declare function idClashMessage(lead: string, id: string, involved: readonly (string | null | undefined)[]): string;
+/** Read a definition in either shape into the canonical `nodes[]` form. */
+export declare function normalizeInput(input: FlowWorkflowInput): FlowWorkflow;
 /**
  * Turn a Workflow into (nodes, edges) with an auto-layout when no positions are
  * known.
@@ -117,11 +132,8 @@ export declare function idClashMessage(lead: string, id: string, involved: reado
  * positioned graph mixes the two: positioned steps sit where they were left,
  * unpositioned ones take their computed slot.
  *
- * `computeLayers` runs over the **whole** graph either way, and the per-column
- * row counter advances for every step including positioned ones — so an
- * unpositioned step's computed coordinate is a pure function of the graph and
- * does not shift depending on which of its neighbours happen to carry a
- * coordinate.
+ * Layout runs over the whole graph, including positioned steps, so a fallback
+ * coordinate does not depend on which neighbours already have saved positions.
  */
 export declare function workflowToFlow(input: FlowWorkflowInput): {
     nodes: StepNode[];
@@ -135,12 +147,12 @@ export declare function workflowToFlow(input: FlowWorkflowInput): {
  * button acts on **what is currently on the canvas**, including steps added and
  * wires drawn since the last save.
  *
- * Same {@link computeLayers} and same {@link slotPosition} as {@link
+ * Same {@link computePositions} as {@link
  * workflowToFlow}, so a graph with no stored positions lays out byte-identically
  * either way (pinned by `flow-utils.test.ts` — "auto-layout agrees with first
  * open"). The **only** difference is that a stored coordinate does not win here:
  * overriding hand placement is precisely what the author asked for by clicking.
- * That is also why the caller confirms first — there is no undo in studio.
+ * The editor records this as one undoable layout change.
  *
  * Layering is keyed by **`node.id`**, not `node.data.step.id`: React Flow's
  * `edge.source`/`edge.target` name node ids, so keying by anything else would
@@ -287,5 +299,7 @@ export declare function stepToJson(step: StepLike): string;
  * writable: the params-only `JsonEditor`'s `onValidChange` feeds straight back
  * into `with`/`withValues`, same as it always has.
  */
-export declare function paramsToJson(step: Pick<StepLike, "with">): string;
+export declare function paramsToJson(step: Pick<StepLike, "with"> & {
+    uses?: StepLike["uses"];
+}): string;
 export {};