jev-devtools 0.4.0 → 0.5.0

package/lib/flow/index.js

@@ -1,5 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { jsonSnapshot, runCallback } from "./runtime.js";
+import { jsonSnapshot, observerSnapshot, observeRequest, runCallback, } from "./runtime.js";
+import { stepContext } from "./step-context.js";
+export { replayClient } from "./replay.js";
+export { flowFixture } from "../src/flow-fixture.js";
+export { compareWithFixture, formatComparison, } from "./compare.js";
 const owners = new WeakMap();
 const builderIds = new WeakMap();
 function freezeAst(ast, depth = 0) {
@@ -64,8 +68,10 @@ export const any = (...conditions) => operation("any", conditions);
 export const not = (condition) => operation("not", [condition]);
 // Nested programs share a reservation budget without exposing execution internals in the API.
 const executionBudgets = new WeakMap();
-function withBudget(options, budget) {
+const itemScopes = new WeakMap();
+function withBudget(options, budget, scope) {
     executionBudgets.set(options, budget);
+    itemScopes.set(options, scope);
     return options;
 }
 function definitionSize(definition) {
@@ -650,6 +656,11 @@ export function defineJevFlow(name, build) {
             };
             const started = performance.now(), values = new Map();
             const budget = executionBudgets.get(options) ?? { used: nodes.length };
+            const scope = itemScopes.get(options) ?? {
+                runId: run.id,
+                flow: name,
+                prefix: "",
+            };
             const reserve = (count) => {
                 if (budget.used + count > 1024)
                     throw new RangeError("Flow exceeds 1024 expanded steps");
@@ -662,16 +673,56 @@ export function defineJevFlow(name, build) {
             catch {
                 /* Recording cannot stop execution. */
             }
+            // Data objects are replaced, never mutated by execution. Keep detached
+            // copies stable so the recorder can reuse its captures on unrelated updates.
+            const observerData = new WeakMap();
+            const snapshotData = (value) => {
+                if (value && typeof value === "object" && observerData.has(value))
+                    return observerData.get(value);
+                let snapshot;
+                try {
+                    snapshot = observerSnapshot(value);
+                }
+                catch {
+                    // Direct flow outputs may be non-JSON; only their capture is unavailable.
+                    snapshot = "[capture unavailable]";
+                }
+                if (value && typeof value === "object")
+                    observerData.set(value, snapshot);
+                return snapshot;
+            };
             const emit = () => {
                 try {
                     if (observer) {
                         const { value, steps, ...metadata } = run;
-                        // Stable data snapshots are captured once by the recorder, not
-                        // cloned/redacted again on every unrelated step update.
                         observer.update({
                             ...structuredClone(metadata),
-                            steps: Object.fromEntries(Object.entries(steps).map(([id, step]) => [id, { ...step }])),
-                            ...(value !== undefined ? { value } : {}),
+                            steps: Object.fromEntries(Object.entries(steps).map(([id, step]) => [
+                                id,
+                                {
+                                    ...step,
+                                    ...(step.data !== undefined
+                                        ? { data: snapshotData(step.data) }
+                                        : {}),
+                                    ...(step.loop ? { loop: { ...step.loop } } : {}),
+                                    ...(step.captureWarnings
+                                        ? { captureWarnings: [...step.captureWarnings] }
+                                        : {}),
+                                    ...(step.collection
+                                        ? {
+                                            collection: {
+                                                ...step.collection,
+                                                // Child runs have already crossed this snapshot boundary.
+                                                // Copy mutable collection metadata, reuse detached children.
+                                                items: step.collection.items.map((item) => ({
+                                                    ...item,
+                                                })),
+                                            },
+                                        }
+                                        : {}),
+                                },
+                            ])),
+                            ...(value !== undefined ? { value: snapshotData(value) } : {}),
                         });
                     }
                 }
@@ -728,23 +779,31 @@ export function defineJevFlow(name, build) {
                                 return evaluate(e.ast, data, values);
                             });
                             abortCheck();
-                            const call = () => options.client.systemOne(request, {
-                                signal: controller.signal,
-                            });
+                            const call = () => {
+                                abortCheck();
+                                return stepContext.run({
+                                    runId: scope.runId,
+                                    stepId: scope.prefix + step.id,
+                                    executionId: state.executionId,
+                                    flow: scope.flow,
+                                }, () => options.client.systemOne(request, {
+                                    signal: controller.signal,
+                                }));
+                            };
                             const link = {
                                 runId: run.id,
                                 stepId: step.id,
                                 executionId: state.executionId,
                             };
-                            value = await runCallback(() => observer
-                                ? observer.request(link, (id) => {
+                            value = await runCallback(() => observeRequest(call, observer
+                                ? (callOnce) => observer.request(link, (id) => {
                                     if (controller.signal.aborted ||
                                         state.status !== "running")
                                         return;
                                     state.traceId = id;
                                     emit();
-                                }, call)
-                                : call(), controller.signal);
+                                }, callOnce)
+                                : undefined), controller.signal);
                             abortCheck();
                         }
                         else if (step.kind === "task") {
@@ -828,7 +887,7 @@ export function defineJevFlow(name, build) {
                                             };
                                         },
                                     },
-                                }, budget));
+                                }, budget, { ...scope, prefix: `${scope.prefix}${step.id}/${index}/` }));
                                 abortCheck();
                                 current = jsonSnapshot(result.value);
                                 state.data = { input: initial, output: current };
