From 68b49aa7f98c2b0ee2fa6b30c55f0dbe6dc35f75 Mon Sep 17 00:00:00 2001
From: Serge Zenchenko <sergeizenchenko@gmail.com>
Date: Wed, 26 Aug 2026 15:11:42 +0100
Subject: [PATCH 1/6] Add custom React views to workflow runs

---
 apps/ui/src/api/client.ts                     |  10 +
 apps/ui/src/api/types.ts                      |  25 +-
 apps/ui/src/app/app.test.tsx                  |  60 ++-
 .../molecules/WorkflowViewFrame.module.css    |  65 +++
 .../molecules/WorkflowViewFrame.tsx           | 151 +++++++
 apps/ui/src/components/organisms/GatePane.tsx |  56 ++-
 apps/ui/src/components/organisms/StepPane.tsx |  10 +
 apps/ui/src/domain/adapt.ts                   |   4 +
 apps/ui/src/domain/types.ts                   |   4 +-
 docs/custom-react-ui-in-workflows.md          | 381 ++++++++++++++++++
 packages/cli/src/commands/check.ts            |   2 +
 packages/cli/src/commands/run.ts              |  15 +-
 packages/core/src/ctx.ts                      |  27 ++
 packages/core/src/engine.ts                   |  35 +-
 packages/core/src/events.ts                   |  27 ++
 packages/core/src/index.ts                    |   3 +
 packages/core/src/projections.ts              |  15 +-
 packages/core/src/replay.ts                   |  35 +-
 packages/core/src/runtime.ts                  | 130 +++++-
 packages/core/test/ui.test.ts                 | 172 ++++++++
 packages/daemon/src/api/presentations.ts      |  89 ++++
 packages/daemon/src/api/starts.ts             |   1 +
 packages/daemon/src/app.ts                    |   2 +
 packages/daemon/src/index.ts                  |   1 +
 packages/daemon/src/state.ts                  |   1 +
 packages/daemon/test/api.test.ts              |  56 +++
 packages/gate/package.json                    |   2 +
 packages/gate/src/bundle.ts                   |  20 +-
 packages/gate/src/load.ts                     |   8 +-
 packages/gate/src/registry.ts                 |  36 +-
 packages/gate/src/ui-bundle.ts                | 312 ++++++++++++++
 packages/gate/test/gate.test.ts               |  80 +++-
 packages/host/src/index.ts                    |   4 +-
 packages/host/src/weft.ts                     |  72 +++-
 packages/mcp/src/runs.ts                      |  10 +-
 packages/mcp/src/tools.ts                     |  44 +-
 packages/mcp/src/typings.ts                   |   2 +-
 packages/sdk/package.json                     |   8 +
 packages/sdk/src/index.ts                     |  14 +-
 packages/sdk/src/types.ts                     |  15 +-
 packages/sdk/src/ui.ts                        |  97 +++++
 pnpm-lock.yaml                                |   6 +
 42 files changed, 2045 insertions(+), 62 deletions(-)
 create mode 100644 apps/ui/src/components/molecules/WorkflowViewFrame.module.css
 create mode 100644 apps/ui/src/components/molecules/WorkflowViewFrame.tsx
 create mode 100644 docs/custom-react-ui-in-workflows.md
 create mode 100644 packages/core/test/ui.test.ts
 create mode 100644 packages/daemon/src/api/presentations.ts
 create mode 100644 packages/gate/src/ui-bundle.ts
 create mode 100644 packages/sdk/src/ui.ts

diff --git a/apps/ui/src/api/client.ts b/apps/ui/src/api/client.ts
index 2d1d834d..e63226db 100644
--- a/apps/ui/src/api/client.ts
+++ b/apps/ui/src/api/client.ts
@@ -147,4 +147,14 @@ export const api = {
       if (!res.ok) throw new ApiError(res.status, `blob ${ref} is not readable`);
       return res.text();
     }),
+
+  blobJson: (ref: string) =>
+    fetch(`/api/blobs/${encodeURIComponent(ref)}?as=json`).then(async (res) => {
+      if (GATEWAY.has(res.status)) throw new ApiError(res.status, UNREACHABLE);
+      if (!res.ok) throw new ApiError(res.status, `blob ${ref} is not readable`);
+      return (await res.json()) as unknown;
+    }),
+
+  presentationFrameUrl: (runId: string, presentationId: string) =>
+    `/api/runs/${encodeURIComponent(runId)}/presentations/${encodeURIComponent(presentationId)}/frame`,
 };
diff --git a/apps/ui/src/api/types.ts b/apps/ui/src/api/types.ts
index a98c101c..0089887d 100644
--- a/apps/ui/src/api/types.ts
+++ b/apps/ui/src/api/types.ts
@@ -30,7 +30,25 @@ export type StepKind =
   | "fs"
   | "env"
   | "check"
-  | "sleep";
+  | "sleep"
+  | "ui"
+  | "signal"
+  | "sideeffect";
+
+export interface UiPresentation {
+  id: string;
+  asset: {
+    id: string;
+    revision: string;
+    bundleRef: { $blob: string; size: number; preview?: string };
+    protocol: 1;
+  };
+  props:
+    | { inline: unknown; hash: string }
+    | { ref: { $blob: string; size: number; preview?: string }; hash: string };
+  mode: "display" | "input";
+  slot?: string;
+}
 
 export type Risk = "low" | "medium" | "high" | "irreversible";
 export type ApprovalMode = "auto" | "ask";
