@w6w/ui 0.0.0-stage → 0.1.0

package/dist/RetryPolicyFields.d.ts

@@ -0,0 +1,18 @@
+import { FlowStep } from './flow-types.ts';
+/** Who this retry policy applies to — picks the helper line's wording. */
+export type RetryTarget = "step" | "function" | "endpoint" | "workflow";
+/** The persisted retry shape (core `rfcs/node-types.md`), minus the `undefined` case. */
+export type RetryPolicyValue = NonNullable<FlowStep["retry"]>;
+/**
+ * The "Retry on failure" checkbox + helper line + Attempts/Delay (ms)/Backoff
+ * row — the one retry shape shared by every host that can offer a retry
+ * policy (core rfcs/R-2 "one retry shape everywhere"). `value` is the
+ * persisted policy or `undefined` for "no retry"; `target` only changes the
+ * helper line's wording, never the behavior.
+ */
+export declare function RetryPolicyFields({ value, onChange, readOnly, target, }: {
+    value: RetryPolicyValue | undefined;
+    onChange: (next: RetryPolicyValue | undefined) => void;
+    readOnly?: boolean;
+    target?: RetryTarget;
+}): import("react").JSX.Element;

package/dist/StepBuilderModal.d.ts

@@ -0,0 +1,375 @@
+import { NodeConfig } from './NodeConfigForm.tsx';
+import { ExpressionStepSource } from './components/ExpressionOptions.tsx';
+import { InternalNodeDef } from './flow-types.ts';
+import { StepStartState } from './provider.tsx';
+import { ActionParam, AppSummary, FunctionSummary, ThemeMode, WorkflowSummary } from './types.ts';
+/** The step the builder emits — the editor assigns the final `id`. `NodeConfig`
+ * carries the base settings (retry / onError / notes) set on the Config view. */
+export interface BuiltStep extends NodeConfig {
+    uses: {
+        app: string;
+        action: string;
+        connection?: string | null;
+    };
+    with?: Record<string, unknown>;
+}
+export interface StepBuilderModalProps {
+    onClose: () => void;
+    /**
+     * Fired once per session, the moment the step first has identity — for an
+     * app step, when Setup completes (action + connection, if needed); for a
+     * control node, on mount. Returns the minted step id so subsequent edits can
+     * target it via {@link StepBuilderModalProps.onDraftChange}.
+     */
+    onAdd: (step: BuiltStep) => string | undefined | void;
+    /**
+     * Fired for every field change **after** the step has been committed via
+     * `onAdd` — keeps the already-added node current without minting a second
+     * one. `id` is the id `onAdd` returned. Progressive commit (mint-then-update)
+     * only engages when this is supplied; omitted callers (the Functions/
+     * Endpoints pickers) keep the original one-shot "Add step" behavior.
+     */
+    onDraftChange?: (id: string, step: BuiltStep) => void;
+    theme?: ThemeMode;
+    /**
+     * Hide the GRAPH-ONLY tabs — Triggers / Controls / Utilities / Data, the
+     * flow-control and internal `@w6w/*` node kinds that only mean something
+     * inside a workflow canvas. Used by every picker that binds a *target*
+     * rather than adding a node to a graph.
+     *
+     * ⚠️ It does NOT hide Functions and Workflows, and did not always behave
+     * that way: it used to, which is why the Implementation card's picker
+     * showed only `Connected apps / Apps / AI` and F-2.0's tabs were
+     * unreachable outside the canvas. A Function and a Workflow are *callable
+     * targets*, not graph-only node kinds — they belong in every picker.
+     * {@link StepBuilderModalProps.callables} is the knob for those two.
+     */
+    appsOnly?: boolean;
+    /**
+     * Which callable families the Functions/Workflows tabs offer. Defaults to
+     * BOTH, so a caller that says nothing keeps the full F-2.0 homepage
+     * (`Connected apps | Functions | Workflows`). Pass a narrower array — or
+     * `[]` — where the surrounding contract cannot accept one of them.
+     */
+    callables?: readonly ("function" | "workflow")[];
+    /**
+     * Which homepage tab opens first. Defaults to `"connected"` — F-2.0's
+     * homepage. A caller re-opening the picker for an already-bound target
+     * passes that target's own family, so "Change" lands where the current
+     * value lives instead of making the author re-find the tab.
+     */
+    initialTab?: "connected" | "functions" | "workflows";
+    /** Modal heading. Defaults to "Add a step". */
+    title?: string;
+    /**
+     * Workflow-step context, when the builder is opened for a step that already
+     * lives in a workflow. When present the `testRequired` save-gate can discover a
+     * previously-saved **passing** test for the step via {@link W6WApi.listStepTests}.
+     * Absent in the plain add-step flow (the step has no id yet) — there the gate is
+     * satisfied by running a passing test in-session.
+     */
+    workflowId?: string;
+    /** Step id paired with {@link StepBuilderModalProps.workflowId}. */
+    stepId?: string;
+    /**
+     * The new step's known graph ancestors, when the builder is opened from the
+     * workflow canvas (`stepBuilderUpstreamSteps`, derived from the connection
+     * drag that opened it). Threaded into the Test tab's `<StepTestRun>` the same
+     * way `StepEditModal` seeds an existing step's Test tab, so a `with` block
+     * written as `{{ steps.<id>.output.<field> }}` resolves instead of coming
+     * back empty. Absent (defaults to `[]`) for the Functions/Endpoints pickers,
+     * which have no graph to draw ancestors from.
+     */
+    upstreamSteps?: ExpressionStepSource[];
+    /**
+     * Pre-select an app when the modal opens. When provided along with
+     * initialAction/initialConnection/initialWith, the modal opens directly
+     * to the action configuration view instead of the app picker.
+     * Used when editing an existing action (e.g., clicking "Change" on an
+     * Endpoint's already-configured target).
+     */
+    initialApp?: AppSummary;
+    /**
+     * Pre-select an action key. Requires initialApp to be set.
+     */
+    initialAction?: string;
+    /**
+     * Pre-select a connection. Requires initialApp and initialAction.
+     */
+    initialConnection?: string;
+    /**
+     * Pre-fill the action's parameter values. Requires initialApp and initialAction.
+     */
+    initialWith?: Record<string, unknown>;
+    /**
+     * Narrow which apps a scoped caller may pick, everywhere an app list is
+     * computed — the "Apps" tab's grid, the "AI" tab's composed filter, and
+     * {@link StepBuilderModalProps.callables}'s "Ready to use" tab. An
+     * `undefined` filter is a no-op; every existing caller (none of which sets
+     * this) is unaffected.
+     *
+     * On "Ready to use", an app built from a connection's inline `app` meta
+     * carries only `id` plus those meta keys (`displayName`, icons, brand
+     * colours) — no `version` or `categories` — so the filter sees just those,
+     * and the selected-app header omits the ` · v<version>` suffix for it.
+     */
+    appsFilter?: (app: AppSummary) => boolean;
+    /**
+     * Stop at "a connection is chosen" — no Action, no Configure/Test. Renders
+     * {@link AppConnectionOnlyConfig} in place of the usual `AppStepConfig`
+     * once an app is picked. Used by a caller that only needs a connection
+     * (e.g. binding a repository), not a runnable step.
+     */
+    connectionOnly?: boolean;
+    /**
+     * Fired once, on {@link AppConnectionOnlyConfig}'s footer button — never on
+     * selection alone. Only meaningful with {@link StepBuilderModalProps.connectionOnly}.
+     */
+    onConnected?: (connectionId: string, app: AppSummary) => void;
+}
+/** The four representations of the Configure tab: form, full-step JSON,
+ * params-only JSON, node settings. */
+export type ConfigView = "props" | "code" | "params-code" | "config";
+/**
+ * The props / code / params-code / config view toggle, right-aligned in the
+ * tabs bar. Disabled off the Configure tab (all four views represent the
+ * action's config).
+ *
+ * `views` narrows it to a subset, in the order given — a fields ⇄ raw-JSON
+ * property form (see `PropertyEntryForm`) passes `["props", "code"]`. There is
+ * deliberately no second toggle component: one glyph set, one styling, one
+ * pressed-state behaviour, however many views a host offers.
+ */
+export declare function ConfigViewToggle({ view, onChange, disabled, views, }: {
+    view: ConfigView;
+    onChange: (v: ConfigView) => void;
+    disabled?: boolean;
+    /** Which views to offer, in order. Defaults to all four. */
+    views?: ConfigView[];
+}): import("react").JSX.Element;
+/**
+ * Guided "add a step" flow. A sidebar toggles between **Apps** (pick app →
+ * ensure a connection → pick action → fill params) and **Controls** — the
+ * internal nodes: triggers, flow control (if/foreach/parallel/wait), and compute
+ * (script/data). Emits a `BuiltStep` via `onAdd`.
+ *
+ * Data + IO come from `useW6WApi()`, so mount it under `<W6WUIProvider>`.
+ */
+export declare function StepBuilderModal({ onClose, onAdd, onDraftChange, theme, appsOnly, callables, initialTab, title, workflowId, stepId, upstreamSteps, initialApp, initialAction, initialConnection, initialWith, appsFilter, connectionOnly, onConnected, }: StepBuilderModalProps): import("react").JSX.Element;
+/**
+ * Config form for a chosen internal node — its schema rendered through the same
+ * `ParamsForm` as app actions, seeded with the node's defaults. Emits the built
+ * step on Add.
+ */
+export declare function ControlStepConfig({ node, onAdd, onClose, onDraftChange, workflowId, upstreamSteps, }: {
+    node: InternalNodeDef;
+    onAdd: (s: BuiltStep) => string | undefined | void;
+    onClose: () => void;
+    /** See {@link StepBuilderModalProps.onDraftChange}. */
+    onDraftChange?: (id: string, step: BuiltStep) => void;
+    workflowId?: string;
+    /** The new step's known graph ancestors — see {@link StepBuilderModalProps.upstreamSteps}. */
+    upstreamSteps?: ExpressionStepSource[];
+}): import("react").JSX.Element;
+/**
+ * Config → test → add flow for a picked Function/Workflow target (D-12,
+ * D-15). Mints a single `@w6w/call` step — `family` only decides which
+ * summary/detail/invoke endpoints are called and what `with.targetKind` is
+ * stamped; it is never two near-copies. Mirrors `ControlStepConfig`'s
+ * progressive-commit shape (mint via `onAdd` the instant the target is
+ * picked, then `onDraftChange` on every later change) — unlike `AppStepConfig`
+ * there is no Setup tab (the target picked in `CallableList` IS the identity)
+ * and no `NodeConfigForm` here: a second onError/retry form is out of scope —
+ * `NodeConfigForm` is reached once the `@w6w/call` step already lives on a
+ * canvas, not at add-time.
+ */
+export declare function CallableStepConfig({ family, targetId, targetLabel, onAdd, onClose, onDraftChange, }: {
+    family: "function" | "workflow";
+    targetId: string;
+    targetLabel: string;
+    onAdd: (s: BuiltStep) => string | undefined | void;
+    onClose: () => void;
+    /** See {@link StepBuilderModalProps.onDraftChange}. */
+    onDraftChange?: (id: string, step: BuiltStep) => void;
+}): import("react").JSX.Element;
+/**
+ * Whether every required param has a usable value — gates the inline "Test run".
+ * A required array (e.g. a `vars` table) may be empty (see the Data node); other
+ * required fields must be non-empty.
+ *
+ * A param hidden by its own `showIf` is skipped, matching `ParamsForm`'s render
+ * visibility — this is what lets `required` and `showIf` combine at all (e.g.
+ * SendGrid's `contentValue`, required only when NOT using a dynamic template):
+ * without it, a conditionally-required field would either block the gate in the
+ * branch where it's moot, or (if left non-required to dodge that) never be
+ * caught here and only surface as a raw runtime error from the app's own
+ * `execute()` — the app was previously written the second way for exactly this
+ * reason; that workaround was fixed alongside this once the gate learned `showIf`.
+ */
+export declare function requiredParamsFilled(params: ActionParam[], values: Record<string, unknown>): boolean;
+/**
+ * Whether adding this step is gated on a **passing** saved test — the per-app
+ * `testRequired` save-gate. Defaults to **required**; an app/node surface may
+ * opt out by carrying `testRequired: false`.
+ *
+ * The flag is read defensively off the app/node surface because the core app
+ * manifest does not carry a `testRequired` field yet (a recorded follow-up); an
+ * absent flag therefore means **required**, so today every app step must pass a
+ * test before it can be added.
+ */
+export declare function isTestRequired(surface: unknown): boolean;
+/**
+ * Where a test run should be persisted. When present, `StepTestRun` saves the
+ * fixture (`saveStepTest`) and records the run's outcome (`recordStepTestRun`)
+ * against the given workflow step after each invoke. `input` is the resolved
+ * incoming state captured alongside the params (`values` → `with`). Absent in
+ * the add-step builder (the step isn't in a workflow yet).
+ */
+export interface StepTestPersist {
+    workflowId: string;
+    stepId: string;
+    input: Record<string, unknown>;
+}
+/** Imperative handle so a host (e.g. the step modal footer) can trigger the run. */
+export interface StepTestRunHandle {
+    run: () => void;
+}
+/**
+ * Inline "Test run" — invokes the action/node with the current params (and, for
+ * app actions, the chosen connection) so the user can try a step from inside the
+ * builder before adding it. Pressable only once required fields are filled.
+ *
+ * When `persist` is supplied (the node editor's Test tab), each run also saves
+ * the fixture and records the outcome server-side, so a step test becomes saved
+ * and re-runnable. `hideRunButton` suppresses the inline button when the host
+ * drives the run from elsewhere (the modal footer) via the imperative handle.
+ */
+export declare const StepTestRun: import('react').ForwardRefExoticComponent<{
+    app: string;
+    action: string;
+    connectionId?: string;
+    values: Record<string, unknown>;
+    canRun: boolean;
+    hideRunButton?: boolean;
+    persist?: StepTestPersist;
+    /**
+     * The run's start state — what the upstream steps last produced — so a
+     * `values` entry written as `{{ steps.<id>.output.<field> }}` resolves
+     * server-side instead of coming back empty. The host builds it (both the
+     * node editor's Test tab and, since T1.1.1, the add-step builder's Test
+     * tab seed it from the upstream fixtures, via `useSeedSources` +
+     * `startStateFromSeeds`); absent only when the host itself has no upstream
+     * steps to offer — the Functions/Endpoints pickers, which have no graph.
+     */
+    state?: StepStartState;
+    /** Notified when the run starts/finishes so a host button can reflect it. */
+    onBusyChange?: (busy: boolean) => void;
+    /**
+     * Notified with the outcome of each finished run (`true` = passed). Lets a
+     * host satisfy the `testRequired` save-gate from an in-session test run.
+     */
+    onResult?: (passed: boolean) => void;
+} & import('react').RefAttributes<StepTestRunHandle>>;
+/**
+ * What the home tab has to show. Lifted out of the tab's own component because
+ * the MODAL needs the answer too: a home tab with nothing in it is not
+ * rendered at all (no connected apps, no Functions, no Workflows ⇒ no tab),
+ * and that decision belongs to whoever draws the sidebar.
+ *
+ * `state` is deliberately four-valued. "Empty" and "not loaded yet" must not
+ * collapse into one: hiding the tab while its fetches are in flight would make
+ * it appear a beat later, moving the sidebar under the cursor.
+ */
+interface ReadyToUse {
+    state: "loading" | "error" | "empty" | "ready";
+    error?: string;
+    apps: AppSummary[];
+    fns: FunctionSummary[];
+    wfs: WorkflowSummary[];
+    /** More connected-app ids remain unresolved — draw an explicit "load more" affordance. */
+    moreApps: boolean;
+    /** Resolve the next bounded batch of connected-app ids. No-op off the bounded path or with nothing left. */
+    loadMoreApps: () => void;
+}
+/**
+ * Clamp the poll-interval text to an integer number of minutes ≥ `min`. Blank,
+ * non-numeric or below-minimum input yields `min`; fractions round to nearest.
+ */
+export declare function clampMinutes(raw: string, min: number): number;
+/**
+ * "Ready to use"'s data: distinct connected app ids (A3) resolved in bounded
+ * batches via the optional `listAppsByIds`, plus Functions/Workflows.
+ *
+ * `/connections` already includes a synthetic zero-credential row per
+ * zero-credential-flagged app the caller's tenant can use with no connection
+ * step (`admin/connections.ts`) — so the DISTINCT connection app ids alone are
+ * the full "ready" membership; unlike the old full-catalog scan, no separate
+ * `AppSummary.zeroCredential` check is needed on this path.
+ *
+ * `listAppsByIds` is optional (older/imported providers implement only
+ * `listApps`): capability is `typeof api.listAppsByIds === "function"`
+ * ALONE — never inferred from a runtime result. A first batch that resolves
+ * to an empty array is a LEGITIMATE answer from a fully-working
+ * `listAppsByIds` (every connected app was since deleted from the catalog,
+ * an ordinary case) and must be shown as such, not treated as evidence the
+ * optional method "isn't really implemented" (T2.1.1 ROUND 2 — that
+ * conflation previously made a correct, well-typed empty result permanently
+ * fall back to the unbounded `listApps()` for the rest of the component's
+ * lifetime, the exact "one request per entire catalog at open" A3 forbids).
+ * When the method is genuinely absent, this hook falls back to the ORIGINAL
+ * full-catalog scan (`listApps()` + the zero-credential check), unchanged —
+ * and with `listApps` itself also absent (now optional, like this member),
+ * settles on the empty catalog instead of calling an undefined function.
+ *
+ * On the bounded path each connection's inline `app` meta is read FIRST: an
+ * app id with a non-null `app` on any of its rows is built as
+ * `{ ...c.app, id: c.appId }` and seeded as resolved + requested, so
+ * `listAppsByIds` is called only for ids whose rows all lack it (`app` absent
+ * or `null`) — and not at all when none do. Such inline apps have no
+ * `version`/`categories`: the selected-app header drops its ` · v<version>`
+ * suffix and `appsFilter` sees only `id` and the meta keys.
+ *
+ * Exported for tests only (not re-exported from the package index).
+ */
+export declare function useReadyToUse(callables: readonly ("function" | "workflow")[], appsFilter?: (app: AppSummary) => boolean): ReadyToUse;
+export declare function AppStepConfig({ appId, app, onAdd, onClose, onDraftChange, onChangeApp, theme, workflowId, stepId, upstreamSteps, initialAction, initialConnection, initialWith, }: {
+    appId: string;
+    app?: AppSummary;
+    onAdd: (s: BuiltStep) => string | undefined | void;
+    onClose: () => void;
+    /** See {@link StepBuilderModalProps.onDraftChange}. */
+    onDraftChange?: (id: string, step: BuiltStep) => void;
+    onChangeApp?: () => void;
+    theme?: ThemeMode;
+    workflowId?: string;
+    stepId?: string;
+    /** The new step's known graph ancestors — see {@link StepBuilderModalProps.upstreamSteps}. */
+    upstreamSteps?: ExpressionStepSource[];
+    /** Pre-selected action key, opens directly to Configure tab when provided with initialWith */
+    initialAction?: string;
+    /** Pre-selected connection id */
+    initialConnection?: string;
+    /** Pre-filled parameter values */
+    initialWith?: Record<string, unknown>;
+}): import("react").JSX.Element;
+/**
+ * {@link AppStepConfig}'s Setup tab, minus the Action and Configure/Test
+ * gate — for a caller that only needs "a connection is chosen" (e.g. binding
+ * a repository), not a runnable step. Copies its App section and all three
+ * Connection-section branches verbatim, same CSS classes; fetches only
+ * {@link W6WApi.getAppAuth} + {@link W6WApi.listConnectionsForApp} (never
+ * `getAppActions`). Ends in one footer button, gated on `connectionSatisfied`
+ * alone, that fires {@link onConnected} once — never on selection (D-sbm-2).
+ */
+export declare function AppConnectionOnlyConfig({ appId, app, onClose, onChangeApp, theme, initialConnection, onConnected, }: {
+    appId: string;
+    app?: AppSummary;
+    onClose: () => void;
+    onChangeApp?: () => void;
+    theme?: ThemeMode;
+    /** Pre-selected connection id */
+    initialConnection?: string;
+    /** Fired once, on the footer button — never on a state change (D-sbm-2). */
+    onConnected: (connectionId: string, app: AppSummary) => void;
+}): import("react").JSX.Element;
+export {};

