@w6w/ui 0.2.11 → 0.2.55

package/dist/node-samples.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Persisted node samples — the server's record of the last output SHAPE (and, when small enough,
+ * the value) each node produced, from a step Test, a node run or a full run
+ * (`GET /workflows/:id/node-samples`). The editor loads them once per workflow so the picker,
+ * the ƒx previews and the Test tab still offer an upstream node's keys after a reload, a reopen or
+ * another browser, without re-running anything.
+ *
+ * They are a FALLBACK under what the editor already holds: a fresh in-memory output (a saved
+ * step-test's `lastRunOutput`) wins, unless the persisted sample is strictly newer. Field
+ * inference (`inferOutputFields`) is the same either way — a skeleton carries the same keys as
+ * the real value it was taken from.
+ *
+ * Pure and JSX-free so `node --test` exercises it directly.
+ */
+/** A node output's structural shape, as the server records it. */
+export type NodeShape = {
+    type: "string" | "number" | "boolean" | "null" | "unknown";
+} | {
+    type: "object";
+    fields: Record<string, NodeShape>;
+} | {
+    type: "array";
+    items?: NodeShape;
+};
+/** One persisted node sample (`GET /workflows/:id/node-samples` → `nodeSamples[]`). */
+export interface NodeSample {
+    nodeId: string;
+    shape: NodeShape;
+    /** The output itself, when the server kept it (omitted when too large — `sampleOmitted`). */
+    sample?: unknown;
+    sampleOmitted?: true;
+    source: "step_test" | "node_run" | "run";
+    runId?: string;
+    /** ISO timestamp of the write. */
+    updatedAt: string;
+}
+/**
+ * A representative value of `shape`: `""`, `0`, `false`, `null`, an object of its fields, an
+ * array of one item skeleton (`[]` when the item shape is unknown). `unknown` is `null`.
+ */
+export declare function shapeToSkeleton(shape: NodeShape | undefined): unknown;
+/** Index `samples` by node id (the last entry for a repeated id wins). */
+export declare function indexNodeSamples(samples: readonly NodeSample[] | undefined): Record<string, NodeSample>;
+/**
+ * One node's effective output for SHAPE inference: the fresh in-memory output wins (unless the
+ * persisted sample is strictly newer than `freshAt`), else the persisted `sample`, else
+ * {@link shapeToSkeleton} of its shape. `undefined` when neither exists.
+ */
+export declare function effectiveNodeOutput(nodeId: string, fresh: Record<string, unknown>, persisted: Record<string, NodeSample>, freshAt?: Record<string, string | null | undefined>): unknown;
+/**
+ * {@link effectiveNodeOutput} for every node with a fresh or persisted output — the map the
+ * editor hands `StepShapeContext.testOutputs`, so a downstream node's picker offers the
+ * persisted keys after a reload.
+ */
+export declare function effectiveNodeOutputs(fresh: Record<string, unknown>, persisted: Record<string, NodeSample>, freshAt?: Record<string, string | null | undefined>): Record<string, unknown>;
+/**
+ * The outputs the Result PREVIEWS read: real values only — never a skeleton, which would preview
+ * a made-up `""`/`0`. Same precedence as {@link effectiveNodeOutput}; a newer persisted sample
+ * with no value falls back to the fresh one.
+ */
+export declare function previewNodeOutputs(fresh: Record<string, unknown>, persisted: Record<string, NodeSample>, freshAt?: Record<string, string | null | undefined>): Record<string, unknown>;
+/**
+ * {@link effectiveNodeOutputs} split into its two tiers, so the editor can hand the picker
+ * `testOutputs` (fresh) and `persistedOutputs` (persisted) SEPARATELY and show the right hint.
+ * A persisted sample wins only when there is no fresh output or it is strictly newer than
+ * `freshAt`; then the fresh entry is dropped from `fresh` and the persisted shape (its kept
+ * value, else its skeleton) goes in `persisted`. Elsewhere `fresh` is the fresh map unchanged.
+ */
+export declare function splitNodeOutputs(fresh: Record<string, unknown>, persisted: Record<string, NodeSample>, freshAt?: Record<string, string | null | undefined>): {
+    fresh: Record<string, unknown>;
+    persisted: Record<string, unknown>;
+};
+/**
+ * {@link previewNodeOutputs} split into tiers: `persisted` holds only REAL kept values of the
+ * persisted samples that win (never a skeleton); `fresh` is the fresh map minus those ids.
+ */
+export declare function splitPreviewOutputs(fresh: Record<string, unknown>, persisted: Record<string, NodeSample>, freshAt?: Record<string, string | null | undefined>): {
+    fresh: Record<string, unknown>;
+    persisted: Record<string, unknown>;
+};

package/dist/output-shape.d.ts

@@ -1,13 +1,11 @@
 /**
  * An upstream step's output SHAPE — the field paths a later step can pick —
- * from the three places one can come from, in precedence order:
- *
- * 1. **Declared** — the app action's `output` (`core/rfcs/action.md`
- *    `OutputField[]`), so a downstream step can reference `get-event`'s
- *    `name.text` before anything has run.
- * 2. **Sample** — the action's `sample` value, when it declares no `output`.
- * 3. **Test run** — the step's last saved test output, when the action
- *    declares neither. With none of the three, the author has to run a test.
+ * from the places one can come from. A real shape (a fresh test output, else
+ * the persisted one) is the BASE and keeps every key; the app's declared
+ * `output` (`core/rfcs/action.md` `OutputField[]`) annotates it and adds its
+ * declared-only keys (muted). With no real shape the declared `output` drives
+ * the keys alone, then keys inferred from the action's `sample`. With none of
+ * these, the author has to run a test.
  *
  * Every field is a dot-separated PATH (`start.utc`), the spec's own notation
  * for nesting (`OutputField.key`: "Dot notation for nested paths"). That is
@@ -24,15 +22,28 @@ export interface OutputFieldRef {
     label?: string;
     /** `true` — `key` is a dot path whose segments are checked one by one. */
     path: true;
+    /**
+     * `true` when a real (fresh/persisted) shape exists and this key came ONLY from the app's
+     * declaration — the picker adds it muted, "declared by the app".
+     */
+    declaredOnly?: true;
 }