@@ -80,6 +98,7 @@ export interface StepState {
   transcriptRef?: { $blob: string; size: number; preview?: string };
   patchRef?: string;
   childRunId?: string;
+  presentation?: UiPresentation;
 }
 
 export interface HumanState {
@@ -90,11 +109,12 @@ export interface HumanState {
   detail?: string;
   risk?: Risk;
   schema: unknown;
-  status: "pending" | "answered";
+  status: "pending" | "answered" | "superseded";
   answer?: unknown;
   answeredBy?: string;
   requestedAt: number;
   artifactRef?: { $blob: string; size: number; preview?: string };
+  ui?: UiPresentation;
 }
 
 /** `GET /api/runs/:id`, with `?detail=1` adding `limits` and `inputs`. */
@@ -142,6 +162,7 @@ export interface PendingRequest {
   rootRunId: string;
   rootWorkflow: string;
   artifactRef?: { $blob: string; size: number; preview?: string };
+  ui?: UiPresentation;
 }
 
 export interface PendingResponse {
diff --git a/apps/ui/src/app/app.test.tsx b/apps/ui/src/app/app.test.tsx
index f23246c9..de02a228 100644
--- a/apps/ui/src/app/app.test.tsx
+++ b/apps/ui/src/app/app.test.tsx
@@ -1,4 +1,4 @@
-import { screen, waitFor, within } from "@testing-library/react";
+import { fireEvent, screen, waitFor, within } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { type FakeDaemon, fakeDaemon } from "~/test/daemon";
 import { renderApp } from "~/test/renderApp";
@@ -113,6 +113,64 @@ describe("a run", () => {
     );
   });
 
+  it("keeps host controls and the standard form around a workflow-provided input view", async () => {
+    const presentation = {
+      id: "h1",
+      asset: {
+        id: "release-review",
+        revision: "2",
+        bundleRef: { $blob: "e".repeat(64), size: 128 },
+        protocol: 1 as const,
+      },
+      props: { inline: { tag: "v0.9.0" }, hash: "f".repeat(64) },
+      mode: "input" as const,
+    };
+    daemon.state.detail["r-waiting"]!.humans[0]!.ui = presentation;
+    daemon.state.pending.pending[0]!.ui = presentation;
+
+    const { user } = renderApp("/runs/r-waiting?from=queue&tab=steps&step=gate:h1");
+    const view = await screen.findByRole("region", { name: "Workflow-provided view: release-review" });
+    expect(within(view).getByText(/revision 2/)).toBeInTheDocument();
+    expect(within(view).getByTitle("Workflow view release-review")).toHaveAttribute(
+      "src",
+      "/api/runs/r-waiting/presentations/h1/frame",
+    );
+    expect(screen.getByLabelText("note")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /Approve/ })).toBeInTheDocument();
+
+    await user.click(within(view).getByRole("button", { name: "Disable" }));
+    expect(screen.getByText(/Custom view disabled/)).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Enable custom view" }));
+    const frame = await screen.findByTitle<HTMLIFrameElement>("Workflow view release-review");
+    const contentWindow = frame.contentWindow;
+    if (!contentWindow) throw new Error("test iframe has no contentWindow");
+
+    let componentPort: MessagePort | undefined;
+    let init: Record<string, unknown> | undefined;
+    contentWindow.postMessage = ((message: unknown, _origin: string, transfer?: Transferable[]) => {
+      init = message as Record<string, unknown>;
+      componentPort = transfer?.[0] as MessagePort | undefined;
+    }) as typeof contentWindow.postMessage;
+    fireEvent.load(frame);
+    await waitFor(() => expect(componentPort).toBeDefined());
+    componentPort!.postMessage({
+      type: "candidate",
+      presentationId: init!.presentationId,
+      generation: init!.generation,
+      answer: { approved: false, note: "not yet" },
+    });
+    expect(await screen.findByRole("button", { name: "Submit and resume" })).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Submit and resume" }));
+    const answered = await waitFor(() => {
+      const call = daemon.calls.find(
+        (candidate) => candidate.method === "POST" && candidate.path.endsWith("/answer"),
+      );
+      expect(call).toBeDefined();
+      return call!;
+    });
+    expect(answered.body).toMatchObject({ answer: { approved: false, note: "not yet" } });
+  });
+
   it("keeps the attached report when the gate falls back to run detail", async () => {
     daemon.state.pending.pending = [];
     renderApp("/runs/r-waiting?from=runs&tab=steps&step=gate:h1");
diff --git a/apps/ui/src/components/molecules/WorkflowViewFrame.module.css b/apps/ui/src/components/molecules/WorkflowViewFrame.module.css
new file mode 100644
index 00000000..1053f855
--- /dev/null
+++ b/apps/ui/src/components/molecules/WorkflowViewFrame.module.css
@@ -0,0 +1,65 @@
+.shell {
+  position: relative;
+  overflow: hidden;
+  border: 1px solid var(--color-line, #d8d6d0);
+  border-radius: 8px;
+  background: var(--color-surface, #fff);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  min-height: 34px;
+  padding: 0 10px;
+  border-bottom: 1px solid var(--color-line, #d8d6d0);
+  color: var(--color-text-muted, #68645c);
+  font:
+    11px / 1.2 ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    monospace;
+}
+
+.header span:nth-child(2) {
+  margin-left: auto;
+}
+
+.header button,
+.fallback button {
+  border: 0;
+  color: inherit;
+  background: transparent;
+  cursor: pointer;
+  text-decoration: underline;
+}
+
+.frame {
+  display: block;
+  width: 100%;
+  min-height: 80px;
+  border: 0;
+  background: transparent;
+}
+
+.loading,
+.error,
+.fallback {
+  display: block;
+  padding: 12px;
+  color: var(--color-text-muted, #68645c);
+  font-size: 12px;
+}
+
+.error {
+  color: #9b2f24;
+  background: #fff2ef;
+}
+
+.fallback {
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+  border: 1px dashed var(--color-line, #d8d6d0);
+  border-radius: 8px;
+}
diff --git a/apps/ui/src/components/molecules/WorkflowViewFrame.tsx b/apps/ui/src/components/molecules/WorkflowViewFrame.tsx
new file mode 100644
index 00000000..397b04b4
--- /dev/null
+++ b/apps/ui/src/components/molecules/WorkflowViewFrame.tsx
@@ -0,0 +1,151 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { api } from "~/api/client";
+import type { UiPresentation } from "~/api/types";
+import styles from "./WorkflowViewFrame.module.css";
+
+type Props = {
+  runId: string;
+  presentation: UiPresentation;
+  onCandidate?: (answer: unknown) => void;
+};
+
+type FrameStatus = "loading" | "ready" | "error" | "disabled";
+
+const MAX_MESSAGE_BYTES = 64 * 1024;
+const MIN_HEIGHT = 80;
+const MAX_HEIGHT = 720;
+const READY_TIMEOUT_MS = 5_000;
+
+function jsonSize(value: unknown): number | undefined {
+  try {
+    const encoded = JSON.stringify(value);
+    return encoded === undefined ? undefined : encoded.length;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Capability-minimal host for one journaled workflow presentation. */
+export function WorkflowViewFrame({ runId, presentation, onCandidate }: Props) {
+  const frame = useRef<HTMLIFrameElement>(null);
+  const channel = useRef<MessageChannel | null>(null);
+  const generation = useRef(0);
+  const readyTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastResize = useRef(0);
+  const [status, setStatus] = useState<FrameStatus>("loading");
+  const [height, setHeight] = useState(180);
+  const [message, setMessage] = useState("");
+
+  useEffect(() => {
+    return () => {
+      if (readyTimer.current) clearTimeout(readyTimer.current);
+      channel.current?.port1.close();
+      channel.current?.port2.close();
+    };
+  }, []);
+
+  const initialize = useCallback(async () => {
+    const target = frame.current?.contentWindow;
+    if (!target || status === "disabled") return;
+    try {
+      const props =
+        "inline" in presentation.props
+          ? presentation.props.inline
+          : await api.blobJson(presentation.props.ref.$blob);
+      const bytes = jsonSize(props);
+      if (bytes === undefined) throw new Error("presentation props must be JSON serializable");
+      if (bytes > MAX_MESSAGE_BYTES * 8) throw new Error("presentation props are too large to render");
+      const next = new MessageChannel();
+      channel.current?.port1.close();
+      channel.current?.port2.close();
+      channel.current = next;
+      const mounted = String(++generation.current);
+      if (readyTimer.current) clearTimeout(readyTimer.current);
+      readyTimer.current = setTimeout(() => {
+        setStatus("error");
+        setMessage("custom view did not become ready in time");
+        next.port1.close();
+      }, READY_TIMEOUT_MS);
+      next.port1.onmessage = (event: MessageEvent<unknown>) => {
+        const value = event.data;
+        if (typeof value !== "object" || value === null) return;
+        const data = value as Record<string, unknown>;
+        if (data.presentationId !== presentation.id || data.generation !== mounted) return;
+        const size = jsonSize(data);
+        if (size === undefined || size > MAX_MESSAGE_BYTES) return;
+        if (data.type === "ready") {
+          if (readyTimer.current) clearTimeout(readyTimer.current);
+          readyTimer.current = null;
+          setStatus("ready");
+        } else if (data.type === "resize" && typeof data.height === "number") {
+          const now = performance.now();
+          if (now - lastResize.current < 50) return;
+          lastResize.current = now;
+          setHeight(Math.max(MIN_HEIGHT, Math.min(MAX_HEIGHT, Math.ceil(data.height))));
+        } else if (data.type === "candidate" && presentation.mode === "input") {
+          if (jsonSize(data.answer) === undefined) return;
+          onCandidate?.(data.answer);
+        } else if (data.type === "error" && typeof data.message === "string") {
+          if (readyTimer.current) clearTimeout(readyTimer.current);
+          readyTimer.current = null;
+          setStatus("error");
+          setMessage(data.message.slice(0, 300));
+        }
+      };
+      next.port1.start();
+      target.postMessage(
+        {
+          type: "weft.ui.init",
+          protocol: 1,
+          presentationId: presentation.id,
+          generation: mounted,
+          props,
+        },
+        "*",
+        [next.port2],
+      );
+    } catch (error) {
+      if (readyTimer.current) clearTimeout(readyTimer.current);
+      readyTimer.current = null;
+      setStatus("error");
+      setMessage(error instanceof Error ? error.message : String(error));
+    }
+  }, [onCandidate, presentation, status]);
+
+  if (status === "disabled") {
+    return (
+      <div className={styles.fallback}>
+        <span>Custom view disabled. The standard data view remains available.</span>
+        <button type="button" onClick={() => setStatus("loading")}>
+          Enable custom view
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <section className={styles.shell} aria-label={`Workflow-provided view: ${presentation.asset.id}`}>
+      <div className={styles.header}>
+        <span>Workflow-provided view</span>
+        <span>
+          {presentation.asset.id} · revision {presentation.asset.revision}
+        </span>
+        <button type="button" onClick={() => setStatus("disabled")}>
+          Disable
+        </button>
+      </div>
+      {status === "error" ? <div className={styles.error}>Custom view unavailable: {message}</div> : null}
+      <iframe
+        ref={frame}
+        className={styles.frame}
+        title={`Workflow view ${presentation.asset.id}`}
+        src={api.presentationFrameUrl(runId, presentation.id)}
+        sandbox="allow-scripts"
+        referrerPolicy="no-referrer"
+        style={{ height }}
+        onLoad={() => void initialize()}
+      />
+      {status === "loading" ? <span className={styles.loading}>Loading custom view…</span> : null}
+    </section>
+  );
+}
diff --git a/apps/ui/src/components/organisms/GatePane.tsx b/apps/ui/src/components/organisms/GatePane.tsx
index 1412e9f3..528a13d8 100644
--- a/apps/ui/src/components/organisms/GatePane.tsx
+++ b/apps/ui/src/components/organisms/GatePane.tsx
@@ -1,5 +1,5 @@
 import { useAtomValue, useSetAtom } from "jotai";
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
 import { api } from "~/api/client";
 import { useAnswerGate } from "~/api/queries";
 import type { JsonSchema } from "~/api/types";
@@ -9,6 +9,7 @@ import { MonoBadge } from "~/components/atoms/MonoBadge";
 import { StatusPill } from "~/components/atoms/StatusPill";
 import { GateQuestionRow } from "~/components/molecules/GateQuestionRow";
 import { SectionHeading } from "~/components/molecules/SectionHeading";
+import { WorkflowViewFrame } from "~/components/molecules/WorkflowViewFrame";
 import { gateAnswer, VERDICT_FIELD } from "~/domain/adapt";
 import type { Gate, StepDetail } from "~/domain/types";
 import { clearGateDraftAtom, gateDraftAtom, setGateFieldAtom, toggleGateChipAtom } from "~/state/atoms";
@@ -38,13 +39,19 @@ export function GatePane({ gate, step, schema, onAnswered }: Props) {
   const toggleChip = useSetAtom(toggleGateChipAtom);
   const clearDraft = useSetAtom(clearGateDraftAtom);
   const answer = useAnswerGate();
+  const [staged, setStaged] = useState<{ gateId: string; value: unknown }>();
+  const candidate = staged?.gateId === gate.id ? staged.value : undefined;
 
   const values = useMemo(() => drafts[gate.id] ?? {}, [drafts, gate.id]);
   const runId = gate.runId ?? "";
 
-  const submit = (override?: Record<string, unknown>) => {
+  const submit = (override?: Record<string, unknown>, exact?: unknown) => {
     answer.mutate(
-      { runId, requestId: gate.id, answer: gateAnswer(schema, { ...values, ...override }) },
+      {
+        runId,
+        requestId: gate.id,
+        answer: exact === undefined ? gateAnswer(schema, { ...values, ...override }) : exact,
+      },
       {
         onSuccess: () => {
           clearDraft(gate.id);
@@ -57,7 +64,9 @@ export function GatePane({ gate, step, schema, onAnswered }: Props) {
   // Previewing the approving answer: it is the one the primary button sends, and a
   // preview that omitted the verdict would show something the run never receives.
   const payload = JSON.stringify(
-    gateAnswer(schema, gate.deniable ? { ...values, [VERDICT_FIELD]: true } : values),
+    candidate === undefined
+      ? gateAnswer(schema, gate.deniable ? { ...values, [VERDICT_FIELD]: true } : values)
+      : candidate,
   );
 
   return (
@@ -100,15 +109,40 @@ export function GatePane({ gate, step, schema, onAnswered }: Props) {
           </SectionHeading>
         </div>
 
+        {gate.ui ? (
+          <div className={styles.questions}>
+            <WorkflowViewFrame
+              key={gate.ui.id}
+              runId={runId}
+              presentation={gate.ui}
+              onCandidate={(value) => setStaged({ gateId: gate.id, value })}
+            />
+            {candidate !== undefined ? (
+              <span className={styles.detail}>
+                Candidate staged by the custom view. Review the payload below, then submit from Weft.
+              </span>
+            ) : null}
+          </div>
+        ) : null}
+
         <div className={styles.questions}>
           {gate.questions.map((question) => (
             <GateQuestionRow
               key={question.key}
               question={question}
               value={values[question.key] as never}
-              onSet={(value) => setField(gate.id, question.key, value)}
-              onToggleChip={(label) => toggleChip(gate.id, question.key, label)}
-              onToggleFlag={() => setField(gate.id, question.key, values[question.key] !== true)}
+              onSet={(value) => {
+                setStaged(undefined);
+                setField(gate.id, question.key, value);
+              }}
+              onToggleChip={(label) => {
+                setStaged(undefined);
+                toggleChip(gate.id, question.key, label);
+              }}
+              onToggleFlag={() => {
+                setStaged(undefined);
+                setField(gate.id, question.key, values[question.key] !== true);
+              }}
             />
           ))}
           {gate.questions.length === 0 ? (
@@ -140,9 +174,13 @@ export function GatePane({ gate, step, schema, onAnswered }: Props) {
           variant="primary"
           size="large"
           disabled={answer.isPending}
-          onClick={() => submit(gate.deniable ? { approved: true } : undefined)}
+          onClick={() =>
+            candidate === undefined
+              ? submit(gate.deniable ? { approved: true } : undefined)
+              : submit(undefined, candidate)
+          }
         >
-          {answer.isPending ? "Answering…" : gate.submitLabel}
+          {answer.isPending ? "Answering…" : candidate === undefined ? gate.submitLabel : "Submit and resume"}
         </Button>
       </div>
     </div>
diff --git a/apps/ui/src/components/organisms/StepPane.tsx b/apps/ui/src/components/organisms/StepPane.tsx
index abd7169a..6a882d2c 100644
--- a/apps/ui/src/components/organisms/StepPane.tsx
+++ b/apps/ui/src/components/organisms/StepPane.tsx
@@ -9,6 +9,7 @@ import { NextStrip } from "~/components/molecules/NextStrip";
 import { DataPane } from "~/components/molecules/OutputPane";
 import { SectionHeading } from "~/components/molecules/SectionHeading";
 import { ToolCallRow } from "~/components/molecules/ToolCallRow";
+import { WorkflowViewFrame } from "~/components/molecules/WorkflowViewFrame";
 import type { Run, StepDetail } from "~/domain/types";
 import styles from "./StepPane.module.css";
 
@@ -127,6 +128,15 @@ export function StepPane({ run, step, stepId, onSelectStep, onGoToGate }: Props)
             <SectionHeading>
               <Kicker>Output</Kicker>
             </SectionHeading>
+            {step.presentation ? (
+              <div className={styles.block}>
+                <WorkflowViewFrame
+                  key={step.presentation.id}
+                  runId={run.id}
+                  presentation={step.presentation}
+                />
+              </div>
+            ) : null}
             <DataPane
               title={step.outTitle}
               note={step.outNote}
diff --git a/apps/ui/src/domain/adapt.ts b/apps/ui/src/domain/adapt.ts
index 7a4e3475..8c91244f 100644
--- a/apps/ui/src/domain/adapt.ts
+++ b/apps/ui/src/domain/adapt.ts
@@ -435,6 +435,7 @@ function machineStep(
     tools: [],
     toolsTitle: "",
     next: failed && step.error?.message ? { k: "error", v: step.error.message, goToGate: false } : null,
+    ...(step.presentation !== undefined ? { presentation: step.presentation } : {}),
   };
 }
 
@@ -481,6 +482,7 @@ function humanStep(human: HumanState, waiting: boolean): StepDetail {
     tools: [],
     toolsTitle: "",
     next: waiting ? { k: "needs you", v: "This question is holding the run.", goToGate: true } : null,
+    ...(human.ui !== undefined ? { presentation: human.ui } : {}),
   };
 }
 
@@ -561,6 +563,7 @@ export function adaptGate(request: PendingRequest): Gate {
           },
         }
       : {}),
+    ...(request.ui !== undefined ? { ui: request.ui } : {}),
   };
 }
 
@@ -583,6 +586,7 @@ function adaptGateFromState(detail: RunDetail, human: HumanState | undefined): G
     ...(human.detail !== undefined ? { detail: human.detail } : {}),
     ...(human.risk !== undefined ? { risk: human.risk } : {}),
     ...(human.artifactRef !== undefined ? { artifactRef: human.artifactRef } : {}),
+    ...(human.ui !== undefined ? { ui: human.ui } : {}),
   });
 }
 
diff --git a/apps/ui/src/domain/types.ts b/apps/ui/src/domain/types.ts
index 16f0abb8..0fa41268 100644
--- a/apps/ui/src/domain/types.ts
+++ b/apps/ui/src/domain/types.ts
@@ -1,5 +1,5 @@
 /** Lifecycle of a whole run, as the journal records it. */
-import type { JsonSchema } from "~/api/types";
+import type { JsonSchema, UiPresentation } from "~/api/types";
 
 export type RunState = "running" | "waiting" | "done" | "stopped" | "failed";
 
@@ -157,6 +157,7 @@ export type StepDetail = {
   toolsTitle: string;
   /** The dashed strip under the output — an error, or what the step is waiting on. */
   next: { k: string; v: string; goToGate: boolean } | null;
+  presentation?: UiPresentation;
 };
 
 export type GateQuestionKind = "cards" | "chips" | "choice" | "select" | "toggle" | "text" | "list" | "note";
@@ -185,6 +186,7 @@ export type Gate = {
   denyLabel: string;
   questions: GateQuestion[];
   artifactRef?: { ref: string; size: number; preview?: string };
+  ui?: UiPresentation;
 };
 
 export type Run = {
diff --git a/docs/custom-react-ui-in-workflows.md b/docs/custom-react-ui-in-workflows.md
new file mode 100644
index 00000000..2f3483ae
--- /dev/null
+++ b/docs/custom-react-ui-in-workflows.md
@@ -0,0 +1,381 @@
+# Custom React UI inside Weft workflows
+
+> Implementation article for Weft's first custom workflow UI release. The public API and runtime contracts below describe the code in this repository. The final section separates automated coverage from the broader browser matrix required before a production release.
+
+Weft workflows can now render custom React components while they run.
+
+Today, when a workflow needs human input, the Workflow Manager generates a form from the step's JSON Schema. That remains the default and the permanent fallback. But some interactions need more than generic fields: reviewing a deployment, comparing candidates, annotating an artifact, or exploring a structured result all benefit from purpose-built UI.
+
+Workflow UI views add that escape hatch without moving workflow execution into the browser. An author places a `.ui.tsx` component beside a workflow and imports it like any other TypeScript module. Weft compiles the file into a browser asset, journals an immutable presentation descriptor, and renders it inside constrained host-owned chrome.
+
+The same mechanism supports three use cases:
+
+- A custom view for a pending human question.
+- A read-only presentation of a validated step result.
+- A composed presentation built from several workflow results.
+
+## Defining an input view
+
+A workflow imports its UI view directly. There is no string path or runtime component registry for authors to keep in sync:
+
+```ts
+import deploymentReview from "./deployment-review.ui.tsx";
+
+export default defineWorkflow(
+  {
+    id: "deploy",
+    description: "Prepare and review a deployment",
+    input: DeployInput,
+    output: DeployOutput,
+  },
+  async (ctx, input) => {
+    const decision = await ctx.human.ask({
+      key: "deployment-review",
+      question: "Review this deployment",
+      schema: DeploymentDecision,
+      ui: {
+        view: deploymentReview,
+        props: {
+          environment: input.environment,
+          services: input.services,
+        },
+      },
+    });
+
+    return decision;
+  },
+);
+```
+
+The companion component is ordinary React, with two important pieces of static metadata: a stable `id` and a semantic `revision`.
+
+```tsx
+import { defineUiView, type InputViewProps } from "@techery/weft-sdk/ui";
+import { useState } from "react";
+import { z } from "zod";
+import { DeploymentDecision } from "./schemas.js";
+
+type Props = {
+  environment: string;
+  services: string[];
+};
+
+type Answer = z.input<typeof DeploymentDecision>;
+
+function DeploymentReview({ props, propose }: InputViewProps<Props, Answer>) {
+  const [selected, setSelected] = useState(props.services);
+
+  const toggle = (service: string) => {
+    setSelected((current) =>
+      current.includes(service)
+        ? current.filter((candidate) => candidate !== service)
+        : [...current, service],
+    );
+  };
+
+  return (
+    <section>
+      <h2>Deploy to {props.environment}</h2>
+
+      {props.services.map((service) => (
+        <label key={service}>
+          <input
+            type="checkbox"
+            checked={selected.includes(service)}
+            onChange={() => toggle(service)}
+          />
+          {service}
+        </label>
+      ))}
+
+      <button onClick={() => propose({ approvedServices: selected })}>
+        Stage this selection
+      </button>
+    </section>
+  );
+}
+
+export default defineUiView<Props, Answer>({
+  id: "deployment-review",
+  revision: "1",
+  component: DeploymentReview,
+});
+```
+
+`propose()` deliberately does not answer the workflow. It sends a candidate value to the parent Workflow Manager, which validates it and shows the exact candidate in host-owned chrome. A person must use the host's **Submit and resume** control before Weft records the answer. Component code therefore cannot answer a question on mount or falsely turn an automated action into a human decision.
+
+The answer type is the schema's input type, while workflow code receives the schema's output type. That distinction matters for defaults, coercions, and transforms. The server remains responsible for applying the authoritative schema.
+
+The `id` and `revision` must be string literals so the compiler can extract them without executing browser code. TypeScript checks the props and candidate answer, while the Weft compiler independently checks the static metadata, import policy, and bundle limits.
+
+## Rendering step results
+
+Custom views are not limited to human input. A workflow can publish a read-only presentation after a step returns a validated result:
+
+```ts
+import analysisView from "./analysis-result.ui.tsx";
+
+const analysis = await ctx.agent("Analyze deployment risk", {
+  key: "deployment-analysis",
+  schema: DeploymentAnalysis,
+});
+
+await ctx.ui.render({
+  key: "render-deployment-analysis",
+  slot: "deployment-analysis",
+  view: analysisView,
+  props: {
+    riskScore: analysis.riskScore,
+    findings: analysis.findings,
+  },
+});
+```
+
+The component receives an explicit, JSON-safe projection of the validated result:
+
+```tsx
+import { defineResultView } from "@techery/weft-sdk/ui";
+
+type Props = {
+  riskScore: number;
+  findings: Array<{ title: string; severity: string }>;
+};
+
+export default defineResultView<Props>({
+  id: "deployment-analysis",
+  revision: "1",
+  component({ props }) {
+    return <RiskDashboard score={props.riskScore} findings={props.findings} />;
+  },
+});
+```
+
+This explicit second operation is intentional for v1. Adding `ui` to the agent's computational payload would make a visual revision invalidate and rerun an expensive agent step. `ctx.ui.render()` is instead its own replayable presentation step. The producing step and its presentation can refer to one another in the timeline without sharing replay identity.
+
+A later convenience API may accept `ui` on a step and desugar it into the same separate presentation occurrence after validation. It must not change the computational step hash.
+
+The standard JSON, Markdown, artifact, or other result renderer is always available beside the custom view. A result view is an interpretation of durable output, never its source of truth.
+
+## Rendering composed workflow state
+
+The same primitive can render a presentation assembled from several results:
+
+```ts
+import summaryView from "./workflow-summary.ui.tsx";
+
+const analysis = await ctx.agent(/* ... */);
+const checks = await Promise.all([
+  ctx.check("unit-tests", { exec: ["pnpm", "test"] }),
+  ctx.check("typecheck", { exec: ["pnpm", "typecheck"] }),
+]);
+
+await ctx.ui.render({
+  key: "render-deployment-summary",
+  slot: "deployment-summary",
+  view: summaryView,
+  props: { analysis, checks },
+});
+```
+
+`key` and `slot` have different jobs:
+
+- `key` is the durable call-site identity used for replay and should be unique to that call site.
+- `slot` is optional grouping metadata for hosts that want to select the current presentation for a named region.
+
+The current Workflow Manager shows each presentation on its journaled timeline step and retains `slot` for future aggregate surfaces. It does not discard earlier occurrences. Authors must not reuse a `key` across unrelated call sites because that would conflate replay identity.
+
+## The durable presentation contract
+
+Input and display views use one versioned contract:
+
+```ts
+type UiAssetRef = {
+  id: string;
+  revision: string;
+  bundleRef: BlobRefJson;
+  protocol: 1;
+};
+
+type UiProps =
+  | { inline: JsonValue; hash: string }
+  | { ref: BlobRefJson; hash: string };
+
+type UiPresentation = {
+  asset: UiAssetRef;
+  props: UiProps;
+  mode: "display" | "input";
+  slot?: string;
+};
+```
+
+Large props are stored once in the blob store rather than copied into an unbounded journal event. The blob is written and verified before the event that references it is appended. Props are durable run data: they must be JSON-safe and size-bounded, and must not contain credentials, tokens, secrets, or transient privileged handles.
+
+The descriptor is recorded in an existing durable lifecycle:
+
+- `human.requested` may carry an input presentation.
+- The `step.completed` event for a replayable UI presentation step carries a display presentation.
+- A future step-attachment convenience API may associate that presentation with its producing step.
+
+V1 does not need a fire-and-forget `ui.rendered` event. `ctx.ui.render()` is a new replay-aware step kind whose semantic hash includes its call-site key, slot, view ID, revision, and canonical props hash. It excludes `bundleRef`, so a bundle-only visual change does not alter replay identity. UI steps also opt out of the existing reuse-by-key cache behavior that could otherwise return stale props.
+
+For human steps, the journal must record the human `key` as well as the view ID, revision, props hash, and answer schema identity. If one of those semantic inputs changes, Weft creates a new request and records the previous same-key request as superseded. The pending-request projection and answer endpoint must reject superseded request IDs; otherwise both the old and new questions would remain answerable.
+
+## Why the component is a TypeScript import
+
+The direct import is authoring syntax, not the browser's runtime lookup mechanism.
+
+Weft gives a `.ui.tsx` import two meanings during compilation:
+
+```text
+deployment-review.ui.tsx
+          │
+          ├── Node workflow graph → inert typed token
+          │
+          └── Browser asset graph → bundled React application
+```
+
+The Node graph intercepts the import before the React module enters the workflow's deterministic module graph. It statically validates the literal `id` and `revision`, records them in the compiled UI catalog, and emits an opaque token similar to:
+
+```ts
+{
+  kind: "weft.ui-view",
+  assetKey: "module-scoped-compiler-key",
+}
+```
+
+The token contains no executable component, semantic revision, or blob reference. It is safe to pass through workflow code, and changing UI source or metadata does not alter the workflow definition hash. When a presentation is created, the runtime resolves the token through the sealed catalog and includes the catalog's current view ID and revision in that presentation's own semantic hash.
+
+Separately, the browser compiler follows the real module, transforms JSX, bundles it with compiler-owned React dependencies, and produces a content-addressed asset. A compiled UI catalog maps the internal `assetKey` to the exact browser asset and its hash. The workflow cannot invent or override a `bundleRef`; only the sealed compiler catalog can resolve one.
+
+This gives authors rename support, navigation, autocomplete, prop checking, and an explicit dependency graph, without putting React or browser APIs into Node workflow execution.
+
+## Two hashes, not one
+
+UI compilation needs two independent identities:
+
+- `defHash` covers emitted Node workflow code and continues to govern workflow replay trust.
+- `buildHash` covers the UI catalog and browser outputs and governs loader and registry caching.
+
+Putting browser metadata or a bundle hash into the Node token would make a UI change alter `defHash` and invalidate replay positions across the workflow. Looking only at `defHash` in the registry cache would have the opposite bug: UI edits would keep serving an old browser bundle. The two-hash model avoids both failures.
+
+The compiled catalog is a first-class build result, not metadata hidden on the workflow definition. It must travel through bundle, load, registry resolution, host resolution, engine start and resume, and named-child resolution. Wrappers that reconstruct a workflow definition must not be able to discard it.
+
+## Durable assets and entry-point boundaries
+
+Before a run records its first presentation, Weft stores the browser bytes content-addressably and journals the exact asset reference. Historical rendering is exact only while every referenced blob is retained. Garbage collection, run export, import, and deletion therefore need to trace and preserve presentation references just like other durable artifacts. If an asset is missing or corrupt, the host shows the standard renderer and an explicit unavailable state.
+
+The implementation carries the UI catalog through every workflow entry point that can compile browser views:
+
+- File and registry workflows receive their catalog from the gate and registry resolver.
+- Inline, STDIN, and MCP-created workflows persist browser assets and a run-local `ui-manifest.json`, so a later process can resume with the same component bytes.
+- Named child workflows use the richer resolver result and receive their own catalog; inline children inherit the parent catalog.
+- Direct engine callers pass `uiCatalog` alongside the `WorkflowDefinition`, which keeps the runtime contract explicit in tests and embedding applications.
+
+An imported view that is absent from the sealed catalog is rejected before it can create a presentation. Weft never starts rendering from a path supplied at runtime.
+
+## Failure semantics
+
+Presentation failures are isolated from already-completed computation, but not every UI-related error is cosmetic:
+
+- A compile error, duplicate view ID, invalid static metadata, forbidden import, or oversized bundle fails `weft check` and workflow resolution before the run starts.
+- Non-JSON or oversized props fail the `ctx.ui.render()` step before it can append a presentation.
+- Blob persistence or durable append failures are ordinary run failures when the workflow awaits the presentation step.
+- A browser load error, protocol mismatch, missing historical asset, or React rendering error falls back to the standard form or result without changing an already-recorded workflow value.
+
+The host always exposes the generic form or raw output—not only after an error—so a misleading, inaccessible, or broken custom view cannot hide the durable source of truth.
+
+## React runs in a constrained frame
+
+Views are trusted application code from the workflow repository. The iframe is defense-in-depth isolation from Weft's DOM and authority; it is not a safe executor for hostile workflows or compromised dependencies.
+
+The frame uses `sandbox="allow-scripts"` without `allow-same-origin`, so it receives an opaque origin. It is served only from an event-associated route such as:
+
+```text
+GET /api/runs/:ownerRunId/presentations/:presentationId/frame
+```
+
+The server folds that run's journal, resolves the bundle reference from the recorded presentation, verifies the content hash and envelope, and returns a server-owned HTML shell. A generic blob endpoint must never become an arbitrary HTML or JavaScript execution endpoint.
+
+The frame response uses an HTTP Content Security Policy—not a meta-only substitute—with a starting policy equivalent to:
+
+```text
+default-src 'none';
+script-src 'sha256-...';
+style-src 'unsafe-inline';
+img-src data: blob:;
+connect-src 'none';
+font-src 'none';
+media-src 'none';
+object-src 'none';
+frame-src 'none';
+worker-src 'none';
+form-action 'none';
+base-uri 'none';
+sandbox allow-scripts;
+frame-ancestors 'self';
+```
+
+The response also sets `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`, a restrictive `Permissions-Policy`, `Cross-Origin-Resource-Policy: same-origin`, and `Cache-Control: no-store`. The parent iframe repeats the sandbox restriction and referrer policy.
+
+This policy blocks parent DOM and storage access, daemon fetches, forms, subresources, workers, popups, and top-level navigation capabilities. It does not provide portable CPU or memory quotas, and a sandboxed document may still navigate its own frame to encode data in an external URL. The Workflow Manager renders only selected presentation surfaces, clamps their dimensions, and gives each one a **Disable** escape hatch. Weft does not claim hostile-code containment.
+
+The browser compiler enforces the same trust boundary at build time. V1 allows only compiler-owned React packages, `@techery/weft-sdk/ui`, and contained relative TypeScript or JavaScript modules. It rejects Node built-ins, path and symlink escapes, environment or secret-file imports, dynamic or remote imports, CSS and other unsupported assets, more than 32 views, and browser bundles over 1 MB. The frame CSP separately blocks network connections, workers, WebAssembly compilation, and `eval`-style execution at runtime. Source maps containing source content are not emitted.
+
+## A parent-controlled message bridge
+
+Because the iframe's opaque origin serializes as `null`, origin-string checks cannot authenticate it. The parent creates a `MessageChannel`, transfers one port after load, and then closes the global bootstrap listener. Messages on the port include a protocol version, presentation ID, and mount generation and are validated for mode, JSON serializability, and byte size. The answer endpoint independently verifies that the request is still pending.
+
+Display views may report readiness and clamped dimensions. Input views may additionally stage a candidate answer. They receive no daemon API client, credentials, filesystem capability, workflow context, or final submission function. Resize messages are rate-limited, stale generations are ignored, and closing the frame closes the channel.
+
+The Workflow Manager keeps host-owned chrome around every view:
+
+- A visible “Workflow-provided view” label.
+- The canonical question, risk, and artifact metadata.
+- A candidate-answer preview and parent-owned submit control for input mode.
+- A permanent standard form or raw output alongside the custom view.
+- Clamped height, load timeout, React error handling, and a **Disable custom view** escape hatch.
+
+Security-sensitive approvals, irreversible confirmations, and other risk-governed controls remain entirely native to Weft.
+
+## How the implementation is split
+
+The feature is implemented as five reviewable layers:
+
+1. **Contracts and journal semantics.** UI token/types, JSON and size validation, the replayable UI step, human request keys and supersession, projections, and generic fallbacks.
+2. **Dual compiler and asset catalog.** Static `.ui.tsx` discovery, a separate browser compiler and import policy, compiler-owned React dependencies, independent `defHash` and `buildHash`, and blob persistence.
+3. **Read-only result views.** The event-associated frame route, strict security headers, host chrome, message channel, timeline association, and raw-output fallback.
+4. **Human input views.** Candidate staging, server schema validation, host-owned confirmation, supersession behavior, and permanent standard-form parity.
+5. **Entry-point propagation.** Inline manifests, child catalogs, MCP typings, registry caching, and explicit engine embedding contracts.
+
+The separation is useful beyond code organization: the workflow engine never needs React, the browser never receives workflow authority, and a visual failure does not erase the generic representation of durable data.
+
+## Repository implementation map
+
+This feature could not be added only in the Workflow Manager. Its implementation crosses these package boundaries:
+
+- `packages/sdk` adds the published `/ui` authoring subpath, opaque typed tokens, input/output type separation, and `ctx.ui.render()` declarations.
+- `packages/gate` discovers `.ui.tsx` imports before the Node gate, runs the distinct browser compiler, produces `defHash`, `buildHash`, and the UI catalog, and applies browser-specific import and size policy.
+- `packages/cli` teaches `weft check` to understand JSX and treats UI compilation errors as fatal rather than relying on its advisory TypeScript pass.
+- `packages/core` adds the replayable UI step, presentation descriptors, JSON/blob props, human keys and supersession events, semantic hashes, projections, and child-runtime catalog resolution.
+- `packages/host` and the registry propagate the catalog through path, named, inline, start, and resume flows instead of attaching metadata to a reconstructable `WorkflowDefinition` object.
+- `packages/daemon` adds the event-associated frame route, verified asset envelope, strict response headers, and rejection of superseded answers.
+- `apps/ui` adds host-owned frame chrome, `MessageChannel` lifecycle, candidate preview and confirmation, per-frame disable controls, generic fallbacks, and timeline presentations.
+- Blob storage, export/import, and garbage collection treat every journaled UI asset and props reference as reachable run data.
+
+This propagation is a launch requirement. Without it, a direct import may compile locally but lose its browser asset during registry loading, wrapping, child execution, or resume.
+
+## Verification status
+
+The repository's automated coverage now proves the core implementation contracts:
+
+- A real file workflow imports `.ui.tsx`, compiles separate Node and browser graphs, records a presentation, and serves only its event-associated frame.
+- A visual-only edit changes `buildHash` but not `defHash`; revision and props participate in presentation identity.
+- Replay does not duplicate `ctx.ui.render()` occurrences, and UI steps refuse stale reuse-by-key salvage.
+- A changed human interaction supersedes the old same-key request, and an old request ID cannot answer the run.
+- The answer schema—not the component—accepts or rejects the staged candidate.
+- Arbitrary presentation IDs cannot turn the blob store into an executable endpoint.
+- The standard form and raw output remain visible beside custom UI.
+
+Before treating the feature as hostile-code containment or completing a production browser rollout, Weft still needs an integration matrix in Chromium, Firefox, and WebKit covering DOM and storage isolation, blocked network/subresources/forms/popups, stale and forged messages, resize flooding, render failure, restart rendering, and the documented self-navigation limitation. Workflow views are trusted repository code; the iframe is defense in depth, not a general-purpose sandbox for hostile JavaScript.
+
+With these contracts, custom React views fit Weft's architecture. They add expressive, workflow-owned presentation while preserving the journal as the source of truth, schemas as the authority over data, replay as an explicit semantic contract, and the host as the only authority that can advance a human decision.
diff --git a/packages/cli/src/commands/check.ts b/packages/cli/src/commands/check.ts
index 12a8a47c..c108e7cc 100644
--- a/packages/cli/src/commands/check.ts
+++ b/packages/cli/src/commands/check.ts
@@ -158,6 +158,8 @@ async function typecheck(files: readonly string[], cwd: string): Promise<string[
     "nodenext",
     "--moduleResolution",
     "nodenext",
+    "--jsx",
+    "react-jsx",
     "--allowImportingTsExtensions",
     "--skipLibCheck",
     ...files,
diff --git a/packages/cli/src/commands/run.ts b/packages/cli/src/commands/run.ts
index f1acadc0..94600f13 100644
--- a/packages/cli/src/commands/run.ts
+++ b/packages/cli/src/commands/run.ts
@@ -6,10 +6,12 @@
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import {
+  type CompiledUiCatalog,
   isWorkflowPathRef,
   loadWorkflow,
   parseBudget,
   persistInlineScript,
+  persistUiCatalog,
   persistWorkflowRef,
   rejectUnknownInput,
   reserveRunId,
@@ -45,7 +47,7 @@ export function runCommand(io: CliIo): Command {
       const weft = await openWeft(cmd);
       try {
         const input = { ...parseArgsJson(opts.args), ...parseDynamicFlags(cmd.args.slice(1)) };
-        const { def, name, hash, code } = await resolveRef(weft, ref, io);
+        const { def, name, hash, code, uiCatalog } = await resolveRef(weft, ref, io);
         await rejectUnknownInput(input, def, name);
         const reuse = parseReuse(opts.reuse);
         const budget = opts.budget === undefined ? undefined : parseBudget(opts.budget);
@@ -59,6 +61,7 @@ export function runCommand(io: CliIo): Command {
         // write into an EXISTING run's directory.
         const runId = await reserveRunId(weft);
         if (code !== undefined) await persistInlineScript(weft, runId, code);
+        if (code !== undefined && uiCatalog !== undefined) await persistUiCatalog(weft, runId, uiCatalog);
         else if (isWorkflowPathRef(ref)) await persistWorkflowRef(weft, runId, ref);
         const handle = await weft.engine
           .start(def, {
@@ -66,6 +69,7 @@ export function runCommand(io: CliIo): Command {
             input,
             cwd: weft.cwd,
             ...(hash !== undefined ? { defHash: hash } : {}),
+            ...(uiCatalog !== undefined ? { uiCatalog } : {}),
             ...(budget !== undefined ? { budget } : {}),
             ...(reuse !== undefined ? { reuse } : {}),
           })
@@ -92,6 +96,7 @@ interface ResolvedRef {
   hash?: string;
   /** The bundled source, present only for inline (stdin) scripts — persisted with the run. */
   code?: string;
+  uiCatalog?: CompiledUiCatalog;
 }
 
 /**
@@ -108,5 +113,11 @@ async function resolveRef(weft: Weft, ref: string, io: CliIo): Promise<ResolvedR
     loaded.def.meta.name === loaded.name
       ? loaded.def
       : { kind: loaded.def.kind, meta: { ...loaded.def.meta, name: loaded.name }, run: loaded.def.run };
-  return { def, name: loaded.name, hash: loaded.hash, code: loaded.code };
+  return {
+    def,
+    name: loaded.name,
+    hash: loaded.hash,
+    code: loaded.code,
+    uiCatalog: loaded.uiCatalog,
+  };
 }
diff --git a/packages/core/src/ctx.ts b/packages/core/src/ctx.ts
index e815616a..58178094 100644
--- a/packages/core/src/ctx.ts
+++ b/packages/core/src/ctx.ts
@@ -2140,6 +2140,7 @@ export function buildCtx(rt: RunRuntime): Ctx {
         wrapped: wire.wrapped,
         ...(opts.timeout !== undefined ? { timeoutMs: parseDuration(opts.timeout) } : {}),
         ...(timeoutSpec(opts.onTimeout) ?? {}),
+        ...(opts.ui !== undefined ? { ui: opts.ui } : {}),
       });
       return outcome.answer as never;
     },
@@ -2173,11 +2174,36 @@ export function buildCtx(rt: RunRuntime): Ctx {
         artifactRef: { $blob: blob.hash, size: blob.size, preview: opts.artifact.slice(0, 200) },
         ...(opts.timeout !== undefined ? { timeoutMs: parseDuration(opts.timeout) } : {}),
         ...(timeoutSpec(opts.onTimeout) ?? {}),
+        ...(opts.ui !== undefined ? { ui: opts.ui } : {}),
       });
       return outcome.answer as never;
     },
   };
 
+  const ui: Ctx["ui"] = {
+    render: async (opts) => {
+      const prepared = await rt.prepareUiPresentation(opts.view, opts.props, "display", "pending", opts.slot);
+      await rt.runStep<void>({
+        kind: "ui",
+        key: opts.key,
+        label: prepared.asset.id,
+        payload: {
+          op: "ui.render",
+          slot: opts.slot ?? null,
+          view: prepared.asset.id,
+          revision: prepared.asset.revision,
+          propsHash: prepared.props.hash,
+        },
+        revive: () => undefined,
+        execute: async (io) => ({
+          value: undefined,
+          journalOutput: null,
+          presentation: { ...prepared, id: `u${io.scheduleIndex}` },
+        }),
+      });
+    },
+  };
+
   function timeoutSpec(
     onTimeout: "deny" | "escalate" | { default: unknown } | undefined,
   ): { onTimeout: "deny" | "escalate" | "default"; timeoutDefault?: unknown } | undefined {
@@ -2881,6 +2907,7 @@ export function buildCtx(rt: RunRuntime): Ctx {
     workflow: workflow as Ctx["workflow"],
     gate: (req) => rt.gateStep(req),
     human,
+    ui,
     fs,
     exec,
     bash,
diff --git a/packages/core/src/engine.ts b/packages/core/src/engine.ts
index 53effaf0..ea5a30fe 100644
--- a/packages/core/src/engine.ts
+++ b/packages/core/src/engine.ts
@@ -7,6 +7,7 @@ import { randomUUID } from "node:crypto";
 import { trace } from "@opentelemetry/api";
 import {
   CancelledError,
+  type CompiledUiCatalog,
   isCancellation,
   isWorkflowDefinition,
   StepError,
@@ -248,7 +249,9 @@ export interface WorkflowRegistry {
   resolve?(identity: {
     id?: string;
     name: string;
-  }): Promise<{ def: WorkflowDefinition; name: string; hash?: string } | undefined>;
+  }): Promise<
+    { def: WorkflowDefinition; name: string; hash?: string; uiCatalog?: CompiledUiCatalog } | undefined
+  >;
   /**
    * The bundle content hash of what `get(name)` would return right now, when the registry
    * knows one.
@@ -265,7 +268,9 @@ export interface WorkflowRegistry {
 async function resolveRegistryWorkflow(
   registry: WorkflowRegistry,
   identity: { id?: string; name: string },
-): Promise<{ def: WorkflowDefinition; name: string; hash?: string } | undefined> {
+): Promise<
+  { def: WorkflowDefinition; name: string; hash?: string; uiCatalog?: CompiledUiCatalog } | undefined
+> {
   if (registry.resolve) return registry.resolve(identity);
   const def = await registry.get(identity.name);
   if (!def) return undefined;
@@ -297,6 +302,7 @@ export interface StartOptions {
   defHash?: string;
   budget?: { tokens?: number; usd?: number };
   reuse?: ReuseMode;
+  uiCatalog?: CompiledUiCatalog;
 }
 
 export interface ResumeOptions {
@@ -309,6 +315,7 @@ export interface ResumeOptions {
    * and the check falls back to the body hash alone.
    */
   defHash?: string;
+  uiCatalog?: CompiledUiCatalog;
 }
 
 export type RunOutcome =
@@ -450,6 +457,7 @@ export class Engine implements EngineHost {
       shared,
       ...(opts.baseRef !== undefined ? { baseRef: opts.baseRef } : {}),
       ...(def.meta.defaults !== undefined ? { workflowDefaults: def.meta.defaults } : {}),
+      ...(opts.uiCatalog !== undefined ? { uiCatalog: opts.uiCatalog } : {}),
     });
     const lease = await this.claimRun(runId);
     // The appended records flow into launch as the projection seed: the run is not
@@ -508,12 +516,14 @@ export class Engine implements EngineHost {
     // The caller's hash names the definition the CALLER brought; a registry lookup here
     // brings its own, and mixing them would compare one script's stamp against another's.
     let bundleHash = opts.def !== undefined ? opts.defHash : undefined;
+    let uiCatalog = opts.def !== undefined ? opts.uiCatalog : undefined;
     if (!def && this.registry) {
       const resolved = await resolveRegistryWorkflow(this.registry, created.workflow);
       if (resolved) {
         def = resolved.def;
         workflowName = resolved.name;
         bundleHash = resolved.hash;
+        uiCatalog = resolved.uiCatalog;
       }
     }
     if (!def) {
@@ -525,6 +535,7 @@ export class Engine implements EngineHost {
     const resumeOpts: ResumeOptions = {
       ...opts,
       ...(bundleHash !== undefined ? { defHash: bundleHash } : {}),
+      ...(uiCatalog !== undefined ? { uiCatalog } : {}),
     };
 
     // The journal holds the RAW input; reapply the schema so a transform hands the
@@ -648,6 +659,7 @@ export class Engine implements EngineHost {
       replay,
       ...(created.baseRef !== undefined ? { baseRef: created.baseRef } : {}),
       ...(def.meta.defaults !== undefined ? { workflowDefaults: def.meta.defaults } : {}),
+      ...(opts.uiCatalog !== undefined ? { uiCatalog: opts.uiCatalog } : {}),
     });
     return this.launch(runtime, def, input, records, lease);
   }
@@ -1272,6 +1284,7 @@ export class Engine implements EngineHost {
           standing = true;
         } else if (r.ev.type === "human.answered" && r.ev.id === requestId) standing = false;
         else if (r.ev.type === "human.rejected" && r.ev.id === requestId) standing = true;
+        else if (r.ev.type === "human.superseded" && r.ev.id === requestId) standing = false;
       }
       if (requested && standing) return { pending: childId };
       if (requested) out.requested ??= childId;
@@ -1307,6 +1320,7 @@ export class Engine implements EngineHost {
   ): Promise<{ output: unknown; usage: import("@techery/weft-sdk").Usage; childRunId: string }> {
     const parent = spec.parent;
     let def: WorkflowDefinition | undefined;
+    let uiCatalog: CompiledUiCatalog | undefined;
     if (spec.def !== undefined) {
       if (!isWorkflowDefinition(spec.def)) {
         throw new StepError("invalid_input", `ctx.workflow: not a workflow definition`, {
@@ -1314,8 +1328,13 @@ export class Engine implements EngineHost {
         });
       }
       def = spec.def;
+      uiCatalog = parent.uiCatalog;
     } else {
-      def = await this.registry?.get(spec.name);
+      const resolved = this.registry
+        ? await resolveRegistryWorkflow(this.registry, { name: spec.name })
+        : undefined;
+      def = resolved?.def;
+      uiCatalog = resolved?.uiCatalog;
     }
     if (!def) {
       throw new StepError("invalid_input", `workflow "${spec.name}" not found in the registry`, {
@@ -1487,6 +1506,7 @@ export class Engine implements EngineHost {
       ...(replay !== undefined ? { replay } : {}),
       ...(parent.baseRef !== undefined ? { baseRef: parent.baseRef } : {}),
       ...(def.meta.defaults !== undefined ? { workflowDefaults: def.meta.defaults } : {}),
+      ...(uiCatalog !== undefined ? { uiCatalog } : {}),
     });
     if (!resuming) {
       // Seed launch with the appended record for the same reason start() does: the
@@ -1673,10 +1693,13 @@ export class Engine implements EngineHost {
         // Distinguish "already answered" (a serialized concurrent caller lost
         // the race) from an id nobody ever requested.
         let standing = false;
+        let superseded = false;
         for (const r of active.records) {
           if (r.ev.type === "human.answered" && r.ev.id === requestId) standing = true;
           else if (r.ev.type === "human.rejected" && r.ev.id === requestId) standing = false;
+          else if (r.ev.type === "human.superseded" && r.ev.id === requestId) superseded = true;
         }
+        if (superseded) throw new Error(`run ${runId}: request ${requestId} was superseded`);
         if (standing) throw new Error(`run ${runId}: request ${requestId} is already answered`);
         throw new Error(`run ${runId}: no pending request ${requestId}`);
       }
@@ -1763,6 +1786,9 @@ export class Engine implements EngineHost {
         if (owner !== undefined) return this.answer(owner, requestId, answer, opts);
         throw new Error(`run ${runId}: no request ${requestId}`);
       }
+      if (records.some((r) => r.ev.type === "human.superseded" && r.ev.id === requestId)) {
+        throw new Error(`run ${runId}: request ${requestId} was superseded`);
+      }
       // A TERMINAL run cannot consume an answer: accepting one against a
       // journal that already holds run.cancelled/completed/failed reports
       // success for a request nothing will ever serve. Resume the run first —
@@ -2083,11 +2109,13 @@ export class Engine implements EngineHost {
     if (created?.type !== "run.created") throw new Error(`run ${runId}: missing run.created`);
     let def = opts.def;
     let workflowName = def?.meta.name ?? created.workflow.name;
+    let uiCatalog = opts.def !== undefined ? opts.uiCatalog : undefined;
     if (!def && this.registry) {
       const resolved = await resolveRegistryWorkflow(this.registry, created.workflow);
       if (resolved) {
         def = resolved.def;
         workflowName = resolved.name;
+        uiCatalog = resolved.uiCatalog;
       }
     }
     if (!def) throw new Error(`run ${runId}: no definition for "${created.workflow.name}"`);
@@ -2119,6 +2147,7 @@ export class Engine implements EngineHost {
       dry: true,
       ...(created.baseRef !== undefined ? { baseRef: created.baseRef } : {}),
       ...(def.meta.defaults !== undefined ? { workflowDefaults: def.meta.defaults } : {}),
+      ...(uiCatalog !== undefined ? { uiCatalog } : {}),
     });
     // Same input the real resume would hand the code: raw from the journal, schema reapplied.
     const inputCheck = await validateSchema(def.meta.input, created.input === undefined ? {} : created.input);
diff --git a/packages/core/src/events.ts b/packages/core/src/events.ts
index bf6a8dd9..c2c336b2 100644
--- a/packages/core/src/events.ts
+++ b/packages/core/src/events.ts
@@ -29,6 +29,7 @@ export type StepKind =
   | "check"
   | "sleep"
   | "signal"
+  | "ui"
   | "sideeffect";
 
 /** Reference to a blob in the content-addressed store. */
@@ -39,6 +40,21 @@ export interface BlobRefJson {
   preview?: string;
 }
 
+export type UiPropsJson = { inline: unknown; hash: string } | { ref: BlobRefJson; hash: string };
+
+export interface UiPresentation {
+  id: string;
+  asset: {
+    id: string;
+    revision: string;
+    bundleRef: BlobRefJson;
+    protocol: 1;
+  };
+  props: UiPropsJson;
+  mode: "display" | "input";
+  slot?: string;
+}
+
 export type HumanKind = "gate" | "ask" | "approve" | "review" | "confirm";
 
 export interface HumanRequestEvent {
@@ -46,6 +62,7 @@ export interface HumanRequestEvent {
   id: string;
   seq: number;
   hash: string;
+  key?: string;
   kind: HumanKind;
   question: string;
   detail?: string;
@@ -58,6 +75,14 @@ export interface HumanRequestEvent {
   timeoutDefault?: unknown;
   /** Token the answer must echo for irreversible confirmations. */
   confirmToken?: string;
+  ui?: UiPresentation;
+}
+
+export interface HumanSupersededEvent {
+  type: "human.superseded";
+  id: string;
+  byId: string;
+  reason: string;
 }
 
 export interface HumanAnsweredEvent {
@@ -140,6 +165,7 @@ export type JournalEvent =
       transcriptRef?: BlobRefJson;
       patchRef?: string;
       attempts?: number;
+      presentation?: UiPresentation;
     }
   /** `settle` means execution completed and only its journal-backed side effects failed. */
   | {
@@ -155,6 +181,7 @@ export type JournalEvent =
   | HumanRequestEvent
   | HumanAnsweredEvent
   | HumanRejectedEvent
+  | HumanSupersededEvent
   | { type: "signal.received"; name: string; payload: unknown }
   // A delivered payload the waiting step REFUSED (schema violation): replay must
   // treat that delivery as consumed, or resume re-takes it ahead of any
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 2520ec8e..930491d1 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -41,10 +41,13 @@ export type {
   HumanAnsweredEvent,
   HumanKind,
   HumanRequestEvent,
+  HumanSupersededEvent,
   JournalEvent,
   JournalRecord,
   RunStatus,
   StepKind,
+  UiPresentation,
+  UiPropsJson,
 } from "./events.ts";
 export { isBlobRef, TERMINAL_STATUSES } from "./events.ts";
 export type { TestHooks } from "./hooks.ts";
diff --git a/packages/core/src/projections.ts b/packages/core/src/projections.ts
index ecfb5645..9fd1e1a3 100644
--- a/packages/core/src/projections.ts
+++ b/packages/core/src/projections.ts
@@ -3,7 +3,7 @@
  * journal — re-derivable at any time, never a source of truth.
  */
 import type { Risk, SerializedStepError, Usage } from "@techery/weft-sdk";
-import type { BlobRefJson, JournalRecord, RunStatus, StepKind } from "./events.ts";
+import type { BlobRefJson, JournalRecord, RunStatus, StepKind, UiPresentation } from "./events.ts";
 
 export interface StepState {
   seq: number;
@@ -27,22 +27,25 @@ export interface StepState {
   transcriptRef?: BlobRefJson;
   patchRef?: string;
   childRunId?: string;
+  presentation?: UiPresentation;
 }
 
 export interface HumanState {
   id: string;
   seq: number;
+  key?: string;
   kind: string;
   question: string;
   detail?: string;
   risk?: Risk;
   schema: unknown;
-  status: "pending" | "answered";
+  status: "pending" | "answered" | "superseded";
   answer?: unknown;
   answeredBy?: string;
   deadline?: number;
   confirmToken?: string;
   artifactRef?: BlobRefJson;
+  ui?: UiPresentation;
   requestedAt: number;
 }
 
@@ -215,6 +218,7 @@ export function reduceState(records: JournalRecord[]): RunState {
         if (ev.sessionId !== undefined) step.sessionId = ev.sessionId;
         if (ev.transcriptRef !== undefined) step.transcriptRef = ev.transcriptRef;
         if (ev.patchRef !== undefined) step.patchRef = ev.patchRef;
+        if (ev.presentation !== undefined) step.presentation = ev.presentation;
         if (step.kind === "check") {
           const out = ev.output as { status?: CheckState["status"]; evidence?: string } | null;
           const meta = checkMetaBySeq.get(ev.seq);
@@ -256,11 +260,13 @@ export function reduceState(records: JournalRecord[]): RunState {
           schema: ev.schema,
           status: "pending",
           requestedAt: rec.at,
+          ...(ev.key !== undefined ? { key: ev.key } : {}),
           ...(ev.detail !== undefined ? { detail: ev.detail } : {}),
           ...(ev.risk !== undefined ? { risk: ev.risk } : {}),
           ...(ev.deadline !== undefined ? { deadline: ev.deadline } : {}),
           ...(ev.confirmToken !== undefined ? { confirmToken: ev.confirmToken } : {}),
           ...(ev.artifactRef !== undefined ? { artifactRef: ev.artifactRef } : {}),
+          ...(ev.ui !== undefined ? { ui: ev.ui } : {}),
         };
         humansById.set(ev.id, human);
         state.humans.push(human);
@@ -285,6 +291,11 @@ export function reduceState(records: JournalRecord[]): RunState {
         delete human.answeredBy;
         break;
       }
+      case "human.superseded": {
+        const human = humansById.get(ev.id);
+        if (human) human.status = "superseded";
+        break;
+      }
       case "note":
         state.notes.push({
           kind: ev.kind,
diff --git a/packages/core/src/replay.ts b/packages/core/src/replay.ts
index 99c54c42..a5ac4877 100644
--- a/packages/core/src/replay.ts
+++ b/packages/core/src/replay.ts
@@ -39,9 +39,11 @@ export interface HumanEntry {
   id: string;
   hash: string;
   seq: number;
+  key?: string;
   request: HumanRequestEvent;
   answer?: { answer: unknown; answeredBy: "human" | "policy" | "timeout"; order: number };
   consumed: boolean;
+  superseded: boolean;
 }
 
 export interface ScheduledEntry {
@@ -69,6 +71,7 @@ export class ReplayIndex {
   readonly byKey = new Map<string, CompletedEntry[]>();
   readonly humansByHash = new Map<string, HumanEntry[]>();
   readonly humansById = new Map<string, HumanEntry>();
+  readonly humansByKey = new Map<string, HumanEntry[]>();
   readonly scheduledByHash = new Map<string, ScheduledEntry[]>();
   readonly signalsByName = new Map<string, SignalEntry[]>();
   /**
@@ -218,17 +221,35 @@ export class ReplayIndex {
           break;
         }
         case "human.requested": {
-          const entry: HumanEntry = { id: ev.id, hash: ev.hash, seq: ev.seq, request: ev, consumed: false };
+          const entry: HumanEntry = {
+            id: ev.id,
+            hash: ev.hash,
+            seq: ev.seq,
+            request: ev,
+            consumed: false,
+            superseded: false,
+            ...(ev.key !== undefined ? { key: ev.key } : {}),
+          };
           const list = index.humansByHash.get(ev.hash) ?? [];
           list.push(entry);
           index.humansByHash.set(ev.hash, list);
           index.humansById.set(ev.id, entry);
+          if (ev.key !== undefined) {
+            const keyed = index.humansByKey.get(ev.key) ?? [];
+            keyed.push(entry);
+            index.humansByKey.set(ev.key, keyed);
+          }
           index.maxSeq = Math.max(index.maxSeq, ev.seq);
           const num = /^h(\d+)$/.exec(ev.id);
           if (num) index.maxHumanId = Math.max(index.maxHumanId, Number(num[1]));
           index.entryCount++;
           break;
         }
+        case "human.superseded": {
+          const entry = index.humansById.get(ev.id);
+          if (entry) entry.superseded = true;
+          break;
+        }
         case "human.answered": {
           // FIRST standing answer wins: two processes racing past the answered-guard
           // can both append, and the owner delivered the first — replay must agree.
@@ -353,9 +374,10 @@ export class ReplayIndex {
     hash: string,
     seq?: number,
     positionsTrusted = true,
+    key?: string,
   ): { entry: HumanEntry; ambiguous?: true } | undefined {
-    const sameHash = this.humansByHash.get(hash) ?? [];
-    const ambiguousKeyless = sameHash.length > 1;
+    const sameHash = (this.humansByHash.get(hash) ?? []).filter((entry) => !entry.superseded);
+    const ambiguousKeyless = key === undefined && sameHash.length > 1;
 
     if (seq !== undefined) {
       const onPosition = sameHash.find((e) => !e.consumed && e.seq === seq);
@@ -370,6 +392,13 @@ export class ReplayIndex {
     return ambiguousKeyless ? { entry, ambiguous: true } : { entry };
   }
 
+  /** An older unanswered request at this call site whose semantics changed. */
+  pendingHumanByKey(key: string): HumanEntry | undefined {
+    return this.humansByKey
+      .get(key)
+      ?.find((entry) => !entry.consumed && !entry.superseded && entry.answer === undefined);
+  }
+
   matchIncompleteScheduled(hash: string, kind: StepKind): ScheduledEntry | undefined {
     return this.scheduledByHash.get(hash)?.find((e) => !e.consumed && !e.completed && e.kind === kind);
   }
diff --git a/packages/core/src/runtime.ts b/packages/core/src/runtime.ts
index e34a8406..2f21fbdd 100644
--- a/packages/core/src/runtime.ts
+++ b/packages/core/src/runtime.ts
@@ -8,6 +8,9 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import {
   type AnySchema,
   CancelledError,
+  type CompiledUiAsset,
+  type CompiledUiCatalog,
+  type CompiledUiViewToken,
   type GateResult,
   isCancellation,
   type Risk,
@@ -28,6 +31,7 @@ import type {
   JournalRecord,
   RunStatus,
   StepKind,
+  UiPresentation,
 } from "./events.ts";
 import { jsonUnsafeAt, unwrapWireValue, wrapWireValue } from "./jsonschema.ts";
 import type { Semaphore } from "./limiter.ts";
@@ -67,6 +71,7 @@ export interface PendingRequest {
   deadline?: number;
   confirmToken?: string;
   artifactRef?: BlobRefJson;
+  ui?: UiPresentation;
 }
 
 export interface ChildRunSpec {
@@ -167,6 +172,7 @@ export interface StepOutcome<T> {
   transcriptRef?: BlobRefJson;
   patchRef?: string;
   attempts?: number;
+  presentation?: UiPresentation;
 }
 
 export interface StepSpec<T> {
@@ -207,6 +213,7 @@ interface HumanSpec {
   artifactRef?: BlobRefJson;
   /** Policy auto-approval: append request+answer in one batch, never wait. */
   auto?: boolean;
+  ui?: { view: unknown; props: unknown };
 }
 
 export interface HumanOutcome {
@@ -247,6 +254,7 @@ export interface RunRuntimeOptions {
   shared: SharedRunResources;
   replay?: ReplayIndex;
   workflowDefaults?: { provider?: string; model?: string; effort?: string };
+  uiCatalog?: CompiledUiCatalog;
   /** replay --dry: serve hits, record would-run steps, never execute or append. */
   dry?: boolean;
 }
@@ -266,6 +274,8 @@ export class RunRuntime {
   readonly replay: ReplayIndex | undefined;
   readonly delivery: OrderedDelivery;
   readonly workflowDefaults: { provider?: string; model?: string; effort?: string };
+  readonly uiCatalog: CompiledUiCatalog | undefined;
+  private readonly uiAssets: Map<string, CompiledUiAsset>;
 
   currentPhase: string | undefined;
   status: RunStatus = "planning";
@@ -322,6 +332,8 @@ export class RunRuntime {
     this.shared = opts.shared;
     this.replay = opts.replay;
     this.workflowDefaults = opts.workflowDefaults ?? {};
+    this.uiCatalog = opts.uiCatalog;
+    this.uiAssets = new Map((opts.uiCatalog?.assets ?? []).map((asset) => [asset.assetKey, asset]));
     this.humanCounter = opts.replay?.maxHumanId ?? 0;
     this.dry = opts.dry ?? false;
     this.dryIndex = (opts.replay?.maxJournalIndex ?? -1) + 1;
@@ -451,6 +463,83 @@ export class RunRuntime {
     return journaled;
   }
 
+  /** Resolve an opaque workflow token through the sealed compiler catalog and persist its durable data. */
+  async prepareUiPresentation(
+    view: unknown,
+    props: unknown,
+    mode: "display" | "input",
+    id: string,
+    slot?: string,
+  ): Promise<UiPresentation> {
+    if (
+      typeof view !== "object" ||
+      view === null ||
+      (view as { kind?: unknown }).kind !== "weft.ui-view" ||
+      typeof (view as { assetKey?: unknown }).assetKey !== "string"
+    ) {
+      throw new StepError("invalid_input", "UI view is not a compiled .ui.tsx token", {
+        step: { kind: "ui", runId: this.runId },
+      });
+    }
+    const token = view as CompiledUiViewToken;
+    const asset = this.uiAssets.get(token.assetKey);
+    if (!asset) {
+      throw new StepError(
+        "invalid_input",
+        `UI asset ${token.assetKey.slice(0, 12)} is not in this workflow build`,
+        {
+          step: { kind: "ui", runId: this.runId },
+        },
+      );
+    }
+    if (asset.mode !== mode) {
+      throw new StepError(
+        "invalid_input",
+        `UI view ${JSON.stringify(asset.id)} is ${asset.mode}, not ${mode}`,
+        { step: { kind: "ui", runId: this.runId } },
+      );
+    }
+    const bad = jsonUnsafeAt(props);
+    if (bad !== undefined) {
+      throw new StepError("invalid_input", `UI props cannot be journaled as JSON at ${bad}`, {
+        step: { kind: "ui", runId: this.runId },
+      });
+    }
+    const json = canonicalJson(props);
+    const propsHash = sha256Hex(json);
+    const propsJson =
+      Buffer.byteLength(json) <= this.host.config.limits.blobThresholdBytes
+        ? ({ inline: props, hash: propsHash } as const)
+        : await this.host.blobs.put(json, { kind: "ui-props", contentType: "application/json" }).then(
+            (ref) =>
+              ({
+                ref: { $blob: ref.hash, size: ref.size, preview: json.slice(0, 200) },
+                hash: propsHash,
+              }) as const,
+          );
+    const stored = await this.host.blobs.put(asset.code, {
+      kind: "ui-bundle",
+      contentType: "text/javascript; charset=utf-8",
+    });
+    if (stored.hash !== asset.hash) {
+      throw new StepError("internal", `compiled UI asset hash mismatch for ${asset.id}`, {
+        step: { kind: "ui", runId: this.runId },
+      });
+    }
+    return {
+      id,
+      asset: {
+        id: asset.id,
+        revision: asset.revision,
+        bundleRef: { $blob: stored.hash, size: stored.size },
+        protocol: 1,
+      },
+      props: propsJson,
+      mode,
+      ...(slot !== undefined ? { slot } : {}),
+    };
+  }
+
   // -- idle / wait tracking -------------------------------------------------
 
   hasPendingWaits(): boolean {
@@ -545,7 +634,10 @@ export class RunRuntime {
         hash,
         spec.kind,
         spec.key,
-        this.shared.reuse,
+        // A UI key names the presentation slot; it is not permission to reuse stale
+        // props or an older component revision. UI replay is therefore always
+        // content-addressed even when the run opts into key-based salvage elsewhere.
+        spec.kind === "ui" ? "content" : this.shared.reuse,
         this.shared.positionsTrusted !== false,
       );
       if (match?.ambiguous) {
@@ -768,6 +860,7 @@ export class RunRuntime {
               ...(outcome.sessionId !== undefined ? { sessionId: outcome.sessionId } : {}),
               ...(outcome.transcriptRef !== undefined ? { transcriptRef: outcome.transcriptRef } : {}),
               ...(outcome.patchRef !== undefined ? { patchRef: outcome.patchRef } : {}),
+              ...(outcome.presentation !== undefined ? { presentation: outcome.presentation } : {}),
               attempts: outcome.attempts ?? attempt,
             },
           ]);
@@ -933,6 +1026,9 @@ export class RunRuntime {
         }
       }
     }
+    const preparedUi = spec.ui
+      ? await this.prepareUiPresentation(spec.ui.view, spec.ui.props, "input", "pending")
+      : undefined;
     const payload = {
       kind: spec.kind,
       question: spec.question,
@@ -948,11 +1044,20 @@ export class RunRuntime {
       ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
       ...(spec.onTimeout !== undefined ? { onTimeout: spec.onTimeout } : {}),
       ...(spec.timeoutDefault !== undefined ? { timeoutDefault: spec.timeoutDefault } : {}),
+      ...(preparedUi !== undefined
+        ? {
+            ui: {
+              id: preparedUi.asset.id,
+              revision: preparedUi.asset.revision,
+              propsHash: preparedUi.props.hash,
+            },
+          }
+        : {}),
     };
     const hash = hashStep("human", payload, undefined, spec.key);
     const seq = ++this.seqCounter;
 
-    let match = this.replay?.matchHuman(hash, seq, this.shared.positionsTrusted !== false);
+    let match = this.replay?.matchHuman(hash, seq, this.shared.positionsTrusted !== false, spec.key);
     if (match?.ambiguous) {
       // Two human call sites share this question and schema, and the script moved, so
       // position cannot say which journaled answer belongs to this one. Re-ask instead
@@ -1022,6 +1127,7 @@ export class RunRuntime {
       id,
       seq,
       hash,
+      ...(spec.key !== undefined ? { key: spec.key } : {}),
       kind: spec.kind,
       question: spec.question,
       schema: spec.schemaJson ?? {},
@@ -1032,16 +1138,31 @@ export class RunRuntime {
       ...(spec.onTimeout !== undefined ? { onTimeout: spec.onTimeout } : {}),
       ...(spec.timeoutDefault !== undefined ? { timeoutDefault: spec.timeoutDefault } : {}),
       ...(spec.confirmToken !== undefined ? { confirmToken: spec.confirmToken } : {}),
+      ...(preparedUi !== undefined ? { ui: { ...preparedUi, id } } : {}),
     };
 
+    const superseded = spec.key !== undefined ? this.replay?.pendingHumanByKey(spec.key) : undefined;
+    const supersedeEvent: JournalEvent | undefined = superseded
+      ? {
+          type: "human.superseded",
+          id: superseded.id,
+          byId: id,
+          reason: "request semantics changed at the same durable key",
+        }
+      : undefined;
+
     if (spec.auto) {
       const answer = { approved: true };
       this.answeredIds.add(id); // the tailer will echo this append; never buffer it
-      await this.append([request, { type: "human.answered", id, answer, answeredBy: "policy" }]);
+      await this.append([
+        ...(supersedeEvent ? [supersedeEvent] : []),
+        request,
+        { type: "human.answered", id, answer, answeredBy: "policy" },
+      ]);
       return { answer, answeredBy: "policy" };
     }
 
-    await this.append([request]);
+    await this.append([...(supersedeEvent ? [supersedeEvent] : []), request]);
     return this.awaitAnswer(request, spec.realSchema, spec.wrapped ?? false);
   }
 
@@ -1102,6 +1223,7 @@ export class RunRuntime {
       ...(request.risk !== undefined ? { risk: request.risk } : {}),
       ...(request.deadline !== undefined ? { deadline: request.deadline } : {}),
       ...(request.confirmToken !== undefined ? { confirmToken: request.confirmToken } : {}),
+      ...(request.ui !== undefined ? { ui: request.ui } : {}),
     });
     return new Promise<HumanOutcome>((resolve, reject) => {
       const wait: PendingWait = {
diff --git a/packages/core/test/ui.test.ts b/packages/core/test/ui.test.ts
new file mode 100644
index 00000000..19d7d753
--- /dev/null
+++ b/packages/core/test/ui.test.ts
@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import type { JournalRecord } from "@techery/weft-core";
+import {
+  type CompiledUiCatalog,
+  type DisplayUiView,
+  defineWorkflow,
+  type InputUiView,
+  z,
+} from "@techery/weft-sdk";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanupRepos, reopen, tempDir, testEngine } from "./helpers.ts";
+
+afterAll(cleanupRepos);
+
+const assetKey = "a".repeat(64);
+
+function catalog(revision = "1", mode: "display" | "input" = "display"): CompiledUiCatalog {
+  const code = `console.log(${JSON.stringify({ revision, mode })})`;
+  const hash = createHash("sha256").update(code).digest("hex");
+  return {
+    buildHash: createHash("sha256").update(`${revision}:${mode}:${hash}`).digest("hex"),
+    assets: [{ assetKey, id: "test-view", revision, mode, protocol: 1, code, hash }],
+  };
+}
+
+async function records(
+  journal: { read(runId: string): AsyncIterable<JournalRecord> },
+  runId: string,
+): Promise<JournalRecord[]> {
+  const out: JournalRecord[] = [];
+  for await (const record of journal.read(runId)) out.push(record);
+  return out;
+}
+
+describe("custom workflow UI", () => {
+  test("ctx.ui.render journals a replayable presentation with durable bundle and props", async () => {
+    const t = testEngine();
+    const view = { kind: "weft.ui-view", assetKey } as unknown as DisplayUiView<{ message: string }>;
+    const def = defineWorkflow(
+      { description: "ui", input: z.object({}), output: z.object({ ok: z.boolean() }) },
+      async (ctx) => {
+        await ctx.ui.render({ key: "summary", slot: "main", view, props: { message: "hello" } });
+        return { ok: true };
+      },
+    );
+    const cwd = await tempDir();
+    const handle = await t.engine.start(def, { input: {}, cwd, uiCatalog: catalog() });
+    await expect(handle.result).resolves.toEqual({ ok: true });
+
+    const state = await t.engine.state(handle.runId);
+    const uiStep = state.steps.find((step) => step.kind === "ui");
+    expect(uiStep?.presentation).toMatchObject({
+      asset: { id: "test-view", revision: "1", protocol: 1 },
+      props: { inline: { message: "hello" } },
+      mode: "display",
+      slot: "main",
+    });
+    expect(await t.blobs.getText(uiStep!.presentation!.asset.bundleRef.$blob)).toContain("console.log");
+
+    const second = reopen(t);
+    const resumed = await second.engine.resume(handle.runId, { def, uiCatalog: catalog() });
+    await expect(resumed.result).resolves.toEqual({ ok: true });
+    const completions = (await records(t.journal, handle.runId)).filter(
+      (record) => record.ev.type === "step.completed" && record.ev.presentation !== undefined,
+    );
+    expect(completions).toHaveLength(1);
+  });
+
+  test("input views stage durable UI while the schema remains authoritative", async () => {
+    const t = testEngine();
+    const Answer = z.object({ choice: z.enum(["a", "b"]) });
+    const view = { kind: "weft.ui-view", assetKey } as unknown as InputUiView<
+      { choices: string[] },
+      z.input<typeof Answer>
+    >;
+    const def = defineWorkflow(
+      { description: "input-ui", input: z.object({}), output: Answer },
+      async (ctx) =>
+        ctx.human.ask({
+          key: "choice",
+          question: "Choose",
+          schema: Answer,
+          ui: { view, props: { choices: ["a", "b"] } },
+        }),
+    );
+    const handle = await t.engine.start(def, {
+      input: {},
+      cwd: await tempDir(),
+      uiCatalog: catalog("1", "input"),
+    });
+    const waiting = await handle.outcome();
+    if (waiting.status !== "waiting_for_human") throw new Error("expected human request");
+    expect(waiting.pending[0]?.ui).toMatchObject({
+      asset: { id: "test-view", revision: "1" },
+      mode: "input",
+    });
+    await expect(t.engine.answer(handle.runId, waiting.pending[0]!.id, { choice: "nope" })).rejects.toThrow(
+      /does not match/,
+    );
+    await t.engine.answer(handle.runId, waiting.pending[0]!.id, { choice: "a" });
+    await expect(handle.result).resolves.toEqual({ choice: "a" });
+  });
+
+  test("a changed input-view revision supersedes the old same-key request", async () => {
+    const first = testEngine();
+    const Answer = z.object({ choice: z.string() });
+    const view = { kind: "weft.ui-view", assetKey } as unknown as InputUiView<
+      Record<string, never>,
+      z.input<typeof Answer>
+    >;
+    const def = defineWorkflow(
+      { description: "supersede", input: z.object({}), output: Answer },
+      async (ctx) =>
+        ctx.human.ask({ key: "choice", question: "Choose", schema: Answer, ui: { view, props: {} } }),
+    );
+    const handle = await first.engine.start(def, {
+      input: {},
+      cwd: await tempDir(),
+      uiCatalog: catalog("1", "input"),
+    });
+    const waiting = await handle.outcome();
+    if (waiting.status !== "waiting_for_human") throw new Error("expected human request");
+    const oldId = waiting.pending[0]!.id;
+    await first.engine.shutdown();
+
+    const second = reopen(first);
+    const resumed = await second.engine.resume(handle.runId, { def, uiCatalog: catalog("2", "input") });
+    const next = await resumed.outcome();
+    if (next.status !== "waiting_for_human") throw new Error("expected replacement request");
+    expect(next.pending[0]?.id).not.toBe(oldId);
+    const state = await second.engine.state(handle.runId);
+    expect(state.humans.find((human) => human.id === oldId)?.status).toBe("superseded");
+    await expect(second.engine.answer(handle.runId, oldId, { choice: "old" })).rejects.toThrow(/superseded/);
+    await second.engine.answer(handle.runId, next.pending[0]!.id, { choice: "new" });
+    await expect(resumed.result).resolves.toEqual({ choice: "new" });
+  });
+
+  test("UI slots never key-reuse a presentation when its props change", async () => {
+    const t = testEngine();
+    const view = { kind: "weft.ui-view", assetKey } as unknown as DisplayUiView<{ message: string }>;
+    const workflow = (message: string) =>
+      defineWorkflow(
+        { description: "ui-reuse", input: z.object({}), output: z.object({ ok: z.boolean() }) },
+        async (ctx) => {
+          await ctx.ui.render({ key: "summary", view, props: { message } });
+          return { ok: true };
+        },
+      );
+    const handle = await t.engine.start(workflow("first"), {
+      input: {},
+      cwd: await tempDir(),
+      uiCatalog: catalog(),
+      reuse: "key",
+    });
+    await expect(handle.result).resolves.toEqual({ ok: true });
+
+    const second = reopen(t);
+    const resumed = await second.engine.resume(handle.runId, {
+      def: workflow("second"),
+      uiCatalog: catalog(),
+      reuse: "key",
+    });
+    await expect(resumed.result).resolves.toEqual({ ok: true });
+    const completions = (await records(t.journal, handle.runId)).filter(
+      (record) => record.ev.type === "step.completed" && record.ev.presentation !== undefined,
+    );
+    expect(completions).toHaveLength(2);
+    expect(completions.at(-1)?.ev).toMatchObject({
+      presentation: { props: { inline: { message: "second" } } },
+    });
+  });
+});
diff --git a/packages/daemon/src/api/presentations.ts b/packages/daemon/src/api/presentations.ts
new file mode 100644
index 00000000..401b1a1d
--- /dev/null
+++ b/packages/daemon/src/api/presentations.ts
@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import type { UiPresentation, Weft } from "@techery/weft-host";
+import type { Hono } from "hono";
+import { fail } from "../http.ts";
+import { stateOf } from "../state.ts";
+
+const PRESENTATION_ID = /^[a-z][a-z0-9-]{0,63}$/i;
+const MAX_BUNDLE_BYTES = 1_000_000;
+
+/** Serve only bundle refs sealed into this run's journal; generic blobs never become executable. */
+export function registerPresentationRoutes(app: Hono, weft: Weft): void {
+  app.get("/api/runs/:id/presentations/:presentationId/frame", async (c) => {
+    try {
+      const runId = c.req.param("id");
+      const presentationId = c.req.param("presentationId");
+      if (!PRESENTATION_ID.test(presentationId)) throw new Error("invalid presentation id");
+      const state = await stateOf(weft, runId);
+      const presentation = findPresentation(state, presentationId);
+      if (!presentation) throw new Error(`presentation ${presentationId} not found in run ${runId}`);
+      if (presentation.asset.protocol !== 1) {
+        throw new Error(`unsupported UI protocol ${presentation.asset.protocol}`);
+      }
+      if (presentation.asset.bundleRef.size > MAX_BUNDLE_BYTES) throw new Error("UI bundle is oversized");
+      const code = await weft.engine.blobs.getText(presentation.asset.bundleRef.$blob);
+      if (Buffer.byteLength(code) !== presentation.asset.bundleRef.size) {
+        throw new Error("UI bundle size does not match its journaled descriptor");
+      }
+      // Prevent an authored string literal from terminating the server-owned script element.
+      const inlineCode = code.replaceAll("</script", "<\\/script");
+      const scriptHash = createHash("sha256").update(inlineCode).digest("base64");
+      const html = frameHtml(inlineCode);
+      const csp = [
+        "default-src 'none'",
+        `script-src 'sha256-${scriptHash}'`,
+        "style-src 'unsafe-inline'",
+        "img-src data: blob:",
+        "connect-src 'none'",
+        "font-src 'none'",
+        "media-src 'none'",
+        "object-src 'none'",
+        "frame-src 'none'",
+        "worker-src 'none'",
+        "form-action 'none'",
+        "base-uri 'none'",
+        "sandbox allow-scripts",
+        "frame-ancestors 'self'",
+      ].join("; ");
+      return c.body(html, 200, {
+        "content-type": "text/html; charset=utf-8",
+        "content-security-policy": csp,
+        "x-content-type-options": "nosniff",
+        "referrer-policy": "no-referrer",
+        "cross-origin-resource-policy": "same-origin",
+        "permissions-policy":
+          "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), bluetooth=()",
+        "cache-control": "no-store",
+      });
+    } catch (err) {
+      return fail(c, err);
+    }
+  });
+}
+
+function findPresentation(
+  state: Awaited<ReturnType<typeof stateOf>>,
+  id: string,
+): UiPresentation | undefined {
+  for (let index = state.steps.length - 1; index >= 0; index--) {
+    const presentation = state.steps[index]?.presentation;
+    if (presentation?.id === id) return presentation;
+  }
+  for (let index = state.humans.length - 1; index >= 0; index--) {
+    const presentation = state.humans[index]?.ui;
+    if (presentation?.id === id) return presentation;
+  }
+  return undefined;
+}
+
+function frameHtml(code: string): string {
+  return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <style>html,body,#root{margin:0;min-height:1px}body{font:14px system-ui,sans-serif;color:#161616;background:transparent}</style>
+</head>
+<body><div id="root"></div><script>${code}</script></body>
+</html>`;
+}
diff --git a/packages/daemon/src/api/starts.ts b/packages/daemon/src/api/starts.ts
index 77b23ddb..249c2516 100644
--- a/packages/daemon/src/api/starts.ts
+++ b/packages/daemon/src/api/starts.ts
@@ -65,6 +65,7 @@ export function registerStartRoutes(app: Hono, weft: Weft): void {
         input,
         cwd: weft.cwd,
         ...(resolved.hash !== undefined ? { defHash: resolved.hash } : {}),
+        ...(resolved.uiCatalog !== undefined ? { uiCatalog: resolved.uiCatalog } : {}),
         ...(budget !== undefined ? { budget } : {}),
         ...(reuse !== undefined ? { reuse } : {}),
       };
diff --git a/packages/daemon/src/app.ts b/packages/daemon/src/app.ts
index a268f45e..69c239e4 100644
--- a/packages/daemon/src/app.ts
+++ b/packages/daemon/src/app.ts
@@ -26,6 +26,7 @@ import { registerBlobRoutes } from "./api/blobs.ts";
 import { registerConfigRoutes } from "./api/config.ts";
 import { registerMetaRoutes } from "./api/meta.ts";
 import { registerPendingRoutes } from "./api/pending.ts";
+import { registerPresentationRoutes } from "./api/presentations.ts";
 import { registerStartRoutes } from "./api/starts.ts";
 import { registerWorkflowRoutes } from "./api/workflows.ts";
 import { detailOf } from "./detail.ts";
@@ -307,6 +308,7 @@ export function createApp(weft: Weft, opts: CreateAppOptions = {}): Hono {
   registerWorkflowRoutes(app, weft);
   registerStartRoutes(app, weft);
   registerBlobRoutes(app, weft);
+  registerPresentationRoutes(app, weft);
   registerArtifactRoutes(app, weft);
   registerConfigRoutes(app, weft);
 
diff --git a/packages/daemon/src/index.ts b/packages/daemon/src/index.ts
index 66aa20bb..62e175a5 100644
--- a/packages/daemon/src/index.ts
+++ b/packages/daemon/src/index.ts
@@ -27,6 +27,7 @@ export { registerBlobRoutes } from "./api/blobs.ts";
 export { registerConfigRoutes } from "./api/config.ts";
 export { registerMetaRoutes } from "./api/meta.ts";
 export { type PendingEntry, registerPendingRoutes } from "./api/pending.ts";
+export { registerPresentationRoutes } from "./api/presentations.ts";
 export { registerStartRoutes } from "./api/starts.ts";
 export { registerWorkflowRoutes } from "./api/workflows.ts";
 export { type CreateAppOptions, createApp } from "./app.ts";
diff --git a/packages/daemon/src/state.ts b/packages/daemon/src/state.ts
index 22ad5c7b..027459d9 100644
--- a/packages/daemon/src/state.ts
+++ b/packages/daemon/src/state.ts
@@ -65,6 +65,7 @@ export function pendingOf(state: RunState): PendingRequest[] {
       ...(human.deadline !== undefined ? { deadline: human.deadline } : {}),
       ...(human.confirmToken !== undefined ? { confirmToken: human.confirmToken } : {}),
       ...(human.artifactRef !== undefined ? { artifactRef: human.artifactRef } : {}),
+      ...(human.ui !== undefined ? { ui: human.ui } : {}),
     }));
 }
 
diff --git a/packages/daemon/test/api.test.ts b/packages/daemon/test/api.test.ts
index 07c34364..6be20d63 100644
--- a/packages/daemon/test/api.test.ts
+++ b/packages/daemon/test/api.test.ts
@@ -412,6 +412,62 @@ describe("GET /api/blobs/:ref", () => {
   });
 });
 
+describe("GET /api/runs/:id/presentations/:presentationId/frame", () => {
+  it("serves only the bundle sealed into a presentation event with strict frame headers", async () => {
+    const cwd = await repo();
+    await writeFile(
+      path.join(cwd, ".weft", "workflows", "panel.ui.tsx"),
+      [
+        `import { defineResultView } from "@techery/weft-sdk/ui";`,
+        `export default defineResultView<{ message: string }>({`,
+        `  id: "panel", revision: "1",`,
+        `  component: ({ props }) => <strong>{props.message}</strong>,`,
+        `});`,
+      ].join("\n"),
+      "utf8",
+    );
+    await writeFile(
+      path.join(cwd, ".weft", "workflows", "panel.ts"),
+      [
+        `import { defineWorkflow, z } from "@techery/weft-sdk";`,
+        `import panel from "./panel.ui.tsx";`,
+        `export default defineWorkflow(`,
+        `  { name: "panel", description: "panel", input: z.object({}), output: z.object({ ok: z.boolean() }) },`,
+        `  async (ctx) => { await ctx.ui.render({ key: "panel", view: panel, props: { message: "hello" } }); return { ok: true }; },`,
+        `);`,
+      ].join("\n"),
+      "utf8",
+    );
+    const weft = await createWeft({ cwd, providers: "mock" });
+    opened.push(weft);
+    const resolved = await resolveWorkflow(weft, "panel");
+    const run = await weft.engine.start(resolved.def, {
+      input: {},
+      cwd,
+      defHash: resolved.hash,
+      uiCatalog: resolved.uiCatalog,
+    });
+    await run.result;
+    const state = await weft.engine.state(run.runId);
+    const presentation = state.steps.find((step) => step.presentation)?.presentation;
+    expect(presentation).toBeDefined();
+
+    const app = createApp(weft, { web: null });
+    const response = await app.request(`/api/runs/${run.runId}/presentations/${presentation!.id}/frame`);
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-security-policy")).toContain("default-src 'none'");
+    expect(response.headers.get("content-security-policy")).toContain("sandbox allow-scripts");
+    expect(response.headers.get("content-security-policy")).toContain("frame-ancestors 'self'");
+    expect(response.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(response.headers.get("referrer-policy")).toBe("no-referrer");
+    expect(await response.text()).toContain("weft.ui.init");
+
+    await weft.engine.blobs.put("alert('not journaled')", { kind: "ui-bundle" });
+    const arbitrary = await app.request(`/api/runs/${run.runId}/presentations/not-recorded/frame`);
+    expect(arbitrary.status).toBe(404);
+  });
+});
+
 describe("GET /api/runs/:id/artifacts and /patch", () => {
   it("inventories what a run produced, and says what is still readable", async () => {
     const cwd = await repo();
diff --git a/packages/gate/package.json b/packages/gate/package.json
index 6f9c7500..143b8a0f 100644
--- a/packages/gate/package.json
+++ b/packages/gate/package.json
@@ -56,6 +56,8 @@
   "dependencies": {
     "@techery/weft-sdk": "workspace:*",
     "esbuild": "^0.28.2",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "typescript": "~5.9.3",
     "zod": "^4.4.3"
   }
diff --git a/packages/gate/src/bundle.ts b/packages/gate/src/bundle.ts
index 67478edb..a38123bf 100644
--- a/packages/gate/src/bundle.ts
+++ b/packages/gate/src/bundle.ts
@@ -12,8 +12,10 @@
 import { createHash } from "node:crypto";
 import { readFile, realpath } from "node:fs/promises";
 import path from "node:path";
+import type { CompiledUiCatalog } from "@techery/weft-sdk";
 import { type BuildFailure, build, type Loader, type Message, type Plugin } from "esbuild";
 import { checkSource, type GateDiagnostic, GateError, resolveAllowBare } from "./rules.ts";
+import { compileUiCatalog, discoverUiViews, uiMessageToDiagnostic } from "./ui-bundle.ts";
 
 export interface BundleOptions {
   /** Path to the workflow file; relative paths resolve against `cwd`. */
@@ -30,6 +32,10 @@ export interface BundleResult {
   code: string;
   /** SHA-256 hex of `code` — the workflow's content version. */
   hash: string;
+  /** Hash of browser assets and metadata; intentionally independent from the Node definition hash. */
+  buildHash: string;
+  /** Browser programs discovered through `.ui.tsx` imports. */
+  uiCatalog: CompiledUiCatalog;
   /** Non-fatal notes (esbuild warnings). Rule violations throw, so they never appear here. */
   diagnostics: GateDiagnostic[];
 }
@@ -54,6 +60,7 @@ export async function bundleWorkflow(opts: BundleOptions): Promise<BundleResult>
   const requestedCwd = opts.cwd ? requestedBase : entry ? path.dirname(entry) : requestedBase;
   const cwd = await realpath(requestedCwd).catch(() => requestedCwd);
   const allowBare = resolveAllowBare(opts.allowBare);
+  const ui = discoverUiViews(cwd);
 
   const violations: GateDiagnostic[] = [];
   const gatePlugin: Plugin = {
@@ -97,7 +104,7 @@ export async function bundleWorkflow(opts: BundleOptions): Promise<BundleResult>
       absWorkingDir: cwd,
       logLevel: "silent",
       legalComments: "none",
-      plugins: [gatePlugin],
+      plugins: [ui.plugin, gatePlugin],
     });
     warnings = result.warnings;
     code = result.outputFiles[0]?.text ?? "";
@@ -110,10 +117,19 @@ export async function bundleWorkflow(opts: BundleOptions): Promise<BundleResult>
 
   if (violations.length > 0) throw GateError.fromDiagnostics(sortDiagnostics(violations));
 
+  const compiledUi = await compileUiCatalog(cwd, ui.entries.values()).catch((err: unknown) => {
+    if (err instanceof GateError) throw err;
+    throw esbuildFailure(err, cwd);
+  });
   return {
     code,
     hash: createHash("sha256").update(code).digest("hex"),
-    diagnostics: warnings.map((w) => messageToDiagnostic(w, "esbuild-warning", cwd)),
+    buildHash: compiledUi.catalog.buildHash,
+    uiCatalog: compiledUi.catalog,
+    diagnostics: [
+      ...warnings.map((w) => messageToDiagnostic(w, "esbuild-warning", cwd)),
+      ...compiledUi.warnings.map((w) => uiMessageToDiagnostic(w, cwd)),
+    ],
   };
 }
 
diff --git a/packages/gate/src/load.ts b/packages/gate/src/load.ts
index f7e384e1..80e7b1fd 100644
--- a/packages/gate/src/load.ts
+++ b/packages/gate/src/load.ts
@@ -17,7 +17,7 @@
  */
 import path from "node:path";
 import vm from "node:vm";
-import { isWorkflowDefinition, type WorkflowDefinition } from "@techery/weft-sdk";
+import { type CompiledUiCatalog, isWorkflowDefinition, type WorkflowDefinition } from "@techery/weft-sdk";
 import { type BundleOptions, bundleWorkflow, INLINE_FILE } from "./bundle.ts";
 import { GateError, isAllowedBare, resolveAllowBare } from "./rules.ts";
 
@@ -30,6 +30,8 @@ export interface LoadedWorkflow {
   def: WorkflowDefinition;
   /** Content hash of the bundle: the version this run pins. */
   hash: string;
+  buildHash: string;
+  uiCatalog: CompiledUiCatalog;
   code: string;
   name: string;
 }
@@ -50,14 +52,14 @@ type ModuleFactory = (
 
 /** Bundle a workflow and execute it in the sandbox. */
 export async function loadWorkflow(opts: LoadOptions): Promise<LoadedWorkflow> {
-  const { code, hash } = await bundleWorkflow(opts);
+  const { code, hash, buildHash, uiCatalog } = await bundleWorkflow(opts);
   const entry = opts.entry ? path.resolve(opts.cwd ?? process.cwd(), opts.entry) : undefined;
   const def = await instantiateBundle(code, {
     filename: entry ?? INLINE_FILE,
     ...(opts.allowBare ? { allowBare: opts.allowBare } : {}),
   });
   const fromFile = entry ? path.basename(entry, path.extname(entry)) : undefined;
-  return { def, hash, code, name: def.meta.name ?? opts.name ?? fromFile ?? "inline" };
+  return { def, hash, buildHash, uiCatalog, code, name: def.meta.name ?? opts.name ?? fromFile ?? "inline" };
 }
 
 /**
diff --git a/packages/gate/src/registry.ts b/packages/gate/src/registry.ts
index 942f793b..572e8d8a 100644
--- a/packages/gate/src/registry.ts
+++ b/packages/gate/src/registry.ts
@@ -15,7 +15,7 @@
  */
 import { readdir, stat } from "node:fs/promises";
 import path from "node:path";
-import type { WorkflowDefinition } from "@techery/weft-sdk";
+import type { CompiledUiCatalog, WorkflowDefinition } from "@techery/weft-sdk";
 import { bundleWorkflow } from "./bundle.ts";
 import { instantiateBundle } from "./load.ts";
 import { GateError } from "./rules.ts";
@@ -26,7 +26,9 @@ export interface WorkflowRegistry {
   resolve?(identity: {
     id?: string;
     name: string;
-  }): Promise<{ def: WorkflowDefinition; name: string; hash?: string } | undefined>;
+  }): Promise<
+    { def: WorkflowDefinition; name: string; hash?: string; uiCatalog?: CompiledUiCatalog } | undefined
+  >;
   /** Bundle content hash of what `get(name)` returns; the engine's resume compares it. */
   hashOf?(name: string): Promise<string | undefined>;
 }
@@ -44,6 +46,8 @@ export interface RegistryLoadResult {
   def: WorkflowDefinition;
   /** Content hash of the bundle — the version a run pins. */
   hash: string;
+  buildHash: string;
+  uiCatalog: CompiledUiCatalog;
   file: string;
 }
 
@@ -55,7 +59,9 @@ export interface FileWorkflowRegistry extends WorkflowRegistry {
   resolve(identity: {
     id?: string;
     name: string;
-  }): Promise<{ def: WorkflowDefinition; name: string; hash?: string } | undefined>;
+  }): Promise<
+    { def: WorkflowDefinition; name: string; hash?: string; uiCatalog?: CompiledUiCatalog } | undefined
+  >;
   hashOf(name: string): Promise<string | undefined>;
 }
 
@@ -67,6 +73,8 @@ export interface RegistryOptions {
 interface CacheEntry {
   file: string;
   hash: string;
+  buildHash: string;
+  uiCatalog: CompiledUiCatalog;
   def: WorkflowDefinition;
   name: string;
   id: string;
@@ -80,13 +88,13 @@ export function createWorkflowRegistry(opts: RegistryOptions): FileWorkflowRegis
   const cache = new Map<string, CacheEntry>();
 
   const loadFile = async (file: string): Promise<CacheEntry> => {
-    const { code, hash } = await bundleWorkflow({
+    const { code, hash, buildHash, uiCatalog } = await bundleWorkflow({
       entry: file,
       cwd: dir,
       ...(allowBare ? { allowBare } : {}),
     });
     const cached = cache.get(file);
-    if (cached?.hash === hash) return cached;
+    if (cached?.hash === hash && cached.buildHash === buildHash) return cached;
 
     const def = await instantiateBundle(code, {
       filename: file,
@@ -95,6 +103,8 @@ export function createWorkflowRegistry(opts: RegistryOptions): FileWorkflowRegis
     const entry: CacheEntry = {
       file,
       hash,
+      buildHash,
+      uiCatalog,
       def,
       name: def.meta.name ?? path.basename(file, path.extname(file)),
       id: def.meta.id ?? def.meta.name ?? path.basename(file, path.extname(file)),
@@ -203,7 +213,13 @@ export function createWorkflowRegistry(opts: RegistryOptions): FileWorkflowRegis
     async load(name: string): Promise<RegistryLoadResult> {
       const entry = await find(name);
       if (!entry) throw new GateError(`workflow "${name}" not found in ${dir}`);
-      return { def: entry.def, hash: entry.hash, file: entry.file };
+      return {
+        def: entry.def,
+        hash: entry.hash,
+        buildHash: entry.buildHash,
+        uiCatalog: entry.uiCatalog,
+        file: entry.file,
+      };
     },
 
     async get(name: string): Promise<WorkflowDefinition | undefined> {
@@ -211,10 +227,14 @@ export function createWorkflowRegistry(opts: RegistryOptions): FileWorkflowRegis
       return entry?.def;
     },
 
-    async resolve(identity): Promise<{ def: WorkflowDefinition; name: string; hash: string } | undefined> {
+    async resolve(
+      identity,
+    ): Promise<
+      { def: WorkflowDefinition; name: string; hash: string; uiCatalog: CompiledUiCatalog } | undefined
+    > {
       const entry = identity.id === undefined ? await find(identity.name) : await findById(identity.id);
       if (!entry) return undefined;
-      return { def: entry.def, name: entry.name, hash: entry.hash };
+      return { def: entry.def, name: entry.name, hash: entry.hash, uiCatalog: entry.uiCatalog };
     },
 
     async hashOf(name: string): Promise<string | undefined> {
diff --git a/packages/gate/src/ui-bundle.ts b/packages/gate/src/ui-bundle.ts
new file mode 100644
index 00000000..13814291
--- /dev/null
+++ b/packages/gate/src/ui-bundle.ts
@@ -0,0 +1,312 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import type { CompiledUiAsset, CompiledUiCatalog, UiViewMode } from "@techery/weft-sdk";
+import { build, type Loader, type Message, type Plugin } from "esbuild";
+import ts from "typescript";
+import { type GateDiagnostic, GateError } from "./rules.ts";
+
+const UI_IMPORT = /\.ui\.[jt]sx$/;
+const UI_FACTORIES = new Map<string, UiViewMode>([
+  ["defineUiView", "input"],
+  ["defineResultView", "display"],
+]);
+const MAX_UI_VIEWS = 32;
+const MAX_UI_BUNDLE_BYTES = 1_000_000;
+const COMPILER_REQUIRE = createRequire(import.meta.url);
+
+export interface DiscoveredUiEntry {
+  file: string;
+  assetKey: string;
+  id: string;
+  revision: string;
+  mode: UiViewMode;
+}
+
+export interface UiDiscovery {
+  plugin: Plugin;
+  entries: Map<string, DiscoveredUiEntry>;
+}
+
+/** Intercept `.ui.tsx` before it reaches the deterministic Node source gate. */
+export function discoverUiViews(root: string): UiDiscovery {
+  const entries = new Map<string, DiscoveredUiEntry>();
+  const ids = new Map<string, string>();
+  const plugin: Plugin = {
+    name: "weft-ui-token",
+    setup(pluginBuild) {
+      pluginBuild.onResolve({ filter: UI_IMPORT }, async (args) => {
+        if (!args.path.startsWith(".") && !path.isAbsolute(args.path)) {
+          return { errors: [{ text: `UI view imports must be relative, got ${JSON.stringify(args.path)}` }] };
+        }
+        const requested = path.resolve(args.resolveDir || root, args.path);
+        const file = await realpath(requested).catch(() => requested);
+        if (!inside(root, file)) {
+          return { errors: [{ text: `UI view escapes the workflow root: ${displayPath(root, file)}` }] };
+        }
+        let entry = entries.get(file);
+        if (!entry) {
+          if (entries.size >= MAX_UI_VIEWS) {
+            return { errors: [{ text: `workflow imports more than ${MAX_UI_VIEWS} UI views` }] };
+          }
+          const source = await readFile(file, "utf8");
+          const meta = readStaticMetadata(source, displayPath(root, file));
+          const prior = ids.get(meta.id);
+          if (prior && prior !== file) {
+            return {
+              errors: [
+                {
+                  text: `duplicate UI view id ${JSON.stringify(meta.id)} in ${displayPath(root, prior)} and ${displayPath(root, file)}`,
+                },
+              ],
+            };
+          }
+          ids.set(meta.id, file);
+          entry = {
+            file,
+            id: meta.id,
+            revision: meta.revision,
+            mode: meta.mode,
+            assetKey: createHash("sha256").update(displayPath(root, file)).digest("hex"),
+          };
+          entries.set(file, entry);
+        }
+        return { path: entry.assetKey, namespace: "weft-ui-token" };
+      });
+      pluginBuild.onLoad({ filter: /.*/, namespace: "weft-ui-token" }, (args) => ({
+        loader: "js",
+        contents: `export default Object.freeze({ kind: "weft.ui-view", assetKey: ${JSON.stringify(args.path)} });`,
+      }));
+    },
+  };
+  return { plugin, entries };
+}
+
+export async function compileUiCatalog(
+  root: string,
+  entries: Iterable<DiscoveredUiEntry>,
+): Promise<{ catalog: CompiledUiCatalog; warnings: Message[] }> {
+  const assets: CompiledUiAsset[] = [];
+  const warnings: Message[] = [];
+  for (const entry of [...entries].sort((a, b) => a.assetKey.localeCompare(b.assetKey))) {
+    const result = await build({
+      stdin: {
+        contents: browserBootstrap(entry),
+        resolveDir: root,
+        sourcefile: `weft-ui:${displayPath(root, entry.file)}`,
+        loader: "ts",
+      },
+      absWorkingDir: root,
+      bundle: true,
+      format: "iife",
+      platform: "browser",
+      target: "es2022",
+      jsx: "automatic",
+      write: false,
+      sourcemap: false,
+      legalComments: "none",
+      minify: true,
+      logLevel: "silent",
+      plugins: [browserImportPolicy(root)],
+    });
+    warnings.push(...result.warnings);
+    const code = result.outputFiles[0]?.text ?? "";
+    const size = Buffer.byteLength(code);
+    if (size > MAX_UI_BUNDLE_BYTES) {
+      throw new GateError(
+        `UI view ${JSON.stringify(entry.id)} is ${size} bytes; limit is ${MAX_UI_BUNDLE_BYTES}`,
+      );
+    }
+    assets.push({
+      assetKey: entry.assetKey,
+      id: entry.id,
+      revision: entry.revision,
+      mode: entry.mode,
+      protocol: 1,
+      code,
+      hash: createHash("sha256").update(code).digest("hex"),
+    });
+  }
+  const buildHash = createHash("sha256")
+    .update(
+      JSON.stringify(
+        assets.map(({ assetKey, id, revision, mode, protocol, hash }) => ({
+          assetKey,
+          id,
+          revision,
+          mode,
+          protocol,
+          hash,
+        })),
+      ),
+    )
+    .digest("hex");
+  return { catalog: { buildHash, assets }, warnings };
+}
+
+function readStaticMetadata(
+  source: string,
+  file: string,
+): { id: string; revision: string; mode: UiViewMode } {
+  const parsed = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const assignment = parsed.statements.find(ts.isExportAssignment);
+  const expression = assignment?.expression;
+  if (!expression || !ts.isCallExpression(expression) || !ts.isIdentifier(expression.expression)) {
+    throw metadataError(file, "default export must call defineUiView({...}) or defineResultView({...})");
+  }
+  const mode = UI_FACTORIES.get(expression.expression.text);
+  if (!mode) throw metadataError(file, "default export must call defineUiView or defineResultView");
+  const object = expression.arguments[0];
+  if (!object || !ts.isObjectLiteralExpression(object)) {
+    throw metadataError(file, "UI view definition must be an object literal");
+  }
+  const literal = (name: string): string => {
+    const property = object.properties.find(
+      (candidate): candidate is ts.PropertyAssignment =>
+        ts.isPropertyAssignment(candidate) &&
+        ((ts.isIdentifier(candidate.name) && candidate.name.text === name) ||
+          (ts.isStringLiteral(candidate.name) && candidate.name.text === name)),
+    );
+    if (!property || !ts.isStringLiteral(property.initializer) || property.initializer.text.trim() === "") {
+      throw metadataError(file, `${name} must be a non-empty string literal`);
+    }
+    return property.initializer.text;
+  };
+  return { id: literal("id"), revision: literal("revision"), mode };
+}
+
+function metadataError(file: string, message: string): GateError {
+  const diagnostic: GateDiagnostic = { rule: "ui-metadata", message, file, line: 0, column: 0 };
+  return GateError.fromDiagnostics([diagnostic], `invalid UI view ${file}`);
+}
+
+function browserImportPolicy(root: string): Plugin {
+  const allowedBare = new Set([
+    "react",
+    "react/jsx-runtime",
+    "react/jsx-dev-runtime",
+    "react-dom",
+    "react-dom/client",
+    "scheduler",
+    "@techery/weft-sdk/ui",
+  ]);
+  const supported = /\.[cm]?[jt]sx?$/;
+  const compilerFiles = new Set(
+    [...allowedBare].flatMap((specifier) => {
+      try {
+        return [COMPILER_REQUIRE.resolve(specifier)];
+      } catch {
+        return [];
+      }
+    }),
+  );
+  return {
+    name: "weft-ui-browser-policy",
+    setup(pluginBuild) {
+      pluginBuild.onResolve({ filter: /.*/ }, (args) => {
+        if (args.kind === "dynamic-import") {
+          return { errors: [{ text: `dynamic imports are not supported in workflow UI (${args.path})` }] };
+        }
+        return null;
+      });
+      pluginBuild.onResolve({ filter: /^[^./]/ }, (args) => {
+        if (!allowedBare.has(args.path)) {
+          return {
+            errors: [{ text: `bare import ${JSON.stringify(args.path)} is not allowed in workflow UI` }],
+          };
+        }
+        try {
+          return { path: COMPILER_REQUIRE.resolve(args.path) };
+        } catch (err) {
+          return {
+            errors: [{ text: `cannot resolve compiler-owned ${args.path}: ${(err as Error).message}` }],
+          };
+        }
+      });
+      pluginBuild.onResolve({ filter: /\.(?:css|scss|sass|less)$/ }, (args) => ({
+        errors: [{ text: `CSS imports are not supported in workflow UI v1 (${args.path})` }],
+      }));
+      pluginBuild.onLoad({ filter: /.*/, namespace: "file" }, async (args) => {
+        if (args.path.includes(`${path.sep}node_modules${path.sep}`) || compilerFiles.has(args.path))
+          return null;
+        if (!inside(root, await realpath(args.path).catch(() => args.path))) {
+          return { errors: [{ text: `browser import escapes the workflow root: ${args.path}` }] };
+        }
+        if (!supported.test(args.path)) {
+          return { errors: [{ text: `unsupported workflow UI asset ${displayPath(root, args.path)}` }] };
+        }
+        return { contents: await readFile(args.path, "utf8"), loader: loaderFor(args.path) };
+      });
+    },
+  };
+}
+
+function browserBootstrap(entry: DiscoveredUiEntry): string {
+  return `
+import React from "react";
+import { createRoot } from "react-dom/client";
+import view from ${JSON.stringify(entry.file)};
+
+let initialized = false;
+window.addEventListener("message", function initialize(event) {
+  if (initialized || event.source !== window.parent) return;
+  const data = event.data;
+  const port = event.ports && event.ports[0];
+  if (!port || !data || data.type !== "weft.ui.init" || data.protocol !== 1) return;
+  initialized = true;
+  const send = (message) => port.postMessage({ ...message, presentationId: data.presentationId, generation: data.generation });
+  const report = (error) => send({ type: "error", message: error instanceof Error ? error.message : String(error) });
+  const root = createRoot(document.getElementById("root"), {
+    onCaughtError: report,
+    onUncaughtError: report,
+    onRecoverableError: report,
+  });
+  const componentProps = view.mode === "input"
+    ? { props: data.props, propose: (answer) => send({ type: "candidate", answer }) }
+    : { props: data.props };
+  try {
+    root.render(React.createElement(view.component, componentProps));
+    send({ type: "ready" });
+    if (typeof ResizeObserver === "function") {
+      const observer = new ResizeObserver(() => send({ type: "resize", height: document.documentElement.scrollHeight }));
+      observer.observe(document.documentElement);
+    } else {
+      send({ type: "resize", height: document.documentElement.scrollHeight });
+    }
+  } catch (error) {
+    send({ type: "error", message: error instanceof Error ? error.message : String(error) });
+  }
+  window.removeEventListener("message", initialize);
+  port.start();
+});
+`;
+}
+
+function loaderFor(file: string): Loader {
+  if (file.endsWith(".tsx")) return "tsx";
+  if (file.endsWith(".ts") || file.endsWith(".mts") || file.endsWith(".cts")) return "ts";
+  if (file.endsWith(".jsx")) return "jsx";
+  return "js";
+}
+
+function inside(root: string, file: string): boolean {
+  const relative = path.relative(root, file);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function displayPath(root: string, file: string): string {
+  const relative = path.relative(root, file);
+  return inside(root, file) ? relative.split(path.sep).join("/") : file;
+}
+
+export function uiMessageToDiagnostic(message: Message, cwd: string): GateDiagnostic {
+  const loc = message.location;
+  return {
+    rule: "ui-bundle-warning",
+    message: message.text,
+    file: loc?.file ? displayPath(cwd, loc.file) : "<ui>",
+    line: loc?.line ?? 0,
+    column: (loc?.column ?? 0) + 1,
+  };
+}
diff --git a/packages/gate/test/gate.test.ts b/packages/gate/test/gate.test.ts
index 3f7a8e48..d2fc0060 100644
--- a/packages/gate/test/gate.test.ts
+++ b/packages/gate/test/gate.test.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { type Ctx, isZodSchema, validateSchema } from "@techery/weft-sdk";
@@ -358,6 +358,84 @@ describe("checkSource", () => {
 // ---------------------------------------------------------------------------
 
 describe("bundleWorkflow", () => {
+  it("builds .ui.tsx as an opaque Node token and a separately hashed browser asset", async () => {
+    const dir = await tempDir();
+    const view = await write(
+      dir,
+      "summary.ui.tsx",
+      [
+        `import { defineResultView } from "@techery/weft-sdk/ui";`,
+        `export default defineResultView<{ message: string }>({`,
+        `  id: "summary",`,
+        `  revision: "1",`,
+        `  component: ({ props }) => <strong>{props.message}</strong>,`,
+        `});`,
+      ].join("\n"),
+    );
+    const entry = await write(
+      dir,
+      "workflow.ts",
+      [
+        `import { defineWorkflow, z } from "@techery/weft-sdk";`,
+        `import summary from "./summary.ui.tsx";`,
+        `export default defineWorkflow(`,
+        `  { description: "ui", input: z.object({}), output: z.object({ ok: z.boolean() }) },`,
+        `  async (ctx) => { await ctx.ui.render({ key: "summary", view: summary, props: { message: "ok" } }); return { ok: true }; },`,
+        `);`,
+      ].join("\n"),
+    );
+
+    const first = await bundleWorkflow({ entry, cwd: dir });
+    expect(first.code).toContain('kind: "weft.ui-view"');
+    expect(first.code).not.toContain("createRoot");
+    expect(first.uiCatalog.assets).toHaveLength(1);
+    expect(first.uiCatalog.assets[0]).toMatchObject({ id: "summary", revision: "1", mode: "display" });
+    expect(first.uiCatalog.assets[0]?.code).toContain("createRoot");
+
+    await writeFile(
+      view,
+      (await readFile(view, "utf8")).replace("<strong>", "<em>").replace("</strong>", "</em>"),
+    );
+    const styled = await bundleWorkflow({ entry, cwd: dir });
+    expect(styled.hash).toBe(first.hash);
+    expect(styled.buildHash).not.toBe(first.buildHash);
+
+    await writeFile(view, (await readFile(view, "utf8")).replace('revision: "1"', 'revision: "2"'));
+    const revised = await bundleWorkflow({ entry, cwd: dir });
+    expect(revised.hash).toBe(first.hash);
+    expect(revised.uiCatalog.assets[0]?.revision).toBe("2");
+  });
+
+  it("rejects dynamic imports from the browser asset graph", async () => {
+    const dir = await tempDir();
+    await write(dir, "lazy.ts", `export const label = "late";`);
+    await write(
+      dir,
+      "panel.ui.tsx",
+      [
+        `import { defineResultView } from "@techery/weft-sdk/ui";`,
+        `export default defineResultView<Record<string, never>>({`,
+        `  id: "panel", revision: "1",`,
+        `  component: () => <button onClick={() => import("./lazy.ts")}>load</button>,`,
+        `});`,
+      ].join("\n"),
+    );
+    const entry = await write(
+      dir,
+      "workflow.ts",
+      [
+        `import { defineWorkflow, z } from "@techery/weft-sdk";`,
+        `import panel from "./panel.ui.tsx";`,
+        `export default defineWorkflow(`,
+        `  { description: "ui", input: z.object({}), output: z.object({ ok: z.boolean() }) },`,
+        `  async (ctx) => { await ctx.ui.render({ key: "panel", view: panel, props: {} }); return { ok: true }; },`,
+        `);`,
+      ].join("\n"),
+    );
+
+    await expect(bundleWorkflow({ entry, cwd: dir })).rejects.toThrow(/dynamic imports are not supported/);
+  });
+
   it("inlines relative imports and keeps @techery/weft-sdk external", async () => {
     const dir = await tempDir();
     const entry = await writeReview(dir);
diff --git a/packages/host/src/index.ts b/packages/host/src/index.ts
index 97432431..10db9606 100644
--- a/packages/host/src/index.ts
+++ b/packages/host/src/index.ts
@@ -44,6 +44,7 @@ export {
   mergedAllowBare,
   persistedDefOf,
   persistInlineScript,
+  persistUiCatalog,
   persistWorkflowRef,
   reserveRunId,
   resolveWorkflow,
@@ -70,6 +71,7 @@ export type {
   StartOptions,
   StepState,
   TreeNode,
+  UiPresentation,
   WorkflowRegistry,
 } from "@techery/weft-core";
 export { Engine, ProviderRegistry, reduceState, renderReport, renderTree } from "@techery/weft-core";
@@ -107,7 +109,7 @@ export type {
   MockRuleOptions,
 } from "@techery/weft-provider-mock";
 export { mock } from "@techery/weft-provider-mock";
-export type { WorkflowDefinition } from "@techery/weft-sdk";
+export type { CompiledUiCatalog, WorkflowDefinition } from "@techery/weft-sdk";
 export { StepError } from "@techery/weft-sdk";
 export type { FsStores } from "@techery/weft-store-fs";
 export { createFsStores } from "@techery/weft-store-fs";
diff --git a/packages/host/src/weft.ts b/packages/host/src/weft.ts
index a470cb31..fdda3354 100644
--- a/packages/host/src/weft.ts
+++ b/packages/host/src/weft.ts
@@ -25,7 +25,7 @@ import {
 } from "@techery/weft-gate";
 import type { RunIndex } from "@techery/weft-index-sqlite";
 import { type MockAgentBuilder, mock } from "@techery/weft-provider-mock";
-import type { WorkflowDefinition } from "@techery/weft-sdk";
+import type { CompiledUiCatalog, WorkflowDefinition } from "@techery/weft-sdk";
 import { createFsStores } from "@techery/weft-store-fs";
 import * as z from "zod";
 import { loadConfig, WEFT_DIR, type WeftConfig } from "./config.ts";
@@ -258,6 +258,26 @@ export async function persistInlineScript(weft: Weft, runId: string, code: strin
   await writeFile(join(dir, "script.ts"), code, "utf8");
 }
 
+/** Persist an inline workflow's browser asset graph so a later process can resume future UI calls. */
+export async function persistUiCatalog(weft: Weft, runId: string, catalog: CompiledUiCatalog): Promise<void> {
+  const assets = [];
+  for (const asset of catalog.assets) {
+    const stored = await weft.engine.blobs.put(asset.code, {
+      kind: "ui-bundle",
+      contentType: "text/javascript; charset=utf-8",
+    });
+    if (stored.hash !== asset.hash) throw new Error(`UI asset hash mismatch for ${asset.id}`);
+    assets.push({ ...asset, code: undefined, blobRef: stored.hash });
+  }
+  const dir = join(weft.runsDir, runId);
+  await mkdir(dir, { recursive: true });
+  await writeFile(
+    join(dir, "ui-manifest.json"),
+    JSON.stringify({ buildHash: catalog.buildHash, assets }),
+    "utf8",
+  );
+}
+
 /** True when a workflow ref is a file path rather than a registry name. */
 export function isWorkflowPathRef(ref: string): boolean {
   return looksLikePath(ref);
@@ -300,7 +320,9 @@ export async function persistedDefOf(weft: Weft, runId: string): Promise<Persist
     const def = await inlineDefOf(weft, runId);
     // An inline run's script is journaled with it, so it cannot have changed and there
     // is nothing for a hash to catch.
-    return def === undefined ? undefined : { def };
+    if (def === undefined) return undefined;
+    const uiCatalog = await persistedUiCatalogOf(weft, runId);
+    return { def, ...(uiCatalog !== undefined ? { uiCatalog } : {}) };
   }
   const parsed = JSON.parse(raw) as { ref?: unknown };
   if (typeof parsed.ref !== "string") {
@@ -309,13 +331,18 @@ export async function persistedDefOf(weft: Weft, runId: string): Promise<Persist
   // A moved file or a failed gate throws here — the caller must see WHY the
   // recorded definition is unavailable, never a quiet fallback.
   const resolved = await resolveWorkflow(weft, parsed.ref);
-  return { def: resolved.def, ...(resolved.hash !== undefined ? { hash: resolved.hash } : {}) };
+  return {
+    def: resolved.def,
+    ...(resolved.hash !== undefined ? { hash: resolved.hash } : {}),
+    ...(resolved.uiCatalog !== undefined ? { uiCatalog: resolved.uiCatalog } : {}),
+  };
 }
 
 /** A run's recorded definition, with the bundle hash where the ref could produce one. */
 export interface PersistedDef {
   def: WorkflowDefinition;
   hash?: string;
+  uiCatalog?: CompiledUiCatalog;
 }
 
 /**
@@ -332,6 +359,7 @@ export function resumeOptions(persisted: PersistedDef | undefined): ResumeOption
   return {
     def: persisted.def,
     ...(persisted.hash !== undefined ? { defHash: persisted.hash } : {}),
+    ...(persisted.uiCatalog !== undefined ? { uiCatalog: persisted.uiCatalog } : {}),
   };
 }
 
@@ -355,6 +383,34 @@ export async function inlineDefOf(weft: Weft, runId: string): Promise<WorkflowDe
   return instantiateBundle(code, { filename: file, ...(allowBare ? { allowBare } : {}) });
 }
 
+async function persistedUiCatalogOf(weft: Weft, runId: string): Promise<CompiledUiCatalog | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(join(weft.runsDir, runId, "ui-manifest.json"), "utf8");
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return undefined;
+    throw err;
+  }
+  const manifest = JSON.parse(raw) as {
+    buildHash?: unknown;
+    assets?: Array<Omit<CompiledUiCatalog["assets"][number], "code"> & { blobRef?: unknown }>;
+  };
+  if (typeof manifest.buildHash !== "string" || !Array.isArray(manifest.assets)) {
+    throw new Error(`run ${runId}: invalid ui-manifest.json`);
+  }
+  const assets = await Promise.all(
+    manifest.assets.map(async (asset) => {
+      if (typeof asset.blobRef !== "string")
+        throw new Error(`run ${runId}: UI manifest asset has no blob ref`);
+      const code = await weft.engine.blobs.getText(asset.blobRef);
+      const { blobRef: _blobRef, ...meta } = asset;
+      return { ...meta, code } as CompiledUiCatalog["assets"][number];
+    }),
+  );
+  return { buildHash: manifest.buildHash, assets };
+}
+
 /** `.weft/workflows` unless the config points elsewhere; relative paths are repo-relative. */
 function workflowsDir(cwd: string, weftDir: string, config: WeftConfig): string {
   const dir = config.workflows?.dir;
@@ -370,6 +426,7 @@ export interface ResolvedWorkflow {
   name: string;
   /** Bundle content hash — the version a run pins (`defHash` on `engine.start`). */
   hash?: string;
+  uiCatalog?: CompiledUiCatalog;
 }
 
 /**
@@ -391,7 +448,7 @@ export async function resolveWorkflow(weft: Weft, ref: string): Promise<Resolved
     });
     if (hit) {
       const name = hit.def.meta.name ?? ref;
-      return { def: named(hit.def, name), name, hash: hit.hash };
+      return { def: named(hit.def, name), name, hash: hit.hash, uiCatalog: hit.uiCatalog };
     }
     throw await unknownRef(weft, ref);
   }
@@ -400,7 +457,12 @@ export async function resolveWorkflow(weft: Weft, ref: string): Promise<Resolved
   if (!existsSync(file)) throw await unknownRef(weft, ref, file);
   const allowBare = mergedAllowBare(weft.config);
   const loaded = await loadWorkflow({ entry: file, ...(allowBare ? { allowBare } : {}) });
-  return { def: named(loaded.def, loaded.name), name: loaded.name, hash: loaded.hash };
+  return {
+    def: named(loaded.def, loaded.name),
+    name: loaded.name,
+    hash: loaded.hash,
+    uiCatalog: loaded.uiCatalog,
+  };
 }
 
 /**
diff --git a/packages/mcp/src/runs.ts b/packages/mcp/src/runs.ts
index 2928fe7a..55f2bb5b 100644
--- a/packages/mcp/src/runs.ts
+++ b/packages/mcp/src/runs.ts
@@ -9,7 +9,14 @@
  * daemon) has no handle here, so its journal is polled instead; the projection carries
  * the same pending requests the handle would have reported.
  */
-import type { PendingRequest, RunHandle, RunState, Weft, WorkflowDefinition } from "@techery/weft-host";
+import type {
+  CompiledUiCatalog,
+  PendingRequest,
+  RunHandle,
+  RunState,
+  Weft,
+  WorkflowDefinition,
+} from "@techery/weft-host";
 
 /** How often the journal is re-read for a run this process did not start. */
 const POLL_MS = 500;
@@ -57,6 +64,7 @@ export interface TrackedRun {
   handle: RunHandle;
   ref?: string;
   def?: WorkflowDefinition;
+  uiCatalog?: CompiledUiCatalog;
 }
 
 /** The handles this server owns. Runs it never started are served from the journal. */
diff --git a/packages/mcp/src/tools.ts b/packages/mcp/src/tools.ts
index 529ecf76..7e211139 100644
--- a/packages/mcp/src/tools.ts
+++ b/packages/mcp/src/tools.ts
@@ -14,6 +14,7 @@ import { join } from "node:path";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import {
+  type CompiledUiCatalog,
   isWorkflowPathRef,
   loadWorkflow,
   mergedAllowBare,
@@ -21,6 +22,7 @@ import {
   parseBudget,
   persistedDefOf,
   persistInlineScript,
+  persistUiCatalog,
   persistWorkflowRef,
   type RunListFilter,
   reserveRunId,
@@ -236,9 +238,16 @@ export function registerTools(server: McpServer, weft: Weft): RunStore {
         let persisted: PersistedDef | undefined;
         if (ref !== undefined) {
           const resolved = await resolveWorkflow(weft, ref);
-          persisted = { def: resolved.def, ...(resolved.hash !== undefined ? { hash: resolved.hash } : {}) };
+          persisted = {
+            def: resolved.def,
+            ...(resolved.hash !== undefined ? { hash: resolved.hash } : {}),
+            ...(resolved.uiCatalog !== undefined ? { uiCatalog: resolved.uiCatalog } : {}),
+          };
         } else if (tracked?.def !== undefined) {
-          persisted = { def: tracked.def };
+          persisted = {
+            def: tracked.def,
+            ...(tracked.uiCatalog !== undefined ? { uiCatalog: tracked.uiCatalog } : {}),
+          };
         } else {
           persisted = await persistedDefOf(weft, args.runId);
         }
@@ -248,7 +257,11 @@ export function registerTools(server: McpServer, weft: Weft): RunStore {
         });
         runs.track({
           handle,
-          ...(ref !== undefined ? { ref } : persisted !== undefined ? { def: persisted.def } : {}),
+          ...(ref !== undefined
+            ? { ref }
+            : persisted !== undefined
+              ? { def: persisted.def, uiCatalog: persisted.uiCatalog }
+              : {}),
         });
         return { runId: handle.runId, status: "resumed" };
       }),
@@ -341,8 +354,10 @@ async function startRun(weft: Weft, runs: RunStore, args: RunArgs): Promise<Trac
   // by an exclusive directory create, so a collision can never write into an
   // EXISTING run's directory.
   const runId = await reserveRunId(weft);
-  if (inline?.code !== undefined) await persistInlineScript(weft, runId, inline.code);
-  else if (args.workflow !== undefined && isWorkflowPathRef(args.workflow)) {
+  if (inline?.code !== undefined) {
+    await persistInlineScript(weft, runId, inline.code);
+    if (inline.uiCatalog !== undefined) await persistUiCatalog(weft, runId, inline.uiCatalog);
+  } else if (args.workflow !== undefined && isWorkflowPathRef(args.workflow)) {
     await persistWorkflowRef(weft, runId, args.workflow);
   }
   const handle = await weft.engine
@@ -353,6 +368,7 @@ async function startRun(weft: Weft, runs: RunStore, args: RunArgs): Promise<Trac
       input: args.input,
       cwd: weft.cwd,
       ...(resolved.hash !== undefined ? { defHash: resolved.hash } : {}),
+      ...(resolved.uiCatalog !== undefined ? { uiCatalog: resolved.uiCatalog } : {}),
       ...(args.budget !== undefined ? { budget: parseBudget(args.budget) } : {}),
       ...(args.reuse !== undefined ? { reuse: args.reuse } : {}),
     })
@@ -365,7 +381,9 @@ async function startRun(weft: Weft, runs: RunStore, args: RunArgs): Promise<Trac
     });
   return runs.track({
     handle,
-    ...(args.workflow !== undefined ? { ref: args.workflow } : { def: resolved.def }),
+    ...(args.workflow !== undefined
+      ? { ref: args.workflow }
+      : { def: resolved.def, uiCatalog: resolved.uiCatalog }),
   });
 }
 
@@ -373,7 +391,12 @@ async function startRun(weft: Weft, runs: RunStore, args: RunArgs): Promise<Trac
 async function loadInline(
   weft: Weft,
   source: string,
-): Promise<{ def: WorkflowDefinition; hash?: string; code?: string }> {
+): Promise<{
+  def: WorkflowDefinition;
+  hash?: string;
+  code?: string;
+  uiCatalog?: CompiledUiCatalog;
+}> {
   // Merged with the defaults: config extras must not cost inline code its zod.
   const allowBare = mergedAllowBare(weft.config);
   const loaded = await loadWorkflow({
@@ -382,7 +405,12 @@ async function loadInline(
     name: "inline",
     ...(allowBare ? { allowBare } : {}),
   });
-  return { def: named(loaded.def, loaded.name), hash: loaded.hash, code: loaded.code };
+  return {
+    def: named(loaded.def, loaded.name),
+    hash: loaded.hash,
+    code: loaded.code,
+    uiCatalog: loaded.uiCatalog,
+  };
 }
 
 /**
diff --git a/packages/mcp/src/typings.ts b/packages/mcp/src/typings.ts
index 26e45634..054b1a25 100644
--- a/packages/mcp/src/typings.ts
+++ b/packages/mcp/src/typings.ts
@@ -12,7 +12,7 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 
 /** The authoring surface, in the order a reader wants it: ctx, then defineWorkflow, then schemas. */
-const FILES = ["types.ts", "define.ts", "schema.ts"] as const;
+const FILES = ["types.ts", "ui.ts", "define.ts", "schema.ts"] as const;
 
 /** Packages that do depend on @techery/weft-sdk, used as resolution hops. */
 const VIA = ["@techery/weft-host", "@techery/weft-core"] as const;
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 0756ea05..fe5b727d 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -30,6 +30,10 @@
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./ui": {
+      "types": "./src/ui.ts",
+      "default": "./src/ui.ts"
     }
   },
   "files": [
@@ -46,6 +50,10 @@
       ".": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
+      },
+      "./ui": {
+        "types": "./dist/ui.d.ts",
+        "default": "./dist/ui.js"
       }
     }
   },
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 5b5a20ca..16555c6e 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -41,7 +41,6 @@ export type {
 export { isZodSchema, validateSchema } from "./schema.ts";
 export type { Settled } from "./settled.ts";
 export { failures, okValues } from "./settled.ts";
-
 export type {
   AgentFn,
   AgentOptions,
@@ -108,3 +107,16 @@ export type {
   WorkflowTaskUpsertInput,
   WriteScope,
 } from "./types.ts";
+export type {
+  CompiledUiAsset,
+  CompiledUiCatalog,
+  CompiledUiViewToken,
+  DisplayUiView,
+  InputUiView,
+  JsonPrimitive,
+  JsonValue,
+  UiApi,
+  UiRenderOptions,
+  UiViewMode,
+  UiViewRef,
+} from "./ui.ts";
diff --git a/packages/sdk/src/types.ts b/packages/sdk/src/types.ts
index 414a8be9..1097228d 100644
--- a/packages/sdk/src/types.ts
+++ b/packages/sdk/src/types.ts
@@ -6,6 +6,7 @@ import type { Duration } from "./duration.ts";
 import type { StepError } from "./errors.ts";
 import type { AnySchema, InferIn, InferOut } from "./schema.ts";
 import type { Settled } from "./settled.ts";
+import type { InputUiView, UiApi } from "./ui.ts";
 
 // ---------------------------------------------------------------------------
 // Routing & effort
@@ -312,7 +313,7 @@ export interface GateResult {
  */
 export type HumanTimeoutPolicy<T> = "deny" | "escalate" | { default: T };
 
-export interface HumanAskOptions<S extends AnySchema> {
+export interface HumanAskOptions<S extends AnySchema, Props = never> {
   /**
    * Stable identity for replay, exactly as on {@link AgentOptions.key}. A human step is
    * otherwise identified by its CONTENT alone — question, detail, schema, risk, timeouts —
@@ -327,6 +328,8 @@ export interface HumanAskOptions<S extends AnySchema> {
   detail?: string;
   timeout?: Duration;
   onTimeout?: HumanTimeoutPolicy<InferIn<S>>;
+  /** Optional workflow-provided presentation; the host remains the submission authority. */
+  ui?: { view: InputUiView<Props, InferIn<S>>; props: Props };
 }
 
 export interface HumanApproveOptions {
@@ -345,7 +348,7 @@ export interface HumanApproveOptions {
   onTimeout?: HumanTimeoutPolicy<{ approved: boolean; note?: string }>;
 }
 
-export interface HumanReviewOptions<S extends AnySchema> {
+export interface HumanReviewOptions<S extends AnySchema, Props = never> {
   /**
    * Stable identity for replay, exactly as on {@link AgentOptions.key}. A human step is
    * otherwise identified by its CONTENT alone — question, detail, schema, risk, timeouts —
@@ -361,13 +364,15 @@ export interface HumanReviewOptions<S extends AnySchema> {
   schema: S;
   timeout?: Duration;
   onTimeout?: HumanTimeoutPolicy<InferIn<S>>;
+  /** Optional workflow-provided presentation; the host remains the submission authority. */
+  ui?: { view: InputUiView<Props, InferIn<S>>; props: Props };
 }
 
 export interface HumanApi {
   /** Always asks a person; the answer is validated against the schema like any output. */
-  ask<S extends AnySchema>(opts: HumanAskOptions<S>): Promise<InferOut<S>>;
+  ask<S extends AnySchema, Props = never>(opts: HumanAskOptions<S, Props>): Promise<InferOut<S>>;
   approve(opts: HumanApproveOptions): Promise<{ approved: boolean; note?: string }>;
-  review<S extends AnySchema>(opts: HumanReviewOptions<S>): Promise<InferOut<S>>;
+  review<S extends AnySchema, Props = never>(opts: HumanReviewOptions<S, Props>): Promise<InferOut<S>>;
 }
 
 // ---------------------------------------------------------------------------
@@ -629,6 +634,8 @@ export interface Ctx {
   // humans
   gate(req: GateRequest): Promise<GateResult>;
   human: HumanApi;
+  /** Durable custom presentations. Rendering is browser-only and never mutates workflow values. */
+  ui: UiApi;
 
   // side effects
   fs: FsApi;
diff --git a/packages/sdk/src/ui.ts b/packages/sdk/src/ui.ts
new file mode 100644
index 00000000..95eac97f
--- /dev/null
+++ b/packages/sdk/src/ui.ts
@@ -0,0 +1,97 @@
+/** JSON values are the only data custom views may receive across the journal/frame boundary. */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export type UiViewMode = "input" | "display";
+
+/**
+ * The opaque value workflow code receives for a `.ui.tsx` import.
+ *
+ * The browser build sees the full definition returned by `defineUiView`; the Node
+ * workflow build replaces the module with an inert token carrying only `assetKey`.
+ * The phantom fields preserve props/answer/mode inference without entering runtime data.
+ */
+export interface UiViewRef<Props, Answer = never, Mode extends UiViewMode = UiViewMode> {
+  readonly kind: "weft.ui-view";
+  readonly __props?: Props;
+  readonly __answer?: Answer;
+  readonly __mode?: Mode;
+}
+
+export type InputUiView<Props, Answer> = UiViewRef<Props, Answer, "input">;
+export type DisplayUiView<Props> = UiViewRef<Props, never, "display">;
+
+export interface InputViewProps<Props, Answer> {
+  props: Props;
+  /** Stage a candidate answer. Only host-owned chrome can submit it to the workflow. */
+  propose(answer: Answer): void;
+}
+
+export interface ResultViewProps<Props> {
+  props: Props;
+}
+
+export interface InputUiViewDefinition<Props, Answer> extends InputUiView<Props, Answer> {
+  id: string;
+  revision: string;
+  mode: "input";
+  component(props: InputViewProps<Props, Answer>): unknown;
+}
+
+export interface DisplayUiViewDefinition<Props> extends DisplayUiView<Props> {
+  id: string;
+  revision: string;
+  mode: "display";
+  component(props: ResultViewProps<Props>): unknown;
+}
+
+export function defineUiView<Props, Answer>(definition: {
+  id: string;
+  revision: string;
+  component(props: InputViewProps<Props, Answer>): unknown;
+}): InputUiViewDefinition<Props, Answer> {
+  return Object.freeze({ kind: "weft.ui-view", mode: "input", ...definition });
+}
+
+export function defineResultView<Props>(definition: {
+  id: string;
+  revision: string;
+  component(props: ResultViewProps<Props>): unknown;
+}): DisplayUiViewDefinition<Props> {
+  return Object.freeze({ kind: "weft.ui-view", mode: "display", ...definition });
+}
+
+/** Token emitted into the Node workflow bundle by the gate compiler. */
+export interface CompiledUiViewToken extends UiViewRef<unknown> {
+  assetKey: string;
+}
+
+/** One browser program produced by the gate. Bytes are stored content-addressably before journaling. */
+export interface CompiledUiAsset {
+  assetKey: string;
+  id: string;
+  revision: string;
+  mode: UiViewMode;
+  protocol: 1;
+  code: string;
+  hash: string;
+}
+
+/** The asset graph paired with one compiled workflow definition. */
+export interface CompiledUiCatalog {
+  buildHash: string;
+  assets: CompiledUiAsset[];
+}
+
+export interface UiRenderOptions<Props> {
+  /** Unique replay identity for this call site. */
+  key: string;
+  /** Optional projection identity for choosing the latest presentation in a UI region. */
+  slot?: string;
+  view: DisplayUiView<Props>;
+  props: Props;
+}
+
+export interface UiApi {
+  render<Props>(opts: UiRenderOptions<Props>): Promise<void>;
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 854e8cfb..6839cf62 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -182,6 +182,12 @@ importers:
       esbuild:
         specifier: ^0.28.2
         version: 0.28.2
+      react:
+        specifier: ^19.2.8
+        version: 19.2.8
+      react-dom:
+        specifier: ^19.2.8
+        version: 19.2.8(react@19.2.8)
       typescript:
         specifier: ~5.9.3
         version: 5.9.3

From c1bd22a8e531cb38f840b8787982e9f2ff06a365 Mon Sep 17 00:00:00 2001
From: Serge Zenchenko <sergeizenchenko@gmail.com>
Date: Wed, 26 Aug 2026 15:25:16 +0100
Subject: [PATCH 2/6] Add custom workflow UI example

---
 examples/09-custom-react-ui/README.md         | 32 ++++++++++
 .../deployment-outcome.ui.tsx                 | 40 ++++++++++++
 .../09-custom-react-ui/deployment-plan.ui.tsx | 31 +++++++++
 .../deployment-review.ui.tsx                  | 61 ++++++++++++++++++
 examples/09-custom-react-ui/schemas.ts        | 22 +++++++
 examples/09-custom-react-ui/workflow.ts       | 63 +++++++++++++++++++
 examples/README.md                            | 21 ++++++-
 package.json                                  |  2 +
 packages/gate/test/gate.test.ts               | 14 +++++
 pnpm-lock.yaml                                |  6 ++
 tsconfig.base.json                            |  1 +
 tsconfig.json                                 |  1 +
 12 files changed, 293 insertions(+), 1 deletion(-)
 create mode 100644 examples/09-custom-react-ui/README.md
 create mode 100644 examples/09-custom-react-ui/deployment-outcome.ui.tsx
 create mode 100644 examples/09-custom-react-ui/deployment-plan.ui.tsx
 create mode 100644 examples/09-custom-react-ui/deployment-review.ui.tsx
 create mode 100644 examples/09-custom-react-ui/schemas.ts
 create mode 100644 examples/09-custom-react-ui/workflow.ts

diff --git a/examples/09-custom-react-ui/README.md b/examples/09-custom-react-ui/README.md
new file mode 100644
index 00000000..8b1fc2be
--- /dev/null
+++ b/examples/09-custom-react-ui/README.md
@@ -0,0 +1,32 @@
+# 09 · Custom React workflow UI
+
+This workflow demonstrates every custom-UI mode in one durable run:
+
+1. `ctx.ui.render()` publishes a read-only deployment plan as its own replayable presentation step.
+2. `ctx.human.ask({ ui: … })` renders a custom selector that can only stage a candidate answer.
+3. A second `ctx.ui.render()` composes workflow input and the validated human decision into a final view.
+
+The standard schema form and raw result stay visible beside custom UI. The component never receives a final
+submission function; the Workflow Manager validates and submits the staged candidate through host-owned chrome.
+
+From the repository root, start the Workflow Manager in one terminal:
+
+```sh
+pnpm exec weft ui
+```
+
+Then start the example in another terminal:
+
+```sh
+pnpm exec weft run ./examples/09-custom-react-ui/workflow.ts \
+  --args '{"environment":"staging","services":["api","web","worker"]}' \
+  --watch
+```
+
+Open the waiting run from the queue. Use **Stage selection** inside the workflow-provided frame, inspect the exact
+candidate in Weft, then choose **Submit and resume**. The final timeline contains both immutable result views and
+the human request. Refreshing the page renders each presentation from its journaled asset and props references.
+
+Files ending in `.ui.tsx` are direct TypeScript imports for authoring, but Weft compiles them twice: the workflow's
+Node graph receives an inert typed token, while a separate browser graph receives the React component and its
+contained imports.
diff --git a/examples/09-custom-react-ui/deployment-outcome.ui.tsx b/examples/09-custom-react-ui/deployment-outcome.ui.tsx
new file mode 100644
index 00000000..37044f6a
--- /dev/null
+++ b/examples/09-custom-react-ui/deployment-outcome.ui.tsx
@@ -0,0 +1,40 @@
+import { defineResultView, type ResultViewProps } from "@techery/weft-sdk/ui";
+import type { Service } from "./schemas.ts";
+
+type Props = {
+  environment: "staging" | "production";
+  approved: Service[];
+  deferred: Service[];
+  note?: string;
+};
+
+function ServiceList({ label, services }: { label: string; services: Service[] }) {
+  return (
+    <section style={{ padding: 14, border: "1px solid #c9d2cc", borderRadius: 10 }}>
+      <strong>{label}</strong>
+      <p style={{ margin: "8px 0 0" }}>{services.length > 0 ? services.join(", ") : "None"}</p>
+    </section>
+  );
+}
+
+function DeploymentOutcome({ props }: ResultViewProps<Props>) {
+  return (
+    <main style={{ padding: 20, color: "#17211b", background: "#f5f8f5" }}>
+      <p style={{ margin: 0, color: "#657068", fontSize: 12, textTransform: "uppercase" }}>
+        Recorded decision
+      </p>
+      <h2 style={{ margin: "6px 0 14px" }}>Deployment to {props.environment}</h2>
+      <div style={{ display: "grid", gridTemplateColumns: "repeat(2, minmax(0, 1fr))", gap: 10 }}>
+        <ServiceList label="Approved" services={props.approved} />
+        <ServiceList label="Deferred" services={props.deferred} />
+      </div>
+      {props.note ? <p style={{ marginBottom: 0 }}>Note: {props.note}</p> : null}
+    </main>
+  );
+}
+
+export default defineResultView<Props>({
+  id: "example.deployment-outcome",
+  revision: "1",
+  component: DeploymentOutcome,
+});
diff --git a/examples/09-custom-react-ui/deployment-plan.ui.tsx b/examples/09-custom-react-ui/deployment-plan.ui.tsx
new file mode 100644
index 00000000..f38dd254
--- /dev/null
+++ b/examples/09-custom-react-ui/deployment-plan.ui.tsx
@@ -0,0 +1,31 @@
+import { defineResultView, type ResultViewProps } from "@techery/weft-sdk/ui";
+import type { Service } from "./schemas.ts";
+
+type Props = {
+  environment: "staging" | "production";
+  services: Service[];
+};
+
+function DeploymentPlan({ props }: ResultViewProps<Props>) {
+  return (
+    <main style={{ padding: 20, color: "#17211b", background: "#f5f8f5" }}>
+      <p style={{ margin: 0, color: "#657068", fontSize: 12, textTransform: "uppercase" }}>
+        Proposed deployment
+      </p>
+      <h2 style={{ margin: "6px 0 14px" }}>{props.environment}</h2>
+      <div style={{ display: "flex", flexWrap: "wrap", gap: 8 }}>
+        {props.services.map((service) => (
+          <span key={service} style={{ padding: "6px 10px", border: "1px solid #a8b8ac", borderRadius: 999 }}>
+            {service}
+          </span>
+        ))}
+      </div>
+    </main>
+  );
+}
+
+export default defineResultView<Props>({
+  id: "example.deployment-plan",
+  revision: "1",
+  component: DeploymentPlan,
+});
diff --git a/examples/09-custom-react-ui/deployment-review.ui.tsx b/examples/09-custom-react-ui/deployment-review.ui.tsx
new file mode 100644
index 00000000..c60be8e6
--- /dev/null
+++ b/examples/09-custom-react-ui/deployment-review.ui.tsx
@@ -0,0 +1,61 @@
+import { defineUiView, type InputViewProps } from "@techery/weft-sdk/ui";
+import { useState } from "react";
+import type { DeploymentDecision, Service } from "./schemas.ts";
+
+type Props = {
+  environment: "staging" | "production";
+  services: Service[];
+};
+
+function DeploymentReview({ props, propose }: InputViewProps<Props, DeploymentDecision>) {
+  const [selected, setSelected] = useState<Service[]>(props.services);
+  const [note, setNote] = useState("");
+
+  const toggle = (service: Service) => {
+    setSelected((current) =>
+      current.includes(service)
+        ? current.filter((candidate) => candidate !== service)
+        : [...current, service],
+    );
+  };
+
+  return (
+    <main style={{ padding: 20, color: "#211b16", background: "#fffaf3" }}>
+      <p style={{ margin: 0, color: "#7b6d61", fontSize: 12, textTransform: "uppercase" }}>Human decision</p>
+      <h2 style={{ margin: "6px 0" }}>Choose services for {props.environment}</h2>
+      <p style={{ margin: "0 0 16px", color: "#675d54" }}>
+        This component stages a candidate. Only Weft's host-owned control submits it.
+      </p>
+      <div style={{ display: "grid", gap: 8 }}>
+        {props.services.map((service) => (
+          <label key={service} style={{ display: "flex", alignItems: "center", gap: 8 }}>
+            <input type="checkbox" checked={selected.includes(service)} onChange={() => toggle(service)} />
+            {service}
+          </label>
+        ))}
+      </div>
+      <label style={{ display: "grid", gap: 6, marginTop: 16 }}>
+        Optional note
+        <textarea
+          value={note}
+          rows={3}
+          onChange={(event) => setNote((event.currentTarget as unknown as { value: string }).value)}
+        />
+      </label>
+      <button
+        type="button"
+        disabled={selected.length === 0}
+        onClick={() => propose({ approvedServices: selected, ...(note ? { note } : {}) })}
+        style={{ marginTop: 16, padding: "8px 12px" }}
+      >
+        Stage selection
+      </button>
+    </main>
+  );
+}
+
+export default defineUiView<Props, DeploymentDecision>({
+  id: "example.deployment-review",
+  revision: "1",
+  component: DeploymentReview,
+});
diff --git a/examples/09-custom-react-ui/schemas.ts b/examples/09-custom-react-ui/schemas.ts
new file mode 100644
index 00000000..86bed0d9
--- /dev/null
+++ b/examples/09-custom-react-ui/schemas.ts
@@ -0,0 +1,22 @@
+import { z } from "@techery/weft-sdk";
+
+export const Service = z.enum(["api", "web", "worker", "billing"]);
+export type Service = z.infer<typeof Service>;
+
+export const DeploymentInput = z.object({
+  environment: z.enum(["staging", "production"]).default("staging"),
+  services: z.array(Service).min(1).default(["api", "web", "worker"]),
+});
+
+export const DeploymentDecision = z.object({
+  approvedServices: z.array(Service).min(1),
+  note: z.string().max(500).optional(),
+});
+export type DeploymentDecision = z.infer<typeof DeploymentDecision>;
+
+export const DeploymentOutput = z.object({
+  environment: z.enum(["staging", "production"]),
+  approvedServices: z.array(Service),
+  deferredServices: z.array(Service),
+  note: z.string().optional(),
+});
diff --git a/examples/09-custom-react-ui/workflow.ts b/examples/09-custom-react-ui/workflow.ts
new file mode 100644
index 00000000..ddc77e1f
--- /dev/null
+++ b/examples/09-custom-react-ui/workflow.ts
@@ -0,0 +1,63 @@
+/**
+ * Custom workflow UI: read-only presentations remain separate replayable steps,
+ * while input views can stage—but never submit—a schema-validated human answer.
+ *
+ *   pnpm exec weft run ./examples/09-custom-react-ui/workflow.ts \
+ *     --args '{"environment":"staging","services":["api","web","worker"]}' --watch
+ */
+import { defineWorkflow } from "@techery/weft-sdk";
+import outcomeView from "./deployment-outcome.ui.tsx";
+import planView from "./deployment-plan.ui.tsx";
+import reviewView from "./deployment-review.ui.tsx";
+import { DeploymentDecision, DeploymentInput, DeploymentOutput } from "./schemas.ts";
+
+export default defineWorkflow(
+  {
+    id: "example.custom-react-ui",
+    name: "custom-react-ui",
+    description: "Render durable React views for a deployment plan, human decision, and composed result.",
+    input: DeploymentInput,
+    output: DeploymentOutput,
+  },
+  async (ctx, input) => {
+    ctx.phase("Present");
+    await ctx.ui.render({
+      key: "deployment-plan",
+      slot: "deployment",
+      view: planView,
+      props: input,
+    });
+
+    ctx.phase("Decide");
+    const decision = await ctx.human.ask({
+      key: "deployment-review",
+      question: `Which services should deploy to ${input.environment}?`,
+      detail: "Use the custom view or the standard schema form, then submit from Weft's host controls.",
+      schema: DeploymentDecision,
+      ui: { view: reviewView, props: input },
+    });
+
+    const approved = new Set(decision.approvedServices);
+    const result = {
+      environment: input.environment,
+      approvedServices: input.services.filter((service) => approved.has(service)),
+      deferredServices: input.services.filter((service) => !approved.has(service)),
+      ...(decision.note ? { note: decision.note } : {}),
+    };
+
+    ctx.phase("Summarize");
+    await ctx.ui.render({
+      key: "deployment-outcome",
+      slot: "deployment",
+      view: outcomeView,
+      props: {
+        environment: result.environment,
+        approved: result.approvedServices,
+        deferred: result.deferredServices,
+        ...(result.note ? { note: result.note } : {}),
+      },
+    });
+
+    return result;
+  },
+);
diff --git a/examples/README.md b/examples/README.md
index a6e094d5..ffc1207c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -3,7 +3,8 @@
 Folders 01–07 are self-contained library tours that run offline and deterministically with
 `@techery/weft-provider-mock`; `03` also builds a throwaway git repository because write steps need real
 worktrees. Folder 08 is a production-style CLI workflow: its test uses fixtures, while an interactive run uses
-the configured review providers and the repository's durable task store.
+the configured review providers and the repository's durable task store. Folder 09 is a file workflow for the
+Workflow Manager and demonstrates custom React result and input views.
 
 ```sh
 pnpm install                                       # once, at the repo root
@@ -20,6 +21,24 @@ npx tsx examples/01-engine-as-a-library/main.ts    # then any example
 | 06 | [`06-stdlib-patterns`](./06-stdlib-patterns) | `loopUntilDry` + `adversarialVerify` + `finalReport` from `@techery/weft-stdlib`, composed inside one workflow |
 | 07 | [`07-testing-workflows`](./07-testing-workflows) | `@techery/weft-testing`'s `runWorkflow`: git fixtures, schema-validated mock fixtures, journal and phase assertions |
 | 08 | [`08-task-backed-code-review`](./08-task-backed-code-review) | A read-only review that consolidates and independently refutes findings, then upserts only human-selected work into a durable deduplicated backlog |
+| 09 | [`09-custom-react-ui`](./09-custom-react-ui) | Browser-compiled React views for a replayable result, schema-authoritative human input, and a composed final presentation |
+
+## Key-feature coverage
+
+Every major public capability has a runnable example. When a new key feature lands, add or extend an example and
+this matrix in the same change.
+
+| Weft capability | Primary example |
+|-----------------|-----------------|
+| Typed workflows, structured agent output, journal-derived reports | 01 · Engine as a library |
+| Durable human gates, cross-process answers, timeout policies | 02 · Human in the loop |
+| Isolated write steps, patch capture, scope enforcement, explicit integration | 03 · Write steps and patches |
+| Content-addressed replay, edit tolerance, dry-run previews, deterministic values | 04 · Resume and replay |
+| Typed child workflows, run trees, shared hard budgets | 05 · Sub-workflows and budget |
+| Reusable adversarial verification and loop-until-dry patterns | 06 · Stdlib patterns |
+| Deterministic fixtures and journal assertions | 07 · Testing workflows |
+| Durable task observation, selection, deduplication, and upsert | 08 · Task-backed code review |
+| Custom result views, custom human input, composed React presentations | 09 · Custom React UI |
 
 Most example *workflows* used by the CLI live separately in [`.weft/workflows/`](../.weft/workflows)
 (`review.ts`, `audit-and-fix.ts`) — those are what `weft run review` executes; the folders
diff --git a/package.json b/package.json
index 96af99c2..e97fb94b 100644
--- a/package.json
+++ b/package.json
@@ -27,6 +27,8 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.10",
     "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "react": "^19.2.8",
     "typescript": "~5.9.3",
     "vitest": "^4.1.11",
     "tsx": "^4.23.12",
diff --git a/packages/gate/test/gate.test.ts b/packages/gate/test/gate.test.ts
index d2fc0060..4e5593a6 100644
--- a/packages/gate/test/gate.test.ts
+++ b/packages/gate/test/gate.test.ts
@@ -1,6 +1,7 @@
 import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { type Ctx, isZodSchema, validateSchema } from "@techery/weft-sdk";
 import { afterAll, describe, expect, it } from "vitest";
 import {
@@ -18,6 +19,7 @@ import { instantiateBundle } from "../src/load.ts";
 // ---------------------------------------------------------------------------
 
 const roots: string[] = [];
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
 
 async function tempDir(): Promise<string> {
   const dir = await mkdtemp(path.join(tmpdir(), "weft-gate-"));
@@ -436,6 +438,18 @@ describe("bundleWorkflow", () => {
     await expect(bundleWorkflow({ entry, cwd: dir })).rejects.toThrow(/dynamic imports are not supported/);
   });
 
+  it("keeps the custom React UI example compilable as three browser views", async () => {
+    const loaded = await loadWorkflow({
+      entry: path.join(repoRoot, "examples/09-custom-react-ui/workflow.ts"),
+    });
+    expect(loaded.name).toBe("custom-react-ui");
+    expect(loaded.uiCatalog.assets.map(({ id, mode }) => ({ id, mode }))).toEqual([
+      { id: "example.deployment-outcome", mode: "display" },
+      { id: "example.deployment-review", mode: "input" },
+      { id: "example.deployment-plan", mode: "display" },
+    ]);
+  });
+
   it("inlines relative imports and keeps @techery/weft-sdk external", async () => {
     const dir = await tempDir();
     const entry = await writeReview(dir);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6839cf62..aeb56067 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -29,6 +29,12 @@ importers:
       '@types/node':
         specifier: ^26.2.0
         version: 26.2.0
+      '@types/react':
+        specifier: ^19.2.18
+        version: 19.2.18
+      react:
+        specifier: ^19.2.8
+        version: 19.2.8
       tsx:
         specifier: ^4.23.12
         version: 4.23.12
diff --git a/tsconfig.base.json b/tsconfig.base.json
index a1c3e857..76b15381 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -11,6 +11,7 @@
     "forceConsistentCasingInFileNames": true,
     "verbatimModuleSyntax": true,
     "isolatedModules": true,
+    "jsx": "react-jsx",
     "skipLibCheck": true,
     "allowImportingTsExtensions": true,
     "noEmit": true,
diff --git a/tsconfig.json b/tsconfig.json
index 88dc98ea..47ac4749 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -4,6 +4,7 @@
     "packages/*/src/**/*.ts",
     "packages/*/test/**/*.ts",
     "examples/**/*.ts",
+    "examples/**/*.tsx",
     ".weft/workflows/**/*.ts"
   ]
 }

From 1a8f155dadfc2a22b6e88084cd1c9ffa2b2cafdd Mon Sep 17 00:00:00 2001
From: Serge Zenchenko <sergeizenchenko@gmail.com>
Date: Wed, 26 Aug 2026 15:27:16 +0100
Subject: [PATCH 3/6] Make custom UI example runnable offline

---
 examples/09-custom-react-ui/README.md |  9 ++++
 examples/09-custom-react-ui/main.ts   | 76 +++++++++++++++++++++++++++
 examples/README.md                    |  4 +-
 3 files changed, 87 insertions(+), 2 deletions(-)
 create mode 100644 examples/09-custom-react-ui/main.ts

diff --git a/examples/09-custom-react-ui/README.md b/examples/09-custom-react-ui/README.md
index 8b1fc2be..06824f19 100644
--- a/examples/09-custom-react-ui/README.md
+++ b/examples/09-custom-react-ui/README.md
@@ -9,6 +9,15 @@ This workflow demonstrates every custom-UI mode in one durable run:
 The standard schema form and raw result stay visible beside custom UI. The component never receives a final
 submission function; the Workflow Manager validates and submits the staged candidate through host-owned chrome.
 
+Run the deterministic offline contract check used by CI:
+
+```sh
+npx tsx examples/09-custom-react-ui/main.ts
+```
+
+It compiles all three real browser assets, drives the human suspension programmatically, and asserts that the
+plan and outcome presentations can be recovered from the journal and blob store.
+
 From the repository root, start the Workflow Manager in one terminal:
 
 ```sh
diff --git a/examples/09-custom-react-ui/main.ts b/examples/09-custom-react-ui/main.ts
new file mode 100644
index 00000000..65bb3940
--- /dev/null
+++ b/examples/09-custom-react-ui/main.ts
@@ -0,0 +1,76 @@
+/**
+ * Deterministic, offline contract check for the interactive custom-UI workflow.
+ * It compiles the real browser asset graph, drives the human suspension through
+ * the engine, and proves both display presentations survive in projected state.
+ *
+ *   npx tsx examples/09-custom-react-ui/main.ts
+ */
+import assert from "node:assert/strict";
+import { fileURLToPath } from "node:url";
+import { Engine, MemoryBlobStore, MemoryJournalStore, ProviderRegistry } from "@techery/weft-core";
+import { loadWorkflow } from "../../packages/gate/src/index.ts";
+
+const entry = fileURLToPath(new URL("./workflow.ts", import.meta.url));
+const loaded = await loadWorkflow({ entry });
+assert.deepEqual(
+  loaded.uiCatalog.assets.map(({ id, mode }) => ({ id, mode })),
+  [
+    { id: "example.deployment-outcome", mode: "display" },
+    { id: "example.deployment-review", mode: "input" },
+    { id: "example.deployment-plan", mode: "display" },
+  ],
+);
+
+const blobs = new MemoryBlobStore();
+const engine = new Engine({
+  journal: new MemoryJournalStore(),
+  blobs,
+  providers: new ProviderRegistry(),
+});
+
+try {
+  const handle = await engine.start(loaded.def, {
+    input: { environment: "staging", services: ["api", "web", "worker"] },
+    cwd: process.cwd(),
+    defHash: loaded.hash,
+    uiCatalog: loaded.uiCatalog,
+  });
+  const waiting = await handle.outcome();
+  assert.equal(waiting.status, "waiting_for_human");
+  if (waiting.status !== "waiting_for_human") throw new Error("workflow did not suspend");
+  const request = waiting.pending[0]!;
+  assert.equal(request.ui?.asset.id, "example.deployment-review");
+  assert.equal(request.ui?.mode, "input");
+
+  const before = await engine.state(handle.runId);
+  assert.deepEqual(
+    before.steps.flatMap((step) => (step.presentation ? [step.presentation.asset.id] : [])),
+    ["example.deployment-plan"],
+  );
+
+  await engine.answer(handle.runId, request.id, {
+    approvedServices: ["api", "worker"],
+    note: "Hold web for the cache migration.",
+  });
+  assert.deepEqual(await handle.result, {
+    environment: "staging",
+    approvedServices: ["api", "worker"],
+    deferredServices: ["web"],
+    note: "Hold web for the cache migration.",
+  });
+
+  const completed = await engine.state(handle.runId);
+  const presentations = completed.steps.flatMap((step) => (step.presentation ? [step.presentation] : []));
+  assert.deepEqual(
+    presentations.map((presentation) => presentation.asset.id),
+    ["example.deployment-plan", "example.deployment-outcome"],
+  );
+  for (const presentation of presentations) {
+    assert.match(await blobs.getText(presentation.asset.bundleRef.$blob), /weft\.ui\.init/);
+  }
+
+  console.log("custom React UI assertions passed");
+  console.log("presentations: deployment plan → human review → deployment outcome");
+} finally {
+  await engine.shutdown();
+}
diff --git a/examples/README.md b/examples/README.md
index ffc1207c..270cf945 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -3,8 +3,8 @@
 Folders 01–07 are self-contained library tours that run offline and deterministically with
 `@techery/weft-provider-mock`; `03` also builds a throwaway git repository because write steps need real
 worktrees. Folder 08 is a production-style CLI workflow: its test uses fixtures, while an interactive run uses
-the configured review providers and the repository's durable task store. Folder 09 is a file workflow for the
-Workflow Manager and demonstrates custom React result and input views.
+the configured review providers and the repository's durable task store. Folder 09 has an offline compiler/runtime
+check plus an interactive file workflow for custom React result and input views in the Workflow Manager.
 
 ```sh
 pnpm install                                       # once, at the repo root

From bcb09225a51529d7d273126cb7333a621c6f3d7c Mon Sep 17 00:00:00 2001
From: Serge Zenchenko <sergeizenchenko@gmail.com>
Date: Wed, 26 Aug 2026 15:37:18 +0100
Subject: [PATCH 4/6] Add minimal examples for every workflow API

---
 .github/workflows/ci.yml                      |   1 +
 examples/10-api-cookbook/README.md            |  18 +++
 examples/10-api-cookbook/composition.ts       |  40 ++++++
 examples/10-api-cookbook/effects.ts           |  27 ++++
 examples/10-api-cookbook/git.ts               | 123 ++++++++++++++++++
 examples/10-api-cookbook/humans-and-waits.ts  |  27 ++++
 .../state-tasks-and-patches.ts                |  43 ++++++
 examples/README.md                            |   2 +
 examples/coverage.json                        |  69 ++++++++++
 package.json                                  |   1 +
 packages/gate/test/gate.test.ts               |  14 ++
 scripts/check-example-coverage.mjs            |  94 +++++++++++++
 12 files changed, 459 insertions(+)
 create mode 100644 examples/10-api-cookbook/README.md
 create mode 100644 examples/10-api-cookbook/composition.ts
 create mode 100644 examples/10-api-cookbook/effects.ts
 create mode 100644 examples/10-api-cookbook/git.ts
 create mode 100644 examples/10-api-cookbook/humans-and-waits.ts
 create mode 100644 examples/10-api-cookbook/state-tasks-and-patches.ts
 create mode 100644 examples/coverage.json
 create mode 100644 scripts/check-example-coverage.mjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4d4a822f..18f648c8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -102,6 +102,7 @@ jobs:
           git config --global user.email "ci@weft.invalid"
           git config --global init.defaultBranch main
       - run: pnpm install --frozen-lockfile
+      - run: pnpm verify:examples
       # Every example is deterministic and offline (03 builds a throwaway git repo).
       - name: Run all examples
         run: |
diff --git a/examples/10-api-cookbook/README.md b/examples/10-api-cookbook/README.md
new file mode 100644
index 00000000..84c60aaa
--- /dev/null
+++ b/examples/10-api-cookbook/README.md
@@ -0,0 +1,18 @@
+# 10 · Minimal API cookbook
+
+Tiny workflow files cover the remaining public workflow APIs without turning one demo into a large application:
+
+- `composition.ts` — structured agents, detailed results, retries, parallel lanes, pipelines, settled helpers, and children.
+- `humans-and-waits.ts` — gates, ask/approve/review, signals, and durable sleep.
+- `effects.ts` — filesystem, exec, bash, fetch, environment, secrets, and all check forms.
+- `git.ts` — every git read and mutation behind one explicit operation switch. Run mutations only in a throwaway repo.
+- `state-tasks-and-patches.ts` — durable values, run/budget state, notes, task operations, integration, and discard.
+
+Each file is a real workflow that typechecks with the repository. `examples/coverage.json` maps every public `Ctx`
+surface to one example, and `pnpm verify:examples` derives the API list from the SDK and fails if the map drifts.
+
+Run any file directly, supplying the small input its schema requests:
+
+```sh
+pnpm exec weft run ./examples/10-api-cookbook/composition.ts --args '{"values":[1,2,3]}' --watch
+```
diff --git a/examples/10-api-cookbook/composition.ts b/examples/10-api-cookbook/composition.ts
new file mode 100644
index 00000000..626a00b6
--- /dev/null
+++ b/examples/10-api-cookbook/composition.ts
@@ -0,0 +1,40 @@
+import { defineWorkflow, failures, okValues, z } from "@techery/weft-sdk";
+
+const child = defineWorkflow(
+  { description: "Double one number", input: z.object({ n: z.number() }), output: z.number() },
+  async (_ctx, { n }) => n * 2,
+);
+
+export default defineWorkflow(
+  {
+    name: "example-composition",
+    description: "Minimal structured agents, parallel lanes, pipelines, and child workflows.",
+    input: z.object({ values: z.array(z.number()).default([1, 2, 3]) }),
+    output: z.object({ values: z.array(z.number()), failures: z.number(), child: z.number() }),
+  },
+  async (ctx, { values }) => {
+    ctx.phase("Compose");
+    ctx.log("Run one structured call and one detailed call.");
+    await ctx.agent("Return the number one.", { key: "one", schema: z.object({ n: z.literal(1) }) });
+    await ctx.agent.detailed("Return the number two.", {
+      key: "two",
+      schema: z.object({ n: z.literal(2) }),
+      retry: { attempts: 2, backoff: "10ms" },
+    });
+    const settled = await ctx.parallel(
+      values.map((value) => async () => value * 2),
+      { concurrency: 2 },
+    );
+    const piped = await ctx
+      .pipeline(ctx.ok(settled))
+      .step((value) => value + 1)
+      .filter((value) => value > 2)
+      .map((value) => value * 10)
+      .run();
+    return {
+      values: okValues(piped),
+      failures: failures(piped).length,
+      child: await ctx.workflow(child, { n: values[0] ?? 0 }, { key: "child" }),
+    };
+  },
+);
diff --git a/examples/10-api-cookbook/effects.ts b/examples/10-api-cookbook/effects.ts
new file mode 100644
index 00000000..621c2a59
--- /dev/null
+++ b/examples/10-api-cookbook/effects.ts
@@ -0,0 +1,27 @@
+import { defineWorkflow, z } from "@techery/weft-sdk";
+
+export default defineWorkflow(
+  {
+    name: "example-effects",
+    description: "Minimal filesystem, process, HTTP, environment, secret, and check effects.",
+    input: z.object({ path: z.string().default("package.json"), url: z.string().url() }),
+    output: z.object({ bytes: z.number(), files: z.number(), status: z.number() }),
+  },
+  async (ctx, input) => {
+    const stat = await ctx.fs.stat(input.path);
+    const read = await ctx.fs.read(input.path);
+    const { paths } = await ctx.fs.glob(["packages/*/package.json"]);
+    await ctx.env.get("CI");
+    const token = ctx.secret("EXAMPLE_TOKEN");
+    await ctx.exec("node", ["-e", "console.log('ok')"], { key: "exec", env: { EXAMPLE_TOKEN: token } });
+    await ctx.bash("node -e 'console.log(JSON.stringify({ok:true}))'", {
+      key: "bash",
+      schema: z.object({ ok: z.boolean() }),
+    });
+    const response = await ctx.fetch(input.url, { key: "fetch", headers: { authorization: token } });
+    await ctx.check("command", { exec: ["node", "--version"], required: true });
+    await ctx.check("function", { fn: () => true });
+    await ctx.check("trusted", { trustPrior: { run: "documented-run", reason: "example only" } });
+    return { bytes: stat.size ?? read.size, files: paths.length, status: response.status };
+  },
+);
diff --git a/examples/10-api-cookbook/git.ts b/examples/10-api-cookbook/git.ts
new file mode 100644
index 00000000..8dfa8ace
--- /dev/null
+++ b/examples/10-api-cookbook/git.ts
@@ -0,0 +1,123 @@
+import { defineWorkflow, z } from "@techery/weft-sdk";
+
+const Operation = z.enum([
+  "status",
+  "head",
+  "branches",
+  "merge-base",
+  "changed",
+  "diff",
+  "log",
+  "show",
+  "blame",
+  "file-at",
+  "snapshot",
+  "add",
+  "commit",
+  "checkout",
+  "fetch",
+  "pull",
+  "push",
+  "reset",
+  "apply",
+  "tag",
+  "branch-create",
+  "branch-delete",
+  "stash-push",
+  "stash-pop",
+  "stash-drop",
+  "clean",
+]);
+
+export default defineWorkflow(
+  {
+    name: "example-git",
+    description:
+      "One minimal switch covering every journaled git operation; use mutations only in a throwaway repo.",
+    input: z.object({ operation: Operation.default("status"), path: z.string().default("README.md") }),
+    output: z.object({ operation: Operation }),
+  },
+  async (ctx, { operation, path }) => {
+    switch (operation) {
+      case "status":
+        await ctx.git.status();
+        break;
+      case "head":
+        await ctx.git.head();
+        break;
+      case "branches":
+        await ctx.git.branches();
+        break;
+      case "merge-base":
+        await ctx.git.mergeBase("HEAD", "HEAD");
+        break;
+      case "changed":
+        await ctx.git.changedSince("HEAD~1");
+        break;
+      case "diff":
+        await ctx.git.diff({ paths: [path] });
+        break;
+      case "log":
+        await ctx.git.log({ max: 5 });
+        break;
+      case "show":
+        await ctx.git.show("HEAD");
+        break;
+      case "blame":
+        await ctx.git.blame(path, { lines: [1, 5] });
+        break;
+      case "file-at":
+        await ctx.git.fileAt("HEAD", path);
+        break;
+      case "snapshot":
+        await ctx.git.snapshot();
+        break;
+      case "add":
+        await ctx.git.add({ paths: [path] });
+        break;
+      case "commit":
+        await ctx.git.commit({ message: "example", paths: [path] });
+        break;
+      case "checkout":
+        await ctx.git.checkout("HEAD", { discard: false });
+        break;
+      case "fetch":
+        await ctx.git.fetch({ remote: "origin" });
+        break;
+      case "pull":
+        await ctx.git.pull({ remote: "origin" });
+        break;
+      case "push":
+        await ctx.git.push({ remote: "origin" });
+        break;
+      case "reset":
+        await ctx.git.reset({ to: "HEAD", mode: "soft" });
+        break;
+      case "apply":
+        await ctx.git.apply({ patch: "" });
+        break;
+      case "tag":
+        await ctx.git.tag("example-tag", { ref: "HEAD" });
+        break;
+      case "branch-create":
+        await ctx.git.branch.create("example-branch", { from: "HEAD" });
+        break;
+      case "branch-delete":
+        await ctx.git.branch.delete("example-branch");
+        break;
+      case "stash-push":
+        await ctx.git.stash.push({ message: "example" });
+        break;
+      case "stash-pop":
+        await ctx.git.stash.pop();
+        break;
+      case "stash-drop":
+        await ctx.git.stash.drop();
+        break;
+      case "clean":
+        await ctx.git.clean({ force: false });
+        break;
+    }
+    return { operation };
+  },
+);
diff --git a/examples/10-api-cookbook/humans-and-waits.ts b/examples/10-api-cookbook/humans-and-waits.ts
new file mode 100644
index 00000000..83d62b2b
--- /dev/null
+++ b/examples/10-api-cookbook/humans-and-waits.ts
@@ -0,0 +1,27 @@
+import { defineWorkflow, z } from "@techery/weft-sdk";
+
+export default defineWorkflow(
+  {
+    name: "example-humans-and-waits",
+    description: "Minimal gates, human questions, signals, and durable waits.",
+    input: z.object({}),
+    output: z.object({ choice: z.string(), signal: z.string() }),
+  },
+  async (ctx) => {
+    await ctx.gate({ action: "Continue the example", risk: "low" });
+    await ctx.human.approve({ key: "approve", action: "Publish the example" });
+    const choice = await ctx.human.ask({
+      key: "ask",
+      question: "Choose a lane",
+      schema: z.object({ lane: z.enum(["a", "b"]) }),
+    });
+    await ctx.human.review({
+      key: "review",
+      artifact: "# Minimal artifact",
+      schema: z.object({ accepted: z.boolean() }),
+    });
+    await ctx.sleep("10ms");
+    const signal = await ctx.signal("external-ready", z.object({ value: z.string() }), { timeout: "5m" });
+    return { choice: choice.lane, signal: signal.value };
+  },
+);
diff --git a/examples/10-api-cookbook/state-tasks-and-patches.ts b/examples/10-api-cookbook/state-tasks-and-patches.ts
new file mode 100644
index 00000000..3bfc7f97
--- /dev/null
+++ b/examples/10-api-cookbook/state-tasks-and-patches.ts
@@ -0,0 +1,43 @@
+import { defineWorkflow, z } from "@techery/weft-sdk";
+
+export default defineWorkflow(
+  {
+    id: "example.state-tasks-and-patches",
+    name: "example-state-tasks-and-patches",
+    description: "Minimal run state, durable values, task mutations, notes, patch integration, and discard.",
+    input: z.object({ taskId: z.string().optional(), integrate: z.boolean().default(false) }),
+    output: z.object({ id: z.string(), now: z.number(), random: z.number(), uuid: z.string() }),
+  },
+  async (ctx, input) => {
+    ctx.phase("State");
+    ctx.log(`run ${ctx.run.id}; remaining tokens ${ctx.budget.remaining.tokens ?? "unlimited"}`);
+    const [now, random, uuid] = await Promise.all([ctx.now(), ctx.random(), ctx.uuid()]);
+    await ctx.note({ kind: "decision", text: "Demonstrate the public state APIs." });
+
+    const snapshot = await ctx.tasks.observe({ statuses: ["todo"] }, { key: "tasks:observe" });
+    await ctx.tasks.upsert(
+      "example",
+      {
+        create: { title: "Example task", description: "Created by the API cookbook." },
+        update: { priority: "low" },
+      },
+      { key: "tasks:upsert" },
+    );
+    const taskId = input.taskId ?? snapshot.tasks[0]?.id;
+    if (taskId) {
+      await ctx.tasks.update(taskId, { status: "in_progress" }, { key: "tasks:update" });
+      await ctx.tasks.note(taskId, "Minimal task note.", { key: "tasks:note" });
+      const criterion = snapshot.tasks.find((task) => task.id === taskId)?.acceptanceCriteria[0];
+      if (criterion) await ctx.tasks.setCriterion(taskId, criterion.id, true, { key: "tasks:criterion" });
+    }
+
+    const change = await ctx.agent.detailed("Make one small documented change.", {
+      key: "change",
+      schema: z.object({ summary: z.string() }),
+      write: { paths: ["docs/**"] },
+    });
+    if (input.integrate) await ctx.integrate([change], { order: "sequential", onConflict: "fail" });
+    else await ctx.discard([change]);
+    return { id: ctx.run.id, now, random, uuid };
+  },
+);
diff --git a/examples/README.md b/examples/README.md
index 270cf945..31e87c37 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -22,6 +22,7 @@ npx tsx examples/01-engine-as-a-library/main.ts    # then any example
 | 07 | [`07-testing-workflows`](./07-testing-workflows) | `@techery/weft-testing`'s `runWorkflow`: git fixtures, schema-validated mock fixtures, journal and phase assertions |
 | 08 | [`08-task-backed-code-review`](./08-task-backed-code-review) | A read-only review that consolidates and independently refutes findings, then upserts only human-selected work into a durable deduplicated backlog |
 | 09 | [`09-custom-react-ui`](./09-custom-react-ui) | Browser-compiled React views for a replayable result, schema-authoritative human input, and a composed final presentation |
+| 10 | [`10-api-cookbook`](./10-api-cookbook) | Minimal, single-purpose workflows covering every remaining public `Ctx` API |
 
 ## Key-feature coverage
 
@@ -39,6 +40,7 @@ this matrix in the same change.
 | Deterministic fixtures and journal assertions | 07 · Testing workflows |
 | Durable task observation, selection, deduplication, and upsert | 08 · Task-backed code review |
 | Custom result views, custom human input, composed React presentations | 09 · Custom React UI |
+| Every remaining public workflow API | 10 · Minimal API cookbook; enforced by `pnpm verify:examples` |
 
 Most example *workflows* used by the CLI live separately in [`.weft/workflows/`](../.weft/workflows)
 (`review.ts`, `audit-and-fix.ts`) — those are what `weft run review` executes; the folders
diff --git a/examples/coverage.json b/examples/coverage.json
new file mode 100644
index 00000000..a170eb43
--- /dev/null
+++ b/examples/coverage.json
@@ -0,0 +1,69 @@
+{
+  "ctx.agent": "examples/10-api-cookbook/composition.ts",
+  "ctx.agent.detailed": "examples/10-api-cookbook/composition.ts",
+  "ctx.bash": "examples/10-api-cookbook/effects.ts",
+  "ctx.budget": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.check": "examples/10-api-cookbook/effects.ts",
+  "ctx.discard": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.env.get": "examples/10-api-cookbook/effects.ts",
+  "ctx.exec": "examples/10-api-cookbook/effects.ts",
+  "ctx.fetch": "examples/10-api-cookbook/effects.ts",
+  "ctx.fs.glob": "examples/10-api-cookbook/effects.ts",
+  "ctx.fs.read": "examples/10-api-cookbook/effects.ts",
+  "ctx.fs.stat": "examples/10-api-cookbook/effects.ts",
+  "ctx.gate": "examples/10-api-cookbook/humans-and-waits.ts",
+  "ctx.git.add": "examples/10-api-cookbook/git.ts",
+  "ctx.git.apply": "examples/10-api-cookbook/git.ts",
+  "ctx.git.blame": "examples/10-api-cookbook/git.ts",
+  "ctx.git.branch.create": "examples/10-api-cookbook/git.ts",
+  "ctx.git.branch.delete": "examples/10-api-cookbook/git.ts",
+  "ctx.git.branches": "examples/10-api-cookbook/git.ts",
+  "ctx.git.changedSince": "examples/10-api-cookbook/git.ts",
+  "ctx.git.checkout": "examples/10-api-cookbook/git.ts",
+  "ctx.git.clean": "examples/10-api-cookbook/git.ts",
+  "ctx.git.commit": "examples/10-api-cookbook/git.ts",
+  "ctx.git.diff": "examples/10-api-cookbook/git.ts",
+  "ctx.git.fetch": "examples/10-api-cookbook/git.ts",
+  "ctx.git.fileAt": "examples/10-api-cookbook/git.ts",
+  "ctx.git.head": "examples/10-api-cookbook/git.ts",
+  "ctx.git.log": "examples/10-api-cookbook/git.ts",
+  "ctx.git.mergeBase": "examples/10-api-cookbook/git.ts",
+  "ctx.git.pull": "examples/10-api-cookbook/git.ts",
+  "ctx.git.push": "examples/10-api-cookbook/git.ts",
+  "ctx.git.reset": "examples/10-api-cookbook/git.ts",
+  "ctx.git.show": "examples/10-api-cookbook/git.ts",
+  "ctx.git.snapshot": "examples/10-api-cookbook/git.ts",
+  "ctx.git.stash.drop": "examples/10-api-cookbook/git.ts",
+  "ctx.git.stash.pop": "examples/10-api-cookbook/git.ts",
+  "ctx.git.stash.push": "examples/10-api-cookbook/git.ts",
+  "ctx.git.status": "examples/10-api-cookbook/git.ts",
+  "ctx.git.tag": "examples/10-api-cookbook/git.ts",
+  "ctx.human.approve": "examples/10-api-cookbook/humans-and-waits.ts",
+  "ctx.human.ask": "examples/10-api-cookbook/humans-and-waits.ts",
+  "ctx.human.review": "examples/10-api-cookbook/humans-and-waits.ts",
+  "ctx.integrate": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.log": "examples/10-api-cookbook/composition.ts",
+  "ctx.note": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.now": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.ok": "examples/10-api-cookbook/composition.ts",
+  "ctx.parallel": "examples/10-api-cookbook/composition.ts",
+  "ctx.phase": "examples/10-api-cookbook/composition.ts",
+  "ctx.pipeline": "examples/10-api-cookbook/composition.ts",
+  "ctx.pipeline.filter": "examples/10-api-cookbook/composition.ts",
+  "ctx.pipeline.map": "examples/10-api-cookbook/composition.ts",
+  "ctx.pipeline.run": "examples/10-api-cookbook/composition.ts",
+  "ctx.pipeline.step": "examples/10-api-cookbook/composition.ts",
+  "ctx.random": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.run": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.secret": "examples/10-api-cookbook/effects.ts",
+  "ctx.signal": "examples/10-api-cookbook/humans-and-waits.ts",
+  "ctx.sleep": "examples/10-api-cookbook/humans-and-waits.ts",
+  "ctx.tasks.note": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.tasks.observe": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.tasks.setCriterion": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.tasks.update": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.tasks.upsert": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.ui.render": "examples/09-custom-react-ui/workflow.ts",
+  "ctx.uuid": "examples/10-api-cookbook/state-tasks-and-patches.ts",
+  "ctx.workflow": "examples/10-api-cookbook/composition.ts"
+}
diff --git a/package.json b/package.json
index e97fb94b..8c653deb 100644
--- a/package.json
+++ b/package.json
@@ -20,6 +20,7 @@
     "format": "biome format --write .",
     "sync:meta": "node scripts/sync-package-meta.mjs",
     "verify:packing": "node scripts/verify-packing.mjs",
+    "verify:examples": "node scripts/check-example-coverage.mjs",
     "version:set": "node scripts/set-version.mjs",
     "verify:install": "node scripts/verify-install.mjs",
     "dev:ui": "pnpm --filter @techery/weft-ui dev"
diff --git a/packages/gate/test/gate.test.ts b/packages/gate/test/gate.test.ts
index 4e5593a6..7b6f66eb 100644
--- a/packages/gate/test/gate.test.ts
+++ b/packages/gate/test/gate.test.ts
@@ -450,6 +450,20 @@ describe("bundleWorkflow", () => {
     ]);
   });
 
+  it("keeps every minimal API cookbook workflow gate-clean", async () => {
+    const files = [
+      "composition.ts",
+      "humans-and-waits.ts",
+      "effects.ts",
+      "git.ts",
+      "state-tasks-and-patches.ts",
+    ];
+    for (const file of files) {
+      const loaded = await loadWorkflow({ entry: path.join(repoRoot, "examples/10-api-cookbook", file) });
+      expect(loaded.def.kind, file).toBe("weft.workflow");
+    }
+  });
+
   it("inlines relative imports and keeps @techery/weft-sdk external", async () => {
     const dir = await tempDir();
     const entry = await writeReview(dir);
diff --git a/scripts/check-example-coverage.mjs b/scripts/check-example-coverage.mjs
new file mode 100644
index 00000000..e307efb6
--- /dev/null
+++ b/scripts/check-example-coverage.mjs
@@ -0,0 +1,94 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import ts from "typescript";
+
+const root = process.cwd();
+const sources = await Promise.all(
+  ["packages/sdk/src/types.ts", "packages/sdk/src/ui.ts"].map(async (file) => ({
+    file,
+    text: await readFile(path.join(root, file), "utf8"),
+  })),
+);
+const interfaces = new Map();
+for (const { file, text } of sources) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  for (const statement of source.statements) {
+    if (ts.isInterfaceDeclaration(statement)) interfaces.set(statement.name.text, statement);
+  }
+}
+
+const api = new Set();
+walkInterface("Ctx", "ctx");
+
+if (process.argv.includes("--list")) {
+  console.log([...api].sort().join("\n"));
+  process.exit(0);
+}
+
+const manifestPath = path.join(root, "examples/coverage.json");
+const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+const covered = new Set(Object.keys(manifest));
+const missing = [...api].filter((key) => !covered.has(key)).sort();
+const stale = [...covered].filter((key) => !api.has(key)).sort();
+const absentFiles = [];
+for (const [key, file] of Object.entries(manifest)) {
+  if (typeof file !== "string") absentFiles.push(`${key}: path must be a string`);
+  else await access(path.join(root, file)).catch(() => absentFiles.push(`${key}: ${file}`));
+}
+if (missing.length || stale.length || absentFiles.length) {
+  if (missing.length) console.error(`Missing example coverage:\n${missing.join("\n")}`);
+  if (stale.length) console.error(`Stale example coverage:\n${stale.join("\n")}`);
+  if (absentFiles.length) console.error(`Missing example files:\n${absentFiles.join("\n")}`);
+  process.exit(1);
+}
+console.log(`example coverage: ${api.size} public workflow surfaces mapped`);
+
+function walkInterface(name, prefix) {
+  const declaration = interfaces.get(name);
+  if (!declaration) return;
+  walkMembers(declaration.members, prefix, name);
+}
+
+function walkMembers(members, prefix, owner) {
+  for (const member of members) {
+    if (ts.isCallSignatureDeclaration(member)) {
+      api.add(prefix);
+      continue;
+    }
+    const name = propertyName(member.name);
+    if (!name) continue;
+    const key = `${prefix}.${name}`;
+    if (ts.isMethodSignature(member)) {
+      api.add(key);
+      if (owner === "Ctx" && typeReferenceName(member.type) === "Pipeline") walkInterface("Pipeline", key);
+      continue;
+    }
+    if (!ts.isPropertySignature(member)) continue;
+    if (member.type && ts.isTypeLiteralNode(member.type)) {
+      walkMembers(member.type.members, key, owner);
+      continue;
+    }
+    const target = typeReferenceName(member.type);
+    const nested = target ? interfaces.get(target) : undefined;
+    if (
+      nested &&
+      [...nested.members].some((child) => ts.isMethodSignature(child) || ts.isCallSignatureDeclaration(child))
+    ) {
+      walkInterface(target, key);
+    } else {
+      api.add(key);
+    }
+  }
+}
+
+function propertyName(name) {
+  if (!name) return undefined;
+  return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+}
+
+function typeReferenceName(node) {
+  return node && ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)
+    ? node.typeName.text
+    : undefined;
+}

From af869ef4a6fb33aa2b8ee551f5a0c73315dfde23 Mon Sep 17 00:00:00 2001
From: Serge Zenchenko <sergeizenchenko@gmail.com>
Date: Wed, 26 Aug 2026 16:21:43 +0100
Subject: [PATCH 5/6] Address custom UI review findings

---
 apps/ui/package.json                          |  1 +
 .../molecules/WorkflowViewFrame.test.tsx      | 58 +++++++++++++++++++
 .../molecules/WorkflowViewFrame.tsx           | 53 +++++++++++++----
 packages/core/src/runtime.ts                  | 11 +++-
 packages/core/test/ui.test.ts                 | 27 +++++++++
 packages/gate/src/ui-bundle.ts                | 36 ++++++++----
 packages/gate/test/gate.test.ts               | 32 ++++++++++
 packages/sdk/src/index.ts                     |  1 +
 packages/sdk/src/ui.ts                        |  3 +
 pnpm-lock.yaml                                |  3 +
 10 files changed, 202 insertions(+), 23 deletions(-)
 create mode 100644 apps/ui/src/components/molecules/WorkflowViewFrame.test.tsx

diff --git a/apps/ui/package.json b/apps/ui/package.json
index d036aa51..5376b0ff 100644
--- a/apps/ui/package.json
+++ b/apps/ui/package.json
@@ -15,6 +15,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@techery/weft-sdk": "workspace:*",
     "@tanstack/react-query": "^5.102.3",
     "@tanstack/react-router": "^1.170.32",
     "jotai": "^2.20.3",
diff --git a/apps/ui/src/components/molecules/WorkflowViewFrame.test.tsx b/apps/ui/src/components/molecules/WorkflowViewFrame.test.tsx
new file mode 100644
index 00000000..f4510c4f
--- /dev/null
+++ b/apps/ui/src/components/molecules/WorkflowViewFrame.test.tsx
@@ -0,0 +1,58 @@
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { api } from "~/api/client";
+import type { UiPresentation } from "~/api/types";
+import { WorkflowViewFrame } from "./WorkflowViewFrame";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+
+function presentation(blob: string, hash: string): UiPresentation {
+  return {
+    id: "u1",
+    asset: {
+      id: "summary",
+      revision: "1",
+      bundleRef: { $blob: "a".repeat(64), size: 128 },
+      protocol: 1,
+    },
+    props: { ref: { $blob: blob, size: 32 }, hash },
+    mode: "display",
+  };
+}
+
+describe("WorkflowViewFrame", () => {
+  it("does not post stale blob props after the run identity changes", async () => {
+    const oldProps = deferred<unknown>();
+    const nextProps = deferred<unknown>();
+    vi.spyOn(api, "blobJson").mockImplementation((ref) =>
+      ref === "old" ? oldProps.promise : nextProps.promise,
+    );
+    const posted: unknown[] = [];
+    const { rerender } = render(
+      <WorkflowViewFrame runId="old-run" presentation={presentation("old", "old-hash")} />,
+    );
+    const oldFrame = screen.getByTitle<HTMLIFrameElement>("Workflow view summary");
+    if (!oldFrame.contentWindow) throw new Error("test iframe has no contentWindow");
+    oldFrame.contentWindow.postMessage = ((message: unknown) => posted.push(message)) as typeof postMessage;
+    fireEvent.load(oldFrame);
+
+    rerender(<WorkflowViewFrame runId="next-run" presentation={presentation("next", "next-hash")} />);
+    const nextFrame = screen.getByTitle<HTMLIFrameElement>("Workflow view summary");
+    if (!nextFrame.contentWindow) throw new Error("test iframe has no contentWindow");
+    nextFrame.contentWindow.postMessage = ((message: unknown) => posted.push(message)) as typeof postMessage;
+    fireEvent.load(nextFrame);
+
+    await act(async () => nextProps.resolve({ run: "next" }));
+    await waitFor(() => expect(posted).toHaveLength(1));
+    expect(posted[0]).toMatchObject({ props: { run: "next" } });
+
+    await act(async () => oldProps.resolve({ run: "old" }));
+    await waitFor(() => expect(posted).toHaveLength(1));
+  });
+});
diff --git a/apps/ui/src/components/molecules/WorkflowViewFrame.tsx b/apps/ui/src/components/molecules/WorkflowViewFrame.tsx
index 397b04b4..e9581fc4 100644
--- a/apps/ui/src/components/molecules/WorkflowViewFrame.tsx
+++ b/apps/ui/src/components/molecules/WorkflowViewFrame.tsx
@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { UI_PROTOCOL_MAX_PROPS_BYTES } from "@techery/weft-sdk/ui";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { api } from "~/api/client";
 import type { UiPresentation } from "~/api/types";
 import styles from "./WorkflowViewFrame.module.css";
@@ -11,15 +12,15 @@ type Props = {
 
 type FrameStatus = "loading" | "ready" | "error" | "disabled";
 
-const MAX_MESSAGE_BYTES = 64 * 1024;
+const MAX_FRAME_MESSAGE_BYTES = 64 * 1024;
 const MIN_HEIGHT = 80;
 const MAX_HEIGHT = 720;
 const READY_TIMEOUT_MS = 5_000;
 
-function jsonSize(value: unknown): number | undefined {
+function jsonByteSize(value: unknown): number | undefined {
   try {
     const encoded = JSON.stringify(value);
-    return encoded === undefined ? undefined : encoded.length;
+    return encoded === undefined ? undefined : new TextEncoder().encode(encoded).byteLength;
   } catch {
     return undefined;
   }
@@ -29,15 +30,38 @@ function jsonSize(value: unknown): number | undefined {
 export function WorkflowViewFrame({ runId, presentation, onCandidate }: Props) {
   const frame = useRef<HTMLIFrameElement>(null);
   const channel = useRef<MessageChannel | null>(null);
+  const initialization = useRef(0);
   const generation = useRef(0);
   const readyTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastResize = useRef(0);
   const [status, setStatus] = useState<FrameStatus>("loading");
   const [height, setHeight] = useState(180);
   const [message, setMessage] = useState("");
+  const identity = JSON.stringify([
+    runId,
+    presentation.id,
+    presentation.asset.bundleRef.$blob,
+    presentation.props.hash,
+  ]);
+  const activeIdentity = useRef(identity);
+
+  useLayoutEffect(() => {
+    if (activeIdentity.current === identity) return;
+    activeIdentity.current = identity;
+    initialization.current += 1;
+    if (readyTimer.current) clearTimeout(readyTimer.current);
+    readyTimer.current = null;
+    channel.current?.port1.close();
+    channel.current?.port2.close();
+    channel.current = null;
+    setStatus("loading");
+    setMessage("");
+    setHeight(180);
+  }, [identity]);
 
   useEffect(() => {
     return () => {
+      initialization.current += 1;
       if (readyTimer.current) clearTimeout(readyTimer.current);
       channel.current?.port1.close();
       channel.current?.port2.close();
@@ -47,14 +71,21 @@ export function WorkflowViewFrame({ runId, presentation, onCandidate }: Props) {
   const initialize = useCallback(async () => {
     const target = frame.current?.contentWindow;
     if (!target || status === "disabled") return;
+    const attempt = ++initialization.current;
+    const currentIdentity = identity;
+    const isCurrent = () =>
+      initialization.current === attempt &&
+      activeIdentity.current === currentIdentity &&
+      frame.current?.contentWindow === target;
     try {
       const props =
         "inline" in presentation.props
           ? presentation.props.inline
           : await api.blobJson(presentation.props.ref.$blob);
-      const bytes = jsonSize(props);
+      if (!isCurrent()) return;
+      const bytes = jsonByteSize(props);
       if (bytes === undefined) throw new Error("presentation props must be JSON serializable");
-      if (bytes > MAX_MESSAGE_BYTES * 8) throw new Error("presentation props are too large to render");
+      if (bytes > UI_PROTOCOL_MAX_PROPS_BYTES) throw new Error("presentation props are too large to render");
       const next = new MessageChannel();
       channel.current?.port1.close();
       channel.current?.port2.close();
@@ -62,6 +93,7 @@ export function WorkflowViewFrame({ runId, presentation, onCandidate }: Props) {
       const mounted = String(++generation.current);
       if (readyTimer.current) clearTimeout(readyTimer.current);
       readyTimer.current = setTimeout(() => {
+        if (!isCurrent()) return;
         setStatus("error");
         setMessage("custom view did not become ready in time");
         next.port1.close();
@@ -71,8 +103,8 @@ export function WorkflowViewFrame({ runId, presentation, onCandidate }: Props) {
         if (typeof value !== "object" || value === null) return;
         const data = value as Record<string, unknown>;
         if (data.presentationId !== presentation.id || data.generation !== mounted) return;
-        const size = jsonSize(data);
-        if (size === undefined || size > MAX_MESSAGE_BYTES) return;
+        const size = jsonByteSize(data);
+        if (size === undefined || size > MAX_FRAME_MESSAGE_BYTES) return;
         if (data.type === "ready") {
           if (readyTimer.current) clearTimeout(readyTimer.current);
           readyTimer.current = null;
@@ -83,7 +115,7 @@ export function WorkflowViewFrame({ runId, presentation, onCandidate }: Props) {
           lastResize.current = now;
           setHeight(Math.max(MIN_HEIGHT, Math.min(MAX_HEIGHT, Math.ceil(data.height))));
         } else if (data.type === "candidate" && presentation.mode === "input") {
-          if (jsonSize(data.answer) === undefined) return;
+          if (jsonByteSize(data.answer) === undefined) return;
           onCandidate?.(data.answer);
         } else if (data.type === "error" && typeof data.message === "string") {
           if (readyTimer.current) clearTimeout(readyTimer.current);
@@ -105,12 +137,13 @@ export function WorkflowViewFrame({ runId, presentation, onCandidate }: Props) {
         [next.port2],
       );
     } catch (error) {
+      if (!isCurrent()) return;
       if (readyTimer.current) clearTimeout(readyTimer.current);
       readyTimer.current = null;
       setStatus("error");
       setMessage(error instanceof Error ? error.message : String(error));
     }
-  }, [onCandidate, presentation, status]);
+  }, [identity, onCandidate, presentation, status]);
 
   if (status === "disabled") {
     return (
diff --git a/packages/core/src/runtime.ts b/packages/core/src/runtime.ts
index 2f21fbdd..a0febfc4 100644
--- a/packages/core/src/runtime.ts
+++ b/packages/core/src/runtime.ts
@@ -16,6 +16,7 @@ import {
   type Risk,
   StepError,
   type StepRef,
+  UI_PROTOCOL_MAX_PROPS_BYTES,
   type Usage,
   validateSchema,
 } from "@techery/weft-sdk";
@@ -506,9 +507,17 @@ export class RunRuntime {
       });
     }
     const json = canonicalJson(props);
+    const propsBytes = Buffer.byteLength(json);
+    if (propsBytes > UI_PROTOCOL_MAX_PROPS_BYTES) {
+      throw new StepError(
+        "invalid_input",
+        `UI props are ${propsBytes} bytes; protocol limit is ${UI_PROTOCOL_MAX_PROPS_BYTES}`,
+        { step: { kind: "ui", runId: this.runId } },
+      );
+    }
     const propsHash = sha256Hex(json);
     const propsJson =
-      Buffer.byteLength(json) <= this.host.config.limits.blobThresholdBytes
+      propsBytes <= this.host.config.limits.blobThresholdBytes
         ? ({ inline: props, hash: propsHash } as const)
         : await this.host.blobs.put(json, { kind: "ui-props", contentType: "application/json" }).then(
             (ref) =>
diff --git a/packages/core/test/ui.test.ts b/packages/core/test/ui.test.ts
index 19d7d753..1803df16 100644
--- a/packages/core/test/ui.test.ts
+++ b/packages/core/test/ui.test.ts
@@ -5,6 +5,7 @@ import {
   type DisplayUiView,
   defineWorkflow,
   type InputUiView,
+  UI_PROTOCOL_MAX_PROPS_BYTES,
   z,
 } from "@techery/weft-sdk";
 import { afterAll, describe, expect, test } from "vitest";
@@ -66,6 +67,32 @@ describe("custom workflow UI", () => {
     expect(completions).toHaveLength(1);
   });
 
+  test("rejects UI props above the protocol byte limit before journaling a presentation", async () => {
+    const t = testEngine({ config: { limits: { blobThresholdBytes: 1 } } });
+    const view = { kind: "weft.ui-view", assetKey } as unknown as DisplayUiView<{ message: string }>;
+    const def = defineWorkflow(
+      { description: "oversized-ui", input: z.object({}), output: z.object({ ok: z.boolean() }) },
+      async (ctx) => {
+        await ctx.ui.render({
+          key: "summary",
+          view,
+          // Multi-byte text verifies the protocol limit is measured as UTF-8 bytes.
+          props: { message: "é".repeat(UI_PROTOCOL_MAX_PROPS_BYTES / 2) },
+        });
+        return { ok: true };
+      },
+    );
+    const handle = await t.engine.start(def, {
+      input: {},
+      cwd: await tempDir(),
+      uiCatalog: catalog(),
+    });
+
+    await expect(handle.result).rejects.toThrow(/UI props are \d+ bytes; protocol limit is 524288/);
+    const state = await t.engine.state(handle.runId);
+    expect(state.steps.some((step) => step.presentation !== undefined)).toBe(false);
+  });
+
   test("input views stage durable UI while the schema remains authoritative", async () => {
     const t = testEngine();
     const Answer = z.object({ choice: z.enum(["a", "b"]) });
diff --git a/packages/gate/src/ui-bundle.ts b/packages/gate/src/ui-bundle.ts
index 13814291..079fbd28 100644
--- a/packages/gate/src/ui-bundle.ts
+++ b/packages/gate/src/ui-bundle.ts
@@ -192,15 +192,7 @@ function browserImportPolicy(root: string): Plugin {
     "@techery/weft-sdk/ui",
   ]);
   const supported = /\.[cm]?[jt]sx?$/;
-  const compilerFiles = new Set(
-    [...allowedBare].flatMap((specifier) => {
-      try {
-        return [COMPILER_REQUIRE.resolve(specifier)];
-      } catch {
-        return [];
-      }
-    }),
-  );
+  const compilerFiles = new Set<string>();
   return {
     name: "weft-ui-browser-policy",
     setup(pluginBuild) {
@@ -210,6 +202,25 @@ function browserImportPolicy(root: string): Plugin {
         }
         return null;
       });
+      pluginBuild.onResolve({ filter: /^(?:\.{1,2}(?:\/|$)|\/)/ }, async (args) => {
+        if (compilerFiles.has(args.importer)) {
+          try {
+            const resolved = createRequire(args.importer).resolve(args.path);
+            compilerFiles.add(resolved);
+            return { path: resolved };
+          } catch (err) {
+            return {
+              errors: [{ text: `cannot resolve compiler-owned ${args.path}: ${(err as Error).message}` }],
+            };
+          }
+        }
+        const requested = path.resolve(args.resolveDir || root, args.path);
+        const file = await realpath(requested).catch(() => requested);
+        if (!inside(root, file)) {
+          return { errors: [{ text: `browser import escapes the workflow root: ${args.path}` }] };
+        }
+        return null;
+      });
       pluginBuild.onResolve({ filter: /^[^./]/ }, (args) => {
         if (!allowedBare.has(args.path)) {
           return {
@@ -217,7 +228,9 @@ function browserImportPolicy(root: string): Plugin {
           };
         }
         try {
-          return { path: COMPILER_REQUIRE.resolve(args.path) };
+          const resolved = COMPILER_REQUIRE.resolve(args.path);
+          compilerFiles.add(resolved);
+          return { path: resolved };
         } catch (err) {
           return {
             errors: [{ text: `cannot resolve compiler-owned ${args.path}: ${(err as Error).message}` }],
@@ -228,8 +241,7 @@ function browserImportPolicy(root: string): Plugin {
         errors: [{ text: `CSS imports are not supported in workflow UI v1 (${args.path})` }],
       }));
       pluginBuild.onLoad({ filter: /.*/, namespace: "file" }, async (args) => {
-        if (args.path.includes(`${path.sep}node_modules${path.sep}`) || compilerFiles.has(args.path))
-          return null;
+        if (compilerFiles.has(args.path)) return null;
         if (!inside(root, await realpath(args.path).catch(() => args.path))) {
           return { errors: [{ text: `browser import escapes the workflow root: ${args.path}` }] };
         }
diff --git a/packages/gate/test/gate.test.ts b/packages/gate/test/gate.test.ts
index 7b6f66eb..57fecaa6 100644
--- a/packages/gate/test/gate.test.ts
+++ b/packages/gate/test/gate.test.ts
@@ -438,6 +438,38 @@ describe("bundleWorkflow", () => {
     await expect(bundleWorkflow({ entry, cwd: dir })).rejects.toThrow(/dynamic imports are not supported/);
   });
 
+  it("rejects relative node_modules paths that escape the workflow root", async () => {
+    const project = await tempDir();
+    const root = path.join(project, ".weft/workflows");
+    await write(project, "node_modules/unapproved/index.js", `export default "escaped";`);
+    await write(
+      root,
+      "panel.ui.tsx",
+      [
+        `import { defineResultView } from "@techery/weft-sdk/ui";`,
+        `import escaped from "../../node_modules/unapproved/index.js";`,
+        `export default defineResultView<Record<string, never>>({`,
+        `  id: "panel", revision: "1",`,
+        `  component: () => <strong>{escaped}</strong>,`,
+        `});`,
+      ].join("\n"),
+    );
+    const entry = await write(
+      root,
+      "workflow.ts",
+      [
+        `import { defineWorkflow, z } from "@techery/weft-sdk";`,
+        `import panel from "./panel.ui.tsx";`,
+        `export default defineWorkflow(`,
+        `  { description: "ui", input: z.object({}), output: z.object({ ok: z.boolean() }) },`,
+        `  async (ctx) => { await ctx.ui.render({ key: "panel", view: panel, props: {} }); return { ok: true }; },`,
+        `);`,
+      ].join("\n"),
+    );
+
+    await expect(bundleWorkflow({ entry })).rejects.toThrow(/browser import escapes the workflow root/);
+  });
+
   it("keeps the custom React UI example compilable as three browser views", async () => {
     const loaded = await loadWorkflow({
       entry: path.join(repoRoot, "examples/09-custom-react-ui/workflow.ts"),
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 16555c6e..82adead7 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -120,3 +120,4 @@ export type {
   UiViewMode,
   UiViewRef,
 } from "./ui.ts";
+export { UI_PROTOCOL_MAX_PROPS_BYTES } from "./ui.ts";
diff --git a/packages/sdk/src/ui.ts b/packages/sdk/src/ui.ts
index 95eac97f..25dc9014 100644
--- a/packages/sdk/src/ui.ts
+++ b/packages/sdk/src/ui.ts
@@ -4,6 +4,9 @@ export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue
 
 export type UiViewMode = "input" | "display";
 
+/** Maximum UTF-8 JSON payload accepted by custom UI protocol v1. */
+export const UI_PROTOCOL_MAX_PROPS_BYTES = 512 * 1024;
+
 /**
  * The opaque value workflow code receives for a `.ui.tsx` import.
  *
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index aeb56067..52f66d3d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -53,6 +53,9 @@ importers:
       '@tanstack/react-router':
         specifier: ^1.170.32
         version: 1.170.32(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+      '@techery/weft-sdk':
+        specifier: workspace:*
+        version: link:../../packages/sdk
       jotai:
         specifier: ^2.20.3
         version: 2.20.3(@types/react@19.2.18)(react@19.2.8)

From 73dab300a343ac31dfacf6c77753a1fe8467bf9f Mon Sep 17 00:00:00 2001
From: Serge Zenchenko <sergeizenchenko@gmail.com>
Date: Wed, 26 Aug 2026 16:37:40 +0100
Subject: [PATCH 6/6] Preserve custom UI in pending requests

---
 packages/core/src/engine.ts   |  2 ++
 packages/core/test/ui.test.ts | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/packages/core/src/engine.ts b/packages/core/src/engine.ts
index ea5a30fe..fd79f96c 100644
--- a/packages/core/src/engine.ts
+++ b/packages/core/src/engine.ts
@@ -2050,6 +2050,8 @@ export class Engine implements EngineHost {
         ...(h.risk !== undefined ? { risk: h.risk } : {}),
         ...(h.deadline !== undefined ? { deadline: h.deadline } : {}),
         ...(h.confirmToken !== undefined ? { confirmToken: h.confirmToken } : {}),
+        ...(h.artifactRef !== undefined ? { artifactRef: h.artifactRef } : {}),
+        ...(h.ui !== undefined ? { ui: h.ui } : {}),
       }));
     for (const { childRunId } of state.children) {
       if (seen.has(childRunId)) continue;
diff --git a/packages/core/test/ui.test.ts b/packages/core/test/ui.test.ts
index 1803df16..36dc973e 100644
--- a/packages/core/test/ui.test.ts
+++ b/packages/core/test/ui.test.ts
@@ -121,6 +121,7 @@ describe("custom workflow UI", () => {
       asset: { id: "test-view", revision: "1" },
       mode: "input",
     });
+    expect((await t.engine.pending(handle.runId))[0]?.ui).toEqual(waiting.pending[0]?.ui);
     await expect(t.engine.answer(handle.runId, waiting.pending[0]!.id, { choice: "nope" })).rejects.toThrow(
       /does not match/,
     );
@@ -128,6 +129,40 @@ describe("custom workflow UI", () => {
     await expect(handle.result).resolves.toEqual({ choice: "a" });
   });
 
+  test("engine.pending preserves child input views after the owner restarts", async () => {
+    const t = testEngine();
+    const Answer = z.object({ choice: z.string() });
+    const view = { kind: "weft.ui-view", assetKey } as unknown as InputUiView<
+      Record<string, never>,
+      z.input<typeof Answer>
+    >;
+    const child = defineWorkflow(
+      { name: "ui-child", description: "child", input: z.object({}), output: Answer },
+      async (ctx) =>
+        ctx.human.ask({ key: "choice", question: "Choose", schema: Answer, ui: { view, props: {} } }),
+    );
+    const parent = defineWorkflow(
+      { name: "ui-parent", description: "parent", input: z.object({}), output: Answer },
+      async (ctx) => (await ctx.workflow(child, {}, { key: "child" })) as z.output<typeof Answer>,
+    );
+    const handle = await t.engine.start(parent, {
+      input: {},
+      cwd: await tempDir(),
+      uiCatalog: catalog("1", "input"),
+    });
+    const waiting = await handle.outcome();
+    if (waiting.status !== "waiting_for_human") throw new Error("expected child human request");
+    await t.engine.shutdown();
+
+    const next = reopen(t);
+    const pending = await next.engine.pending(handle.runId);
+    expect(pending).toHaveLength(1);
+    expect(pending[0]).toMatchObject({
+      ui: { asset: { id: "test-view", revision: "1" }, mode: "input" },
+    });
+    expect(pending[0]?.runId).not.toBe(handle.runId);
+  });
+
   test("a changed input-view revision supersedes the old same-key request", async () => {
     const first = testEngine();
     const Answer = z.object({ choice: z.string() });