package/dist/TriggerFillForm.d.ts

@@ -0,0 +1,52 @@
+import { StepTestPersist } from './StepBuilderModal.tsx';
+/**
+ * The Test-tab widget for a manual/webhook trigger. A trigger's configured
+ * `fields` ARE the run's starting state, so testing it means **filling those
+ * fields**, not running the raw config (which is why the trigger's output used to
+ * come back `{}` — the invoke never carried an `input`).
+ *
+ * It projects the trigger's `fields` into params (see `./trigger-fields.ts`) and
+ * hands them to {@link PropertyEntryForm} — the one property-entry surface, which
+ * gives it the per-field widgets, per-field `ƒx`, and the fields ⇄ raw-JSON
+ * toggle. This component keeps only the *run*: it enforces each field's
+ * `required` via {@link requiredParamsFilled} before enabling Test, and invokes
+ * with `{ input: {…filled} }` so the handler (which passes `params.input`
+ * through) returns the populated values as the trigger's output state.
+ *
+ * A trigger with no declared fields (e.g. a webhook, whose payload is arbitrary)
+ * gets the raw JSON payload editor — that is the entry form's own empty-params
+ * path, not a second code path here — so the operator can still supply a
+ * starting state, and the same `{ input }` projection applies.
+ *
+ * **Remembered values (T4.1.3).** With `persist` supplied, the values are not
+ * just used for the invoke: they are saved as the step's latest `step_tests`
+ * fixture (`with`) and the run is recorded **against that fixture's id**, and the
+ * form seeds itself from the latest fixture next time it opens. The store is
+ * project-owned and shared per workflow — any editor of the workflow sees the
+ * same saved values, which is the answer to HITL-2. The canvas ▶ Run collect
+ * form reads and writes the same fixture, so values entered on either surface
+ * come back on the other.
+ *
+ * That persistence is **local to testing** — `TriggerFillForm` itself never
+ * calls `POST /workflows/:id/run`. It does not by itself reach a production
+ * workflow run: that route does accept an `input` body field, and the server
+ * lands it as the entry trigger's output (`run-workflow.ts`,
+ * `EnqueueRunInput.input`), but a CALLER has to fetch the saved fixture and
+ * pass it in. Studio's header ▶ Run is that caller (`WorkflowsPage.tsx`'s
+ * `onRunClick` → `resolveHeaderRunInput`,
+ * `packages/studio/src/lib/workflow-live-run.ts`): it fetches the manual
+ * trigger's latest `step_tests` row and sends its `with` verbatim as `input`.
+ * This form is not in that path; it only writes the fixture that call reads.
+ */
+export declare function TriggerFillForm({ app, action, fields, persist, }: {
+    app: string;
+    action: string;
+    /** The trigger's `fields` param value (an array of field definitions). */
+    fields: unknown;
+    /**
+     * Where to remember the entered values. Absent in the add-step builder — that
+     * step is not in a workflow yet, so there is no `(workflowId, stepId)` to key
+     * a fixture by and this form neither reads nor writes one.
+     */
+    persist?: StepTestPersist;
+}): import("react").JSX.Element;

