@w6w/ui 0.0.0-stage → 0.1.0

package/dist/components/server-resources-format.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure formatting + geometry helpers for the server-resources family, kept in
+ * their own module so they carry no React and can be unit-tested on their own.
+ *
+ * `ServerResourceSample` is a thin LOCAL copy of the sampler's wire sample
+ * (`plan.md` §Pinned wire) — the same deliberate duplication `UptimeStrip.tsx`
+ * keeps of the health union, and for the same reason: it keeps `@w6w/ui` a
+ * pure-presentation leaf with no transport/spec coupling, so nothing here has
+ * to move when the server's payload grows a field.
+ *
+ * Every helper is TOTAL: an unknown number is never rendered as `0`, it is
+ * rendered as an em dash. A node whose CPU reading is missing must not read as
+ * an idle node.
+ */
+/** One sample of the host's resource usage, exactly as the server sends it. */
+export interface ServerResourceSample {
+    /** ISO-8601 instant the sample was taken. */
+    ts: string;
+    cpus: number | null;
+    cpuLimit: number | null;
+    load1: number | null;
+    load5: number | null;
+    load15: number | null;
+    memoryTotal: number | null;
+    memoryAvailable: number | null;
+    memoryLimit: number | null;
+    processRss: number | null;
+    processHeapUsed: number | null;
+    processHeapTotal: number | null;
+}
+/**
+ * A byte count as a short human string: exact bytes below 1 KiB (`1023 B`),
+ * one decimal place per binary magnitude from KiB up (`1.5 KiB`, `15.6 GiB`).
+ * `null` (nothing measured) is `—`.
+ */
+export declare function formatBytes(n: number | null): string;
+/**
+ * A 0…1-ish fraction as a whole-percent string (`0.123` → `12%`). Not clamped:
+ * a load above the CPU count is real and reads `135%`. `null` is `—`.
+ */
+export declare function formatPercent(f: number | null): string;
+/**
+ * `load1` against the effective CPU budget — the container's `cpuLimit` when
+ * the server set one, otherwise the host CPU count. `null` when either operand
+ * is unknown or the divisor is ≤ 0 (a zero-CPU budget is not "0% busy", it is
+ * "not measurable").
+ */
+export declare function cpuLoadFraction(s: ServerResourceSample | undefined): number | null;
+/**
+ * Used memory as a fraction of total: `(memoryTotal − memoryAvailable) /
+ * memoryTotal`. `null` when either operand is unknown or the total is ≤ 0.
+ */
+export declare function memoryUsedFraction(s: ServerResourceSample | undefined): number | null;
+/**
+ * The `points` attribute of a sparkline polyline, hand-drawn — this package
+ * has no chart dependency on purpose (D-5), and a polyline over ~60 samples
+ * does not justify one.
+ *
+ * The x axis is positional (`i / (n − 1) · width`), so a gap in the series
+ * still advances the line; `y` is inverted (SVG grows downward) and scaled
+ * against `max`. Nulls are SKIPPED, not plotted as zero, and a series of fewer
+ * than two values has no line at all (`""` — a single point is not a shape).
+ * `max ≤ 0` flattens the line along the baseline rather than dividing by it.
+ *
+ * Every coordinate is rounded to two decimals so the attribute stays short and
+ * a snapshot of it stays readable.
+ */
+export declare function sparklinePoints(values: readonly (number | null)[], width: number, height: number, max: number): string;

package/dist/components/server-resources.fixture.d.ts

@@ -0,0 +1,9 @@
+import { ServerResourceSample } from './server-resources-format.ts';
+/**
+ * `count` samples, oldest first, of a host with 8 CPUs under a 2-CPU cgroup
+ * limit and 16 GiB of RAM — so the CPU fraction is a fraction of the LIMIT
+ * (load ≈ 0.5 of a 2-CPU budget reads ~25%) and the memory fraction moves
+ * around 55%. Every series is non-flat, which is the point: a sparkline over a
+ * constant is a straight line and proves nothing in a story.
+ */
+export declare function demoServerResourceSamples(count?: number): ServerResourceSample[];

package/dist/components/use-copy.d.ts

