@agent-native/core 0.163.4 → 0.164.3

package/corpus/templates/design/app/pages/design-editor/commands/apply-local-content-update.ts

@@ -0,0 +1,304 @@
+import { assertDesignHtmlEditIntegrity } from "@shared/html-integrity";
+import { sourceContentHash } from "@shared/source-workspace";
+import type { QueryClient } from "@tanstack/react-query";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { toast } from "sonner";
+import * as Y from "yjs";
+
+import { trace } from "@/components/design/design-trace";
+import type { ClipboardContentMutationPublication } from "@/lib/clipboard-content-lineage";
+import {
+  LOCAL_EDIT_ORIGIN,
+  TAB_ID,
+} from "@/pages/design-editor/editor-session";
+import type { PreviewContentReplaceResult } from "@/pages/design-editor/editor-state";
+import { previewContentReplaceNeedsRenderFallback } from "@/pages/design-editor/editor-state";
+import type {
+  ContentHistoryChange,
+  ContentHistoryEntry,
+} from "@/pages/design-editor/history";
+import { designSaveErrorMessage } from "@/pages/design-editor/save-failure";
+import type { DesignFile } from "@/pages/design-editor/types";
+
+export interface ApplyLocalContentUpdateArgs {
+  acknowledgeAuthoritativeClipboardMutation: (args: {
+    fileId: string;
+    nextContent: string;
+    publication?: ClipboardContentMutationPublication;
+  }) => void;
+  activeFile: DesignFile;
+  canEditDesignRef: RefObject<boolean>;
+  cancelQueuedFileContentSave: (fileId: string) => void;
+  clearPendingLocalFileContent: (
+    fileId: string,
+    expectedContent?: string,
+  ) => void;
+  collabContentFileIdRef: RefObject<string | null>;
+  collabContentRef: RefObject<string | null>;
+  id: string | undefined;
+  isSynced: boolean;
+  lastAckedFileContentHashRef: RefObject<Record<string, string>>;
+  lastLocalContentRef: RefObject<string | null>;
+  latestActiveContentRef: RefObject<string | null>;
+  markPendingLocalFileContent: (
+    fileId: string,
+    content: string,
+    baseUpdatedAt?: string | null,
+  ) => void;
+  queryClient: QueryClient;
+  queueFileContentSave: (
+    fileId: string,
+    content: string,
+    options?: { syncCollab?: boolean; immediate?: boolean },
+  ) => void;
+  recordContentHistoryEntry: (entry: ContentHistoryEntry) => void;
+  recordLocalContentHistoryChangeFallback: (
+    change: ContentHistoryChange,
+  ) => void;
+  recordLocalContentHistoryEntry: (change: ContentHistoryChange) => void;
+  replacePreviewContent: (
+    nextContent: string,
+    selector?: string | null,
+    options?: { forceFullDocument?: boolean },
+  ) => PreviewContentReplaceResult;
+  setCollabContent: Dispatch<SetStateAction<string | null>>;
+  setCollabContentFileId: Dispatch<SetStateAction<string | null>>;
+  setContentRenderRevision: Dispatch<SetStateAction<number>>;
+  suppressContentHistoryRef: RefObject<boolean>;
+  t: (key: string, options?: Record<string, unknown>) => string;
+  undoManagerRef: RefObject<Y.UndoManager | null>;
+  viewModeRef: RefObject<"single" | "overview">;
+  ydoc: Y.Doc | null;
+}
+
+export function runApplyLocalContentUpdate(
+  {
+    acknowledgeAuthoritativeClipboardMutation,
+    activeFile,
+    canEditDesignRef,
+    cancelQueuedFileContentSave,
+    clearPendingLocalFileContent,
+    collabContentFileIdRef,
+    collabContentRef,
+    id,
+    isSynced,
+    lastAckedFileContentHashRef,
+    lastLocalContentRef,
+    latestActiveContentRef,
+    markPendingLocalFileContent,
+    queryClient,
+    queueFileContentSave,
+    recordContentHistoryEntry,
+    recordLocalContentHistoryChangeFallback,
+    recordLocalContentHistoryEntry,
+    replacePreviewContent,
+    setCollabContent,
+    setCollabContentFileId,
+    setContentRenderRevision,
+    suppressContentHistoryRef,
+    t,
+    undoManagerRef,
+    viewModeRef,
+    ydoc,
+  }: ApplyLocalContentUpdateArgs,
+  nextContent: string,
+  options: {
+    refreshPreview?: boolean;
+    skipPreview?: boolean;
+    forcePreviewFullDocument?: boolean;
+    immediateSave?: boolean;
+    persist?: boolean;
+    recordHistory?: boolean;
+    historyBeforeContent?: string;
+    updatedAt?: string;
+    clipboardMutation?: ClipboardContentMutationPublication;
+  } = {},
+) {
+  trace("persist", "write-file", {
+    file: activeFile?.filename ?? null,
+    bytes: nextContent.length,
+    blocked: !activeFile
+      ? "no active file"
+      : !canEditDesignRef.current
+        ? "read-only design"
+        : null,
+  });
+  if (!activeFile || !canEditDesignRef.current) return;
+  const shouldRecordHistory =
+    options.recordHistory !== false && !options.updatedAt;
+  const previousContent =
+    typeof options.historyBeforeContent === "string"
+      ? options.historyBeforeContent
+      : collabContentFileIdRef.current === activeFile.id &&
+          typeof collabContentRef.current === "string"
+        ? collabContentRef.current
+        : (activeFile.content ?? "");
+  try {
+    assertDesignHtmlEditIntegrity({
+      previousContent,
+      nextContent,
+      fileType: activeFile.fileType,
+    });
+  } catch (error) {
+    toast.error(designSaveErrorMessage(error) ?? t("common.genericError"), {
+      id: `design-source-integrity:${activeFile.id}`,
+    });
+    return;
+  }
+  // No implicit authority from `recordHistory`: save/query/Yjs echoes can
+  // traverse this same function with history enabled. Only a publication
+  // allocated synchronously at a user-action boundary may advance lineage.
+  acknowledgeAuthoritativeClipboardMutation({
+    fileId: activeFile.id,
+    nextContent,
+    publication: options.clipboardMutation,
+  });
+  const yjsHistoryAvailable = Boolean(
+    shouldRecordHistory &&
+    viewModeRef.current !== "overview" &&
+    ydoc &&
+    isSynced &&
+    undoManagerRef.current,
+  );
+  if (
+    !suppressContentHistoryRef.current &&
+    shouldRecordHistory &&
+    !yjsHistoryAvailable &&
+    previousContent !== nextContent
+  ) {
+    const change = {
+      fileId: activeFile.id,
+      before: previousContent,
+      after: nextContent,
+    };
+    if (viewModeRef.current === "overview") {
+      recordContentHistoryEntry(change);
+    } else {
+      recordLocalContentHistoryEntry(change);
+    }
+  } else if (
+    !suppressContentHistoryRef.current &&
+    shouldRecordHistory &&
+    yjsHistoryAvailable &&
+    previousContent !== nextContent
+  ) {
+    // The Yjs UndoManager is the primary undo path here, but it (and its
+    // whole undo stack) is destroyed on every view-mode switch and zoom
+    // (docId goes null -> ydoc changes). Mirror the same before/after into
+    // the local fallback stack so handleUndo can still recover the edit
+    // once the Yjs stack is gone; it is only consulted when Yjs itself has
+    // nothing left to undo, so this never causes a double-undo.
+    recordLocalContentHistoryChangeFallback({
+      fileId: activeFile.id,
+      before: previousContent,
+      after: nextContent,
+    });
+  }
+  if (options.updatedAt) {
+    clearPendingLocalFileContent(activeFile.id);
+    // options.updatedAt means this content is already server-persisted
+    // (apply-source-edit's onApplied host-sync and friends) — record it
+    // as the server-acknowledged base so the next guarded update-file
+    // save carries the POST-shader hash, not a stale pre-shader one.
+    lastAckedFileContentHashRef.current[activeFile.id] =
+      sourceContentHash(nextContent);
+  } else {
+    markPendingLocalFileContent(
+      activeFile.id,
+      nextContent,
+      activeFile.updatedAt,
+    );
+  }
+  setCollabContent(nextContent);
+  setCollabContentFileId(activeFile.id);
+  collabContentRef.current = nextContent;
+  collabContentFileIdRef.current = activeFile.id;
+  lastLocalContentRef.current = nextContent;
+  latestActiveContentRef.current = nextContent;
+  if (id) {
+    queryClient.setQueryData(["action", "get-design", { id }], (old: any) => {
+      if (!old || typeof old !== "object" || !Array.isArray(old.files)) {
+        return old;
+      }
+      return {
+        ...old,
+        files: old.files.map((file: DesignFile) =>
+          file.id === activeFile.id
+            ? // Update content optimistically but keep the file's prior
+              // (server-clock) updatedAt. Seeding the reconcile watermark
+              // from a client-clock timestamp can, under clock skew, make a
+              // later server-authored agent edit look "older" and get
+              // dropped by the watermark gate (agent edit silently lost).
+              {
+                ...file,
+                content: nextContent,
+                ...(options.updatedAt ? { updatedAt: options.updatedAt } : {}),
+              }
+            : file,
+        ),
+      };
+    });
+  }
+  const forceRefresh = options.refreshPreview === true;
+  // Holistic flash pipeline: `forcePreviewFullDocument` tells the bridge
+  // to use its whole-document innerHTML replace (needed when the change
+  // isn't scoped to the currently selected element's subtree — e.g. an
+  // undo/redo that can touch anywhere in the document), NOT to force a
+  // full iframe srcdoc rebuild here. `replaceRuntimeDocument`'s full-body
+  // branch already swaps content inside the SAME live iframe document (no
+  // navigation, no onload refire, persistent overlay nodes preserved —
+  // see that function's module doc) — it is exactly as flash-free as the
+  // scoped single-element patch, just broader. Previously this always
+  // bumped contentRenderRevision whenever forcePreviewFullDocument was
+  // set, even after replacePreviewContent already applied the update in
+  // place, forcing a completely redundant full srcdoc rebuild (real
+  // iframe reload, white flash, lost scroll/CSS-transition/Alpine state)
+  // on top of a change that had already rendered correctly. Only fall
+  // back to the expensive srcdoc rebuild when the live patch genuinely
+  // couldn't run (bridge not registered for this surface yet, or an
+  // explicit forceRefresh request).
+  const replacedPreview = options.skipPreview
+    ? "applied"
+    : forceRefresh
+      ? "unavailable"
+      : replacePreviewContent(
+          nextContent,
+          null,
+          options.forcePreviewFullDocument
+            ? { forceFullDocument: true }
+            : undefined,
+        );
+  if (
+    forceRefresh ||
+    previewContentReplaceNeedsRenderFallback(replacedPreview)
+  ) {
+    setContentRenderRevision((revision) => revision + 1);
+  }
+  if (ydoc && isSynced) {
+    const ytext = ydoc.getText("content");
+    if (ytext.toString() !== nextContent) {
+      if (!yjsHistoryAvailable) {
+        // Untracked full rewrite (recordHistory:false callers such as the
+        // code-layer id-stamping effect, or history-suppressed replays) —
+        // see U1 note above: clear the undo stack so a stale tracked
+        // delta can't be replayed against content it no longer matches.
+        undoManagerRef.current?.clear(true, false);
+      }
+      ydoc.transact(
+        () => {
+          ytext.delete(0, ytext.length);
+          ytext.insert(0, nextContent);
+        },
+        yjsHistoryAvailable ? LOCAL_EDIT_ORIGIN : TAB_ID,
+      );
+    }
+  }
+  if (options.persist === false) {
+    cancelQueuedFileContentSave(activeFile.id);
+  } else {
+    queueFileContentSave(activeFile.id, nextContent, {
+      syncCollab: !(ydoc && isSynced),
+      immediate: options.immediateSave,
+    });
+  }
+}

