@w6w/ui 0.0.0-stage → 0.1.0

package/dist/output-shape.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ *
+ * 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
+ * also exactly how the engine resolves a ref — JSONLogic `var` splits on `.`
+ * (`core/packages/expr/src/jsonlogic.ts` `getVar`) — so `steps.<id>.output.<path>`
+ * reaches the nested value. A segment that can't survive that split is dropped
+ * by the picker (`isRefSafePath`).
+ *
+ * Pure and JSX-free so `node --test` exercises it directly.
+ */
+/** One pickable output field of a step. `key` is a dot path; `label` is display-only. */
+export interface OutputFieldRef {
+    key: string;
+    label?: string;
+    /** `true` — `key` is a dot path whose segments are checked one by one. */
+    path: true;
+}
+/** Where a step's offered fields came from. */
+export type OutputShapeSource = "declared" | "sample" | "test";
+/**
+ * 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;
+/**
+ * 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
+ * objects up to {@link MAX_DEPTH}. Arrays and scalars are leaves. `undefined`
+ * when the value isn't a plain object with at least one key.
+ */
+export declare function inferOutputFields(value: unknown): OutputFieldRef[] | undefined;
+/** The value at a dot path inside `value`, or `undefined` when any segment is missing. */
+export declare function valueAtPath(value: unknown, path: string): unknown;
+/** The subset of an action definition this module reads. */
+export interface ActionShapeDef {
+    output?: unknown;
+    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.
+ */
+export declare function resolveOutputShape(action: ActionShapeDef | undefined, testOutput: unknown): {
+    fields: OutputFieldRef[];
+    from: OutputShapeSource;
+} | undefined;

package/dist/provider.d.ts

@@ -0,0 +1,420 @@
+import { ReactNode } from 'react';
+import { ActionDef, ApiCallRecord, AppSummary, AuthDef, ConnectionSummary, FunctionDetail, FunctionSummary, SavedTest, SubscriptionSummary, ThemeMode, TriggerSummary, 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
+ * `saved_test_runs`; this is the history row shown in the test screens.
+ * `summary` is null when the run recorded no summary; `occurredAt` is ISO.
+ */
+export interface TestRunSummary {
+    id: string;
+    actionKey: string;
+    ok: boolean;
+    summary: string | null;
+    occurredAt: string;
+}
+/**
+ * Which app, version, action and connection a step ran with. A local structural
+ * copy of the engine's `StepMeta` (`@w6w/workflow-types`); the server sanitizes it.
+ */
+export interface StepMeta {
+    app: string;
+    version: string;
+    action: string;
+    connectionId: string | null;
+}
+/**
+ * A saved per-step test fixture — a reusable, project-owned named capture of a
+ * workflow step's resolved incoming state (`input`) and its params (`with`),
+ * keyed by `(workflowId, stepId)`. Mirrors the connection-scoped `SavedTest`,
+ * re-keyed to a workflow step. `lastRun*` denormalizes the most recent run.
+ */
+export interface StepTest {
+    id: string;
+    workflowId: string;
+    stepId: string;
+    name: string | null;
+    input: Record<string, unknown>;
+    with: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    /** When this fixture was last run (ISO), or null/undefined if never run. */
+    lastRunAt?: string | null;
+    /** The most recent run's status (e.g. `succeeded`/`failed`), or null. */
+    lastRunStatus?: string | null;
+    /** The most recent run's error payload, or null when it succeeded/never ran. */
+    lastRunError?: unknown;
+    /** The most recent run's captured output, or null. */
+    lastRunOutput?: unknown;
+    /** The most recent run's step metadata; omitted when the server has none. */
+    lastRunMeta?: StepMeta | null;
+}
+/**
+ * The **start state** a single-step invoke may carry — the RFC's third
+ * `executeNode(workflow, nodeId, startState)` argument
+ * (`core/rfcs/node-types.md`), sent as the invoke body's `state` field.
+ *
+ * Structurally the server's `StartStateInput`
+ * (`server/packages/api/ambient-scope.ts`): `steps` seeds `steps.<id>.output`
+ * and `trigger.event` seeds `trigger.event`, so a `with` block written as
+ * `{{ steps.<id>.output.<field> }}` resolves instead of concatenating as `""`.
+ * Anything else in it is ignored server-side — `vars`, `documents` and
+ * `secrets` are host-owned and loaded from the caller's authenticated scope, so
+ * a start state can only echo back data the caller already had.
+ *
+ * ⚠️ It is honoured by the **single-step** invoke route only. A full run
+ * (`POST /workflows/:id/run`) builds its own scope and takes nothing from here.
+ */
+export interface StepStartState {
+    /** Outputs of steps that already ran, keyed by step id → `steps.<id>.output`. */
+    steps?: Record<string, {
+        output?: unknown;
+        meta?: StepMeta;
+    }>;
+    /** Trigger context; only `event` is honoured → `trigger.event`. */
+    trigger?: {
+        event?: unknown;
+    };
+}
+/**
+ * A caller-supplied override merged into an app action's outbound request at
+ * the wire — the escape hatch for a vendor field the Action's own `params`
+ * don't declare (`.claude/docs/overrides.md`). Rides on the invocation
+ * envelope beside `params`, never inside it; `resolveParams` never sees it.
+ * Mirrors the server's `RequestOverrides`
+ * (`core/packages/types/src/overrides.ts`) structurally.
+ */
+export interface RequestOverrides {
+    /** Merged over the request body — deep-merges objects, index-merges arrays. */
+    body?: Record<string, unknown>;
+    /** Merged into the URL's query string; `null` removes a key the action set. */
+    query?: Record<string, string | number | boolean | null>;
+    /** Added to the request headers; applied before the auth `sign` hook, so it can't hijack it. */
+    headers?: Record<string, string>;
+    /** Which outbound request receives the overrides. Defaults to `"first"`. */
+    target?: "first" | "first-write" | "all";
+    /** Restrict the merge to requests whose URL contains this substring. */
+    match?: string;
+}
+/**
+ * The surface every w6w-io component may call. Grows as we add components;
+ * new members are added at the end so consumer implementations only need to
+ * grow when they want to use the new component.
+ */
+/**
+ * Options for {@link W6WApi.listAppsPage} — one bounded, server-paged
+ * request. Every member is optional; an omitted member is a host-defined
+ * default (usually "no filter"/"first page"), never a client-side guess.
+ */
+export interface ListAppsPageOptions {
+    /** Full-text search term, forwarded to the server verbatim. */
+    q?: string;
+    /** Server-side category filter (e.g. `"ai"`). */
+    category?: string;
+    /** Opaque pagination cursor from a prior {@link AppsPageResult.nextCursor}. */
+    cursor?: string;
+    /** Page size; a host may clamp this to its own bounds. */
+    limit?: number;
+    /** Ask the host for a bounded picker-summary projection (heavy fields like inline icons may be trimmed). */
+    compact?: boolean;
+    /** Abort this request. Local request control only; never a wire field. */
+    signal?: AbortSignal;
+}
+/** One page of apps, as returned by {@link W6WApi.listAppsPage}. */
+export interface AppsPageResult {
+    apps: AppSummary[];
+    /** Present unless this is the last page. */
+    nextCursor?: string;
+}
+export interface W6WApi {
+    /**
+     * List registered apps to pick from in the connection modal.
+     *
+     * OPTIONAL: the legacy, full-catalog counterpart to {@link listAppsPage}
+     * and {@link listAppsByIds} — `createW6WApi.ts`'s own implementation still
+     * provides it, and every bounded seam above is preferred wherever a host
+     * implements it. Callers MUST guard on `typeof api.listApps === "function"`
+     * before invoking it: a host with neither this nor a bounded seam settles
+     * into that call site's own existing empty state instead of making a
+     * request, never a crash.
+     */
+    listApps?(): Promise<AppSummary[]>;
+    /**
+     * Fetch ONE bounded, server-paged slice of the app catalog — the seam every
+     * bounded picker UI (`AppPicker`'s paged mode, `StepBuilderModal`'s
+     * Apps/AI/Triggers tabs) prefers over {@link listApps} when a host
+     * implements it. OPTIONAL and ADDITIVE: an older/imported provider that
+     * only implements `listApps` still typechecks and simply keeps the
+     * eager-list behavior everywhere this member is absent — and a host with
+     * neither this nor `listApps` settles into each caller's own existing empty
+     * state instead of ever requesting a catalog.
+     */
+    listAppsPage?(options?: ListAppsPageOptions): Promise<AppsPageResult>;
+    /**
+     * Resolve a bounded, explicit set of app ids to their summaries — the seam
+     * behind the "Ready to use" tab's connected-app batching and
+     * `AddConnectionModal`'s `initialAppId` resolution: a caller that already
+     * knows exactly which ids it needs never has to fetch (or filter) the whole
+     * catalog to find them. OPTIONAL, like {@link listAppsPage}: absent, a
+     * caller falls back to its pre-existing `listApps`-based resolution; absent
+     * too, that caller settles into its own not-found/empty outcome instead of
+     * ever calling an undefined function.
+     * Missing/404 ids are simply omitted from the result, never an error for
+     * the whole batch.
+     */
+    listAppsByIds?(ids: readonly string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<AppSummary[]>;
+    /** 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>;
+    /**
+     * 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
+     * callback message (see `startOAuthPopup`).
+     */
+    startAppOAuthFlow(appId: string, authKey: string, body: {
+        displayName?: string;
+    }): Promise<{
+        authorizationUrl: string;
+    }>;
+    /** List the actions an app exposes, to pick from in the step builder. */
+    getAppActions(appId: string): Promise<ActionDef[]>;
+    /** List the connections that already exist for a given app. */
+    listConnectionsForApp(appId: string): Promise<ConnectionSummary[]>;
+    /** List every connection across apps — drives the "Connected apps" tab. */
+    listConnections(): Promise<ConnectionSummary[]>;
+    /**
+     * Invoke a single action — used to test-run one step from the visual editor.
+     * Pass `connectionId` to run with a stored connection's credential. Pass
+     * `project` to resolve document expressions against the workflow's selected
+     * project (omitted → the scope's default/starter project). Pass `state` — the
+     * {@link StepStartState} — so `{{ steps.<id>.output.<field> }}` in the params
+     * resolves against what those upstream steps last produced; omitted, every
+     * such reference resolves to the empty string.
+     *
+     * `apiCalls` carries the outbound HTTP calls the action made (redacted); a
+     * failed invoke rejects with an `ApiError` whose `body ?? raw` holds the same
+     * field (ui's own class carries it on `body`, `@w6w/sdk`'s on `raw`).
+     *
+     * Pass `overrides` — a {@link RequestOverrides} — to reach a vendor field the
+     * action's own params don't declare. It rides on the invocation envelope,
+     * never merged into `params`; an absent or empty envelope is a no-op.
+     */
+    invokeAction(appId: string, actionKey: string, params: Record<string, unknown>, opts?: {
+        connectionId?: string;
+        project?: string;
+        state?: StepStartState;
+        overrides?: RequestOverrides;
+    }): Promise<{
+        value: unknown;
+        logs?: string[];
+        apiCalls?: ApiCallRecord[];
+        meta?: StepMeta;
+    }>;
+    /** List the saved action-test inputs stored against a connection. */
+    listSavedTests(connectionId: string): Promise<SavedTest[]>;
+    /** Save a new set of action-test inputs against a connection. */
+    createSavedTest(connectionId: string, body: {
+        actionKey: string;
+        name: string;
+        values: Record<string, unknown>;
+    }): Promise<SavedTest>;
+    /** Rename a saved test or replace its stored input values. */
+    updateSavedTest(connectionId: string, id: string, patch: {
+        name?: string;
+        values?: Record<string, unknown>;
+    }): Promise<SavedTest>;
+    /** Delete a saved test by id. */
+    deleteSavedTest(connectionId: string, id: string): Promise<void>;
+    /**
+     * Record the outcome of an action-test run against a connection. Appends a
+     * run-log row server-side; when `savedTestId` is present the saved test's
+     * `lastRun*` fields are updated too. POSTs to `/connections/:connId/test-runs`.
+     */
+    recordTestRun(connId: string, body: {
+        savedTestId?: string | null;
+        actionKey: string;
+        ok: boolean;
+        summary?: string;
+        result?: unknown;
+    }): Promise<void>;
+    /**
+     * List a connection's recent tester-run history from the unified `run_log`
+     * ledger (`GET /connections/:connId/test-runs` → the `.runs` array). Powers
+     * the run-history list in the test screens, complementing the per-test
+     * `lastRun*` badge with the full ledger.
+     *
+     * OPTIONAL: consumers that don't render history (or haven't wired it up yet)
+     * may omit it, so a missing member never poisons their typecheck. Callers
+     * MUST guard on its presence before invoking.
+     */
+    listTestRuns?(connectionId: string): Promise<TestRunSummary[]>;
+    /**
+     * Save a reusable per-step test fixture against a workflow step. Captures the
+     * resolved incoming state (`input`) and the step's params (`with`); the server
+     * stores both verbatim, project-owned. Mirrors `createSavedTest`, re-keyed from
+     * a connection to a `(workflowId, stepId)`. POSTs to
+     * `/workflows/:workflowId/steps/:stepId/tests`.
+     */
+    saveStepTest(workflowId: string, stepId: string, body: {
+        name?: string;
+        input: Record<string, unknown>;
+        with: Record<string, unknown>;
+    }): Promise<StepTest>;
+    /**
+     * Record the outcome of a step-test run so every run (saved or ad-hoc) is
+     * logged authoritatively server-side. The run row mirrors `node_executions`
+     * (status/input/output/error). When `stepTestId` is present the fixture's
+     * `lastRun*` fields are updated too. Mirrors `recordTestRun`, re-keyed to a
+     * workflow step. POSTs to `/workflows/:workflowId/steps/:stepId/test-runs`.
+     */
+    recordStepTestRun(workflowId: string, stepId: string, body: {
+        stepTestId?: string | null;
+        status: string;
+        input?: unknown;
+        output?: unknown;
+        error?: unknown;
+        meta?: unknown;
+    }): Promise<void>;
+    /**
+     * List the saved test fixtures for a workflow step (project-owned, not
+     * subject-filtered). Added now so the ui-only incoming-state picker and
+     * test-gate tasks need no further studio change. Mirrors `listSavedTests`,
+     * re-keyed to a `(workflowId, stepId)`. GETs
+     * `/workflows/:workflowId/steps/:stepId/tests`.
+     */
+    listStepTests(workflowId: string, stepId: string): Promise<StepTest[]>;
+    /**
+     * List the caller's registered Functions (core rfcs/function.md) — drives
+     * the step builder's Functions tab (F-2.0). GETs `/functions`.
+     */
+    listFunctions(): Promise<FunctionSummary[]>;
+    /**
+     * Load one Function's canonical interface (`inputs`), so the Functions tab
+     * can render its Configure stage's `ParamsForm`. GETs `/functions/:id`.
+     */
+    getFunction(id: string): Promise<FunctionDetail>;
+    /**
+     * Invoke a Function directly — the Functions tab's Test stage
+     * (`CallableStepConfig`), NOT the `@w6w/call` node's own run-time path (that
+     * goes through `ctx.invokeCallable`, host-side). Returns the raw output —
+     * `unknown`, not an invocation envelope — matching the committed
+     * `studio/src/repos/functions.ts`. POSTs `/functions/:id/invoke`.
+     */
+    invokeFunction(id: string, inputs: Record<string, unknown>): Promise<unknown>;
+    /**
+     * List the caller's registered Workflows — drives the step builder's
+     * Workflows tab (F-2.0). GETs `/workflows`.
+     */
+    listWorkflows(): Promise<WorkflowSummary[]>;
+    /**
+     * Load one Workflow's full definition, so the Workflows tab can derive its
+     * entry/trigger step's declared `with.fields` for the Configure stage's
+     * `ParamsForm`. GETs `/workflows/:id`.
+     */
+    getWorkflow(id: string): Promise<WorkflowDetail>;
+    /**
+     * Run a Workflow synchronously — the Workflows tab's Test stage (D-11/
+     * D-15(c)): the SAME `?wait=true` path the saved `@w6w/call` step takes at
+     * run time, never a client-side enqueue-and-poll. `terminal` is derived from
+     * the response's HTTP status (`200` ⇒ `true`, the server's own `202`
+     * synchronous-wait timeout ⇒ `false` — a legitimate "still running" outcome,
+     * not an error). POSTs `/workflows/:id/run?wait=true`.
+     */
+    runWorkflow(id: string, opts?: {
+        variables?: Record<string, unknown>;
+        input?: Record<string, unknown>;
+    }): Promise<{
+        runId: string;
+        status: string;
+        output?: unknown;
+        error?: unknown;
+        terminal: boolean;
+    }>;
+    /**
+     * 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`).
+     *
+     * OPTIONAL, like `listTestRuns?` above: a host that hasn't wired this member
+     * still typechecks and simply doesn't render the App-triggers section.
+     */
+    listTriggerApps?(): Promise<AppSummary[]>;
+    /**
+     * List one app's declared triggers. GETs `/apps/:id/triggers`.
+     */
+    getAppTriggers?(appId: string): Promise<TriggerSummary[]>;
+    /**
+     * List the Subscriptions bound to one workflow (rfcs/trigger.md). Powers
+     * the webhook-URL panel's get-or-create check (I-2) — GETs
+     * `/workflows/:id/subscriptions`.
+     */
+    listSubscriptionsForWorkflow?(workflowId: 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
+     * webhook-URL panel (I-2) call, per DECISIONS.md HITL-1. POSTs
+     * `/apps/:id/triggers/:key/subscriptions`.
+     */
+    createSubscription?(appId: string, triggerKey: string, input: {
+        workflowId: string;
+        connectionId?: string | null;
+        params?: Record<string, unknown>;
+        /** Poll triggers only, in milliseconds. */
+        intervalMs?: number;
+    }): Promise<SubscriptionSummary>;
+}
+export interface W6WUIProviderProps {
+    api: W6WApi;
+    /**
+     * Force the theme every `@w6w/ui` component resolves to — both the CSS
+     * tokens (`styles.css`'s `:where([data-theme=...])` blocks) and the
+     * JS-side theme-aware components (`AppIcon`, `CodeEditor`, `JsonEditor`,
+     * `WorkflowFlowEditor`, via `useEffectiveTheme`) — instead of each one
+     * independently falling back to `data-theme` on `<html>` or the visitor's
+     * OS `prefers-color-scheme`.
+     *
+     * Omit to keep that pre-existing default — the right choice for `@w6w/ui`'s
+     * own app (studio), which already manages `data-theme` on `<html>` itself.
+     * But it's a silent trap for a HOST embedding these components inside its
+     * own page: without this prop, `@w6w/ui` resolves its theme from the
+     * visitor's OS setting, independently of whatever theme the host's own
+     * page is using — a visitor with a dark-mode OS preference gets `@w6w/ui`
+     * components rendered in ITS dark palette sitting inside an otherwise-light
+     * host page (or vice versa). Pass your host's own resolved theme here to
+     * make `@w6w/ui` follow it instead. See `docs/theming.md`.
+     */
+    theme?: ThemeMode;
+    children: ReactNode;
+}
+/**
+ * Provides the w6w API client to every component under it, and — when
+ * `theme` is given — forces `@w6w/ui`'s theme to match it (see
+ * `W6WUIProviderProps.theme` above). Setting `theme` wraps `children` in a
+ * `data-theme` DOM node: CSS custom properties cascade to every descendant
+ * regardless of specificity, so this alone is enough for every `@w6w/ui`
+ * stylesheet rule to resolve correctly — no need to also set the attribute
+ * on `<html>` yourself. `display: contents` keeps that wrapper invisible to
+ * layout (flex/grid gap, `:nth-child`, etc. all behave as if it weren't
+ * there).
+ */
+export declare function W6WUIProvider({ api, theme, children }: W6WUIProviderProps): import("react").JSX.Element;
+/**
+ * Access the w6w API client. Throws a helpful error if used outside a
+ * `<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, }: {
+    project?: 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;

package/dist/resolve-params.d.ts

@@ -0,0 +1,112 @@
+import { StepMeta, StepStartState } from './provider.tsx';
+/**
+ * Per-segment resolution outcome. Every value that can contain a `var`/`expr`
+ * part resolves to an ARRAY of these (one per part of a multipart `ExprValue`,
+ * or one for a single top-level marker/literal) — never a bare `string`, which
+ * is exactly the shape `renderResult` collapses to and loses the distinction.
+ *
+ * `value` on `"resolved"` is `unknown` and explicitly INCLUDES `null` / `""` /
+ * `false` / `0` — those are real, present values, not absence. `"unresolved"`
+ * carries no `value` at all (there is nothing to show) and always carries the
+ * `ref` that failed to resolve, so a caller can render "this ref, unresolved"
+ * without ever falling back to rendering the ref as if it WERE the value.
+ */
+export type ResolvedSegment = {
+    status: "resolved";
+    ref?: string;
+    value: unknown;
+} | {
+    status: "unresolved";
+    ref: string;
+} | {
+    status: "not-evaluated";
+    ref?: string;
+} | {
+    status: "masked";
+    ref?: string;
+};
+/**
+ * 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.*`).
+ */
+export interface ResolveScope {
+    vars: Record<string, unknown>;
+    documents: Record<string, unknown>;
+    steps: Record<string, {
+        output?: unknown;
+        meta?: StepMeta;
+    }>;
+    trigger: {
+        event?: unknown;
+    };
+    /**
+     * The original flat `sampleValues` map, keyed by full ref string — checked
+     * BEFORE the nested walk in {@link resolveRef}. `documentSampleValues`
+     * (`document-sources.ts`) emits a document field's sample as its OWN
+     * complete flat entry (`"documents.<key>.<field>"`), not as a nested value
+     * living under the shorter `"documents.<key>"` entry — so the one-hop strip
+     * below reconstructs `documents["<key>.<field>"]` (one key, a literal dot
+     * in it) instead of `documents["<key>"]["<field>"]`, and a real
+     * `"<key>"` entry (the whole document's raw content, a string) already
+     * occupies that slot besides. `walkPath`'s segment-by-segment walk can
+     * 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`
+     * never produces a matching flat key for in the first place.
+     *
+     * Optional: a `ResolveScope` built by hand (as most tests in
+     * `resolve-params.test.ts` do, to exercise the walk directly) has no flat
+     * map to check and falls straight through to `walkPath` — only
+     * `buildResolveScope` populates it.
+     */
+    flat?: Record<string, unknown>;
+}
+/**
+ * Build a {@link ResolveScope} from the two sources scope fidelity requires
+ * they come from separately:
+ *
+ *  - `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.
+ */
+export declare function buildResolveScope(sampleValues: Record<string, unknown> | undefined, testStartState: StepStartState | undefined): ResolveScope;
+/** A hand-authored whole-value path marker: `{ "$": "<path>" }`, exactly one key. */
+export declare function isDollarPath(v: unknown): v is {
+    $: unknown;
+};
+/** A hand-authored whole-value JSONLogic marker: `{ "$expr": <logic> }`, exactly one key. */
+export declare function isDollarExpr(v: unknown): v is {
+    $expr: unknown;
+};
+/**
+ * Resolve one configured param VALUE (or one `vars`-row's `value`, per A5 — the
+ * same function, called again per row) against `scope`. Returns one segment
+ * per part of a multipart `ExprValue`, or a single segment for anything else:
+ * a `SecretValue` at-rest envelope (`masked`), a hand-authored `{"$":…}` /
+ * `{"$expr":…}` marker (resolved as a ref lookup / not-evaluated — NOT as a
+ * literal object, per the acceptance pin), or a plain literal (`resolved`,
+ * `value` as-is, no `ref`).
+ */
+export declare function resolveParamValue(value: unknown, scope: ResolveScope): ResolvedSegment[];
+/**
+ * Structural deep-equality over JSON-shaped values (primitives, arrays, plain
+ * objects, recursively) — no new dependency. Used by the Test tab's "unchanged
+ * from default" filter (D-1/A1): equality, not presence, so a value the
+ * hand-editable JSON view baked in explicitly is still recognized as
+ * unchanged when it matches the declared default. `a === b` covers primitives
+ * (including `undefined === undefined`, so a param with neither a value nor a
+ * declared default is "equal" too) and short-circuits identical references
+ * before the recursive object/array walk.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/resolved-json.d.ts

@@ -0,0 +1,21 @@
+import { ResolveScope, ResolvedSegment } from './resolve-params.ts';
+/**
+ * Fold a param's full segment array (the shape {@link resolveParamValue}
+ * returns) into ONE JSON value, per A6's pinned table: a single segment folds
+ * to its own token/value; multiple segments (a multipart `ExprValue`)
+ * concatenate into one string, each `resolved` part contributing its text
+ * (strings as-is, non-strings `JSON.stringify`d) and every other part
+ * contributing its placeholder token.
+ */
+export declare function foldResolvedSegments(segments: ResolvedSegment[]): unknown;
+/** Resolve + fold one param VALUE against `scope` in a single call. */
+export declare function resolveParamJson(value: unknown, scope: ResolveScope): unknown;
+/**
+ * A `vars`-typed param's configured rows, folded into one object keyed by
+ * each row's own `key` (`"(no key)"` when blank — mirrors `ResolvedVarsRow`'s
+ * fallback), each row's `value` folded by the same rules as any other param.
+ */
+export declare function resolveVarsJson(rows: Array<{
+    key?: string;
+    value: unknown;
+}>, scope: ResolveScope): Record<string, unknown>;