@w6w/embed 0.0.0-stage → 0.1.1

package/dist/chrome/JsonToggle.d.ts

@@ -0,0 +1,51 @@
+export type JsonToggleMode = "synced" | "disconnected";
+/** The header icon button: `IconButton` with the set's `json` glyph — the
+ *  curly-brace icon, distinct from the `code` `</>` "Call from code" icon
+ *  beside it, so the two stop reading as the same button. The local
+ *  `JsonIcon` SVG this file used to carry is now `icon="json"` in the shared
+ *  set. */
+export declare function JsonToggleButton(props: {
+    onClick: () => void;
+}): import("react").JSX.Element;
+export interface JsonToggleProps {
+    /** Parent-owned; render nothing when false. */
+    open: boolean;
+    onClose: () => void;
+    /** Modal title. */
+    title: string;
+    mode: JsonToggleMode;
+    /** Parent-owned text; the component keeps NO copy of it. */
+    value: string;
+    /** Every JsonEditor change, both modes. */
+    onChange: (text: string) => void;
+    /** JsonEditor's, error ?? null. */
+    onValidityChange?: (v: {
+        valid: boolean;
+        error: string | null;
+    }) => void;
+    /** When non-null: "Invalid JSON — {invalidReason}" (Workflow's existing line). */
+    invalidReason?: string | null;
+    /** Evaluated on `value` every render; non-null → shown in
+     *  <p className="muted small" data-testid="json-toggle-reason">. */
+    guard?: (text: string) => string | null;
+    /** disconnected only. */
+    onSave?: () => void;
+    /** disconnected only. */
+    saving?: boolean;
+    /** disconnected only; rendered as <div className="error"> inside the dialog. */
+    error?: string | null;
+    /** JsonEditor aria-label. */
+    editorLabel: string;
+}
+/**
+ * The JSON⇄editor toggle's chrome — the header icon button's dialog, extracted
+ * verbatim from `WorkflowsPage.tsx`'s raw-JSON modal (T2.1.1 D-2) so a second
+ * host can reuse it in `mode="disconnected"` (T2.1.2). Wraps `@w6w/ui`'s
+ * `JsonEditor` and studio's own `Modal` (not `@w6w/ui`'s) — both existing
+ * JSON-toggle-shaped precedents in this repo use studio's `Modal`.
+ *
+ * The component holds NO copy of `value`: every render shows exactly what the
+ * parent hands it, which is what keeps a reopened dialog free of a stale
+ * snapshot from the previous time it was open.
+ */
+export declare function JsonToggle(props: JsonToggleProps): JSX.Element | null;

package/dist/chrome/Modal.d.ts

@@ -0,0 +1,20 @@
+interface ModalProps {
+    title: string;
+    onClose: () => void;
+    children: React.ReactNode;
+    /** Widen the dialog (e.g. for a JSON editor that needs room). */
+    wide?: boolean;
+    /** Widen further still (e.g. for the plan comparison grid). */
+    xl?: boolean;
+    /** Trailing control on the title row (e.g. a close `IconButton`). Given,
+     *  the title and this node share one `.modal-head` row; absent, the title
+     *  renders as a direct child exactly as before. */
+    headerRight?: React.ReactNode;
+}
+/**
+ * Small dialog modal. Built on the native <dialog> element so it gets focus
+ * trapping, Esc-dismiss, and accessibility semantics for free. A button
+ * positioned over the backdrop catches outside-clicks to close.
+ */
+export declare function Modal({ title, onClose, children, wide, xl, headerRight, }: ModalProps): import("react").JSX.Element;
+export {};

package/dist/chrome/RightRail.d.ts

@@ -0,0 +1,24 @@
+import { ComponentType } from 'react';
+import { WorkspaceCallable } from './workspace.tsx';
+export interface RailTool {
+    /** Stable; used as the persisted `activeTool`. */
+    id: string;
+    /** Strip tooltip + panel heading. */
+    title: string;
+    /** The strip glyph, as a component — built-in tools render a 16×16 `<Icon name="…" />`
+     *  from `@w6w/ui`'s shared set; a tool may bring its own glyph instead. A component,
+     *  not an `IconName`, so this seam never narrows to the shared set. */
+    Icon: ComponentType;
+    isAvailable(ctx: WorkspaceCallable): boolean;
+    /** Panel renders its own heading when it includes section actions. */
+    rendersHeading?: boolean;
+    Panel: ComponentType<{
+        ctx: WorkspaceCallable;
+    }>;
+}
+/** `storageKey === null`: no key to persist under yet (pin 12) — the strip renders closed and
+ * nothing is written to localStorage. No available tool ⇒ no rail element at all (C/D-C3). */
+export declare function RightRail({ tools, storageKey, }: {
+    tools: readonly RailTool[];
+    storageKey: string | null;
+}): import("react").JSX.Element | null;