-/** Where a step's offered fields came from. */
-export type OutputShapeSource = "declared" | "sample" | "test";
+/**
+ * Where a step's offered fields came from: a fresh test output, the persisted test shape,
+ * the app's declared `output`, or keys inferred from the app's `sample`.
+ */
+export type OutputShapeSource = "fresh" | "persisted" | "declared" | "sample";
 /**
  * The fields an action's `output` declares, or `undefined` when it declares
  * none. A `DynamicOutput` (`{ source }`) is resolved by a hook the editor does
  * not run, so it counts as "nothing declared" and the test-run fallback applies.
  */
 export declare function declaredOutputFields(output: unknown): OutputFieldRef[] | undefined;
+/**
+ * The item keys a declared array field's `items` lists (`undefined` when the key is not a
+ * declared array field with items) — what a never-run For each over that array iterates.
+ */
+export declare function declaredItemFields(output: unknown, key: string): OutputFieldRef[] | undefined;
 /**
  * Field paths inferred from a concrete value (an action's `sample` or a test
  * run's output): every key of a plain object, recursing into nested plain
@@ -48,11 +59,16 @@ export interface ActionShapeDef {
     sample?: unknown;
 }
 /**
- * Resolve a step's offered fields by the precedence above. `action` is the
- * app action definition (`undefined` while its app's actions are loading, or
- * for a node that has none); `testOutput` is the step's last saved test output.
+ * Resolve a step's offered fields. KEYS MERGE and never hide:
+ * - with a real shape (the fresh test output, else the persisted one) every real key is
+ *   offered; the app's declared `output` annotates matching keys (label) and its
+ *   declared-only keys are appended with `declaredOnly: true`;
+ * - with no real shape, the declared `output` drives the keys alone (`declared`), else
+ *   the keys inferred from `sample` (`sample`).
+ * `action` is the app action/trigger definition (`undefined` while its app is loading);
+ * `fresh` / `persisted` are SEPARATE inputs so the tier stays visible.
  */