@@ -0,0 +1,14 @@
+/** Majority precedent across the tree: `admin/src/components/CopyButton.tsx:17`,
+ *  `studio/src/pages/EndpointsPage.tsx:823`. */
+export declare const COPIED_MS = 1500;
+/**
+ * The clipboard-write + copied/revert-timer state machine, factored out of
+ * `Copyable` so `JsonEditor` can drive its own in-box button without a second
+ * clipboard call site. This is the ONLY spot in `@w6w/ui`'s `src` that writes
+ * to the clipboard — `Copyable` and `JsonEditor` both consume it rather than
+ * each writing their own.
+ */
+export declare function useCopyToClipboard(value: string, copiedMs?: number): {
+    copied: boolean;
+    copy: () => Promise<void>;
+};

package/dist/createW6WApi.d.ts

@@ -0,0 +1,31 @@
+import { W6WApi } from './provider.tsx';
+export interface CreateW6WApiOptions {
+    /** Absolute URL or path prefix — e.g. `"https://w6w.example.com"` or `"/api"`. */
+    baseUrl: string;
+    /**
+     * Bearer token to send. Accepts a string (static) or a supplier function so
+     * a JWT that rotates on refresh is fetched fresh on every request. The
+     * supplier may be sync or return a `Promise` — either way it is awaited
+     * once per request. It receives an optional `{ forceRefresh? }` ctx arg
+     * (unused by this client today, but part of the shape so a caller's
+     * supplier can share one implementation with `@w6w/sdk`'s `TokenProvider`).
+     */
+    token?: string | ((ctx?: {
+        forceRefresh?: boolean;
+    }) => string | null | undefined | Promise<string | null | undefined>);
+    /** Optional fetch replacement — handy for tests. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export declare class ApiError extends Error {
+    status: number;
+    code: string;
+    /**
+     * The parsed error response body, when the server sent one. Carries the
+     * fields that ride alongside an error — e.g. an invoke's `logs` and
+     * `apiCalls` — which the message alone would drop.
+     */
+    body?: unknown;
+    constructor(status: number, code: string, message: string, body?: unknown);
+}
+/** Build a fetch-based W6WApi client bound to a base URL + token supplier. */
+export declare function createW6WApi(opts: CreateW6WApiOptions): W6WApi;

package/dist/flow-connect.d.ts