package/dist/WaitEditor.d.ts

@@ -0,0 +1,6 @@
+/** Both input modes write the same duration field; switching never discards a compound value. */
+export declare function WaitEditor({ values, onChange, readOnly, }: {
+    values: Record<string, unknown>;
+    onChange: (values: Record<string, unknown>) => void;
+    readOnly?: boolean;
+}): import("react").JSX.Element;

package/dist/WorkflowFlowEditor.d.ts

@@ -0,0 +1,119 @@
+import { ExpressionOptions, ExpressionStepSource } from './components/ExpressionOptions.tsx';
+import { FlowStep, FlowWorkflow } from './flow-types.ts';
+import { RunState } from './run-visuals.ts';
+import { AppSummary } from './types.ts';
+export interface WorkflowFlowEditorProps {
+    /** The workflow being edited. The editor re-derives layout when this changes identity. */
+    value: FlowWorkflow;
+    /** Fired whenever the user changes the graph — new nodes, edges, or step edits. */
+    onChange: (next: FlowWorkflow) => void;
+    /** Disable all interactions — pans/zooms are still enabled. */
+    readOnly?: boolean;
+    /** Height of the editor viewport. Defaults to 480px. */
+    height?: string | number;
+    /**
+     * Registered apps, used to render each action node with its owning app's icon,
+     * display name, and version. A step only carries `uses.app` (an id), so the
+     * card joins that id against this list. Optional — unknown/absent apps degrade
+     * to an initials tile with no version. Metadata is looked up at render time and
+     * never stored on nodes, so it can't corrupt round-tripping back to a workflow.
+     */
+    apps?: AppSummary[];
+    /**
+     * EXTRA scope for each step field's expression picker, on top of whatever
+     * this editor is already mounted under.
+     *
+     * Optional, and normally omitted: `ExpressionOptionsProvider` layers, so a
+     * host that provides the project's vars/secrets/documents above this editor
+     * (studio does, once, in its app shell) needs to pass nothing here. Use it
+     * only to add or override something at this level.
+     *
+     * Names only — secret plaintext never reaches the client.
+     */
+    exprOptions?: ExpressionOptions;
+    /**
+     * The workflow's currently-selected project id. Threaded into ad-hoc
+     * test-invokes so document expressions resolve against that project's docs
+     * (not the scope's default/starter project). The host (studio) passes the
+     * active project here; omitted → server default-project behavior. See T2.1.2 /
+     * HITL-4(b): the invoke path's ambient scope is already project-aware.
+     */
+    project?: string;
+    /**
+     * The live run's per-step state, when the canvas is showing one (T1.1.1).
+     * Omitted ⇒ the canvas renders exactly as it does today: every node in its
+     * default look, every edge unstyled beyond its own `when` lane. This
+     * editor does no fetching of its own — the host (`studio`) owns polling
+     * `GET /runs/:id` and passes each successive result here, the same
+     * "host owns the query, editor is presentational" split `apps`/`readOnly`
+     * already establish for every other external data source.
+     *
+     * A structural subset of `RunState` in `@w6w/workflow-types` (mirrors this
+     * file's own `FlowWorkflow`/`FlowStep` — see `flow-types.ts`'s header
+     * note): `packages/ui` takes no dependency on the engine's types, so a
+     * caller who already has the real `RunState` is compatible for free.
+     *
+     * Never persisted: {@link flowToWorkflow} never reads it — a run is not
+     * part of the workflow that ran, and `data.stepStatus`/`data.runStatus`
+     * (where this ends up on the canvas) are never among the fields it reads
+     * back off a node.
+     */
+    runState?: RunState;
+    /**
+     * Fired the instant a step test starts — the ▶ collect form's Run button, or
+     * `StepEditModal`'s footer Test button — before the invoke goes out, so a host
+     * can drop whatever run its canvas was showing (T1.1.1) instead of leaving a
+     * test to run underneath a stale run's highlighting.
+     *
+     * On the click, never on the result: only one of those two surfaces has a
+     * completion to report at all, and the click is the one moment both share.
+     */
+    onTestRun?: () => void;
+    /**
+     * Re-frames the canvas when the host changes the space around it. When this
+     * value changes after mount (compared with `Object.is`), the editor calls
+     * `fitView({ duration: 300 })` once. It never fires on mount, and omitting it
+     * or passing the same value again adds no fit.
+     *
+     * For a host whose page layout resizes the canvas without the graph changing,
+     * e.g. a side panel docking beside it (pass the panel's open state). React Flow
+     * keeps its pan/zoom transform when its pane narrows, so nodes near the edge
+     * would otherwise end up behind the panel. The editor does not watch its own
+     * size, so the host decides which layout changes deserve a re-frame.
+     *
+     * A fit replaces whatever camera is showing, including a saved viewport the
+     * editor restored on open. The fit is not user-initiated, so it never emits
+     * `onChange` and never overwrites the stored viewport.
+     */
+    fitViewKey?: string | number | boolean;
+}
+/** Which view the step edit modal opens in: the tabbed form, raw JSON, or node settings. */
+type EditView = "props" | "json" | "settings";
+/**
+ * Visual workflow editor. Renders a Workflow's DAG as a React Flow graph:
+ *
+ *   - Auto-layouted on load (topological columns + sibling rows).
+ *   - Nodes render differently for action steps vs. control steps
+ *     (`uses.app === "@w6w/control"`).
+ *   - `+ Step` opens a guided builder (pick app → connection → action → params,
+ *     or a flow control). Drag nodes to reposition; connect handles to add edges.
+ *   - Selecting a node reveals a toolbar above it: Edit / Duplicate / Delete.
+ *   - Edit opens a modal with a Form ⇄ JSON toggle for that step.
+ *   - Every meaningful change fires `onChange` with an updated Workflow.
+ */
+export declare function WorkflowFlowEditor(props: WorkflowFlowEditorProps): import("react").JSX.Element;
+export declare function StepEditModal({ workflowId, step: initialStep, upstreamSteps, onChange, onClose, readOnly, initialView, fanOutCount, onTestRun, }: {
+    workflowId: string;
+    step: FlowStep;
+    /** Graph ancestors of this step (from `upstreamStateSources`); the incoming-state picker seeds from their saved tests. */
+    upstreamSteps: ExpressionStepSource[];
+    onChange: (next: FlowStep) => void;
+    onClose: () => void;
+    readOnly?: boolean;
+    initialView?: EditView;
+    /** Most outgoing edges this step has in one lane; "Run next steps" needs >= 2. */
+    fanOutCount?: number;
+    /** Fired the instant the footer Test button is clicked, before the test runs (T1.1.1). */
+    onTestRun?: () => void;
+}): import("react").JSX.Element;
+export {};