-export declare function resolveOutputShape(action: ActionShapeDef | undefined, testOutput: unknown): {
+export declare function resolveOutputShape(action: ActionShapeDef | undefined, fresh: unknown, persisted?: unknown): {
     fields: OutputFieldRef[];
     from: OutputShapeSource;
 } | undefined;

package/dist/param-customization.d.ts

@@ -0,0 +1,7 @@
+import { ResolveScope } from './resolve-params.ts';
+/** Authored JSON customization is kept apart from the editable form values. */
+export declare function hasParamCustomization(values: Record<string, unknown>): boolean;
+/** null: invalid; undefined: a binding whose fields can only be checked at runtime. */
+export declare function customizedParamValues(values: Record<string, unknown>): Record<string, unknown> | undefined | null;
+/** Resolve authored children only. A substituted object is data, not another template. */
+export declare function previewCustomization(value: unknown, scope: ResolveScope, literalKeys?: readonly string[]): unknown;

package/dist/provider.d.ts

@@ -1,5 +1,7 @@
 import { ReactNode } from 'react';
-import { ActionDef, ApiCallRecord, AppSummary, AuthDef, ConnectionBinding, ConnectionSummary, CreateConnectionBody, CredentialDependents, CredentialSummary, CredentialTestResult, FunctionDetail, FunctionSummary, ResolveFieldsBody, ResolveFieldsResult, SavedTest, SubscriptionSummary, ThemeMode, TriggerSummary, WorkflowDetail, WorkflowSummary } from './types.ts';
+import { NodeSample } from './node-samples.ts';
+import { NodeTestInput } from './test-inputs.ts';
+import { ActionDef, ApiCallRecord, AppSummary, AuthDef, ConnectionBinding, ConnectionSummary, CreateConnectionBody, CredentialDependents, CredentialSummary, CredentialTestResult, FunctionDetail, FunctionSummary, ResolveFieldsBody, ResolveFieldsResult, SavedTest, SubscriptionSummary, ThemeMode, TriggerSummary, WebhookListenSession, WorkflowDetail, WorkflowSummary } from './types.ts';
 /**
  * A single tester-run summary from the unified `run_log` ledger, keyed to a
  * connection. Thin by design — the full result payload stays server-side in
@@ -75,6 +77,14 @@ export interface StepStartState {
     trigger?: {
         event?: unknown;
     };
+    /**
+     * The iteration scope of a step inside a For each body → `foreach.item` / `foreach.index`
+     * (on the wire `state.foreach = { item, index }`, index defaulting to 0).
+     */
+    foreach?: {
+        item?: unknown;
+        index?: number;
+    };
 }
 /**
  * A caller-supplied override merged into an app action's outbound request at
@@ -111,6 +121,8 @@ export interface ListAppsPageOptions {
     q?: string;
     /** Server-side category filter (e.g. `"ai"`). */
     category?: string;
+    /** Server-side filter to apps declaring at least one trigger (`GET /apps?hasTriggers=true`); `total` is then the filtered total. */
+    hasTriggers?: boolean;
     /** Server-side id allow-list (`GET /apps?ids=a,b`); `total` is then the filtered total. */
     ids?: string[];
     /** Opaque pagination cursor from a prior {@link AppsPageResult.nextCursor}. */
@@ -137,6 +149,20 @@ export interface AppsPageResult {
     limit?: number;
     expiresAt?: string;
 }