@@ -0,0 +1,138 @@
+import { Edge } from '@xyflow/react';
+import { PortsLookup } from './flow-types.ts';
+import { StepNode } from './flow-utils.ts';
+/**
+ * Which lane a React Flow edge belongs to (core `rfcs/workflow.md` · `Edge.when`
+ * amendment). **Omitted ⇒ `"success"`**, and read defensively: an edge that
+ * predates the `data.when` stamp — or one React Flow synthesised — may carry no
+ * `data` at all. The single accessor: every consumer calls this rather than
+ * re-deriving the fallback, so "absent means success" is decided once.
+ */
+export declare function edgeLane(e: Edge): "success" | "error";
+/**
+ * A refused connection: the source's exit port is full **in this lane** and the cap
+ * is finite. Drawing past a finite `out` cap is refused, never satisfied by evicting
+ * an existing edge (an unbounded `"many"` out never refuses).
+ */
+export type OutCapRefusal = {
+    refused: "out_cap";
+    cap: number;
+};
+/**
+ * The hard rules for an edge `source → target` — the ones no amount of
+ * replacement can satisfy: a real, *distinct* pair (no self-loops), no duplicate
+ * edge, the target accepts an entry port (blocks connecting *into* a trigger,
+ * which declares `in: 0`), and the source has an exit port. Port **capacity** is
+ * deliberately NOT checked here: a full single-slot port is freed by replacement
+ * (see `applyConnect`), so dragging a new wire from an already-connected node
+ * re-points it rather than being rejected. Used as the live `isValidConnection`.
+ *
+ * The duplicate-pair check is **lane-blind by design**, and that is a v1 *editor*
+ * limit, not a model limit: the model permits a success edge and an error edge
+ * between the same two steps (D-T1-8 widened the engine's `skippedEdges` key so
+ * they cannot collide), but v1 declines to author that pair because there are no
+ * id'd source handles to pick the lane from (D-T1-7).
+ *
+ * A colliding minted **id** is deliberately NOT rejected here, even though
+ * {@link applyConnect} refuses it: this predicate is the live `isValidConnection`,
+ * and a `false` here means React Flow never fires `onConnect`, so the editor never
+ * gets to *say why*. That refusal is invisible (and, worse, lands in
+ * `onConnectEnd`'s "dropped on empty canvas" branch, which opens the step builder).
+ * Letting the drop through and refusing in `applyConnect` is what lets the reason
+ * paint — see {@link connectConflict}.
+ */
+export declare function canConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], lookup?: PortsLookup): boolean;
+/**
+ * Build the next edge set for a new `source → target` connection. **Additive at the
+ * source**: a source under its `out` cap (or unbounded) keeps every existing edge and
+ * gains one; at a finite cap the connection is **refused** (see {@link connectRefusal}),
+ * never satisfied by evicting. The target's entry port is still single-slot-replacing:
+ * the oldest inbound edge(s) are dropped to make room. Returns `null` when the
+ * connection is disallowed by {@link canConnect}, refused at the out cap — **or when the minted id would
+ * duplicate a surviving edge's id**, the same refusal {@link setEdgeWhen} performs
+ * through the same {@link collidingEdgeId} test.
+ *
+ * That last one closes the reverse order of the `:error` collision: marking `a → b`
+ * as the error lane is refused when `a → "b:error"` already exists, but *first*
+ * marking `a → b` Error and *then* drawing `a → "b:error"` used to be allowed and
+ * minted a duplicate id — React Flow's id-keyed store then held one wire for two
+ * edges (measured `storeSize 1 / 2`). Refusing here is narrow on purpose; rejecting
+ * the step id itself is the durable fix and would also have to reject ids inside
+ * workflows that already exist (FOLLOWUPS.md). The caller must surface the refusal —
+ * see {@link connectConflict}.
+ *
+ * The source's exit capacity is **per lane** (T3.2.2): success edges compete only
+ * with success edges, error edges only with error edges. So a finite `out: 1`
+ * step refuses a second success edge *within* a lane,
+ * while additionally being able to hold one error edge — which is what makes a
+ * `send → (error) → fallback` shape authorable at all. No `ports.out` bump is
+ * needed, so every persisted definition and palette entry stays valid.
+ *
+ * The target's entry capacity stays **lane-blind**, and that asymmetry is the
+ * point: a converging tail step receiving one success and one error edge is
+ * governed by `ports.in` alone. Partitioning the target rule by lane too — the
+ * plausible "symmetry" cleanup — would let a `ports.in: 1` node silently accept
+ * two inbound edges.
+ */
+export declare function applyConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: "success" | "error", lookup?: PortsLookup): Edge[] | null;
+/**
+ * The id of the existing edge that drawing `source → target` would collide with, or
+ * `null` when the connection is safe (or refused for an ordinary reason — a
+ * duplicate pair, a self-loop, a portless step — which the drag already showed the
+ * user by marking the drop invalid). The creation-path twin of
+ * {@link edgeWhenConflict}, and the same channel: it lets the caller *name* the
+ * offending edge in an inline refusal instead of losing a wire silently. The editor
+ * selects that edge and renders the message in the edge-lane panel (never a browser
+ * dialog; see `.ai/conventions.md`).
+ */
+export declare function connectConflict(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: "success" | "error", lookup?: PortsLookup): string | null;
+/**
+ * The out-cap refusal for drawing `source → target`, or `null` when the source has
+ * room (or is unbounded). The editor renders `cap` in an inline message on the same
+ * channel as {@link connectConflict}; {@link applyConnect} returns `null` for it.
+ */
+export declare function connectRefusal(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: "success" | "error", lookup?: PortsLookup): OutCapRefusal | null;
+/**
+ * Re-lane one edge. Updates its `data.when`, its visuals and its id, and frees
+ * nothing: when the destination lane is at a finite out cap the switch is refused
+ * (see {@link relaneRefusal}) — the same rule `applyConnect` applies on creation.
+ *
+ * Returns a **new** array and mutates nothing (React Flow's state handle compares
+ * by identity), or **`null` when the switch must be refused** — the `applyConnect`
+ * idiom. It is refused when the re-minted id would duplicate a surviving edge's
+ * id, which happens for a step id ending in `:error`: `flowEdgeId` qualifies the
+ * error lane with that same suffix, so `a → b` in the error lane and `a → "b:error"`
+ * in the success lane mint one id, and React Flow's id-keyed store would collapse
+ * them — one wire silently vanishing from the canvas, which reads as the editor
+ * losing the author's work. The caller must surface the refusal (see
+ * {@link edgeWhenConflict}); rejecting the step id itself is the durable fix and
+ * is deliberately NOT done here, because it would also have to reject ids inside
+ * workflows that already exist (FOLLOWUPS.md).
+ *
+ * It is refused for one more reason: an `edgeId` owned by more than one edge. That
+ * edge set is already corrupt, and re-laning by id would rewrite **every** match,
+ * overwriting the other edge's endpoints (`edgeWhenConflict` returns `null` there —
+ * there is no *other* edge to name, so the caller's generic refusal applies).
+ */
+export declare function setEdgeWhen(edges: Edge[], edgeId: string, when: "success" | "error", nodes: StepNode[], lookup?: PortsLookup): Edge[] | null;
+/**
+ * The id of the existing edge that {@link setEdgeWhen} would collide with, or
+ * `null` when the switch is safe. Lets the caller *name* the offending edge in an
+ * inline refusal instead of failing silently — the editor renders it in the
+ * edge-lane panel (never a browser dialog; see `.ai/conventions.md`).
+ */
+export declare function edgeWhenConflict(edges: Edge[], edgeId: string, when: "success" | "error", nodes: StepNode[], lookup?: PortsLookup): string | null;
+/** The out-cap refusal for re-laning `edgeId`, or `null` — the re-lane twin of {@link connectRefusal}. */
+export declare function relaneRefusal(edges: Edge[], edgeId: string, when: "success" | "error", nodes: StepNode[], lookup?: PortsLookup): OutCapRefusal | null;
+/**
+ * Rewrite the edge set after a step's id changed from `prevId` to `nextId`:
+ * re-point every endpoint and **re-mint the id in the edge's own lane**.
+ *
+ * Extracted from `updateStep` so it is testable, and fixing a real defect: the
+ * rewrite used to rebuild every id as `` `${source}->${target}` `` unconditionally,
+ * dropping an error edge's `:error` qualifier — so renaming a step collapsed a
+ * same-target success+error pair into one edge in React Flow's id-keyed store.
+ * That was unreachable while a second outgoing edge deleted the first; per-lane
+ * exit capacity is what makes it reachable, hence the fix ships alongside it.
+ */
+export declare function renameStepInEdges(edges: Edge[], prevId: string, nextId: string): Edge[];