package/dist/chrome/TagEditor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A chip input for a workflow's free-form tags: type text, `,` commits the
+ * typed value as a chip (or paste a whole comma-separated list to commit
+ * several at once — `../lib/tag-editor.ts`'s `commitTag`), each chip carries
+ * an `×` to remove it, and a still-typable tail follows the chips — one
+ * control, not a stacked input-above-list.
+ *
+ * Built fresh (T2.2.1) rather than extended from the retiring
+ * `WorkflowsPage.tsx` tags-editing modal: that component was a submit-button
+ * "Add" form with its own inline add/remove branching, a different
+ * interaction shape from a comma-commits chip editor. The shared data
+ * contract (trim, dedupe-on-add, drop empties) now lives in
+ * `../lib/tag-editor.ts`'s
+ * `commitTag`/`removeTag`, so this component holds no branching of its own —
+ * it only calls them and renders the result. Controlled, mirroring
+ * `InputListEditor.tsx`'s shape: the caller owns `tags`, this component owns
+ * only the not-yet-committed typed tail.
+ */
+export interface TagEditorProps {
+    tags: string[];
+    onChange: (next: string[]) => void;
+}
+export declare function TagEditor({ tags, onChange }: TagEditorProps): import("react").JSX.Element;

package/dist/chrome/VersionHistoryModal.d.ts

@@ -0,0 +1,38 @@
+import { VersionsKind } from '@w6w/embed/repos';
+/**
+ * Version viewer for Function/Workflow/Endpoint (T3.1.1, extended by T5.3.1): one
+ * kind-parametrized component, mirroring `ImportSpecModal.tsx:12-46`'s established shape (a
+ * `kind` prop plus per-kind `TESTIDS`, one component mounted from more than one place rather than
+ * three near-copies). This project mounts it from `SettingsTool.tsx` only — the component
+ * boundary exists so a second mount point later costs one line.
+ *
+ * Renders the version's own read-only definition through the same two primitives
+ * `SettingsTool.tsx`'s existing Export modal already uses — the studio-local `Modal` and
+ * `@w6w/ui`'s `CodeBlock` — plus, since T5.3.1, two live actions:
+ *
+ * - **"Revert to this version"** — confirmed via the studio-local `ConfirmModal` (P2-D4:
+ *   `./ConfirmModal.tsx`, never `@w6w/ui`'s), rendered as a SIBLING of `<Modal>` in
+ *   the returned fragment, never nested inside it. Overwrites the LIVE resource's `definition`
+ *   with this version's content, preserving its `key`/address (HITL-4's pinned default).
+ * - **"Invoke this version"** — one click, NO confirm (ruling #12: an invoke is a call, not a
+ *   write to the resource, and the LIVE invoke action it mirrors carries no confirm either). Runs
+ *   this version's own archived definition, never the live one, and renders the response body
+ *   inline via `CodeBlock`, or a failure inline via the `ApiError` idiom (never a thrown error, a
+ *   blank modal, or a browser dialog).
+ *
+ * Both actions read `kind`/`id`/`versionNumber` from props, and both mutations are fresh
+ * `useMutation` instances scoped to this component instance — since `SettingsTool.tsx`'s
+ * `openVersion` gate fully unmounts/remounts this component per version rather than swapping
+ * props on a surviving instance, any prior invoke result or error is gone the moment a different
+ * version is opened.
+ *
+ * Amendments #5/#6 (project.md, Phase 2) supersede the earlier pin that made both of the above
+ * out of scope (HITL-2's "invocation always runs the live definition"; Amendment #5's "restore is
+ * out of scope, not even a disabled button").
+ */
+export declare function VersionHistoryModal(props: {
+    kind: VersionsKind;
+    id: string;
+    versionNumber: number;
+    onClose: () => void;
+}): import("react").JSX.Element;

package/dist/chrome/history-open-run.d.ts

@@ -0,0 +1,7 @@
+import { CallableKind, ExecutionSummary } from '../repos/index.ts';
+/**
+ * The open-in-editor decision for a History view: only a workflow run has an editor to open, and
+ * only when the host supplied `onOpenRun`. The handler closes the modal BEFORE handing the run id
+ * to the host (the host's navigation then lands on an unobscured page).
+ */
+export declare function historyOpenRun(kind: CallableKind, onOpenRun: ((runId: string) => void) | undefined, onClose: () => void): ((execution: ExecutionSummary) => void) | undefined;

package/dist/chrome/index.d.ts

@@ -0,0 +1,36 @@
+export { CallableSettingsModal } from './CallableSettingsModal.tsx';
+export { CallFromCodeBody, CallFromCodeButton, SNIPPET_TABS, snippetTabsFor, } from './CallFromCodeButton.tsx';
+export type { SnippetTabId } from './CallFromCodeButton.tsx';
+export { ConfirmModal } from './ConfirmModal.tsx';
+export { DangerZone } from './DangerZone.tsx';
+export type { DangerZoneProps } from './DangerZone.tsx';
+export { ExecutionProfileHeader } from './ExecutionProfileHeader.tsx';
+export type { EditableProfileTitle, ExecutionProfileHeaderProps, ExecutionProfileTitle, ReadOnlyProfileTitle, } from './ExecutionProfileHeader.tsx';
+export { JsonToggle, JsonToggleButton } from './JsonToggle.tsx';
+export type { JsonToggleMode, JsonToggleProps } from './JsonToggle.tsx';
+export { Modal } from './Modal.tsx';
+export { TagEditor } from './TagEditor.tsx';
+export type { TagEditorProps } from './TagEditor.tsx';
+export { HistoryButton } from './HistoryButton.tsx';
+export type { HistoryButtonProps } from './HistoryButton.tsx';
+export { HistoryModal } from './HistoryModal.tsx';
+export type { HistoryModalProps } from './HistoryModal.tsx';
+export { HistoryView } from './HistoryView.tsx';
+export { historyOpenRun } from './history-open-run.ts';
+export { ImportSpecModal } from './ImportSpecModal.tsx';
+export type { ImportSpecModalProps } from './ImportSpecModal.tsx';
+export { VersionHistoryModal } from './VersionHistoryModal.tsx';
+export { RightRail } from './RightRail.tsx';
+export type { RailTool } from './RightRail.tsx';
+export { WorkspaceProvider, useWorkspace, useWorkspaceCallable } from './workspace.tsx';
+export type { WorkspaceCallable, WorkspaceKind } from './workspace.tsx';
+export { RailEnvProvider, useRailEnv } from '../rail/rail-env.tsx';
+export type { RailEnv, RailNavigation } from '../rail/rail-env.tsx';
+export { type SettingsOpenState, WorkflowSettingsPanel, settingsTool, } from '../rail/SettingsTool.tsx';
+export { MetadataSection, SettingsDangerZone, SettingsHeading, SpecActionsTrigger, SpecChooserModal, VersionListModal, VersionSection, } from '../rail/settings-sections.tsx';
+export type { SettingsKind } from '../rail/settings-sections.tsx';
+export { codeTool } from '../rail/CodeTool.tsx';
+export { ErrorHandlerSection, errorHandlingTool } from '../rail/ErrorHandlingTool.tsx';
+export type { ErrorHandlerKind, ErrorHandlerSectionProps } from '../rail/ErrorHandlingTool.tsx';
+export { ProjectExpressionScope, useProjectExpressionOptions } from '../rail/ExpressionScope.tsx';
+export { editorRailTools } from '../rail/editor-tools.ts';

package/dist/chrome/workspace.d.ts

@@ -0,0 +1,67 @@
+import { CallablePolicy, SnippetInput, TriggerPreview } from '@w6w/embed/lib';
+import { ReactNode } from 'react';
+/**
+ * T2.1.2: widened to a discriminated union, one arm per kind — every new
+ * field OPTIONAL, no new required member, so every existing producer keeps
+ * compiling and behaving identically (`{kind, id}` alone still satisfies any
+ * arm). The extra fields are what `CodeTool`'s snippet panel needs per kind
+ * (mirrors `lib/sdk-snippets.ts`'s `SnippetCallable`, field-for-field where
+ * the names match — see `lib/code-rail.ts`'s `toSnippetCallable` for the one
+ * field that doesn't, `label` -> `displayName`).
+ */
+export type WorkspaceCallable = {
+    kind: "function";
+    id: string;
+    label?: string;
+    key?: string;
+    inputs?: readonly SnippetInput[];
+    alias?: string;
+} | {
+    kind: "endpoint";
+    id: string;
+    label?: string;
+    key?: string;
+    invokeUrl?: string;
+    invokeUrlByKey?: string;
+    urlForm?: "id" | "key";
+    alias?: string;
+    inputs?: readonly SnippetInput[];
+} | {
+    kind: "workflow";
+    id: string;
+    label?: string;
+    key?: string;
+    triggers?: TriggerPreview[];
+    /**
+     * The workflow's run-level error policy, and the writer that applies it
+     * (core Workflow RFC — *Amendment — 2026-08-21: the run-level error
+     * handler*). Published ONLY by the page that owns the definition buffer
+     * — the canvas editor — so the rail's Error handling tool edits the same
+     * text the editor is about to save instead of racing it over the wire.
+     * `ErrorHandlingTool` is the only reader; see `lib/settings-rail.ts`'s
+     * `isAvailable` for why the tool hides itself when they are absent.
+     *
+     * ⚠️ `onPolicyChange` MUST be referentially stable across renders (a
+     * `useCallback` reading through a ref). `useWorkspace` keys its publish
+     * effect on `JSON.stringify(resource)`, which drops functions — so the
+     * stored callback is whichever one was current when some OTHER field
+     * last changed, and a closure that captured stale editor state would
+     * write stale bytes.
+     */
+    policy?: CallablePolicy;
+    onPolicyChange?: (policy: CallablePolicy) => void;
+} | {
+    kind: "connection";
+    id: string;
+    label?: string;
+} | null;
+/** Derived from {@link WorkspaceCallable}, never redeclared — the arm a
+ * `RailTool.isAvailable`/route wrapper narrows on. */
+export type WorkspaceKind = Exclude<WorkspaceCallable, null>["kind"];
+export declare function WorkspaceProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Publisher. Compute during render, effect-write, clear on unmount. */
+export declare function useWorkspace(resource: WorkspaceCallable): void;
+/** Reader — used by the rail and by every tool `Panel`. Throws outside the provider. */
+export declare function useWorkspaceCallable(): WorkspaceCallable;

package/dist/client-context-CX61Bgw-.js

@@ -0,0 +1,16 @@
+import { createElement as n, useContext as r, createContext as i } from "react";
+const t = i(null);
+function l(e) {
+  return n(t.Provider, { value: e.client }, e.children);
+}
+function u() {
+  const e = r(t);
+  if (e === null)
+    throw new Error("useEmbedClient must be used inside an <EmbedClientProvider>.");
+  return e;
+}
+export {
+  l as E,
+  u
+};
+//# sourceMappingURL=client-context-CX61Bgw-.js.map

package/dist/client-context-CX61Bgw-.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-context-CX61Bgw-.js","sources":["../src/draft/client-context.ts"],"sourcesContent":["/**\n * The embed-owned client context for the headless draft hook.\n *\n * The hook talks to the server through the SDK `W6WClient` (`workflows.get` / `workflows.update`),\n * never through `@w6w/ui`'s `W6WApi` — that interface has no save member and is not extended here.\n * `W6WEmbedProvider` supplies the client from `useW6WClient()`; Studio supplies its own from\n * `useApiClient()`. A plain `.ts` module (no JSX) so Node's type stripping can load it.\n */\nimport type { W6WClient } from \"@w6w/sdk\";\nimport { type ReactNode, createContext, createElement, useContext } from \"react\";\n\nconst EmbedClientContext = createContext<W6WClient | null>(null);\n\nexport function EmbedClientProvider(p: { client: W6WClient; children?: ReactNode }) {\n  return createElement(EmbedClientContext.Provider, { value: p.client }, p.children);\n}\n\n/** The SDK client for the nearest {@link EmbedClientProvider}. Throws outside one. */\nexport function useEmbedClient(): W6WClient {\n  const client = useContext(EmbedClientContext);\n  if (client === null) {\n    throw new Error(\"useEmbedClient must be used inside an <EmbedClientProvider>.\");\n  }\n  return client;\n}\n"],"names":["EmbedClientContext","createContext","EmbedClientProvider","p","createElement","useEmbedClient","client","useContext"],"mappings":";AAWA,MAAMA,IAAqBC,EAAgC,IAAI;AAExD,SAASC,EAAoBC,GAAgD;AAClF,SAAOC,EAAcJ,EAAmB,UAAU,EAAE,OAAOG,EAAE,OAAA,GAAUA,EAAE,QAAQ;AACnF;AAGO,SAASE,IAA4B;AAC1C,QAAMC,IAASC,EAAWP,CAAkB;AAC5C,MAAIM,MAAW;AACb,UAAM,IAAI,MAAM,8DAA8D;AAEhF,SAAOA;AACT;"}

