@w6w/ui 0.2.0 → 0.2.54

package/dist/flow-connect.d.ts

@@ -1,5 +1,6 @@
 import { Edge } from '@xyflow/react';
-import { PortsLookup } from './flow-types.ts';
+import { LoopRefusalReason } from './flow-loop.ts';
+import { CanvasLane, PortsLookup } from './flow-types.ts';
 import { StepNode } from './flow-utils.ts';
 /**
  * Which lane a React Flow edge belongs to (core `rfcs/workflow.md` · `Edge.when`
@@ -8,7 +9,7 @@ import { StepNode } from './flow-utils.ts';
  * `data` at all. The single accessor: every consumer calls this rather than
  * re-deriving the fallback, so "absent means success" is decided once.
  */
-export declare function edgeLane(e: Edge): "success" | "error";
+export declare function edgeLane(e: Edge): CanvasLane;
 /**
  * A refused connection: the source's exit port is full **in this lane** and the cap
  * is finite. Drawing past a finite `out` cap is refused, never satisfied by evicting
@@ -18,14 +19,22 @@ export type OutCapRefusal = {
     refused: "out_cap";
     cap: number;
 };
+/**
+ * A refused connection that would break the v1 linear-body rule of a For each
+ * (see {@link loopRefusal}). Raised before the out-cap census and before any
+ * inbound eviction, always against the INPUT edges.
+ */
+export type LoopRefusal = {
+    refused: "loop";
+    reason: LoopRefusalReason;
+};
 /**
  * The hard rules for an edge `source → target` — the ones no amount of
  * replacement can satisfy: a real, *distinct* pair (no self-loops), no duplicate
  * edge, the target accepts an entry port (blocks connecting *into* a trigger,
  * which declares `in: 0`), and the source has an exit port. Port **capacity** is
- * deliberately NOT checked here: a full single-slot port is freed by replacement
- * (see `applyConnect`), so dragging a new wire from an already-connected node
- * re-points it rather than being rejected. Used as the live `isValidConnection`.
+ * deliberately NOT checked here: an input accepts any number of edges, and the exit
+ * cap is refused in `applyConnect`. Used as the live `isValidConnection`.
  *
  * The duplicate-pair check is **lane-blind by design**, and that is a v1 *editor*
  * limit, not a model limit: the model permits a success edge and an error edge
@@ -41,13 +50,13 @@ export type OutCapRefusal = {
  * Letting the drop through and refusing in `applyConnect` is what lets the reason
  * paint — see {@link connectConflict}.
  */
-export declare function canConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], lookup?: PortsLookup): boolean;
+export declare function canConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], lookup?: PortsLookup, route?: string): boolean;
 /**
  * Build the next edge set for a new `source → target` connection. **Additive at the
  * source**: a source under its `out` cap (or unbounded) keeps every existing edge and
  * gains one; at a finite cap the connection is **refused** (see {@link connectRefusal}),
- * never satisfied by evicting. The target's entry port is still single-slot-replacing:
- * the oldest inbound edge(s) are dropped to make room. Returns `null` when the
+ * never satisfied by evicting. The target's entry port accepts any number of
+ * inbound edges, so nothing is ever evicted there. Returns `null` when the
  * connection is disallowed by {@link canConnect}, refused at the out cap — **or when the minted id would
  * duplicate a surviving edge's id**, the same refusal {@link setEdgeWhen} performs
  * through the same {@link collidingEdgeId} test.
@@ -68,13 +77,10 @@ export declare function canConnect(source: string | null | undefined, target: st
  * `send → (error) → fallback` shape authorable at all. No `ports.out` bump is
  * needed, so every persisted definition and palette entry stays valid.
  *
- * The target's entry capacity stays **lane-blind**, and that asymmetry is the
- * point: a converging tail step receiving one success and one error edge is
- * governed by `ports.in` alone. Partitioning the target rule by lane too — the
- * plausible "symmetry" cleanup — would let a `ports.in: 1` node silently accept
- * two inbound edges.
+ * The target's entry has no capacity: any number of edges, from any number of
+ * sources (several triggers may feed one node), converge on it.
  */
-export declare function applyConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: "success" | "error", lookup?: PortsLookup): Edge[] | null;
+export declare function applyConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: CanvasLane, lookup?: PortsLookup, route?: string): Edge[] | null;
 /**
  * The id of the existing edge that drawing `source → target` would collide with, or
  * `null` when the connection is safe (or refused for an ordinary reason — a
@@ -85,13 +91,13 @@ export declare function applyConnect(source: string | null | undefined, target:
  * selects that edge and renders the message in the edge-lane panel (never a browser
  * dialog; see `.ai/conventions.md`).
  */