package/dist/flow-fanout.d.ts

@@ -0,0 +1,15 @@
+import { Edge } from '@xyflow/react';
+import { FlowStep } from './flow-types.ts';
+export type FanOutMode = "sequential" | "parallel";
+/**
+ * `count` is the largest number of outgoing edges the step has in any ONE lane
+ * (success / error); fan-out only means something at `count >= 2`.
+ */
+export declare function fanOutState(stepId: string, edges: readonly Edge[]): {
+    enabled: boolean;
+    count: number;
+};
+/** Sequential is the default, so it is expressed by the key's ABSENCE. */
+export declare function setFanOut(step: FlowStep, mode: FanOutMode): FlowStep;
+/** Card-badge wording: how many next steps run, and in which mode. */
+export declare function fanOutLabel(count: number, mode: FanOutMode): string;

package/dist/flow-types.d.ts

@@ -0,0 +1,356 @@
+import { EdgeRunState } from './run-visuals.ts';
+import { ActionParam } from './types.ts';
+export interface FlowStep {
+    id: string;
+    uses: {
+        app: string;
+        action: string;
+        connection?: string | null;
+    };
+    /**
+     * Declared connection-port cardinality for this step (see core
+     * `rfcs/node-types.md` · Ports & cardinality). Omitted fields fall through field-wise to the catalog action, the internal def, then `{ in: 1, out: "many" }`.
+     * A persisted value wins over the node's default — `in > 1` opts the step into
+     * accepting multiple inbound edges (e.g. a flow-control aggregator joining
+     * several upstream branches).
+     */
+    ports?: PortsDecl;
+    with?: Record<string, unknown>;
+    retry?: {
+        maxAttempts: number;
+        backoff?: "fixed" | "exponential";
+        delayMs?: number;
+    };
+    /**
+     * What to do when this step errors:
+     * - `fail` — stop the run (default)
+     * - `continue` — swallow the error and keep going
+     * - `continue-record` — keep going, but record the error into the run's end state
+     */
+    onError?: "fail" | "continue" | "continue-record";
+    /** Free-form author notes for this step. Not executed. */
+    notes?: string;
+    /**
+     * How this step's outgoing edges in one lane run when there are two or more:
+     * `parallel` runs them concurrently; omitted (never written as `"sequential"`)
+     * runs them one after another.
+     */
+    fanOut?: "sequential" | "parallel";
+    /**
+     * Authoring-time canvas coordinate for this step, in this editor's own
+     * coordinate space (core `rfcs/workflow.md` · "Amendment — 2026-07-29:
+     * authoring presentation (`Step.position`, `Workflow.settings`)" — the spec
+     * pins no unit, origin or grid). Declarative only: the engine ignores it
+     * exactly as it ignores `notes`.
+     *
+     * **Omitted ⇒ the editor computes a layout** from the graph alone, exactly as
+     * before this field existed, so it is additive and backward-compatible.
+     * Partial coverage is valid: `workflowToFlow` places the steps that declare a
+     * `position` and computes a slot for the rest.
+     *
+     * Rename-safe by construction — the coordinate travels *with* the step, so
+     * there is no workflow-level `id → {x,y}` map to fix up on rename (D-I0-2).
+     *
+     * Mirrors `Step.position` in `@w6w/workflow-types` by hand — see the header
+     * note: these types are deliberately a structural subset with no compiler
+     * tie, so the spelling here must stay identical to the engine's.
+     */
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+export interface FlowEdge {
+    from: string;
+    to: string;
+    /**
+     * Which outcome of the `from` step this edge carries (core
+     * `rfcs/workflow.md` · "Amendment — 2026-07-29: failure-conditioned edges
+     * (`Edge.when`)"). **Omitted ⇒ `"success"`**, so every pre-existing edge is a
+     * success edge and needs no migration.
+     * - `"success"` — activates when `from` succeeds. Per the house
+     *   omit-the-default idiom it is written as **absent**, never spelled out:
+     *   this editor emits no `when` for a success edge, which is what keeps an
+     *   untouched definition byte-identical across a load/save cycle.
+     * - `"error"` — activates when `from` fails, and overrides that step's
+     *   `onError`.
+     *
+     * Mirrors `Edge.when` in `@w6w/workflow-types` by hand — see the header note:
+     * these types are deliberately a structural subset, with no compiler tie, so
+     * the spelling here must stay identical to the engine's.
+     */
+    when?: "success" | "error";
+}
+/**
+ * The React Flow presentation for an edge lane — **the one place** the error
+ * look is spelled out.
+ *
+ * Three callers need it and they run at different times: `workflowToFlow` stamps
+ * a *stored* edge on load, `setEdgeWhen` (`flow-connect.ts`) stamps an edge the
+ * author re-lanes **live**, before any save, and a live-run repaint effect
+ * (`WorkflowFlowEditor.tsx`, T1.1.1) restyles an edge as a run polls in. Spelled
+ * out more than once, the copies drift and a freshly marked error edge stops
+ * looking like a reloaded one. The className is what `styles.css`'s
+ * `.w6w-edge-error`/`.w6w-edge-taken`/`.w6w-edge-skipped` blocks paint from
+ * `--w6w-danger`/`--w6w-success`/`--w6w-muted`; no custom edge component is
+ * involved (D-T1-7).
+ *
+ * `runState` (T1.1.1) is the edge's OWN taken/skipped verdict (see
+ * `run-visuals.ts`'s `edgeRunState`) — omitted (or `undefined`) when there is no
+ * run in progress, or the run hasn't decided this edge's fate yet, in which case
+ * this returns exactly what it always has. `workflowToFlow`'s and `setEdgeWhen`'s
+ * call sites deliberately never have a live run's state available (a *stored*
+ * load and a live *re-lane* are never mid-run), so both pass no `runState` at
+ * all — only the new repaint-effect call site does.
+ *
+ * A `"success"`/absent lane with no `runState` returns an **empty object** — not
+ * `{ className: "" }` — so an untouched success edge carries neither key and a
+ * definition round-trips unchanged. That makes it a trap for a *re-laning*
+ * caller: spreading `{}` over an edge that already carries the error class
+ * leaves the class in place, so `setEdgeWhen` assigns both keys explicitly
+ * rather than spreading.
+ */
+export declare function edgeVisuals(when: "success" | "error" | undefined, runState?: EdgeRunState): {
+    className?: string;
+    label?: string;
+};
+/**
+ * The React Flow handle id a step/control node's **error exit port** carries
+ * (T1.1.1). Internal to `@w6w/ui` — not re-exported from `flow.ts` / `index.ts`
+ * (D-P2), since no consumer outside this package needs it.
+ */
+export declare const ERROR_SOURCE_HANDLE = "out-error";
+/**
+ * The `sourceHandle` a minted/re-laned/loaded edge carries for a given lane —
+ * the inverse of {@link laneForSourceHandle}. `undefined` for `"success"`/
+ * absent is **load-bearing, not stylistic**: React Flow anchors a handle-less
+ * edge to the node's sole *unnamed* handle, which is the exit every
+ * already-saved workflow's edges implicitly use. An empty string would not do
+ * this — an empty string is a real, if degenerate, handle id.
+ */
+export declare function sourceHandleForLane(when: "success" | "error" | undefined): string | undefined;
+/**
+ * The lane a drag started from, read off the handle id React Flow reports.
+ * **The one canonicalisation point** every minting/re-laning site calls
+ * (`onConnect`, `onConnectEnd`) so the handle-id spelling is decided once and
+ * both drag gestures provably agree — two inline comparisons is the shape
+ * where one gesture silently drifts. Exactly {@link ERROR_SOURCE_HANDLE} is
+ * `"error"`; everything else — a near-miss id, `null`, `undefined` — is
+ * `"success"`.
+ */
+export declare function laneForSourceHandle(handleId: string | null | undefined): "success" | "error";
+export interface FlowWorkflow {
+    manifestVersion: string;
+    id: string;
+    name: string;
+    displayName?: string;
+    description?: string;
+    variables?: Array<{
+        key: string;
+        type?: string;
+        required?: boolean;
+        default?: unknown;
+    }>;
+    steps: FlowStep[];
+    edges?: FlowEdge[];
+    /**
+     * Authoring-time presentation and preferences for this workflow (core
+     * `rfcs/workflow.md` · "Amendment — 2026-07-29: authoring presentation
+     * (`Step.position`, `Workflow.settings`)"). Declarative only — the engine
+     * ignores it, exactly like `FlowStep.notes` and `FlowStep.position`.
+     * `viewport` sits *inside* `settings` deliberately, so exactly one new
+     * top-level key enters the portable workflow document. `settings` is itself
+     * optional; when the object is absent every member below still takes its own
+     * default.
+     *
+     * ⚠️ **`autoSave` and `savePosition` default to `true` when omitted.** That is
+     * *deliberately unlike* the `ports`/`onError` rule ("omitted reproduces the
+     * status quo") — here it does not. Read them as `?? true` / `!== false`, never
+     * `?? false` and never `=== true`. The consequence, stated plainly: **a
+     * workflow that has never been saved by the new editor starts persisting step
+     * coordinates the first time it is saved.** That is intended (the product
+     * requires both features on by default); only an explicit `false` turns one
+     * off.
+     *
+     * HITL-6 asked whether a workflow's arrangement and its auto-save preference
+     * belong to *the workflow* or to *the person looking at it*; the amendment
+     * takes the **workflow** answer, so everyone who opens a workflow sees the
+     * same arrangement. HITL-6 is still open — a viewer-owned answer would move
+     * these fields out of the document and re-contract this shape.
+     *
+     * Mirrors `Workflow.settings` in `@w6w/workflow-types` by hand (structural
+     * subset, no compiler tie — the spelling must stay identical).
+     */
+    settings?: {
+        /**
+         * Whether an authoring tool persists edits without an explicit save action.
+         * Omitted ⇒ **true** — auto-save is ON. Not read by this module; the editor
+         * and its host own it (T3.3.2 / T4.1.x).
+         */
+        autoSave?: boolean;
+        /**
+         * Whether an authoring tool persists step coordinates (`FlowStep.position`)
+         * and `settings.viewport` when it saves. Omitted ⇒ **true** — positions ARE
+         * persisted. When explicitly `false`, `flowToWorkflow` writes no `position`;
+         * any value already stored is **left as it is, never erased**.
+         */
+        savePosition?: boolean;
+        /**
+         * The camera position the author last left the canvas at, so reopening the
+         * workflow restores the view. **No default** — a workflow with no `viewport`
+         * opens at whatever view the editor computes, exactly as today. Written by
+         * the component (T3.3.2), not by `flowToWorkflow`, whose signature cannot
+         * see a viewport.
+         */
+        viewport?: {
+            x: number;
+            y: number;
+            zoom: number;
+        };
+    };
+}
+/** Reserved namespace for internal pseudo-apps. */
+export declare const INTERNAL_APP_PREFIX = "@w6w/";
+/** Engine-native flow control (if/foreach/parallel/wait). */
+export declare const CONTROL_APP = "@w6w/control";
+/** Host-run inline JS. */
+export declare const SCRIPT_APP = "@w6w/script";
+/** Host-run typed key/value data. */
+export declare const DATA_APP = "@w6w/data";
+/** The workflow's entry/trigger node. */
+export declare const TRIGGER_APP = "@w6w/trigger";
+/** Host-run outbound HTTP(S) request. */
+export declare const HTTP_APP = "@w6w/http";
+/** Inbound HTTP(S) webhook trigger (entry node; provisions a receive URL). */
+export declare const WEBHOOK_APP = "@w6w/webhook";
+/** Time-based scheduler trigger (entry node; fires the workflow on a schedule). */
+export declare const SCHEDULER_APP = "@w6w/scheduler";
+/** "Respond to Webhook" — shapes the HTTP response for `responseMode: responseNode`. */
+export declare const RESPOND_APP = "@w6w/respond";
+/**
+ * Sub-workflow / Function caller (core rfcs/node-types.md · F-3). The host runs
+ * this node itself: it resolves `with.target` to a project-scoped `CallableRef` (a
+ * Function or a Workflow) and invokes it through `ctx.invokeCallable`, honoring
+ * the per-node `with.wait` flag. The engine never loads the target.
+ */
+export declare const CALL_APP = "@w6w/call";
+/**
+ * Read a stored JSON document by key (core rfcs/node-types.md · F-3 amendment,
+ * "Reserved internal pseudo-app"). Host node: `runInternalNode` short-circuits
+ * this id before the registry loads a module — the run's own project is bound
+ * host-side, so there is no `project` param (C-6).
+ */
+export declare const DOCUMENT_APP = "@w6w/document";
+/**
+ * Compile a Handlebars `template` string against a resolved `values` object
+ * (core rfcs/node-types.md · F-3 amendment, "the `@w6w/template` host node").
+ * Host node: `runInternalNode` short-circuits this id before the registry
+ * loads a module — it needs no privileged host resource (no DB, no
+ * tenant/project scope), and runs host-side only because the template
+ * compiles to a JS function, the same risk shape `@w6w/script` has.
+ */
+export declare const TEMPLATE_APP = "@w6w/template";
+/** True when `app` is a reserved internal pseudo-app id (`@w6w/*`). */
+export declare function isInternalApp(app: string): boolean;
+/** True when a node is an engine-native flow-control node (can't run standalone). */
+export declare function isControlApp(app: string): boolean;
+/**
+ * Whether a step is an entry/trigger node — the one predicate, shared by the
+ * step editor's Test tab and the canvas ▶ collect phase. A trigger's configured
+ * `fields` are *definitions*, so both surfaces project them into a fillable form
+ * and send the filled values as `{ input }` rather than running the raw config.
+ */
+export declare function isTriggerApp(app: string): boolean;
+/** A palette entry for an internal node: its id, label, group, and config schema. */
+export interface InternalNodeDef {
+    app: string;
+    action: string;
+    label: string;
+    /**
+     * Human display name (mirrors an app's `displayName`). Defaults conceptually
+     * to `label`; kept explicit so internal pseudo-apps carry the same info an app
+     * does. Shown wherever an app's name would be.
+     */
+    displayName: string;
+    group: "trigger" | "control" | "compute" | "request";
+    /**
+     * Inline SVG *inner* markup (paths / circles / polylines) for this primitive's
+     * glyph — internal pseudo-apps have no icon asset dir, so the glyph is bundled
+     * here. Drawn on a 24×24 `viewBox`, stroked with `currentColor` (theme-aware),
+     * so both app nodes and internal nodes display a consistent icon on the canvas.
+     */
+    icon: string;
+    /**
+     * Hidden from every palette list but still resolvable by `internalNodeDef`, so
+     * a workflow already using the node keeps rendering and editing.
+     */
+    hidden?: boolean;
+    /**
+     * Connection ports: how many inbound (entry) and outbound (exit) connections
+     * this node accepts. A port is the ability to receive/emit a connection —
+     * rendered as a React Flow Handle. Defaults to one of each (`{ in: 1, out: 1 }`)
+     * when omitted; a trigger overrides to `{ in: 0, out: 1 }` (nothing flows into
+     * the entry node). Fixed for now — not user-editable.
+     */
+    ports?: PortsDecl;
+    /** Config schema (same `ActionParam[]` shape apps declare) rendered by ParamsForm. */
+    params: ActionParam[];
+    /**
+     * This node's static output field keys, when its shape is known ahead of any
+     * run — same shape as `ExpressionStepSource.outputs`
+     * (`components/ExpressionOptions.tsx`), fed verbatim by `projectStepSources`
+     * (`step-preview-state.ts`) so the expression rail can offer
+     * `steps.<id>.output.<key>` for a step using this node. Omitted (not `[]`)
+     * when the node's output is not statically knowable (e.g. `@w6w/document ·
+     * get`, whose shape is whatever JSON the referenced document holds).
+     */
+    output?: {
+        key: string;
+        label?: string;
+    }[];
+}
+/** A declared port count: a number, or `"many"` (unbounded). */
+export type PortCount = number | "many";
+/** A (possibly partial) port declaration, as an author / catalog / def writes it. */
+export interface PortsDecl {
+    in?: PortCount;
+    out?: PortCount;
+}
+/** Resolved inbound (entry) and outbound (exit) connection-port counts; `"many"` is `Infinity`. */
+export interface NodePorts {
+    in: number;
+    out: number;
+}
+/** The default a node gets when nothing declares ports: 1 in, unbounded out. */
+export declare const DEFAULT_NODE_PORTS: NodePorts;
+/** Field-wise resolution: first declared value per field wins, else the default. */
+export declare function resolvePorts(...layers: (PortsDecl | undefined)[]): NodePorts;
+/** Catalog lookup of an action's declared ports, passed as an argument (never stamped on a step). */
+export type PortsLookup = (app: string, action: string) => PortsDecl | undefined;
+/**
+ * Resolve a node's connection ports from its internal def only (triggers drop the
+ * entry port); everything else gets the default.
+ */
+export declare function nodePorts(app: string, action: string): NodePorts;
+/**
+ * Resolve a *step's* ports field-wise: `step.ports` → catalog action (via `lookup`)
+ * → internal def → default `{ in: 1, out: Infinity }`. The catalog is read through
+ * the `lookup` argument and never written onto the step, so it never serializes.
+ */
+export declare function nodePortsForStep(step: FlowStep, lookup?: PortsLookup): NodePorts;
+/** The built-in internal nodes, in palette order. */
+export declare const INTERNAL_NODES: InternalNodeDef[];
+/** Look up an internal node's definition by its (app, action) pair. */
+export declare function internalNodeDef(app: string, action: string): InternalNodeDef | undefined;
+/** The label the editor shows for an internal node (falls back to the action key). */
+export declare function internalNodeLabel(app: string, action: string): string;
+/**
+ * The inline SVG glyph markup for an internal node (empty when unknown). Lets a
+ * node retrieve its icon from just the (app, action) pair — same lookup path as
+ * `internalNodeLabel`.
+ */
+export declare function internalNodeIcon(app: string, action: string): string;
+/** The config schema for an internal node (empty when unknown). */
+export declare function internalNodeParams(app: string, action: string): ActionParam[];
+/** Build an internal node's default `with` from its param schema defaults. */
+export declare function internalNodeDefaults(app: string, action: string): Record<string, unknown>;