package/dist/draft/autosave-flush.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Flush a pending debounced write before the page actually goes away.
+ *
+ * ## Why this exists at all
+ *
+ * `autosave.ts`'s `createAutoSaver` coalesces edits behind an `AUTOSAVE_DEBOUNCE_MS`
+ * (1200ms) window timer (`autosave.ts:45`) — a `push()` inside that window never writes,
+ * it only re-arms the timer. Nothing in `autosave.ts` itself ever
+ * flushes on navigation, so a canvas pan (or any other edit) that lands less than the
+ * window's width before a refresh is lost: the tab is gone before the timer fires (I-3).
+ * A zoom gesture "works" only by accident — it takes longer than the window to finish.
+ *
+ * This module does not touch the debounce, the `AutoSaver` interface, or its save
+ * decision (`fire()`'s `enabled`/`canSave`/dedup checks in `autosave.ts:98-107` already
+ * apply to a flush exactly as they do to a natural fire) — it only decides WHEN to call
+ * the `flush()` the caller already owns.
+ *
+ * ## The rule
+ *
+ * Two signals, both wired here, neither replacing the other:
+ *
+ * - `visibilitychange` with `document.visibilityState === "hidden"` is the PRIMARY path.
+ *   It fires on tab close, tab switch, and navigation alike, and — unlike `beforeunload`
+ *   — a listener registered on it is not itself a signal to the browser that the page is
+ *   unusual, so it carries no risk of suppressing the back/forward cache.
+ * - `beforeunload` is the BELT, wired unconditionally (it does not check
+ *   `visibilityState`): some navigations do not reliably fire `visibilitychange` first in
+ *   every browser, so this is a second chance at the same flush.
+ *
+ * **Known, accepted limit — do not claim this race is provably closed.** A `fetch`
+ * kicked off from either handler is not guaranteed to complete before the browser
+ * actually tears the page down (`beforeunload` in particular has no such guarantee in
+ * every browser). `visibilitychange`+`hidden` fires earlier in the common
+ * switch-tab/navigate-away cases, which is why it is the primary path and `beforeunload`
+ * only the belt — this module narrows the loss window, it does not eliminate it.
+ *
+ * ## Why the parameters are typed the way they are
+ *
+ * `WindowLike`/`DocumentLike` below name only the handful of members this module
+ * actually calls. That is what lets `node --test` — which cannot load `.tsx`, the same
+ * reason `autosave.ts` itself lives in a plain `.ts` module (`autosave.ts:37-41`) — pass
+ * a plain fake object in tests, while `tsc -b --noEmit` still proves the real
+ * `window`/`document` satisfy the same shape at the call site in `WorkflowsPage.tsx`.
+ */
+/** The subset of `Window` this module needs: register/unregister `beforeunload`. */
+export interface WindowLike {
+    addEventListener(type: "beforeunload", listener: () => void): void;
+    removeEventListener(type: "beforeunload", listener: () => void): void;
+}
+/**
+ * The subset of `Document` this module needs: register/unregister `visibilitychange`,
+ * and read the visibility state the moment the event fires.
+ */
+export interface DocumentLike {
+    readonly visibilityState: string;
+    addEventListener(type: "visibilitychange", listener: () => void): void;
+    removeEventListener(type: "visibilitychange", listener: () => void): void;
+}
+/**
+ * Register both listeners; call `flush` when the page is going away. Returns a cleanup
+ * that removes both — callers wire this straight into a `useEffect`'s return.
+ */
+export declare function registerFlushOnHide(windowTarget: WindowLike, documentTarget: DocumentLike, flush: () => void): () => void;