-export declare function connectConflict(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: "success" | "error", lookup?: PortsLookup): string | null;
+export declare function connectConflict(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: CanvasLane, lookup?: PortsLookup, route?: string): string | null;
 /**
  * The out-cap refusal for drawing `source → target`, or `null` when the source has
  * room (or is unbounded). The editor renders `cap` in an inline message on the same
  * channel as {@link connectConflict}; {@link applyConnect} returns `null` for it.
  */
-export declare function connectRefusal(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: "success" | "error", lookup?: PortsLookup): OutCapRefusal | null;
+export declare function connectRefusal(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: CanvasLane, lookup?: PortsLookup, route?: string): OutCapRefusal | LoopRefusal | null;
 /**
  * Re-lane one edge. Updates its `data.when`, its visuals and its id, and frees
  * nothing: when the destination lane is at a finite out cap the switch is refused

package/dist/flow-delete.d.ts

@@ -0,0 +1,16 @@
+import { Edge } from '@xyflow/react';
+import { FlowCanvas } from './canvas-types.ts';
+import { StepNode } from './flow-utils.ts';
+export interface FlowDeleteSelection {
+    nodeIds: string[];
+    edgeIds: string[];
+}
+/** Capture the full selection, independently of the first item shown in the side panel. */
+export declare function selectedFlowElements(nodes: StepNode[], edges: Edge[]): FlowDeleteSelection;
+/** Apply the entire confirmed selection before the editor emits one change/history entry. */
+export declare function deleteFlowSelection(selection: FlowDeleteSelection, nodes: StepNode[], edges: Edge[], canvas: FlowCanvas): {
+    nodes: StepNode[];
+    edges: Edge[];
+    canvas: FlowCanvas;
+};
+export declare function flowDeleteMessage(selection: FlowDeleteSelection, nodes: StepNode[], edges: Edge[]): string;

package/dist/flow-fanout.d.ts