package/corpus/templates/design/app/pages/design-editor/commands/apply-pending-visual-styles-with-agent.ts

@@ -0,0 +1,376 @@
+import { callAction } from "@agent-native/core/client/hooks";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import { toast } from "sonner";
+
+import { sendDesignSourceHandoffAndConfirm } from "@/lib/agent-chat";
+import { actionErrorDetail } from "@/pages/design-editor/action-error";
+import type {
+  PendingStructureVerificationSession,
+  PendingStructureVerificationStatus,
+  RuntimeLayerSnapshot,
+} from "@/pages/design-editor/command-types";
+import type { OverviewScreen } from "@/pages/design-editor/derive/overview-screens";
+import {
+  HOST_TURN_START_TIMEOUT_MS,
+  PENDING_STRUCTURE_RUNTIME_POLL_MS,
+  PENDING_STRUCTURE_RUNTIME_TIMEOUT_MS,
+  PENDING_STRUCTURE_SOURCE_POLL_MS,
+  PENDING_STRUCTURE_VERIFICATION_TIMEOUT_MS,
+} from "@/pages/design-editor/editor-constants";
+import type {
+  PendingLiveNonStyleEdit,
+  PendingLiveStructureEdit,
+  PendingVisualStyleEdit,
+} from "@/pages/design-editor/pending-edits";
+import {
+  buildPendingVisualStyleRevertPatches,
+  pendingStructureEditSourcePaths,
+} from "@/pages/design-editor/pending-edits";
+import { verifyPendingStructuresRuntime } from "@/pages/design-editor/pending-structure-verification";
+import type { DesignLeftPanel } from "@/pages/design-editor/types";
+
+export interface ApplyPendingVisualStylesWithAgentArgs {
+  cancelPendingStructureVerification: (
+    nextStatus?: PendingStructureVerificationStatus,
+  ) => void;
+  clearPendingLiveEditState: () => void;
+  id: string | undefined;
+  overviewScreens: OverviewScreen[];
+  pendingAgentHandoffBusyRef: RefObject<boolean>;
+  pendingLiveNonStyleEdits: PendingLiveNonStyleEdit[];
+  stagedHandoffStartTimerRef: RefObject<number | undefined>;
+  stagedSourceHandoffRef: RefObject<"idle" | "awaiting-start" | "running">;
+  pendingStructureVerificationRevisionRef: RefObject<number>;
+  pendingStructureVerificationSessionRef: RefObject<
+    PendingStructureVerificationSession | undefined
+  >;
+  pendingStructureVerificationSnapshotsRef: RefObject<
+    Map<number, Record<string, RuntimeLayerSnapshot>>
+  >;
+  pendingStructureVerificationStatus: PendingStructureVerificationStatus;
+  pendingVisualStyleEdits: PendingVisualStyleEdit[];
+  pendingVisualStylePrompt: string;
+  setActiveLeftPanel: Dispatch<SetStateAction<DesignLeftPanel>>;
+  setApplyingViaHost: Dispatch<SetStateAction<boolean>>;
+  setPendingAgentHandoffBusy: Dispatch<SetStateAction<boolean>>;
+  setPendingStructureAckRequest: Dispatch<
+    SetStateAction<{
+      requestId: number;
+      acks: Array<{ screenId: string; requestId: string; applied: boolean }>;
+    } | null>
+  >;
+  setPendingStructureVerificationStatus: Dispatch<
+    SetStateAction<PendingStructureVerificationStatus>
+  >;
+  setPendingVisualStyleBaselineResetRequest: Dispatch<
+    SetStateAction<number | null>
+  >;
+  setPendingVisualStyleRevertRequest: Dispatch<
+    SetStateAction<{
+      requestId: number;
+      patches: ReturnType<typeof buildPendingVisualStyleRevertPatches>;
+    } | null>
+  >;
+  setRuntimeStructureVerificationRequest: Dispatch<
+    SetStateAction<{ requestId: number; screenIds: string[] } | null>
+  >;
+  t: (key: string, options?: Record<string, unknown>) => string;
+}
+
+export async function runApplyPendingVisualStylesWithAgent({
+  cancelPendingStructureVerification,
+  clearPendingLiveEditState,
+  id,
+  overviewScreens,
+  pendingAgentHandoffBusyRef,
+  pendingLiveNonStyleEdits,
+  stagedHandoffStartTimerRef,
+  stagedSourceHandoffRef,
+  pendingStructureVerificationRevisionRef,
+  pendingStructureVerificationSessionRef,
+  pendingStructureVerificationSnapshotsRef,
+  pendingStructureVerificationStatus,
+  pendingVisualStyleEdits,
+  pendingVisualStylePrompt,
+  setActiveLeftPanel,
+  setApplyingViaHost,
+  setPendingAgentHandoffBusy,
+  setPendingStructureAckRequest,
+  setPendingStructureVerificationStatus,
+  setPendingVisualStyleBaselineResetRequest,
+  setPendingVisualStyleRevertRequest,
+  setRuntimeStructureVerificationRequest,
+  t,
+}: ApplyPendingVisualStylesWithAgentArgs) {
+  if (
+    pendingVisualStyleEdits.length === 0 &&
+    pendingLiveNonStyleEdits.length === 0
+  ) {
+    return;
+  }
+  if (
+    pendingAgentHandoffBusyRef.current ||
+    pendingStructureVerificationStatus === "checking-source" ||
+    pendingStructureVerificationStatus === "awaiting-source" ||
+    pendingStructureVerificationStatus === "awaiting-runtime"
+  ) {
+    return;
+  }
+  pendingAgentHandoffBusyRef.current = true;
+  setPendingAgentHandoffBusy(true);
+  try {
+    const preservePreviewPatches = pendingVisualStyleEdits
+      .map((edit) => ({
+        screenId: edit.screenId,
+        selector: edit.selector,
+        sourceId: edit.sourceId,
+        styles: edit.styles,
+        ...(edit.interactionState
+          ? { interactionState: edit.interactionState }
+          : {}),
+      }))
+      .filter((patch) => Object.keys(patch.styles).length > 0);
+    const structureEdits = pendingLiveNonStyleEdits.filter(
+      (edit): edit is PendingLiveStructureEdit => edit.kind === "structure",
+    );
+    const structureAcks = structureEdits
+      .filter((edit) => Boolean(edit.requestId))
+      .map((edit) => ({
+        screenId: edit.screenId,
+        requestId: edit.requestId!,
+        applied: true,
+      }));
+
+    const finalizeWithoutStructureVerification = () => {
+      clearPendingLiveEditState();
+      const previewRequestId = Date.now() + Math.random();
+      window.setTimeout(() => {
+        if (preservePreviewPatches.length > 0) {
+          setPendingVisualStyleRevertRequest({
+            requestId: previewRequestId,
+            patches: preservePreviewPatches,
+          });
+        }
+        setPendingVisualStyleBaselineResetRequest(previewRequestId);
+      }, 50);
+    };
+
+    if (structureEdits.length === 0) {
+      const delivery = await sendDesignSourceHandoffAndConfirm(
+        {
+          message: t("designEditor.pendingVisualStyles.agentMessage"),
+          context: pendingVisualStylePrompt,
+          submit: true,
+          openSidebar: true,
+        },
+        { timeoutMs: 10_000 },
+      );
+      if (!delivery.delivered) {
+        toast.error(
+          t("designEditor.pendingVisualStyles.agentHandoffFailedToast"),
+        );
+        return;
+      }
+      if (delivery.awaitingHostTurn) {
+        stagedSourceHandoffRef.current = "awaiting-start";
+        setApplyingViaHost(true);
+        stagedHandoffStartTimerRef.current = window.setTimeout(() => {
+          stagedHandoffStartTimerRef.current = undefined;
+          if (stagedSourceHandoffRef.current !== "awaiting-start") return;
+          stagedSourceHandoffRef.current = "idle";
+          setApplyingViaHost(false);
+          toast.error(
+            t("designEditor.pendingVisualStyles.agentHandoffFailedToast"),
+          );
+        }, HOST_TURN_START_TIMEOUT_MS);
+      } else finalizeWithoutStructureVerification();
+      if (delivery.target === "local") setActiveLeftPanel("agent");
+      toast.success(t("designEditor.pendingVisualStyles.sentToast"));
+      return;
+    }
+
+    if (!id) return;
+    pendingStructureVerificationRevisionRef.current += 1;
+    const requestId = pendingStructureVerificationRevisionRef.current;
+    const session: PendingStructureVerificationSession = {
+      requestId,
+      cancelled: false,
+      edits: structureEdits,
+      sources: [],
+    };
+    pendingStructureVerificationSessionRef.current = session;
+    pendingStructureVerificationSnapshotsRef.current.set(requestId, {});
+    setPendingStructureVerificationStatus("checking-source");
+
+    const sourceTargets = new Map<
+      string,
+      { connectionId: string; path: string }
+    >();
+    for (const edit of structureEdits) {
+      const connectionId = overviewScreens.find(
+        (screen) => screen.id === edit.screenId,
+      )?.connectionId;
+      const paths = pendingStructureEditSourcePaths(edit);
+      if (!connectionId || !paths) {
+        cancelPendingStructureVerification("conflict");
+        toast.error(t("designEditor.toasts.reactSourceAnchorsLoading"));
+        return;
+      }
+      for (const path of paths) {
+        sourceTargets.set(`${connectionId}:${path}`, {
+          connectionId,
+          path,
+        });
+      }
+    }
+
+    try {
+      session.sources = await Promise.all(
+        Array.from(sourceTargets.values()).map(async (source) => {
+          // read-local-file declares `http: { method: "GET" }`, so a
+          // default POST is refused with 405 and every Apply preflight
+          // fails before it reads a single baseline hash.
+          const result = (await callAction(
+            "read-local-file",
+            {
+              designId: id,
+              connectionId: source.connectionId,
+              path: source.path,
+            },
+            { method: "GET" },
+          )) as { versionHash?: string } | undefined;
+          if (!result?.versionHash) {
+            throw new Error(`Missing version hash for ${source.path}`);
+          }
+          return {
+            ...source,
+            baselineVersionHash: result.versionHash,
+          };
+        }),
+      );
+      if (session.cancelled) return;
+
+      const delivery = await sendDesignSourceHandoffAndConfirm(
+        {
+          message: t("designEditor.pendingVisualStyles.agentMessage"),
+          context: pendingVisualStylePrompt,
+          submit: true,
+          openSidebar: true,
+        },
+        { timeoutMs: 10_000 },
+      );
+      if (session.cancelled) return;
+      if (!delivery.delivered) {
+        cancelPendingStructureVerification();
+        toast.error(
+          t("designEditor.pendingVisualStyles.agentHandoffFailedToast"),
+        );
+        return;
+      }
+
+      const screenIds = Array.from(
+        new Set(structureEdits.map((edit) => edit.screenId)),
+      );
+      setPendingStructureVerificationStatus("awaiting-source");
+      if (delivery.target === "local") setActiveLeftPanel("agent");
+      toast.success(t("designEditor.pendingVisualStyles.sentToast"));
+
+      let deadline = Date.now() + PENDING_STRUCTURE_VERIFICATION_TIMEOUT_MS;
+      let nextSourcePollAt = 0;
+      let sourceChanged = false;
+      let verificationRuntimeMounted = false;
+      while (!session.cancelled && Date.now() < deadline) {
+        const runtimeSnapshots =
+          pendingStructureVerificationSnapshotsRef.current.get(requestId) ?? {};
+        if (
+          verificationRuntimeMounted &&
+          screenIds.every((screenId) => runtimeSnapshots[screenId])
+        ) {
+          const runtimeResult = verifyPendingStructuresRuntime(
+            runtimeSnapshots,
+            structureEdits,
+          );
+          if (runtimeResult.ok) {
+            if (structureAcks.length > 0) {
+              setPendingStructureAckRequest({
+                requestId: Date.now() + Math.random(),
+                acks: structureAcks,
+              });
+            }
+            clearPendingLiveEditState();
+            toast.success(t("designEditor.pendingVisualStyles.verifiedToast"));
+            return;
+          }
+        }
+
+        if (Date.now() >= nextSourcePollAt) {
+          nextSourcePollAt = Date.now() + PENDING_STRUCTURE_SOURCE_POLL_MS;
+          try {
+            const currentVersions = await Promise.all(
+              session.sources.map(async (source) => {
+                const result = (await callAction(
+                  "read-local-file",
+                  {
+                    designId: id,
+                    connectionId: source.connectionId,
+                    path: source.path,
+                  },
+                  { method: "GET" },
+                )) as { versionHash?: string } | undefined;
+                return result?.versionHash;
+              }),
+            );
+            if (session.cancelled) return;
+            sourceChanged = currentVersions.some(
+              (versionHash, index) =>
+                Boolean(versionHash) &&
+                versionHash !== session.sources[index]?.baselineVersionHash,
+            );
+            if (sourceChanged) {
+              if (!verificationRuntimeMounted) {
+                verificationRuntimeMounted = true;
+                deadline = Math.min(
+                  deadline,
+                  Date.now() + PENDING_STRUCTURE_RUNTIME_TIMEOUT_MS,
+                );
+                pendingStructureVerificationSnapshotsRef.current.set(
+                  requestId,
+                  {},
+                );
+                setRuntimeStructureVerificationRequest({
+                  requestId,
+                  screenIds,
+                });
+              }
+              setPendingStructureVerificationStatus("awaiting-runtime");
+            }
+            // coercion-ok: moved verbatim; a failed optional probe here is indistinguishable from "not applicable" by design.
+          } catch {
+            // A transient bridge read must not discard the still-undoable
+            // preview. Keep polling until the bounded deadline.
+          }
+        }
+        await new Promise((resolve) =>
+          window.setTimeout(resolve, PENDING_STRUCTURE_RUNTIME_POLL_MS),
+        );
+      }
+      if (session.cancelled) return;
+      cancelPendingStructureVerification("conflict");
+      toast.error(t("designEditor.pendingVisualStyles.conflictToast"));
+    } catch (error) {
+      if (session.cancelled) return;
+      console.error(
+        "[DesignEditor] pending structure verification failed:",
+        error,
+      );
+      cancelPendingStructureVerification("conflict");
+      toast.error(
+        t("designEditor.pendingVisualStyles.sourceCheckFailedToast"),
+        { description: actionErrorDetail(error) },
+      );
+    }
+  } finally {
+    pendingAgentHandoffBusyRef.current = false;
+    setPendingAgentHandoffBusy(false);
+  }
+}