package/dist/draft/autosave.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The debouncing, coalescing, payload-deduplicated saver behind auto-save.
+ *
+ * ## Why this exists at all
+ *
+ * Every edit on the canvas replaces the whole definition: a single keystroke in a
+ * step's param form travels `ParamsForm onChange → commit → StepEditModal onChange
+ * → updateStep → emitChange → onChange(flowToWorkflow(…))` and lands in
+ * `WorkflowsPage` as `setJson(JSON.stringify(next, null, 2))`. So a naive
+ * `useEffect(() => save(), [json])` is **one `POST /workflows` per character
+ * typed**. This module is the thing that stands between those two facts.
+ *
+ * ## The rule
+ *
+ * **Trailing debounce, single pending entry, decided at fire time.**
+ *
+ * - `push` never writes. It replaces the one pending entry and restarts a
+ *   `delayMs` window. N pushes inside one window therefore produce exactly ONE
+ *   `save`, carrying the LAST payload.
+ * - The decision to save is taken when the timer fires, not when the payload was
+ *   pushed. That is what makes a transiently-invalid edit harmless: while the JSON
+ *   modal round-trips text through `JsonEditor`, `canSave` flickers false
+ *   mid-typing, and a push-time decision would discard the save the author is
+ *   waiting for. An invalid push still re-arms the window; the next valid one wins.
+ * - A payload equal to the last saved one is dropped without a request. The
+ *   comparison is on the serialised JSON **text**, the same structural-equality
+ *   dirty signal the house already uses (`packages/ui/src/ActionTestForm.tsx`,
+ *   *"Compared by structural JSON so a load→edit→revert cycle clears it"*), which
+ *   is why an in-place mutation of some nested object can never fool it: nothing
+ *   here holds a reference to a live object across ticks.
+ *
+ * Deliberately absent: retry/backoff. On a failed save the host stops and shows
+ * the existing error surface; a background retry against a server that just
+ * refused is worse than a visible failure (and, with a stale-write conflict on
+ * screen, it would retry into the dialog the author is reading).
+ *
+ * It lives here rather than in `@w6w/ui` because `@w6w/ui` owns no workflow write
+ * at all — the canvas emits `onChange`, the host decides when to persist — and in
+ * a plain `.ts` module rather than in `WorkflowsPage.tsx` so it is executable:
+ * that file is JSX, which Node 24's type-stripping cannot parse, so nothing in it
+ * can be loaded by `node --test`. Same shape as `workflow-save.ts`.
+ */
+/** The debounce window. One quiet beat after the last keystroke, not per keystroke. */
+export declare const AUTOSAVE_DEBOUNCE_MS = 1200;
+export interface AutoSaverOpts {
+    /** May return a promise (awaited by `flush`); any other return value is ignored. */
+    save: (payload: string, ctx?: unknown) => unknown;
+    delayMs?: number;
+    /** Injectable for tests; defaults to the globals. */
+    setTimer?: (fn: () => void, ms: number) => number;
+    clearTimer?: (handle: number) => void;
+}
+export interface AutoSaver {
+    /** Consider a payload. (Re)starts the debounce window. */
+    push(payload: string, enabled: boolean, canSave: boolean, ctx?: unknown): void;
+    /**
+     * Fire the pending save now (the Save button). Resolves after the fired save settles
+     * (`Promise.resolve()` when nothing fired); rejects if the fired save rejects.
+     */
+    flush(): Promise<void>;
+    /** Drop any pending save without firing (unmount / workflow switch / stale conflict). */
+    cancel(): void;
+    /** This payload is now on the server. */
+    markSaved(payload: string): void;
+    /** Does `payload` diverge from the last-saved one? */
+    isDirty(payload: string): boolean;
+}
+export declare function createAutoSaver(opts: AutoSaverOpts): AutoSaver;

package/dist/draft/client-context.d.ts

@@ -0,0 +1,8 @@
+import { W6WClient } from '@w6w/sdk';
+import { ReactNode } from 'react';
+export declare function EmbedClientProvider(p: {
+    client: W6WClient;
+    children?: ReactNode;
+}): import('react').FunctionComponentElement<import('react').ProviderProps<W6WClient | null>>;
+/** The SDK client for the nearest {@link EmbedClientProvider}. Throws outside one. */
+export declare function useEmbedClient(): W6WClient;

package/dist/draft/draft-registry.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+export interface DraftRegistry {
+    /** Register a draft's flush. Returns the unregister function. */
+    register(flush: () => Promise<unknown>): () => void;
+    /** Await every registered flush, at most `timeoutMs` (default 5000). Never rejects. */
+    flushAll(timeoutMs?: number): Promise<void>;
+}
+export declare function createDraftRegistry(): DraftRegistry;
+export declare function DraftRegistryProvider(p: {
+    registry: DraftRegistry;
+    children?: ReactNode;
+}): import('react').FunctionComponentElement<import('react').ProviderProps<DraftRegistry | null>>;
+/** The nearest registry, or `null` when there is no provider (the hook then skips registering). */
+export declare function useDraftRegistry(): DraftRegistry | null;

package/dist/draft/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@w6w/embed/draft` — the headless draft lifecycle (debounced autosave, flush-on-hide, the
+ * workflow save precondition). No UI and no `@w6w/ui`: it imports only `react`,
+ * `@tanstack/react-query` and type-only `@w6w/sdk`, so a host can use it without the editor.
+ */
+export { AUTOSAVE_DEBOUNCE_MS, createAutoSaver } from './autosave.ts';
+export type { AutoSaver, AutoSaverOpts } from './autosave.ts';
+export { registerFlushOnHide } from './autosave-flush.ts';
+export type { DocumentLike, WindowLike } from './autosave-flush.ts';
+export { isStaleWrite, nextSaveToken } from './workflow-save.ts';
+export { EmbedClientProvider, useEmbedClient } from './client-context.ts';
+export { DraftRegistryProvider, createDraftRegistry, useDraftRegistry, } from './draft-registry.ts';
+export type { DraftRegistry } from './draft-registry.ts';
+export { useWorkflowDraft } from './use-workflow-draft.ts';
+export type { FlushOutcome, UseWorkflowDraftOptions, WorkflowDraft, } from './use-workflow-draft.ts';