@@ -2,7 +2,7 @@ import { Edge } from '@xyflow/react';
 import { FlowStep } from './flow-types.ts';
 export type FanOutMode = "sequential" | "parallel";
 /**
- * `count` is the largest number of outgoing edges the step has in any ONE lane
+ * `count` is the largest number of outgoing edges the node has in any ONE lane
  * (success / error); fan-out only means something at `count >= 2`.
  */
 export declare function fanOutState(stepId: string, edges: readonly Edge[]): {
@@ -11,5 +11,5 @@ export declare function fanOutState(stepId: string, edges: readonly Edge[]): {
 };
 /** Sequential is the default, so it is expressed by the key's ABSENCE. */
 export declare function setFanOut(step: FlowStep, mode: FanOutMode): FlowStep;
-/** Card-badge wording: how many next steps run, and in which mode. */
+/** Card-badge wording: how many next nodes run, and in which mode. */
 export declare function fanOutLabel(count: number, mode: FanOutMode): string;

package/dist/flow-history.d.ts

@@ -0,0 +1,75 @@
+import { Edge } from '@xyflow/react';
+import { FlowCanvas } from './canvas-types.ts';
+import { FlowStep, FlowWorkflow } from './flow-types.ts';
+import { StepNode } from './flow-utils.ts';
+/** Only authored graph data. Tests, samples, run paint, selection and viewport never enter history. */
+export interface FlowEditSnapshot {
+    nodes: FlowStep[];
+    edges: NonNullable<FlowWorkflow["edges"]>;
+    connections: NonNullable<FlowWorkflow["connections"]>;
+    canvas: FlowCanvas;
+    /** Keep the live layout even when saving positions is switched off. */
+    positions: Record<string, {
+        x: number;
+        y: number;
+    }>;
+}
+export declare function captureFlowEdit(base: FlowWorkflow, nodes: StepNode[], edges: Edge[], connections: FlowEditSnapshot["connections"], canvas: FlowCanvas): FlowEditSnapshot;
+export declare function restoreFlowEdit(base: FlowWorkflow, snapshot: FlowEditSnapshot): {
+    nodes: {
+        position: {
+            x: number;
+            y: number;
+        };
+        id: string;
+        data: import('./flow-utils.ts').StepNodeData;
+        sourcePosition?: import('@xyflow/react').Position;
+        targetPosition?: import('@xyflow/react').Position;
+        hidden?: boolean;
+        selected?: boolean;
+        dragging?: boolean;
+        draggable?: boolean;
+        selectable?: boolean;
+        connectable?: boolean;
+        deletable?: boolean;
+        dragHandle?: string;
+        width?: number;
+        height?: number;
+        initialWidth?: number;
+        initialHeight?: number;
+        parentId?: string;
+        zIndex?: number;
+        extent?: "parent" | import('@xyflow/react').CoordinateExtent | null;
+        expandParent?: boolean;
+        ariaLabel?: string;
+        origin?: import('@xyflow/react').NodeOrigin;
+        handles?: import('@xyflow/react').NodeHandle[];
+        measured?: {
+            width?: number;
+            height?: number;
+        };
+        type?: string | undefined;
+        style?: import('react').CSSProperties;
+        className?: string;
+        resizing?: boolean;
+        focusable?: boolean;
+        ariaRole?: import('react').AriaRole;
+        domAttributes?: Omit<import('react').HTMLAttributes<HTMLDivElement>, "id" | "style" | "className" | "draggable" | "role" | "aria-label" | "defaultValue" | "dangerouslySetInnerHTML" | keyof import('react').DOMAttributes<HTMLDivElement>>;
+    }[];
+    edges: Edge[];
+};
+/** Bounded, editor-session history. One text-field focus session is one undoable edit. */
+export declare class FlowEditHistory {
+    private past;
+    private future;
+    private present;
+    private group;
+    private readonly limit;
+    constructor(initial: FlowEditSnapshot, limit?: number);
+    reset(initial: FlowEditSnapshot): void;
+    record(snapshot: FlowEditSnapshot, group?: object): void;
+    undo(): FlowEditSnapshot | undefined;
+    redo(): FlowEditSnapshot | undefined;
+}
+/** Leave native text undo and CodeMirror's own history alone. */
+export declare function isFlowTextTarget(target: EventTarget | null): boolean;

package/dist/flow-layout.d.ts

@@ -0,0 +1,13 @@
+import { Edge } from '@xyflow/react';
+import { FlowCanvas } from './canvas-types.ts';
+import { StepNode } from './flow-utils.ts';
+/**
+ * Arrange paths and their section frames together. Membership is authored data:
+ * fit each frame to its members, never infer new membership from moved geometry.
+ * A section spanning non-members is moved with its members below the obstruction.
+ * Notes and empty sections retain their authored geometry.
+ */
+export declare function relayoutFlow(nodes: StepNode[], edges: Edge[], canvas: FlowCanvas): {
+    nodes: StepNode[];
+    canvas: FlowCanvas;
+};

package/dist/flow-loop-colors.d.ts

@@ -0,0 +1,39 @@
+import { Edge } from '@xyflow/react';
+import { CSSProperties } from 'react';
+import { StepNode } from './flow-utils.ts';
+/** How many `--w6w-loop-N` tokens `_tokens.scss` defines. */
+export declare const LOOP_TONES = 6;
+/**
+ * Tone index (1-based) per For each id. Ids are visited in sorted order so the result
+ * does not depend on node order; each takes its hashed tone, or the next free one.
+ */
+export declare function assignLoopTones(foreachIds: Iterable<string>): Map<string, number>;
+/** The CSS colour for a tone index. */
+export declare function loopToneVar(tone: number): string;
+/** The loops enclosing `id`, outermost first, following each For each's own `loopOf`. */
+export declare function enclosingLoops(id: string, loopOfById: ReadonlyMap<string, string | undefined>): string[];
+/**
+ * Paint each-lane edges with the colour of the loop they belong to: the For each itself
+ * for its Each item link, else the loop the edge's source step runs in. Sets the
+ * `--w6w-loop-color` custom property the `.w6w-edge-each` rule reads, so run-state
+ * classes still compose over it. Same array when nothing needs painting.
+ */
+export declare function paintLoopEdges(edges: Edge[], tones: ReadonlyMap<string, number>, loopOfById: ReadonlyMap<string, string | undefined>): Edge[];
+/**
+ * The colour custom property a card's root carries: a For each's own tone, read by its
+ * Each item port. A loop-body step gets none — it looks exactly like a step outside a
+ * loop; its dots are what mark it.
+ */
+export declare function loopCardStyle(id: string, tones: ReadonlyMap<string, number>): CSSProperties | undefined;
+/** What the canvas paints loops from: each For each's tone, and each step's own loop. */
+export type LoopPaint = {
+    tones: ReadonlyMap<string, number>;
+    loopOf: ReadonlyMap<string, string | undefined>;
+};
+/**
+ * A string that changes only when a loop's membership does — the memo key for
+ * {@link loopPaint}, so dragging a node does not hand every card a new context value.
+ */
+export declare function loopPaintKey(nodes: readonly StepNode[]): string;
+/** Rebuild the {@link LoopPaint} a {@link loopPaintKey} describes. */
+export declare function loopPaint(key: string): LoopPaint;

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 {};