+/**
+ * One page of a data store's entries for the `data-store-key` picker
+ * ({@link W6WApi.listDataStoreEntries}). `value` is the stored JSON, which the
+ * picker shortens to a one-line preview; `updatedAt` is an ISO timestamp.
+ */
+export interface DataStoreEntryOptions {
+    items: {
+        key: string;
+        value?: unknown;
+        updatedAt?: string;
+    }[];
+    /** True when further matching entries exist past this page. */
+    more?: boolean;
+}
 export interface W6WApi {
     /**
      * List registered apps to pick from in the connection modal.
@@ -189,6 +215,34 @@ export interface W6WApi {
         model: string;
         status: "active" | "broken";
     }[]>;
+    /**
+     * OPTIONAL: the project's data stores, for the `data-store` step-param
+     * picker (`@w6w/store`). Absent, the param renders as a plain text input and
+     * this is never called. Archived stores are not listed by the host.
+     * `project` is the editor's own project (`WorkflowProjectProvider`) when it
+     * has one — a host should list THAT project's stores, not guess one from its
+     * URL; `undefined` leaves the choice to the host.
+     */
+    listDataStores?(project?: string): Promise<{
+        name: string;
+        kind: string;
+    }[]>;
+    /**
+     * OPTIONAL: ONE page of a data store's entries, for the `data-store-key`
+     * step-param picker (`@w6w/store` get/set/delete/increment). Absent, the key
+     * renders as a plain text input and this is never called.
+     * `store` is the store's NAME (what the step's `store` param holds) — the
+     * host resolves it to its own id. `prefix` is the server-side key search
+     * (the host's `GET /data-stores/:id/entries?prefix=`); `limit` caps the page,
+     * so a picker never loads a whole store. `more` is true when the store holds
+     * further matches past this page. `project` follows the `listDataStores` rule.
+     */
+    listDataStoreEntries?(store: string, opts: {
+        project?: string;
+        prefix?: string;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<DataStoreEntryOptions>;
     /**
      * OPTIONAL: resolve the choices of `options: { source: "resolveFields" }`
      * params from the current form (`POST` to the host). Absent, those params
@@ -275,6 +329,11 @@ export interface W6WApi {
         project?: string;
         state?: StepStartState;
         overrides?: RequestOverrides;
+        /**
+         * The workflow the step belongs to, so the host resolves `nodes.<id>.config` (e.g. a
+         * webhook node's `url`) as on a run. The host reads only the caller's own workflows.
+         */
+        workflowId?: string;
     }): Promise<{
         value: unknown;
         logs?: string[];
@@ -354,6 +413,28 @@ export interface W6WApi {
      * `/workflows/:workflowId/steps/:stepId/tests`.
      */
     listStepTests(workflowId: string, stepId: string): Promise<StepTest[]>;
+    /**
+     * OPTIONAL. The workflow's persisted node samples — each node's last output shape (and value,
+     * when kept) from a step Test, a node run or a full run, written server-side on every one of
+     * them. The flow editor loads them once per workflow so upstream keys survive a reload
+     * (`node-samples.ts`); a host without it behaves exactly as before. GETs
+     * `/workflows/:workflowId/node-samples` → `{ nodeSamples }`.
+     */
+    loadNodeSamples?(workflowId: string): Promise<NodeSample[]>;
+    /**
+     * OPTIONAL. The test input each node of the workflow last ran with in the editor (a trigger's
+     * filled fields, any other node's incoming state) — so the Run node modal, the Test tabs and the
+     * header Run reopen prefilled (`test-inputs.ts`). Server-side, never in the workflow definition.
+     * GETs `/workflows/:workflowId/test-inputs` → `{ testInputs }`. A host without it falls back to
+     * the latest step-test fixture, as before.
+     */
+    loadTestInputs?(workflowId: string): Promise<NodeTestInput[]>;
+    /**
+     * OPTIONAL. Remember the node's test input (newest wins; `{}` is a CLEAR). The server drops
+     * sealed envelopes; the caller drops literal secrets first (`rememberableInput`). PUTs
+     * `/workflows/:workflowId/nodes/:nodeId/test-input` `{ input }`.
+     */
+    saveTestInput?(workflowId: string, nodeId: string, input: Record<string, unknown>): Promise<void>;
     /**
      * List the caller's registered Functions (core rfcs/function.md) — drives
      * the step builder's Functions tab (F-2.0). GETs `/functions`.
@@ -403,11 +484,11 @@ export interface W6WApi {
     }>;
     /**
      * List apps that declare at least one trigger — the Triggers tab's
-     * "App triggers" section (T-0). GETs whatever the host resolves to (e.g.
-     * apps filtered by `triggerCount > 0`).
+     * Apps filtered by `triggerCount > 0`. UNUSED by the step builder: the Triggers
+     * tab resolves connected apps via `listAppsByIds` and searches via
+     * `listAppsPage({ hasTriggers: true })`. The member stays on the public surface.
      *
-     * OPTIONAL, like `listTestRuns?` above: a host that hasn't wired this member
-     * still typechecks and simply doesn't render the App-triggers section.
+     * OPTIONAL, like `listTestRuns?` above.
      */
     listTriggerApps?(): Promise<AppSummary[]>;
     /**
@@ -420,6 +501,31 @@ export interface W6WApi {
      * `/workflows/:id/subscriptions`.
      */
     listSubscriptionsForWorkflow?(workflowId: string): Promise<SubscriptionSummary[]>;
+    /**
+     * "Listen for test event" on a `@w6w/webhook` subscription: opens a short-lived session in
+     * which the receive URL captures the next request, even for an unpublished workflow. POSTs
+     * `/subscriptions/:id/listen`.
+     */
+    startWebhookListen?(subscriptionId: string): Promise<{
+        session: WebhookListenSession;
+        webhookUrl: string;
+    }>;
+    /**
+     * Long-poll a listen session (`GET /subscriptions/:id/listen/:sessionId?wait=`). Resolves as
+     * soon as a request is captured or the session expires, else after `waitSeconds` (max 25).
+     */
+    pollWebhookListen?(subscriptionId: string, sessionId: string, opts?: {
+        waitSeconds?: number;
+        signal?: AbortSignal;
+    }): Promise<WebhookListenSession>;
+    /** Stop listening (`DELETE /subscriptions/:id/listen/:sessionId`). */
+    stopWebhookListen?(subscriptionId: string, sessionId: string): Promise<void>;
+    /**
+     * Retry a failed trigger registration. POSTs
+     * `/subscriptions/:id/retry-registration`; resolves the updated Subscription.
+     * Absent => the trigger node offers no Retry.
+     */
+    retrySubscriptionRegistration?(subscriptionId: string): Promise<SubscriptionSummary>;
     /**
      * Create a Subscription binding an app trigger to a workflow — the one
      * explicit user action both the Triggers-tab app section (T-0) and the
@@ -480,10 +586,16 @@ export declare function useW6WApi(): W6WApi;
  * throwing — for optional enhancements (e.g. the `model-route` picker).
  */
 export declare function useOptionalW6WApi(): W6WApi | undefined;
-/** Scopes test-invokes under it to `project`; the editor wraps its body with this. */
-export declare function WorkflowProjectProvider({ project, children, }: {
+/**
+ * Scopes test-invokes under it to `project`, and names `workflowId` on them; the editor wraps
+ * its body with this.
+ */
+export declare function WorkflowProjectProvider({ project, workflowId, children, }: {
     project?: string;
+    workflowId?: string;
     children: ReactNode;
 }): import("react").JSX.Element;
 /** The selected workflow project id in scope, or `undefined` outside the editor. */
 export declare function useWorkflowProject(): string | undefined;
+/** The edited workflow's id in scope, or `undefined` outside the editor. */
+export declare function useWorkflowId(): string | undefined;

package/dist/resolve-params.d.ts

@@ -18,6 +18,16 @@ export type ResolvedSegment = {
 } | {
     status: "unresolved";
     ref: string;
+}
+/**
+ * A `nodes.<id>.meta.config.<key>` (alias `nodes.<id>.config.<key>`) ref this client cannot
+ * know — a key no node configures here, or one the host fills only at run time — or a
+ * `nodes.<id>.meta.<key>` its static meta lacks (a `version` the canvas does not know). Neutral, not a failure: the engine
+ * resolves it on the run.
+ */
+ | {
+    status: "at-run";
+    ref: string;
 } | {
     status: "not-evaluated";
     ref?: string;
@@ -29,11 +39,19 @@ export type ResolvedSegment = {
  * The scope a param's `var` refs resolve against. Built by {@link buildResolveScope}
  * from the SAME two things `StepEditModal` already computes: `testStartState`
  * (for `steps.*`/`trigger.*` — the object literally sent as the test's `state`)
- * and `sampleValues` (for `vars.*`/`documents.*`).
+ * and `sampleValues` (for `var.*`/`documents.*`/`const.*`).
+ *
+ * The fields mirror the engine's `RunScope` (`vars`, `constants`); the roots a ref
+ * names are what the engine's data root exposes — `var.*` (with `vars.*` as its
+ * permanent alias) and `const.*`. {@link resolveRef} maps one onto the other.
  */
 export interface ResolveScope {
     vars: Record<string, unknown>;
+    /** The SAME object as {@link vars}: `state`, `var` and `vars` are one tree (optional: hand-built scopes omit it). */
+    state?: Record<string, unknown>;
     documents: Record<string, unknown>;
+    /** Account constants, read as `const.<name>`. */
+    constants?: Record<string, unknown>;
     steps: Record<string, {
         output?: unknown;
         meta?: StepMeta;
@@ -46,6 +64,14 @@ export interface ResolveScope {
     trigger: {
         event?: unknown;
     };
+    /**
+     * The For each iteration scope (`foreach.item` / `foreach.index`), present only when
+     * `sampleValues` carries a `foreach.*` key. Mirrors the engine's inner scope.
+     */
+    foreach?: {
+        item?: unknown;
+        index?: number;
+    };
     /**
      * The original flat `sampleValues` map, keyed by full ref string — checked
      * BEFORE the nested walk in {@link resolveRef}. `documentSampleValues`
@@ -59,8 +85,8 @@ export interface ResolveScope {
      * never reach either shape. An exact flat-key hit here resolves any ref
      * `sampleValues` names directly, regardless of how many segments it has;
      * the nested walk stays the fallback for a ref whose own reconstructed
-     * value happens to be an object (`vars.address` = `{ city: "X" }`, walking
-     * into it for `vars.address.city`), which is a value shape `sampleValues`
+     * value happens to be an object (`var.address` = `{ city: "X" }`, walking
+     * into it for `var.address.city`), which is a value shape `sampleValues`
      * never produces a matching flat key for in the first place.
      *
      * Optional: a `ResolveScope` built by hand (as most tests in
@@ -69,6 +95,16 @@ export interface ResolveScope {
      * `buildResolveScope` populates it.
      */
     flat?: Record<string, unknown>;
+    /**
+     * Each node's static configuration ({@link ExpressionOptions.nodeConfig}), laid over `nodes`
+     * at `meta.config` and the `config` alias exactly as the engine's `withConfig` does.
+     */
+    config?: Record<string, Record<string, unknown>>;
+    /**
+     * Each node's static metadata ({@link ExpressionOptions.nodeMeta}), laid under the state's own
+     * `meta` (which wins key by key) exactly as the engine's `withConfig` does.
+     */
+    meta?: Record<string, Record<string, unknown>>;
 }
 /**
  * Build a {@link ResolveScope} from the two sources scope fidelity requires
@@ -77,15 +113,13 @@ export interface ResolveScope {
  *  - `steps`/`trigger` come from `testStartState` — the exact object the test
  *    invoke sends as `state`, so a `steps.<id>.output.<field>` ref resolves to
  *    what the test will ACTUALLY see, not a design-time sample.
- *  - `vars`/`documents` come from `sampleValues` (`useExpressionOptions()`), a
- *    FLAT map keyed by full ref (`"vars.from_email"`, `"documents.<key>"`).
- *    Reconstructed into a nested object here (strip the root prefix, one hop)
- *    so {@link walkPath} can dot-walk into a var/document whose OWN value is an
- *    object — `sampleValues["vars.address"]` holding `{ city: "X" }` still
- *    resolves `vars.address.city` correctly, because the walk continues INTO
- *    the reconstructed value rather than doing a second flat-key lookup.
+ *  - `vars`/`documents`/`constants` come from `sampleValues` (`useExpressionOptions()`), a
+ *    FLAT map keyed by full ref (`"var.from_email"`, `"documents.<key>"`, `"const.<name>"`).
+ *    State paths are reconstructed into one nested tree; whole-object samples
+ *    take precedence over their indexed descendants. The original flat map
+ *    remains available for exact field lookups, including parsed document fields.
  */
-export declare function buildResolveScope(sampleValues: Record<string, unknown> | undefined, testStartState: StepStartState | undefined): ResolveScope;
+export declare function buildResolveScope(sampleValues: Record<string, unknown> | undefined, testStartState: StepStartState | undefined, config?: Record<string, Record<string, unknown>>, meta?: Record<string, Record<string, unknown>>): ResolveScope;
 /** A hand-authored whole-value path marker: `{ "$": "<path>" }`, exactly one key. */
 export declare function isDollarPath(v: unknown): v is {
     $: unknown;

package/dist/run-visuals.d.ts

@@ -1,21 +1,4 @@
-/**
- * Pure derivation of a live run's canvas visuals (T1.1.1) — step node styling
- * and main-graph edge taken/skipped/untouched state. Plain functions of (run
- * state, step/edge identity) → visual state, with **no React import**, so
- * `node --test` exercises them directly (A7) the same way `flow-connect.ts`'s
- * connection rules do.
- *
- * `RunStatus`/`StepStatus`/`RunState`/`StepExecution` below are thin LOCAL
- * copies of the shapes `@w6w/workflow-types` declares
- * (`packages/w6w-workflow/packages/types/mod.ts`) — the same house idiom
- * `components/HealthStatusPill.tsx`'s `HealthPillState` uses, and the same
- * design note `flow-types.ts`'s own header already states for
- * `FlowWorkflow`/`FlowStep`: `packages/ui/package.json` has no dependency on
- * `@w6w/workflow-types` and must not gain one, so this module stays a
- * pure-presentation leaf with no transport/spec coupling. A caller who
- * already has the real `RunState`/`StepExecution` is structurally compatible
- * for free.
- */
+import { CanvasLane } from './flow-types.ts';
 /** Mirrors `RunStatus` in `@w6w/workflow-types`. */
 export type RunStatus = "queued" | "running" | "succeeded" | "failed" | "canceled";
 /** Mirrors `StepStatus` in `@w6w/workflow-types`. */
@@ -23,6 +6,15 @@ export type StepStatus = "pending" | "running" | "succeeded" | "failed" | "skipp
 /** The slice of `StepExecution` this module reads. */
 export interface StepExecution {
     status: StepStatus;
+    /** Why a `skipped` step did not run; `"not_on_path"` = never part of this run (no paint). */
+    skipReason?: string;
+    output?: unknown;
+    /** For each only (I3): per-iteration body-step records, keyed by body-step id. */
+    iterations?: ReadonlyArray<{
+        nodes?: Record<string, {
+            status: StepStatus;
+        }>;
+    }>;
 }
 /** The slice of `RunState` this module reads — steps keyed by step id, same
  *  as the engine's own `RunState.steps`. */
@@ -46,9 +38,10 @@ export type StepVisualState = "no-run" | StepStatus;
  * The rendered state for step `stepId` under `runState` — the StepStatus
  * half of A3's RunStatus × StepStatus mapping. Pure function of the run's own
  * step records; no additional data needed (`GET /runs/:id` already returns
- * everything this reads).
+ * everything this reads). A step whose record says `skipReason: "not_on_path"` (or whose
+ * enclosing loop's does) was never part of the run: `"no-run"`, the unpainted look.
  */
-export declare function stepVisualState(runState: RunState | undefined, stepId: string): StepVisualState;
+export declare function stepVisualState(runState: RunState | undefined, stepId: string, loops?: readonly string[]): StepVisualState;
 /** One node's non-persisted, run-aware look. Colour is never the only signal
  *  (the house rule `HealthStatusPill`'s own doc comment states) — every
  *  non-default state also differs from the default (`"no-run"`) in
@@ -90,4 +83,4 @@ export type EdgeRunState = "taken" | "skipped";
  *   - `from` is **running**, or has no record at all (not yet reached): the
  *     edge's fate isn't decided yet ⇒ `undefined`.
  */
-export declare function edgeRunState(runState: RunState | undefined, from: string, when: "success" | "error" | undefined): EdgeRunState | undefined;
+export declare function edgeRunState(runState: RunState | undefined, from: string, when: CanvasLane | undefined, route?: string, to?: string): EdgeRunState | undefined;

package/dist/script-bindings.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `{{ }}` inside a Run script's CODE. The host never templates `@w6w/script`'s `code` (the
+ * engine's `LITERAL_PARAMS`, node-types RFC amendment 2026-10-30): a marker typed into the code
+ * reaches the sandbox as literal text — `'{{ nodes.a.output.total }}'` is that exact string at
+ * run time, never the value. JavaScript/TypeScript insert `$.get(root, ...keys)` reads;
+ * Python inserts `ctx.get(root, *keys)` reads. Existing globals remain supported.
+ *
+ * {@link findCodeBindings} finds the markers that would run (strings and code, not comments),
+ * {@link codeReadFor} spells one reference as that code read, and
+ * {@link convertCodeBindingsToReads} rewrites every convertible marker in a script — what the
+ * step editor does when a script opens, behind a visible note with Undo.
+ */
+export type ScriptLanguage = "javascript" | "typescript" | "python";
+/** Where a marker sits: plain code, or inside a string literal of the given quote. */
+type Context = {
+    kind: "code";
+} | {
+    kind: "string";
+    quote: string;
+    start: number;
+    end: number;
+};
+export interface CodeBinding {
+    /** Offset of the `{{` in the code. */
+    start: number;
+    /** Offset just past the `}}`. */
+    end: number;
+    /** The marker's inner text, trimmed — what Input binds (`{{ <ref> }}`). */
+    ref: string;
+    context: Context;
+}
+/**
+ * Every `{{ … }}` in `code` that is not inside a comment, with the string literal (if any)
+ * around it. A small scanner, not a parser: it tracks `'…'`, `"…"` (and, in JavaScript,
+ * `` `…` ``; in Python, triple quotes) and the language's comments, which is what deciding
+ * "would this marker run" needs.
+ */
+export declare function findCodeBindings(code: string, language?: ScriptLanguage): CodeBinding[];
+/**
+ * Turn a reference into `$.get(root, ...keys)` (JavaScript/TypeScript) or
+ * `ctx.get(root, *keys)` (Python). Unsupported roots (secrets, documents, Function inputs)
+ * and non-path expressions return null. State always means the state tree without run aliases.
+ */
+export declare function codeReadFor(ref: string, language?: ScriptLanguage): string | null;
+export interface ConvertResult {
+    code: string;
+    /** Markers rewritten to code reads. */
+    converted: number;
+    /** Markers left as they were: not a readable reference, or inside a string they can't leave. */
+    left: number;
+}
+/**
+ * Rewrite each running `{{ ref }}` in `code` to the code read {@link codeReadFor} gives:
+ *  - a marker that IS a whole string literal (`'{{ ref }}'`) becomes the read, keeping the
+ *    value's type;
+ *  - a bare marker in code becomes the read;
+ *  - inside a JavaScript template literal it becomes `${read}`;
+ *  - inside a longer `'…'`/`"…"` string it is spliced in by concatenation (`str(read)` in Python);
+ *  - anything else (a Python triple-quoted or prefixed string, a reference with no code read) is
+ *    left as it was and counted in `left`.
+ */
+export declare function convertCodeBindingsToReads(code: string, language?: ScriptLanguage): ConvertResult;
+export {};

package/dist/script-completion-service.d.ts

@@ -0,0 +1,9 @@
+export interface ScriptSuggestion {
+    label: string;
+    type: string;
+}
+/** Virtual files only: no evaluation of user code, filesystem, or network access. */
+export declare function createScriptCompletionService(libraries: Record<string, string>): {
+    complete(code: string, position: number): ScriptSuggestion[];
+    dispose: () => void;
+};

package/dist/script-completion.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/script-completions.d.ts

@@ -0,0 +1,2 @@
+/** Per-editor lazy worker; compiling suggestions never blocks typing or runs the script. */
+export declare function scriptCompletions(): import('@codemirror/state').Extension[];

package/dist/state-shape.d.ts

@@ -0,0 +1,38 @@
+import { Edge } from '@xyflow/react';
+import { ExpressionStateField } from './components/ExpressionOptions.tsx';
+import { FlowWorkflow } from './flow-types.ts';
+import { StepNode } from './flow-utils.ts';
+import { StepShapeContext } from './step-preview-state.ts';
+/** The merged state at one anchor node. */
+export interface StateShape {
+    /** Every field path of the merged tree (depth/count capped like a step's output fields). */
+    fields: ExpressionStateField[];
+    /**
+     * Preview values keyed by the ref the picker inserts (`state.<path>`), from REAL values only
+     * (test outputs, the app's `sample`, starting data, variable defaults) — never a skeleton.
+     */
+    sampleValues: Record<string, unknown>;
+}
+export interface StateShapeInput {
+    /** The node whose incoming state this is (`null` → empty shape). */
+    anchorId: string | null | undefined;
+    nodes: StepNode[];
+    edges: Edge[];
+    initialState?: FlowWorkflow["initialState"];
+    variables?: FlowWorkflow["variables"];
+    /** The same shape context the picker's "Previous steps" projection reads. */
+    shapes?: StepShapeContext;
+    /** Each node's REAL output (fresh test, else persisted), for preview values. */
+    previewOutputs?: Record<string, unknown>;
+}
+/**
+ * The engine's run order over `nodes`/`edges`: Kahn's, the ready queue seeded in declared node
+ * order, successors released in declared edge order. Nodes a cycle leaves out follow in declared
+ * order (the engine refuses such a plan; the editor still has to show something).
+ */
+export declare function stateWriteOrder(nodes: StepNode[], edges: Edge[]): string[];
+/**
+ * The merged state shape a node reads — see the file header. Empty (no fields) when nothing on
+ * any path into `anchorId` writes state and there is no starting data or variable.
+ */
+export declare function computeStateShape(input: StateShapeInput): StateShape;