package/dist/draft/use-workflow-draft.d.ts

@@ -0,0 +1,67 @@
+export type FlushOutcome = {
+    status: "clean";
+} | {
+    status: "saved";
+} | {
+    status: "blocked";
+    reason: string;
+} | {
+    status: "failed";
+    error: unknown;
+};
+export interface UseWorkflowDraftOptions {
+    /** `null` ⇒ idle (the hook stays mounted above an early return). */
+    workflowId: string | null;
+    /** REQUIRED to save; empty/absent ⇒ the save is refused and no request is sent. */
+    project: string | null | undefined;
+    /** Default true; a debounced save follows the last edit. */
+    autoSave?: boolean;
+    /** Injected busy probe (Studio: expression modal open). Gates AUTOMATIC saves only. */
+    canAutoSave?: () => boolean;
+    /** Injected key-edit guard: a reason blocks saving. */
+    saveGuard?: (parsed: unknown) => string | null;
+    /** Injected (B/D-3): reported as `publishBlockedReason`, not enforced by save. */
+    publishBlockedReason?: (parsed: unknown) => string | null;
+    /**
+     * Called exactly once when a handover (client/project change) or an identity switch
+     * (`flushAll`) drops a dirty buffer it could not save. `blocked`: the save was refused before a
+     * request (invalid text, no project, a guard, busy); `failed`: the request was sent or the row
+     * was stale and the save did not succeed. No UI here: the host decides what to show.
+     */
+    onDiscard?: (info: {
+        workflowId: string;
+        text: string;
+        reason: "blocked" | "failed";
+    }) => void;
+}
+export interface WorkflowDraft {
+    json: string;
+    setJson(next: string): void;
+    parsed: unknown | null;
+    syntaxError: string | null;
+    loading: boolean;
+    loadError: unknown | null;
+    dirty: boolean;
+    saving: boolean;
+    canSave: boolean;
+    saveBlockedReason: string | null;
+    stale: boolean;
+    error: unknown | null;
+    publishBlockedReason: string | null;
+    /** Push + fire now (Ctrl/Cmd+S, the Save button). */
+    saveNow(): void;
+    flush(): Promise<FlushOutcome>;
+    /** Flush, then run `action` only when the buffer is clean or just saved. */
+    flushThen<T>(action: () => Promise<T>): Promise<{
+        ok: true;
+        value: T;
+    } | {
+        ok: false;
+        outcome: FlushOutcome;
+    }>;
+    /** `setJson(next)` + an immediate save (the saveMeta / onPolicyChange paths). */
+    commit(next: string): Promise<FlushOutcome>;
+    /** 409 recovery: GET, replace the buffer and token, clear `stale`. */
+    reload(): Promise<void>;
+}
+export declare function useWorkflowDraft(o: UseWorkflowDraftOptions): WorkflowDraft;