package/dist/YamlEditor.d.ts

@@ -0,0 +1,46 @@
+import { ThemeMode } from './types.ts';
+export interface YamlEditorProps {
+    value: string;
+    onChange: (value: string) => void;
+    /** Placeholder text shown when value is empty. */
+    placeholder?: string;
+    /** Minimum editor height. Defaults to "240px". */
+    minHeight?: string;
+    /** Maximum editor height before scrolling. Defaults to no cap. */
+    maxHeight?: string;
+    /**
+     * Explicit editor height. Pass `"100%"` to fill a flex parent (the whole-config
+     * "code" view). Omit to let the editor grow with its content between
+     * `minHeight` and `maxHeight` — an inline YAML/group field wants this.
+     */
+    height?: string;
+    /** Read-only mode — useful for previewing a stored definition. */
+    readOnly?: boolean;
+    /**
+     * Explicit theme. If omitted, the editor auto-detects `data-theme` on
+     * `<html>` and falls back to `prefers-color-scheme` — same behavior as
+     * `<AppIcon>`. Uses CodeMirror's built-in one-dark for dark mode.
+     */
+    theme?: ThemeMode;
+    /** Accessible label for the editor. */
+    "aria-label"?: string;
+    /**
+     * Render an in-box copy-to-clipboard button, a direct child of this
+     * component's own `.w6w-yaml-editor` wrapper (sibling to the CodeMirror
+     * mount — no extra DOM node). Copies the current `value` verbatim.
+     *
+     * Off by default: the other mounts of this component must render byte-
+     * identically to before this prop existed.
+     */
+    copyable?: boolean;
+}
+/**
+ * YAML editor built on CodeMirror 6. Syntax highlighting, folding, gutter,
+ * and line numbers. Themed with the `--w6w-*` custom properties so it
+ * inherits from the consumer's palette.
+ *
+ * ```tsx
+ * <YamlEditor value={text} onChange={setText} minHeight="320px" />
+ * ```
+ */
+export declare function YamlEditor(props: YamlEditorProps): import("react").JSX.Element;

