@w6w/ui 0.2.0 → 0.2.54

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/note-markdown.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The note editor's Markdown round-trip. A note is edited in place as a `contentEditable` block
+ * (no textarea); these two functions convert between its stored Markdown and that editable DOM.
+ *
+ * The editable model is line-based and covers exactly what the note toolbar writes: a heading
+ * level per line (`#`…`######`) and `**bold**` runs. Everything else (links, lists, `code`, …) is
+ * kept as literal text while editing and rendered by `Markdown` when not, so a line the toolbar
+ * never touched round-trips byte-for-byte.
+ *
+ * The DOM is built with `createElement` + text nodes only — note content is imported,
+ * attacker-controllable text and must never reach `innerHTML`.
+ */
+/** Build the editable DOM for `content` into `root` (its children are replaced). */
+export declare function renderEditable(root: HTMLElement, content: string): void;
+/** Serialize the editable DOM under `root` back to Markdown. */
+export declare function editableToMarkdown(root: HTMLElement): string;
+/**
+ * The content handed to `Markdown` for display. A note is typed line by line, so a single
+ * newline must show as a line break — Markdown would fold it into a space. A soft break between
+ * two non-empty lines becomes a hard break (two trailing spaces); the stored content is untouched.
+ */
+export declare function noteDisplayMarkdown(content: string): string;

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, ConnectionSummary, FunctionDetail, FunctionSummary, 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,10 @@ 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}. */
     cursor?: string;
     /** Page size; a host may clamp this to its own bounds. */
@@ -135,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.
@@ -174,15 +202,59 @@ export interface W6WApi {
     listAppsByIds?(ids: readonly string[], options?: {
         signal?: AbortSignal;
     }): Promise<AppSummary[]>;
+    /**
+     * OPTIONAL: the tenant's model routes, for the `model-route` step-param
+     * picker (`@w6w/model` `complete`). Absent, the param renders as a plain text
+     * input and this is never called. A `broken` route is still selectable.
+     * `project` is the editor's own project (`WorkflowProjectProvider`) when it
+     * has one — a host should list THAT project's routes, not guess one from its
+     * URL; `undefined` leaves the choice to the host.
+     */
+    listModelRoutes?(project?: string): Promise<{
+        name: string;
+        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
+     * render as plain inputs and this is never called.
+     */
+    resolveActionFields?(appId: string, actionKey: string, body: ResolveFieldsBody, opts?: {
+        signal?: AbortSignal;
+    }): Promise<ResolveFieldsResult>;
     /** Load auth methods declared by an app's manifest, with availability flags. */
     getAppAuth(appId: string): Promise<AuthDef[]>;
     /** Create a non-OAuth connection with a user-supplied credential. */
-    createConnection(appId: string, body: {
-        authKey: string;
-        credential: Record<string, unknown>;
-        displayName?: string;
-        profile?: Record<string, unknown>;
-    }): Promise<ConnectionSummary>;
+    createConnection(appId: string, body: CreateConnectionBody): Promise<ConnectionSummary>;
     /**
      * Rename a connection and/or replace some of its credential fields (`PATCH /connections/:id`).
      * Send only the fields being changed: the server merges a partial `credential` over the stored
@@ -191,8 +263,34 @@ export interface W6WApi {
      */
     updateConnection?(id: string, body: {
         displayName?: string;
+        binding?: ConnectionBinding;
+        credentialId?: string;
         credential?: Record<string, unknown>;
     }): Promise<ConnectionSummary>;
+    /** List stored credentials, optionally narrowed (`GET /credentials`). */
+    listCredentials?(filter?: {
+        contract?: string;
+        appId?: string;
+        authKey?: string;
+    }): Promise<CredentialSummary[]>;
+    /** Store a new credential (`POST /credentials`). `source` is the auth's field-value record. */
+    createCredential?(body: {
+        name: string;
+        contract: string;
+        source: Record<string, unknown>;
+    }): Promise<CredentialSummary>;
+    getCredential?(id: string): Promise<CredentialSummary>;
+    /** Replace a credential's secret (`POST /credentials/:id/rotate`). */
+    rotateCredential?(id: string, body: {
+        source: Record<string, unknown>;
+    }): Promise<CredentialSummary>;
+    /** Disable (`/disable`) or re-enable (`/enable`) a credential. */
+    setCredentialStatus?(id: string, status: "active" | "disabled"): Promise<CredentialSummary>;
+    /** Mint-level health check; distinct from a connection's app-access test. */
+    testCredential?(id: string): Promise<CredentialTestResult>;
+    credentialDependents?(id: string): Promise<CredentialDependents>;
+    /** Rejects with `ApiError` code `credential_in_use` (body.error.dependents) when in use. */
+    deleteCredential?(id: string): Promise<void>;
     /**
      * Start an OAuth 2.0 flow. Server builds the provider's authorize URL and
      * returns it; the caller opens it in a popup and awaits the server's
@@ -231,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[];
@@ -310,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`.
@@ -359,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[]>;
     /**
@@ -376,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
@@ -431,10 +581,21 @@ export declare function W6WUIProvider({ api, theme, children }: W6WUIProviderPro
  * `<W6WUIProvider>` — the common mistake is forgetting to wrap the app root.
  */
 export declare function useW6WApi(): W6WApi;
-/** Scopes test-invokes under it to `project`; the editor wraps its body with this. */
-export declare function WorkflowProjectProvider({ project, children, }: {
+/**
+ * Like {@link useW6WApi} but returns `undefined` outside a provider instead of
+ * throwing — for optional enhancements (e.g. the `model-route` picker).
+ */
+export declare function useOptionalW6WApi(): W6WApi | undefined;
+/**
+ * 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,18 +39,39 @@ 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;
     }>;
+    /** `nodes.<id>…` root — the SAME object as `steps` (one state, two roots). */
+    nodes?: Record<string, {
+        output?: unknown;
+        meta?: StepMeta;
+    }>;
     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`
@@ -54,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
@@ -64,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
@@ -72,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,12 +6,24 @@ 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`. */
 export interface RunState {
     status: RunStatus;
-    steps: Record<string, StepExecution>;
+    /** Canonical per-node records (D2). */
+    nodes?: Record<string, StepExecution>;
+    /** Legacy alias of `nodes`; read as `nodes ?? steps` (un-upgraded server). */
+    steps?: Record<string, StepExecution>;
 }
 /**
  * A step node's rendered state — exactly the five {@link StepStatus} values
@@ -43,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
@@ -87,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;