package/dist/draft/workflow-save.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The two decisions behind the workflow save precondition (optimistic
+ * concurrency; server half in `packages/server` `packages/api/workflows.ts`).
+ *
+ * `POST /workflows` accepts an optional `x-w6w-if-unmodified-since` header
+ * carrying the exact ISO-8601 `updatedAt` the client last saw. If the stored row
+ * has moved on, the save is refused with **409 `workflow_stale`** instead of
+ * silently overwriting whoever saved in between.
+ *
+ * Both functions here are pure functions of their inputs, and they live in a
+ * `.ts` module rather than in `WorkflowsPage.tsx` so they are executable:
+ * `WorkflowsPage.tsx` is JSX, which Node 24's type-stripping cannot parse, so
+ * nothing in it can be loaded by `node --test`. Same shape as
+ * `src/lib/sdk-snippets.ts` + its `.test.ts`.
+ */
+/**
+ * Is this the one save failure an author can fix by reloading?
+ *
+ * Keyed on the error **code**, never on the HTTP status. The server answers 409
+ * for two completely different situations and only one of them is recoverable:
+ *
+ * - `workflow_stale` — your copy is out of date. Reload and re-save. ← this one
+ * - `workflow_conflict` — another `(tenant, subject)` owns that workflow id.
+ *   Reloading changes nothing; offering a reload here would be a dead end.
+ *
+ * Anything that carries no `code` (a thrown `TypeError`, a string, `null`) is
+ * not a server verdict at all, so it is not a stale write either.
+ *
+ * Duck-typed on the `code` property rather than `instanceof ApiError`: this module is
+ * headless and must not value-import the SDK, and two SDK copies would defeat `instanceof`.
+ */
+export declare function isStaleWrite(e: unknown): boolean;
+/**
+ * The precondition token to send with the NEXT save, given the token we sent
+ * with this one and the response that came back.
+ *
+ * The server rides `updatedAt` on both the `GET /workflows/:id` body and the
+ * `POST /workflows` 201, precisely so a client can advance without a re-GET.
+ *
+ * When the response carries no usable `updatedAt`, the answer is **`null`** (no
+ * precondition on the next save), never `prev`: `prev` is by then a value the
+ * server may already have moved past, so resending it would 409 forever with no
+ * way out. Dropping the guard for one save is the weaker failure — it is exactly
+ * the pre-existing last-write-wins behaviour, which the header is optional for.
+ */
+export declare function nextSaveToken(prev: string | null, res: {
+    updatedAt?: unknown;
+}): string | null;

