@w6w/ui 0.2.0 → 0.2.54

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;

package/dist/step-preview-state.d.ts

@@ -1,8 +1,10 @@
 import { Edge } from '@xyflow/react';
-import { ExpressionStepSource } from './components/ExpressionOptions.tsx';
+import { ExpressionFieldSource, ExpressionLoopSource, ExpressionStepSource } from './components/ExpressionOptions.tsx';
 import { StepNode } from './flow-utils.ts';
-import { ActionShapeDef } from './output-shape.ts';
+import { ActionShapeDef, OutputShapeSource } from './output-shape.ts';
 import { StepMeta, StepStartState, StepTest } from './provider.tsx';
+import { SubscriptionSummary } from './types.ts';
+import { FlowConnections } from './workflow-connections.ts';
 /**
  * What the editor knows about upstream steps' output SHAPES beyond the static
  * `internalNodeDef(...).output` — both optional, so a caller without them gets
@@ -15,8 +17,20 @@ export interface StepShapeContext {
      * no "run a test" claim it might have to retract a moment later.
      */
     actionDef?: (app: string, action: string) => ActionShapeDef | undefined;
-    /** Each step's latest saved test-run output, by step id. */
+    /**
+     * An app TRIGGER's definition (its declared `output` / `sample`), same "undefined = not
+     * loaded, no claim" semantics as `actionDef`. Feeds `trigger.event.<key>`.
+     */
+    triggerDef?: (app: string, trigger: string) => ActionShapeDef | undefined;
+    /** Each step's FRESH test-run output (this session), by step id. */
     testOutputs?: Record<string, unknown>;