package/dist/app-categories.d.ts

@@ -0,0 +1,38 @@
+import { AppSummary } from './types.ts';
+/**
+ * Display label for a category slug. A known override wins; otherwise the
+ * slug is split on `-`/`_`/whitespace and each word is capitalized. Never
+ * throws — an empty/non-string slug renders as `""`, and any out-of-
+ * vocabulary slug still gets a readable (title-cased) label.
+ *
+ * @example
+ * categoryLabel("crm");                // "CRM"            (override)
+ * categoryLabel("project-management"); // "Project Management"
+ * categoryLabel("sales");              // "Sales"           (out-of-vocabulary, still safe)
+ */
+export declare function categoryLabel(slug: string): string;
+/** One category chip's derived data — a slug, its display label, and how
+ * many of the supplied apps carry it. */
+export interface CategoryChip {
+    slug: string;
+    label: string;
+    count: number;
+}
+/**
+ * Distinct category slugs present across `apps`, each with its app count.
+ * Ordered by count DESCENDING; ties break on the derived LABEL, ascending
+ * (a deterministic order — never insertion/slug order, which would vary with
+ * the catalog's own listing order).
+ *
+ * Derive from the caller's already-visible catalog (post any `filter` prop),
+ * never from the full RFC vocabulary — a category with nothing behind it in
+ * the current list is a dead end (D-1a).
+ */
+export declare function deriveCategories(apps: readonly AppSummary[]): CategoryChip[];
+/**
+ * Whether `app` matches a set of selected category slugs. An EMPTY selection
+ * means "all" (every app matches); a non-empty selection is OR-across-
+ * selected — the app matches if it carries ANY of the selected slugs. Mirrors
+ * `AppsPage.tsx`'s `cats.size === 0 ? … : appCats.some((c) => cats.has(c))`.
+ */
+export declare function matchesCategories(app: AppSummary, selected: readonly string[]): boolean;