package/dist/draft-registry-YF0tqNN0.js

@@ -0,0 +1,49 @@
+import { createElement as c, useContext as u, createContext as l } from "react";
+const m = 5e3;
+function y() {
+  const e = /* @__PURE__ */ new Set();
+  return {
+    register(r) {
+      const t = () => r();
+      return e.add(t), () => {
+        e.delete(t);
+      };
+    },
+    async flushAll(r = m) {
+      const t = [...e].map(
+        (n) => new Promise((s) => {
+          try {
+            Promise.resolve(n()).then(
+              () => s(),
+              () => s()
+            );
+          } catch {
+            s();
+          }
+        })
+      );
+      let i;
+      const a = new Promise((n) => {
+        i = setTimeout(n, r);
+      });
+      try {
+        await Promise.race([Promise.all(t), a]);
+      } finally {
+        clearTimeout(i);
+      }
+    }
+  };
+}
+const o = l(null);
+function d(e) {
+  return c(o.Provider, { value: e.registry }, e.children);
+}
+function P() {
+  return u(o);
+}
+export {
+  d as D,
+  y as c,
+  P as u
+};
+//# sourceMappingURL=draft-registry-YF0tqNN0.js.map

package/dist/draft-registry-YF0tqNN0.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-registry-YF0tqNN0.js","sources":["../src/draft/draft-registry.ts"],"sourcesContent":["/**\n * The draft registry: every mounted `useWorkflowDraft` registers its `flush` here so a host can\n * settle all of them before an identity swap (logout, account switch) — see `flushAll`.\n *\n * `flushAll` NEVER rejects and is bounded: a flush that throws synchronously, rejects, or never\n * settles must not block or fail the swap. Each call is wrapped individually so one bad draft\n * cannot stop the others being awaited (`createAutoSaver().flush()` rejects when its save rejects\n * and lets a synchronous throw from `save` escape synchronously — both are absorbed here).\n */\nimport { type ReactNode, createContext, createElement, useContext } from \"react\";\n\nexport interface DraftRegistry {\n  /** Register a draft's flush. Returns the unregister function. */\n  register(flush: () => Promise<unknown>): () => void;\n  /** Await every registered flush, at most `timeoutMs` (default 5000). Never rejects. */\n  flushAll(timeoutMs?: number): Promise<void>;\n}\n\nconst DEFAULT_FLUSH_ALL_TIMEOUT_MS = 5000;\n\nexport function createDraftRegistry(): DraftRegistry {\n  const flushes = new Set<() => Promise<unknown>>();\n\n  return {\n    register(flush) {\n      // Wrapped so registering the same function twice yields two independent entries.\n      const entry = () => flush();\n      flushes.add(entry);\n      return () => {\n        flushes.delete(entry);\n      };\n    },\n    async flushAll(timeoutMs = DEFAULT_FLUSH_ALL_TIMEOUT_MS) {\n      const settled = [...flushes].map(\n        (flush) =>\n          new Promise<void>((resolve) => {\n            try {\n              Promise.resolve(flush()).then(\n                () => resolve(),\n                () => resolve(),\n              );\n            } catch {\n              resolve();\n            }\n          }),\n      );\n      let timer: ReturnType<typeof setTimeout> | undefined;\n      const timeout = new Promise<void>((resolve) => {\n        timer = setTimeout(resolve, timeoutMs);\n      });\n      try {\n        await Promise.race([Promise.all(settled), timeout]);\n      } finally {\n        clearTimeout(timer);\n      }\n    },\n  };\n}\n\nconst DraftRegistryContext = createContext<DraftRegistry | null>(null);\n\nexport function DraftRegistryProvider(p: { registry: DraftRegistry; children?: ReactNode }) {\n  return createElement(DraftRegistryContext.Provider, { value: p.registry }, p.children);\n}\n\n/** The nearest registry, or `null` when there is no provider (the hook then skips registering). */\nexport function useDraftRegistry(): DraftRegistry | null {\n  return useContext(DraftRegistryContext);\n}\n"],"names":["DEFAULT_FLUSH_ALL_TIMEOUT_MS","createDraftRegistry","flushes","flush","entry","timeoutMs","settled","resolve","timer","timeout","DraftRegistryContext","createContext","DraftRegistryProvider","p","createElement","useDraftRegistry","useContext"],"mappings":";AAkBA,MAAMA,IAA+B;AAE9B,SAASC,IAAqC;AACnD,QAAMC,wBAAc,IAAA;AAEpB,SAAO;AAAA,IACL,SAASC,GAAO;AAEd,YAAMC,IAAQ,MAAMD,EAAA;AACpB,aAAAD,EAAQ,IAAIE,CAAK,GACV,MAAM;AACX,QAAAF,EAAQ,OAAOE,CAAK;AAAA,MACtB;AAAA,IACF;AAAA,IACA,MAAM,SAASC,IAAYL,GAA8B;AACvD,YAAMM,IAAU,CAAC,GAAGJ,CAAO,EAAE;AAAA,QAC3B,CAACC,MACC,IAAI,QAAc,CAACI,MAAY;AAC7B,cAAI;AACF,oBAAQ,QAAQJ,EAAA,CAAO,EAAE;AAAA,cACvB,MAAMI,EAAA;AAAA,cACN,MAAMA,EAAA;AAAA,YAAQ;AAAA,UAElB,QAAQ;AACN,YAAAA,EAAA;AAAA,UACF;AAAA,QACF,CAAC;AAAA,MAAA;AAEL,UAAIC;AACJ,YAAMC,IAAU,IAAI,QAAc,CAACF,MAAY;AAC7C,QAAAC,IAAQ,WAAWD,GAASF,CAAS;AAAA,MACvC,CAAC;AACD,UAAI;AACF,cAAM,QAAQ,KAAK,CAAC,QAAQ,IAAIC,CAAO,GAAGG,CAAO,CAAC;AAAA,MACpD,UAAA;AACE,qBAAaD,CAAK;AAAA,MACpB;AAAA,IACF;AAAA,EAAA;AAEJ;AAEA,MAAME,IAAuBC,EAAoC,IAAI;AAE9D,SAASC,EAAsBC,GAAsD;AAC1F,SAAOC,EAAcJ,EAAqB,UAAU,EAAE,OAAOG,EAAE,SAAA,GAAYA,EAAE,QAAQ;AACvF;AAGO,SAASE,IAAyC;AACvD,SAAOC,EAAWN,CAAoB;AACxC;"}