+    /**
+     * Each step's PERSISTED test output (server-side `node_samples`), by step id. A SEPARATE
+     * input from `testOutputs` so the tiers stay visible; fresh beats persisted.
+     */
+    persistedOutputs?: Record<string, unknown>;
+    /** Each For each's saved Test sample (`foreachTestSample`), by step id — the item-shape fallback. */
+    loopSamples?: Record<string, unknown[]>;
 }
 /** A graph ancestor carrying a saved step-test, offered as a one-click seed. */
 export interface SeedSource {
@@ -35,7 +49,41 @@ export interface SeedSource {
 interface PendingConnect {
     nodeId: string;
     handleType: "source" | "target";
+    /** The lane the drag came off (WFE's `pendingConnect` carries it). */
+    lane?: "success" | "error" | "each";
 }
+/**
+ * Every node id that is a graph ancestor of `rootId` — walks `edges` backward. Exported for
+ * `state-shape.ts` (which imports this module, never the reverse).
+ */
+export declare function ancestorIds(rootId: string, edges: Edge[]): Set<string>;
+/**
+ * The array a For each's `items` resolves to at design time, or `undefined`.
+ * A whole-value ref (`{{ nodes.x.output.tickets }}` / `{ "$": … }`) resolves through
+ * `resolve-params.ts` against the saved test outputs; a literal array is returned as-is;
+ * anything else (a non-array result, a multipart template, a missing ref) is `undefined`.
+ */
+export declare function resolveLoopItems(items: unknown, testOutputs: Record<string, unknown>): unknown[] | undefined;
+/**
+ * {@link resolveLoopItems} against a whole Test start state (`startStateFromSeeds`), so a
+ * For each's own Test resolves `items` exactly as the other steps' Test previews do — a
+ * `trigger.event` ref included.
+ */
+export declare function resolveLoopItemsInState(items: unknown, state: StepStartState | undefined): unknown[] | undefined;
+/** How many items a For each's saved Test keeps: enough for the shape, never the whole list. */
+export declare const FOREACH_TEST_SAMPLE_MAX = 10;
+/**
+ * The step-test fixture a For each's Test saves. Nothing runs, so no run is recorded and
+ * `lastRunOutput` stays empty — the For each's real output is its BODY's results, and an
+ * after-loop step must not preview (or be seeded with) the input list as that. The sample
+ * rides in the fixture's `with` instead: the resolved `items` (capped) and the full count.
+ */
+export declare function foreachTestFixture(items: unknown[], input: Record<string, unknown>): {
+    input: Record<string, unknown>;
+    with: Record<string, unknown>;
+};
+/** The sample a For each's saved Test carries (`foreachTestFixture`), or `undefined`. */
+export declare function foreachTestSample(test: StepTest | null | undefined): unknown[] | undefined;
 /**
  * The workflow state a given step can reference: the outputs of every step
  * that runs before it (its graph ancestors) plus whether a trigger precedes
@@ -77,9 +125,19 @@ interface PendingConnect {
  *
  * With no specific step (shouldn't happen for a field edit) every node is offered.
  */
-export declare function upstreamStateSources(editingId: string | null, nodes: StepNode[], edges: Edge[], shapes?: StepShapeContext): {
+export declare function upstreamStateSources(editingId: string | null, nodes: StepNode[], edges: Edge[], shapes?: StepShapeContext, draftId?: string | null): {
     steps: ExpressionStepSource[];
     hasTrigger: boolean;
+    /** Present iff the anchor step is a loop-body member. */
+    loop?: ExpressionLoopSource;
+    /**
+     * Saved tests the projection reads beyond `steps`: an after-loop For each's last body step,
+     * and the enclosing For each itself (its Test's item sample).
+     */
+    extraSampleIds?: string[];
+    /** An app trigger ancestor's declared `trigger.event.<key>` fields. */
+    eventOutputs?: ExpressionFieldSource[];
+    eventOutputsFrom?: OutputShapeSource;
 };
 /**
  * The new add-step wizard's graph ancestors, derived from `pendingConnect` —
@@ -98,6 +156,8 @@ export declare function upstreamStateSources(editingId: string | null, nodes: St
  * {@link upstreamStateSources} uses.
  */
 export declare function stepBuilderUpstreamSteps(pendingConnect: PendingConnect | null, nodes: StepNode[], edges: Edge[], shapes?: StepShapeContext): ExpressionStepSource[];
+/** The `loop` source for the add-step builder's new step — the same decision as its rail. */
+export declare function stepBuilderLoop(pendingConnect: PendingConnect | null, nodes: StepNode[], edges: Edge[], shapes?: StepShapeContext): ExpressionLoopSource | undefined;
 /**
  * Gather each graph ancestor's latest saved step-test so the incoming-state
  * control can offer it as a seed. **One implementation**, called by every
@@ -133,11 +193,100 @@ export declare function fetchSeedSources(listStepTests: (stepId: string) => Prom
  * ⚠️ Single-step scope only. A full run (`POST /workflows/:id/run`) builds its
  * own scope and is not affected by this.
  */
-export declare function startStateFromSeeds(seeds: SeedSource[]): StepStartState | undefined;
+export declare function startStateFromSeeds(seeds: SeedSource[], loop?: {
+    item?: unknown;
+    index?: number;
+}): StepStartState | undefined;
+/** The default `{ item, index }` a loop-body Test is seeded with: the sample item, index 0. */
+export declare function loopSeedFromSource(loop: ExpressionLoopSource | undefined): {
+    item?: unknown;
+    index?: number;
+} | undefined;
+/** The editable "Current item" text a loop's sample item starts as (`""` when there is none). */
+export declare function loopItemText(loop: ExpressionLoopSource | undefined): string;
+/**
+ * Parse the loop seed control's two fields. A blank item means "no item"; a blank index means 0.
+ * Invalid item JSON, or an index that is not a non-negative integer, is an ERROR — the caller
+ * refuses the run rather than falling back to the sample.
+ */
+export declare function parseLoopSeed(itemText: string, indexText: string): {
+    ok: true;
+    value: {
+        item?: unknown;
+        index: number;
+    };
+} | {
+    ok: false;
+    error: string;
+};
 /**
- * Sample values for a step's `steps.<id>.meta.*` refs, from a saved fixture's
+ * Sample values for a step's `nodes.<id>.meta.*` refs (and the `steps.` alias), from a saved fixture's
  * `lastRunMeta`. Reads the four named fields only; absent meta yields nothing
  * (a version or connection is never derived from anywhere else).
  */
 export declare function stepMetaSampleValues(stepId: string, meta: StepMeta | null | undefined): Record<string, unknown>;
+/**
+ * The flat `sampleValues` the expression editor's Result preview reads: each upstream step's
+ * last test output on the very refs the picker inserts (`nodes.<id>.output`, `.output.<key>`,
+ * each offered nested path), mirrored under `steps.` (the compat alias), plus metadata and,
+ * for a loop-body step, `foreach.item` / `foreach.item.<key>` / `foreach.index` (= 0, the
+ * sample element's position). Lives here (not in WFE) so a render test can drive it.
+ */
+export declare function upstreamSampleValues(steps: ExpressionStepSource[], testOutputs: Record<string, unknown>, testMetas: Record<string, StepMeta>, loop?: ExpressionLoopSource, tiers?: SampleTiers): Record<string, unknown>;
+/**
+ * The lower tiers of preview values, beside the fresh `testOutputs`: the PERSISTED test
+ * outputs and the app's declared `sample`s (by step id; `event` is an app trigger's sample,
+ * read as `trigger.event`). Precedence per ref: fresh > persisted > sample.
+ */
+export interface SampleTiers {
+    persisted?: Record<string, unknown>;
+    samples?: Record<string, unknown>;
+    event?: unknown;
+}
+/** Which tier each value in {@link upstreamSampleValues} came from, keyed by the same ref. */
+export declare function upstreamSampleValueSources(steps: ExpressionStepSource[], testOutputs: Record<string, unknown>, testMetas: Record<string, StepMeta>, loop?: ExpressionLoopSource, tiers?: SampleTiers): Record<string, "fresh" | "persisted" | "sample">;
+/**
+ * The declared `sample` of each app step (by id) and of an app trigger (as the event
+ * sample), read through `shapes.actionDef` / `triggerDef`. An `output`-only definition
+ * contributes nothing: no placeholders are fabricated.
+ */
+export declare function declaredSamples(nodes: StepNode[], shapes: StepShapeContext): {
+    samples: Record<string, unknown>;
+    event?: unknown;
+};
+/**
+ * Each node's configuration keys for the picker's "Node settings" group — what the engine lays
+ * at `nodes.<id>.config` (`nodeConfigOf`): the step's literal `with` keys (never a secret, never a
+ * binding), plus `url` for a webhook trigger node (the host adds it from the node's subscription).
+ * A node with none is left out.
+ */
+export declare function nodeConfigSources(nodes: StepNode[]): {
+    id: string;
+    keys: string[];
+}[];
+/**
+ * Each node's configuration VALUES — the client's `nodeConfigOf`: the step's static `with`
+ * (sealed secrets and bindings dropped, so nothing sealed ever reaches a preview) with a webhook
+ * trigger node's `url` laid over it from the workflow's subscriptions, picked as the server's
+ * `hostNodeConfig` picks it (the one bound to the node, else for a `@w6w/webhook` node the newest
+ * webhook subscription). A node with nothing to configure is absent.
+ */
+export declare function nodeConfigValues(nodes: StepNode[], subs: readonly SubscriptionSummary[]): Record<string, Record<string, unknown>>;
+/**
+ * Each node's static metadata VALUES — the client's `nodeMetaOf`: `app`, `action` and
+ * `connectionId` (the node's own connection, else `null`) from the definition, plus a webhook
+ * trigger node's `subscriptionId` and `url` from its subscription ({@link subscriptionFor}), and
+ * `version` from `apps` — the same summary the canvas labels the node with (`<id> - v<version>`),
+ * i.e. the version it will dispatch. Readable at `nodes.<id>.meta.<key>` whether or not the node
+ * ran; a run's reported meta overrides it. An app with no known version has no `version` (the
+ * previews then say "resolved at run"). A node with no app is absent.
+ */
+export declare function nodeMetaValues(nodes: StepNode[], subs: readonly SubscriptionSummary[], apps?: ReadonlyMap<string, {
+    version?: string;
+}>, connections?: FlowConnections): Record<string, Record<string, unknown>>;
+/**
+ * {@link nodeMetaValues} as the flat `sampleValues` the Result preview reads, on the refs the
+ * picker inserts (`nodes.<id>.meta.<key>`, mirrored under `steps.`).
+ */
+export declare function nodeMetaSampleValues(meta: Record<string, Record<string, unknown>>): Record<string, unknown>;
 export {};

package/dist/step-problems.d.ts

@@ -0,0 +1,64 @@
+import { LoopInvalid } from './flow-loop.ts';
+/** A one-click fix: pure data, applied by `applyStepProblemFix` on the author's click. */
+export type StepProblemFix = {
+    kind: "unwrap_items";
+    label: "Unwrap Items";
+} | {
+    kind: "use_current_item";
+    foreachId: string;
+    label: "Use Current item";
+};
+export type StepProblem = {
+    code: "unknown_connection";
+    connection: string;
+} | {
+    code: "foreach_wrapped_items";
+    fix: StepProblemFix;
+} | {
+    code: "foreach_body_refs_output";
+    foreachId: string;
+    refs: string[];
+    fix: StepProblemFix;
+} | {
+    code: "loop_body_invalid";
+    reason: LoopInvalid;
+}
+/** Writes a state path that a step running at the same time (`with`) also writes (`findStateWriteProblems`). */
+ | {
+    code: "state_parallel_write";
+    path: string[];
+    with: string[];
+}
+/** The saved workflow still lacks setup (unbound alias, empty store, missing var/secret/constant); `items` name what. */
+ | {
+    code: "setup_incomplete";
+    items: string[];
+};
+/** Keyed by step id; a step carries every problem it has (D-B1). */
+export type StepProblems = Record<string, StepProblem[]>;
+interface ProblemNode {
+    id: string;
+    data: {
+        stepProblems?: StepProblem[];
+    };
+}
+/**
+ * Stamp `data.stepProblems` from `problems`, clearing it for steps no longer in
+ * the map (or mapped to `[]`). Returns the SAME node object when the incoming
+ * list deep-equals the stamped one.
+ */
+export declare function applyStepProblems<N extends ProblemNode>(nodes: N[], problems: StepProblems | undefined): N[];
+export declare function stepProblemTooltip(p: StepProblem): string;
+/** True while the step still points at a connection the host reports missing (any entry). */
+export declare function isConnectionBlocked(step: {
+    uses: {
+        connection?: string | null;
+    };
+}, problems: StepProblem[] | undefined): boolean;
+/** The Setup tab's Connection button label — exactly five outcomes. */
+export declare function connectionButtonLabel(connection: string | undefined | null, conns: {
+    id: string;
+    displayName?: string;
+    builtIn?: boolean;
+}[] | null, failed: boolean): string;
+export {};

package/dist/test-inputs.d.ts

@@ -0,0 +1,25 @@
+import { ActionParam } from './types.ts';
+/** One remembered input (`GET /workflows/:id/test-inputs` → `testInputs[]`). */
+export interface NodeTestInput {
+    nodeId: string;
+    input: Record<string, unknown>;
+    /** ISO timestamp of the write. */
+    updatedAt: string;
+}
+/**
+ * The remembered input of `nodeId`: `undefined` when the node has no row (the
+ * caller may fall back to an older source, e.g. the latest step-test fixture),
+ * `{}` when it was CLEARED (stay on the declared defaults), else the values.
+ */
+export declare function findTestInput(rows: readonly NodeTestInput[] | undefined, nodeId: string): Record<string, unknown> | undefined;
+/**
+ * What may be remembered of `values`: a literal typed into a `secret` param is
+ * DROPPED (it must never be persisted in plain text — the operator re-enters
+ * it), a binding to a secret is kept as the expression, and a sealed envelope
+ * is dropped anywhere at the top level (the server strips nested ones too).
+ */
+export declare function rememberableInput(values: Record<string, unknown>, params?: readonly ActionParam[]): Record<string, unknown>;
+/** Track `save` until it settles (it never rejects into the tracker). Returns `save`. */
+export declare function trackTestInputSave<T>(save: Promise<T>): Promise<T>;
+/** Resolves once every remembered-input save issued so far has settled (never rejects). */
+export declare function testInputSavesSettled(): Promise<void>;

package/dist/trigger-registration.d.ts

@@ -0,0 +1,28 @@
+import { SubscriptionSummary } from './types.ts';
+export type RegistrationTone = "ok" | "pending" | "danger" | "muted";
+export interface RegistrationDisplay {
+    label: string;
+    tone: RegistrationTone;
+    /** `lastError.message`, only for a failed subscription that carries one. */
+    error: string | null;
+    /** Always set: a distinct "never fired" text when `lastFireAt` is null/absent/unparseable. */
+    lastFire: string;
+    /** True iff the subscription is `failed` AND the host can retry. */
+    retryVisible: boolean;
+}
+export declare const NEVER_FIRED = "Never fired";
+/** UTC, minute precision, so the text is stable across locales and test hosts. */
+export declare function formatLastFire(iso: string | null | undefined): string;
+/** Null when the summary has no known status (older server): the node shows no badge. */
+export declare function registrationDisplay(sub: SubscriptionSummary | undefined, canRetry: boolean): RegistrationDisplay | null;
+/** nodeId -> subscription for the node-bound ones (a null `nodeId` is workflow-level). */
+export declare function subscriptionsByNode(subs: readonly SubscriptionSummary[]): Map<string, SubscriptionSummary>;
+/**
+ * The app trigger nodes of a workflow value. Total over a value that has no `nodes` yet
+ * (embed mounts pass a partial value): an absent list is no trigger nodes.
+ */
+export declare function appTriggerNodesOf<N extends {
+    uses?: {
+        trigger?: boolean;
+    };
+}>(nodes: readonly N[] | null | undefined): N[];