@@ -897,7 +956,10 @@ export function defineJevFlow(name, build) {
                                                     };
                                                 },
                                             },
-                                        }, budget));
+                                        }, budget, {
+                                            ...scope,
+                                            prefix: `${scope.prefix}${step.id}/${index}/`,
+                                        }));
                                         results[index] = result.value;
                                     }
                                     catch (error) {
@@ -1004,7 +1066,7 @@ export function defineJevFlow(name, build) {
                     throw new Error("Flow must return a named output");
                 run.status = "success";
                 run.outcome = result.outcome;
-                // Only the recorder snapshots output data; runtime keeps the actual typed value.
+                // emit() detaches the observer's output; callers keep the actual typed value.
                 if (result.value !== undefined)
                     run.value = result.value;
                 return { runId: run.id, ...result };

package/lib/flow/replay.d.ts

@@ -0,0 +1,5 @@
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import type { FlowFixture } from "../src/flow-fixture.js";
+export type { FlowFixture } from "../src/flow-fixture.js";
+/** Answers each jev step from fixture.steps[stepId]; no network or API key. Use only as a flow run's client. */
+export declare function replayClient(fixture: FlowFixture): TypeSafeClient;

package/lib/flow/replay.js

@@ -0,0 +1,55 @@
+import { APIPromise, TypeSafeClient, } from "@typesafe-ai/sdk";
+import { stepContext } from "./step-context.js";
+const record = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function replayError(fixture, questions) {
+    const step = stepContext.getStore();
+    if (!step)
+        return new Error("Replay client was called outside a flow run. Pass it as the client of flow.run().");
+    if (fixture.flow !== step.flow)
+        return new Error(`Fixture was recorded from flow "${fixture.flow}" but is replaying flow "${step.flow}".`);
+    if (!Object.hasOwn(fixture.steps, step.stepId))
+        return new Error(`Fixture has no response for step "${step.stepId}". The run took a route the fixture didn't record, or that step's capture was missing when the fixture was copied.`);
+    const response = fixture.steps[step.stepId];
+    const answers = record(response) && record(response.answers) ? response.answers : {};
+    const absent = Object.keys(record(questions) ? questions : {}).filter((name) => !Object.hasOwn(answers, name));
+    if (absent.length)
+        return new Error(`Fixture step "${step.stepId}" has no answer for ${absent.join(", ")}. Re-record the fixture.`);
+    return undefined;
+}
+// Checks run before the SDK so replay failures are not reported as connection errors.
+class ReplayClient extends TypeSafeClient {
+    fixture;
+    constructor(fixture) {
+        super({
+            apiKey: "replay-fixture",
+            fetch: async () => {
+                const step = stepContext.getStore();
+                if (!step || !Object.hasOwn(fixture.steps, step.stepId))
+                    throw new Error("Replay fetch outside a checked flow step");
+                return Response.json(fixture.steps[step.stepId]);
+            },
+            // Bodies are discarded, so skip compressing them.
+            compression: false,
+            logLevel: "off",
+            retry: { maxRetries: 0 },
+        });
+        this.fixture = fixture;
+    }
+    systemOne(request, options) {
+        const error = replayError(this.fixture, request.questions);
+        if (!error)
+            return super.systemOne(request, options);
+        // Same shape as the SDK's own early rejections.
+        const response = Promise.reject(error);
+        return new APIPromise(response, () => response);
+    }
+}
+/** Answers each jev step from fixture.steps[stepId]; no network or API key. Use only as a flow run's client. */
+export function replayClient(fixture) {
+    if (fixture?.version !== 1 ||
+        typeof fixture.flow !== "string" ||
+        !record(fixture.steps))
+        throw new TypeError("Expected a version 1 flow fixture with flow and steps");
+    // A snapshot, so later edits to the caller's fixture don't change replay.
+    return new ReplayClient(structuredClone(fixture));
+}

package/lib/flow/runtime.d.ts

@@ -1,5 +1,9 @@
 import type { Json } from "../src/protocol.js";
 /** Detached JSON snapshot, without capture truncation or lossy JSON.stringify. */
 export declare function jsonSnapshot(value: unknown, seen?: Set<object>, depth?: number): Json;
+/** Observer-only copy: preserve aliases inside the snapshot, never to execution data. */
+export declare function observerSnapshot(value: unknown): Json;
+/** Recording may establish synchronous context, but cannot replace or repeat execution. */
+export declare function observeRequest<T>(callback: () => T, observe?: (call: () => T) => unknown): T;
 /** Cancellation ends awaiting, even when user code ignores the cooperative signal. */
 export declare function runCallback(callback: (signal: AbortSignal) => unknown, parent: AbortSignal, timeoutMs?: number): Promise<unknown>;

package/lib/flow/runtime.js

@@ -29,6 +29,80 @@ export function jsonSnapshot(value, seen = new Set(), depth = 0) {
         seen.delete(value);
     }
 }
+/** Observer-only copy: preserve aliases inside the snapshot, never to execution data. */
+export function observerSnapshot(value) {
+    const copies = new WeakMap();
+    const ancestors = new Set();
+    const visit = (input, depth) => {
+        if (depth > 40)
+            throw new TypeError("Observer data nesting exceeds 40");
+        if (input === null || typeof input !== "object")
+            return jsonSnapshot(input);
+        const previous = copies.get(input);
+        if (previous) {
+            // A shared subtree reached through a deeper path still obeys the depth limit.
+            if (depth + previous.height > 40)
+                throw new TypeError("Observer data nesting exceeds 40");
+            return previous.value;
+        }
+        if ((!Array.isArray(input) &&
+            Object.getPrototypeOf(input) !== Object.prototype &&
+            Object.getPrototypeOf(input) !== null) ||
+            Object.getOwnPropertySymbols(input).length)
+            throw new TypeError("Observer data must be JSON-compatible");
+        if (ancestors.has(input))
+            throw new TypeError("Observer data cannot contain cycles");
+        ancestors.add(input);
+        try {
+            let height = 0;
+            const child = (value) => {
+                const copy = visit(value, depth + 1);
+                const childHeight = value && typeof value === "object" ? copies.get(value).height : 0;
+                height = Math.max(height, childHeight + 1);
+                return copy;
+            };
+            const value = Array.isArray(input)
+                ? Array.from(input, child)
+                : Object.fromEntries(Object.entries(input).map(([key, value]) => [key, child(value)]));
+            const copy = { value, height };
+            copies.set(input, copy);
+            return value;
+        }
+        finally {
+            ancestors.delete(input);
+        }
+    };
+    return visit(value, 0);
+}
+/** Recording may establish synchronous context, but cannot replace or repeat execution. */
+export function observeRequest(callback, observe) {
+    let called = false;
+    let result;
+    let failure;
+    const callOnce = () => {
+        if (!called) {
+            called = true;
+            try {
+                result = callback();
+            }
+            catch (error) {
+                failure = { error };
+            }
+        }
+        if (failure)
+            throw failure.error;
+        return result;
+    };
+    try {
+        // Observe rejected hook promises without awaiting them or changing the SDK result.
+        if (observe)
+            void Promise.resolve(observe(callOnce)).catch(() => { });
+    }
+    catch {
+        // A hook can fail before or after calling through. Reuse that invocation below.
+    }
+    return callOnce();
+}
 /** Cancellation ends awaiting, even when user code ignores the cooperative signal. */
 export function runCallback(callback, parent, timeoutMs) {
     const controller = new AbortController();

package/lib/flow/step-context.d.ts

@@ -0,0 +1,7 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Trace } from "../src/protocol.js";
+export type StepLink = NonNullable<Trace["flow"]> & {
+    flow: string;
+};
+/** The jev step whose SDK call is in progress, read by the replay client. */
+export declare const stepContext: AsyncLocalStorage<StepLink>;

package/lib/flow/step-context.js

@@ -0,0 +1,3 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** The jev step whose SDK call is in progress, read by the replay client. */
+export const stepContext = new AsyncLocalStorage();

package/lib/server/flows.d.ts

@@ -6,7 +6,6 @@ export declare class FlowRecorder {
     private runs;
     private definitions;
     private sessions;
-    private definitionRevisions;
     private revisions;
     private revision;
     private listeners;
@@ -21,8 +20,9 @@ export declare class FlowRecorder {
     private remove;
     private prune;
     clear(session: string): void;
-    changes(session: string, cursor?: number): {
+    changes(session: string, cursor?: number, knownDefinitions?: ReadonlySet<string>): {
         revision: number;
+        retainedDefinitionIds: Set<string>;
         data: FlowUpdate;
     };
 }

package/lib/server/flows.js

@@ -5,7 +5,6 @@ export class FlowRecorder {
     runs = new Map();
     definitions = new Map();
     sessions = new Map();
-    definitionRevisions = new Map();
     revisions = new Map();
     revision = 0;
     listeners = new Set();
@@ -49,7 +48,6 @@ export class FlowRecorder {
             };
             redactRules(stored);
             this.definitions.set(definition.id, stored);
-            this.definitionRevisions.set(definition.id, ++this.revision);
         }
         this.runs.set(run.id, run);
         this.sessions.set(run.id, session);
@@ -155,7 +153,6 @@ export class FlowRecorder {
         for (const id of this.definitions.keys())
             if (!used.has(id)) {
                 this.definitions.delete(id);
-                this.definitionRevisions.delete(id);
             }
     }
     clear(session) {
@@ -166,18 +163,19 @@ export class FlowRecorder {
         this.revision++;
         this.notify(new Set([session]));
     }
-    changes(session, cursor) {
+    changes(session, cursor, knownDefinitions = new Set()) {
         const current = [...this.runs.values()]
             .filter((r) => this.sessions.get(r.id) === session)
             .reverse();
         const used = new Set(current.map((r) => r.definitionId));
         return {
             revision: this.revision,
+            retainedDefinitionIds: used,
             data: structuredClone({
                 version: 1,
                 definitions: [...used]
-                    .filter((id) => cursor === undefined ||
-                    this.definitionRevisions.get(id) > cursor)
+                    // Creation time says nothing about what this particular reader has.
+                    .filter((id) => cursor === undefined || !knownDefinitions.has(id))
                     .map((id) => this.definitions.get(id)),
                 upserts: current.filter((r) => cursor === undefined || this.revisions.get(r.id) > cursor),
                 order: current.map((r) => r.id),

package/lib/server/index.js

@@ -113,14 +113,25 @@ export function createJevDevtools(options) {
             const body = new ReadableStream({
                 start(controller) {
                     let closed = false, dirty = true, cursor, timer;
+                    let knownDefinitions = new Set();
                     const flush = () => {
                         timer = undefined;
                         if (closed || !dirty || (controller.desiredSize ?? 0) <= 0)
                             return;
-                        dirty = false;
-                        const update = flows.changes(session, cursor);
-                        cursor = update.revision;
-                        controller.enqueue(encoder.encode(`event: flows\ndata: ${JSON.stringify(update.data)}\n\n`));
+                        try {
+                            const update = flows.changes(session, cursor, knownDefinitions);
+                            controller.enqueue(encoder.encode(`event: flows\ndata: ${JSON.stringify(update.data)}\n\n`));
+                            // Match the browser's pruning after this delivered order. A clear
+                            // coalesced away under backpressure must not discard reader state.
+                            knownDefinitions = update.retainedDefinitionIds;
+                            cursor = update.revision;
+                            dirty = false;
+                        }
+                        catch {
+                            // A failed delivery must not advance the cursor or escape into
+                            // application execution; reconnect starts with a full snapshot.
+                            stop();
+                        }
                     };
                     const wake = () => {
                         if (!closed && dirty && !timer)
@@ -140,6 +151,7 @@ export function createJevDevtools(options) {
                         if (closed)
                             return;
                         closed = true;
+                        knownDefinitions.clear();
                         unsubscribe();
                         clearImmediate(timer);
                         clearInterval(heartbeat);

package/lib/server/recorder.js

@@ -1,7 +1,33 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { Image } from "@typesafe-ai/sdk";
-const secretKey = /^(authorization|cookie|set-cookie|api[-_]?key|password|secret|access[-_]?token|refresh[-_]?token)$/i;
+// Whole field names only: tokenCount, sessionId, apiKeyName, etc. stay useful.
+// Keep the documented lists in docs/integration.md aligned with these policies.
+const credentialKeys = new Set([
+    "authorization",
+    "proxyauthorization",
+    "cookie",
+    "cookies",
+    "setcookie",
+    "apikey",
+    "xapikey",
+    "password",
+    "passwd",
+    "passphrase",
+    "secret",
+    "clientsecret",
+    "token",
+    "accesstoken",
+    "refreshtoken",
+    "sessiontoken",
+    "authtoken",
+    "xauthtoken",
+    "xaccesstoken",
+    "idtoken",
+    "bearertoken",
+    "privatekey",
+    "secretkey",
+]);
 const safeMessage = (value) => value.replace(/Bearer\s+\S+/gi, "Bearer [redacted]").slice(0, 500);
 // Snapshot before the caller can mutate its request. Bounded and cycle-safe;
 // image handles become explicit previews/references instead of opaque SDK objects.
@@ -9,7 +35,8 @@ export function capture(value, warnings, redact) {
     const seen = new WeakSet();
     let budget = 96_000;
     const visit = (input, path, depth) => {
-        if (secretKey.test(path.at(-1) || ""))
+        const key = (path.at(-1) ?? "").replace(/[-_]/g, "").toLowerCase();
+        if (credentialKeys.has(key))
             return "[redacted]";
         if (redact)
             input = redact(path, input);
@@ -243,18 +270,27 @@ export class JevRecorder {
                         void promise
                             .asResponse()
                             .then(async (response) => {
-                            const data = await response.clone().json();
+                            let result;
+                            try {
+                                const data = await response.clone().json();
+                                result = capture(data, warnings, this.options.redact);
+                            }
+                            catch {
+                                // Capture failures are not SDK failures, and redactor errors
+                                // may contain the sensitive values they were meant to hide.
+                                warnings.add("Response snapshot failed; result unavailable.");
+                            }
                             this.update(id, (t) => {
                                 t.status = "success";
                                 t.durationMs = performance.now() - started;
                                 t.requestId =
                                     response.headers.get("x-typesafe-request-id") ?? undefined;
-                                t.result = capture(data, warnings, this.options.redact);
+                                t.result = result;
                                 t.captureWarnings = [...warnings];
                             });
                         }, fail)
-                            .catch((error) => {
-                            fail(error);
+                            .catch(() => {
+                            /* Recording errors must not affect inference or expose data. */
                         });
                         return promise;
                     }

package/lib/src/ConnectedInspector.d.ts

@@ -1,2 +1,2 @@
 import type { JevDevtoolsProps } from "./index.js";
-export default function ConnectedInspector({ endpoint, defaultOpen, }: Omit<JevDevtoolsProps, "enabled">): import("react").JSX.Element;
+export default function ConnectedInspector({ endpoint, defaultOpen, redactAdditionalSensitiveData, }: Omit<JevDevtoolsProps, "enabled">): import("react").JSX.Element;

package/lib/src/ConnectedInspector.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { memo, useCallback, useEffect, useRef, useState } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createDisplayRedactor } from "./display-redaction.js";
 import { JevPanel } from "./JevDevtools.js";
 import { JevDrawer } from "./JevDrawer.js";
 import { connectTraceStream } from "./trace-stream.js";
@@ -15,7 +16,7 @@ function endpointUrl(endpoint) {
         throw new Error("Use a same-origin inspector endpoint without a query or fragment.");
     return url.href.replace(/\/$/, "");
 }
-export default function ConnectedInspector({ endpoint = "/api/jev-devtools", defaultOpen = true, }) {
+export default function ConnectedInspector({ endpoint = "/api/jev-devtools", defaultOpen = true, redactAdditionalSensitiveData = true, }) {
     const [open, setOpen] = useState(defaultOpen);
     const [visited, setVisited] = useState(defaultOpen);
     const visible = useRef(defaultOpen);
@@ -25,6 +26,16 @@ export default function ConnectedInspector({ endpoint = "/api/jev-devtools", def
         flows: emptyFlows,
     });
     const [snapshot, setSnapshot] = useState(latest.current);
+    const [redactor] = useState(createDisplayRedactor);
+    const traces = useMemo(() => redactAdditionalSensitiveData
+        ? snapshot.traces.map(redactor.trace)
+        : snapshot.traces, [snapshot.traces, redactor, redactAdditionalSensitiveData]);
+    const flows = useMemo(() => redactAdditionalSensitiveData
+        ? {
+            runs: snapshot.flows.runs.map(redactor.run),
+            definitions: snapshot.flows.definitions.map(redactor.definition),
+        }
+        : snapshot.flows, [snapshot.flows, redactor, redactAdditionalSensitiveData]);
     const toggle = (value) => {
         visible.current = value;
         setOpen(value);
@@ -91,5 +102,5 @@ export default function ConnectedInspector({ endpoint = "/api/jev-devtools", def
         if (!response.ok)
             throw new Error(`Cannot clear history (${response.status})`);
     }, [endpoint]);
-    return (_jsx(JevDrawer, { open: open, onOpenChange: toggle, children: visited && _jsx(RetainedPanel, { ...snapshot, onClear: clear }) }));
+    return (_jsx(JevDrawer, { open: open, onOpenChange: toggle, children: visited && (_jsx(RetainedPanel, { traces: traces, flows: flows, connection: snapshot.connection, onClear: clear })) }));
 }

package/lib/src/CopyFixture.d.ts

@@ -0,0 +1,22 @@
+import type { FlowDefinition, FlowRun } from "./flow-protocol.js";
+import type { Trace } from "./protocol.js";
+import { type BuiltFlowFixture } from "./flow-fixture.js";
+type CopyResult = {
+    built: BuiltFlowFixture;
+    json: string;
+    copied: boolean;
+    status: FlowRun["status"];
+};
+export type FixtureCopy = {
+    copy: () => void;
+    disabled: boolean;
+    result?: CopyResult;
+};
+export declare function useFixtureCopy(definition: FlowDefinition, run: FlowRun, traces: ReadonlyMap<string, Trace>): FixtureCopy;
+export declare function CopyFixtureButton({ control }: {
+    control: FixtureCopy;
+}): import("react").JSX.Element;
+export declare function CopyFixtureReport({ control }: {
+    control: FixtureCopy;
+}): import("react").JSX.Element | null;
+export {};

package/lib/src/CopyFixture.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { flowFixture, hasCompletedJev, } from "./flow-fixture.js";
+const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+function partial(status) {
+    return status === "error"
+        ? "Run failed. The fixture has completed Jev responses only."
+        : status === "cancelled"
+            ? "Run cancelled. The fixture has completed Jev responses only."
+            : undefined;
+}
+export function useFixtureCopy(definition, run, traces) {
+    const source = useMemo(() => ({ definition, run, traces }), [definition, run, traces]);
+    const [attempt, setAttempt] = useState();
+    const pending = useRef(undefined);
+    // Masking replaces the display projection. Hide its old JSON during render,
+    // including results from clipboard promises that settle after that change.
+    const current = attempt?.source === source ? attempt : undefined;
+    const completed = useMemo(() => hasCompletedJev(definition, run), [definition, run]);
+    const copy = async () => {
+        if (pending.current === source)
+            return;
+        pending.current = source;
+        setAttempt({ source });
+        const built = flowFixture(definition, run, traces);
+        const json = JSON.stringify(built.fixture, null, 2);
+        let copied = false;
+        try {
+            await navigator.clipboard.writeText(json);
+            copied = true;
+        }
+        catch {
+            // Clipboard access can be refused; show the JSON for manual copying instead.
+        }
+        setAttempt((latest) => latest?.source === source
+            ? { source, result: { built, json, copied, status: run.status } }
+            : latest);
+        if (pending.current === source)
+            pending.current = undefined;
+    };
+    return {
+        copy: () => void copy(),
+        disabled: (!!current && !current.result) || run.status === "pending" || !completed,
+        result: current?.result,
+    };
+}
+export function CopyFixtureButton({ control }) {
+    const [confirmation, setConfirmation] = useState();
+    useEffect(() => {
+        setConfirmation(control.result?.copied ? control.result : undefined);
+        if (!control.result?.copied)
+            return;
+        const timer = setTimeout(() => setConfirmation(undefined), 2000);
+        return () => clearTimeout(timer);
+    }, [control.result]);
+    const copied = !!control.result?.copied && confirmation === control.result;
+    return (_jsx("button", { className: "flow-fixture-button", "data-copied": copied || undefined, "aria-live": "polite", "aria-atomic": "true", disabled: control.disabled, onClick: control.copy, children: copied ? "Copied" : "Copy fixture" }));
+}
+export function CopyFixtureReport({ control }) {
+    const { result } = control;
+    const note = result && partial(result.status);
+    if (!result ||
+        (result.copied && !note && !result.built.missing.length && !result.built.warnings.length)) {
+        return null;
+    }
+    return (_jsxs("div", { className: "flow-fixture", children: [_jsxs("div", { role: "status", children: [!result.copied && (_jsx("p", { className: "muted", children: "Clipboard unavailable. Select the JSON below." })), result.built.missing.length > 0 && (_jsxs("p", { className: "warning", children: [plural(result.built.missing.length, "Jev response"), " missing from the fixture."] })), note && _jsx("p", { className: "warning", children: note }), result.built.warnings.length > 0 && (_jsxs("p", { className: "warning", children: ["Capture warnings: ", result.built.warnings.join(" ")] }))] }), result.built.missing.length > 0 && (_jsxs("details", { children: [_jsx("summary", { children: "Missing steps" }), _jsx("ul", { tabIndex: 0, "aria-label": "Steps missing from the fixture", children: result.built.missing.map((id) => (_jsx("li", { children: id }, id))) })] })), !result.copied && (_jsx("textarea", { "aria-label": "Fixture JSON", readOnly: true, value: result.json, onFocus: (e) => e.currentTarget.select() }))] }));
+}