@agent-native/core 0.180.0 → 0.180.1-nightly-20260915205111

package/corpus/templates/design/app/components/design/DesignCanvas.tsx

@@ -107,12 +107,14 @@ import {
   getEmbeddedIframeBackgroundColor,
 } from "./design-canvas/embedded-frame";
 import {
+  classifyBridgeRegistrationFailure,
   getDesignCanvasIframeSandbox,
   getSnapshotRetryDelayMs,
   resolveLiveEditPreviewUrl,
   sanitizeLocalhostSourceSnapshotHtml,
   shouldFetchExternalSourceSnapshot,
   shouldUseIframeLoadReadyFallback,
+  type BridgeRegistrationFailureKind,
 } from "./design-canvas/external-preview";
 import { isOsFileDragEvent } from "./design-canvas/file-drop";
 import {
@@ -130,6 +132,7 @@ import {
   type EmbeddedCanvasPanSession,
 } from "./design-canvas/iframe-pan";
 import { withLocalRuntimes } from "./design-canvas/local-runtime";
+import { LocalNetworkAccessPrompt } from "./design-canvas/LocalNetworkAccessPrompt";
 import type { MotionTrackWire } from "./design-canvas/motion-types";
 import {
   PENDING_TEXT_EDIT_TIMEOUT_MS,
@@ -1706,12 +1709,55 @@ export function DesignCanvas({
   // "Preparing live editor..." with no explanation and no way to recover
   // short of reloading the whole page.
   const bridgeRegistrationRetryAttemptRef = useRef(0);
+  const bridgeRegistrationRetryTimerRef = useRef<number | undefined>(undefined);
+  // Two registration attempts can be in flight at once — the automatic
+  // effect-driven one and a manually-triggered "Connect" click (see
+  // attemptBridgeRegistration/handleConnectLocalNetworkAccess below) — and
+  // they can resolve out of order. Only the most recent attempt's result may
+  // ever be written to state, or an earlier failure resolving after a later
+  // success would incorrectly flip the UI back to "still blocked".
+  const bridgeRegistrationAttemptGenerationRef = useRef(0);
   const [bridgeRegistrationRetryNonce, setBridgeRegistrationRetryNonce] =
     useState(0);
+  // Scoped strictly to the registration fetch() itself failing — drives
+  // externalPreviewUrl's raw-URL fallback and the floating
+  // LocalNetworkAccessPrompt card below. Deliberately separate from
+  // bridgeConnectionLostError: a fetch failure and "the live document never
+  // confirmed ready after a successful registration" (handleSuspectedBridge
+  // Restart's destructive paths) are different failure modes — the latter
+  // proves the bridge WAS reachable, so a permission-flavored "maybe you need
+  // to grant local network access" message would be actively misleading
+  // there, and unlike a fetch failure there's no still-reachable raw
+  // dev-server document to fall back to showing (the live document itself is
+  // what stopped responding).
   const [bridgeRegistrationError, setBridgeRegistrationError] = useState<{
     bridgeKey: string;
     message: string;
   } | null>(null);
+  // handleSuspectedBridgeRestart's destructive terminal states (retry budget
+  // exhausted, or /health itself confirms the process is unreachable) keep
+  // their original full-cover blocking card and retry action, untouched by
+  // the raw-fallback/floating-card behavior above — see
+  // bridgeRegistrationError's comment for why these must not share state.
+  const [bridgeConnectionLostError, setBridgeConnectionLostError] = useState<{
+    bridgeKey: string;
+    message: string;
+  } | null>(null);
+  // Distinguishes "Chrome's Local Network Access permission is blocking this
+  // request" from "the dev server is genuinely down" — see
+  // classifyBridgeRegistrationFailure. Drives which copy/icon the floating
+  // LocalNetworkAccessPrompt card shows; null while unclassified or resolved.
+  const [bridgeRegistrationFailureKind, setBridgeRegistrationFailureKind] =
+    useState<BridgeRegistrationFailureKind | null>(null);
+  // Dismissing the floating connect card is per-script-revision: keyed by the
+  // liveEditBridgeKey it was shown for, so a genuinely new script/mode change
+  // re-surfaces the card instead of leaving it permanently dismissed.
+  const [
+    localNetworkAccessDismissedForKey,
+    setLocalNetworkAccessDismissedForKey,
+  ] = useState<string | null>(null);
+  const [connectingLocalNetworkAccess, setConnectingLocalNetworkAccess] =
+    useState(false);
   // Cache of the bridgeInstanceId returned by the client's LAST successful
   // /live-edit-bridge registration POST (see the registration effect below).
   // Compared against a later /health probe's bridgeInstanceId to tell "the
@@ -1762,12 +1808,13 @@ export function DesignCanvas({
     bridgeKey: string;
     message: string;
   } | null>(null);
-  // Set on unmount so the async /health probe (and its escalation re-arm
-  // timer) never touches state after this component is gone.
-  const isUnmountedRef = useRef(false);
+  // Clears the escalation re-arm timer on unmount so it can't fire and
+  // schedule a fetch after this component is gone. (A stray fetch would be a
+  // no-op anyway — every /health probe checkpoint is generation-guarded via
+  // bridgeRegistrationAttemptGenerationRef, see handleSuspectedBridgeRestart
+  // — but there's no reason to let the timer fire in the first place.)
   useEffect(
     () => () => {
-      isUnmountedRef.current = true;
       if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
         window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
         liveEditSameInstanceRearmTimerRef.current = undefined;
@@ -1902,8 +1949,20 @@ export function DesignCanvas({
   const usesLiveEditInjectedBridge =
     sourceType === "localhost" &&
     Boolean(bridgeUrl && previewToken && rawExternalPreviewUrl);
+  // Hoisted above usesLiveEditEditorBridge (rather than declared next to
+  // externalPreviewUrl/usingRawFallbackPreview below, which reuse it) because
+  // a failed registration's raw-URL fallback document has no injected editor
+  // bridge script and can never answer an editor command or post the ready
+  // handshake — usesLiveEditEditorBridge must already reflect that, or the
+  // still-"editable" chrome above it (selection, inspector, hover) lets the
+  // user attempt edits that silently queue forever against a frame that will
+  // never respond (see postOneShotBridgeMessage's queueing above).
+  const bridgeRegistrationFailedForCurrentKey =
+    bridgeRegistrationError?.bridgeKey === liveEditBridgeKey;
   const usesLiveEditEditorBridge =
-    usesLiveEditInjectedBridge && includeLiveEditEditorChrome;
+    usesLiveEditInjectedBridge &&
+    includeLiveEditEditorChrome &&
+    !bridgeRegistrationFailedForCurrentKey;
   const effectiveRegisteredLiveEditBridgeKey =
     registeredLiveEditBridgeKey ??
     (hasRecentLiveEditRegistration(registrationHandoffKey)
@@ -2001,9 +2060,25 @@ export function DesignCanvas({
   // registration succeeds, the one real proxied document mounts directly.
   // A viewer with no previewToken has no bridge to wait for, so it loads the
   // dev server directly rather than degrading to a snapshot.
+  //
+  // A FAILED registration (most commonly Chrome's Local Network Access
+  // permission blocking the fetch — see classifyBridgeRegistrationFailure)
+  // falls back the same way: the dev server itself is still reachable via a
+  // plain iframe navigation (unlike fetch/XHR, navigations aren't subject to
+  // that permission check), so showing it read-only beats hiding a working
+  // app behind an indefinite loading state. LocalNetworkAccessPrompt offers
+  // the way to actually enable editing from here.
+  const usingRawFallbackPreview =
+    usesLiveEditInjectedBridge &&
+    !liveEditExternalPreviewUrl &&
+    bridgeRegistrationFailedForCurrentKey;
   const externalPreviewUrl =
     liveEditExternalPreviewUrl ??
-    (usesLiveEditInjectedBridge ? null : rawExternalPreviewUrl);
+    (usesLiveEditInjectedBridge
+      ? bridgeRegistrationFailedForCurrentKey
+        ? rawExternalPreviewUrl
+        : null
+      : rawExternalPreviewUrl);
   const runtimeVerificationUrl = useMemo(() => {
     if (!runtimeVerificationRequest || !externalPreviewUrl) return null;
     return externalPreviewUrl;
@@ -2145,8 +2220,149 @@ export function DesignCanvas({
   // null forever (console.warn only, no retry, no error UI), pinning
   // waitingForLiveEditBridge true with no way to recover short of a full
   // page reload.
+  const scheduleBridgeRegistrationRetry = useCallback(() => {
+    const delay = getSnapshotRetryDelayMs(
+      bridgeRegistrationRetryAttemptRef.current,
+    );
+    bridgeRegistrationRetryAttemptRef.current += 1;
+    bridgeRegistrationRetryTimerRef.current = window.setTimeout(() => {
+      setBridgeRegistrationRetryNonce((nonce) => nonce + 1);
+    }, delay);
+  }, []);
+  // Invalidates any registration attempt still in flight when THIS effect
+  // instance unmounts — deliberately not a one-way "isUnmounted" flag: that
+  // shape never resets, so under StrictMode's dev-only mount→cleanup→mount
+  // replay it would stay stuck true after the first (intentionally
+  // discarded) cleanup and permanently block every later, genuinely-live
+  // attempt. Bumping the generation counter here instead only invalidates
+  // the specific attempt that was in
+  // flight at THIS cleanup; the next mount's own attempt captures a fresh
+  // generation and is unaffected.
+  useEffect(
+    () => () => {
+      bridgeRegistrationAttemptGenerationRef.current += 1;
+    },
+    [],
+  );
+  // Single source of truth for a registration attempt, shared by the
+  // automatic effect below and the manual "Connect" button (see
+  // handleConnectLocalNetworkAccess) — see bridgeRegistrationAttemptGeneration
+  // Ref's comment for why a shared, generation-guarded function is required
+  // instead of each caller firing its own independent fetch.
+  // Returns true/false for a definite, still-applicable outcome, or null when
+  // a newer attempt (effect-driven or manual) has already superseded this
+  // one — callers must treat null as "nothing to do", not as a failure, or a
+  // stale attempt could schedule a redundant retry after a later attempt
+  // already succeeded.
+  const attemptBridgeRegistration = useCallback(async (): Promise<
+    boolean | null
+  > => {
+    if (!usesLiveEditInjectedBridge || !bridgeUrl || !previewToken) {
+      return null;
+    }
+    const generation = ++bridgeRegistrationAttemptGenerationRef.current;
+    // Unmount is covered by the dedicated cleanup-only effect above, which
+    // bumps this same counter — a manual Connect click's fetch has no effect
+    // cleanup of its own to cancel it, but that effect's bump still
+    // invalidates it the same way a superseded attempt is invalidated.
+    const isCurrent = () =>
+      bridgeRegistrationAttemptGenerationRef.current === generation;
+    // A fresh attempt — whether auto-retry or a manual Connect click,
+    // including one retried from the destructive bridgeConnectionLostError
+    // card's own Retry button (see handleConnectLocalNetworkAccess) — means
+    // we're no longer in "connection lost, needs a click" limbo. Clear it now
+    // rather than only on success/failure, or the full-cover destructive card
+    // stays visible (it takes priority in the overlay below) even once this
+    // attempt resolves as an ordinary registration-fetch failure instead.
+    setBridgeConnectionLostError(null);
+    const endpoint = new URL("/live-edit-bridge", bridgeUrl).toString();
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-design-preview-token": previewToken,
+        },
+        body: JSON.stringify({
+          script: liveEditBridgeScript,
+          bridgeKey: liveEditBridgeKey,
+        }),
+      });
+      if (!response.ok) {
+        throw new Error(`Bridge registration failed (${response.status})`);
+      }
+      // coercion-ok: response.ok already confirmed the registration itself
+      // succeeded above; bridgeInstanceId is supplementary metadata for the
+      // restart-detection heuristic only (see classifyLiveEditHealthProbe),
+      // and the null/missing case below is checked explicitly, not treated
+      // as equivalent to a present value.
+      const payload = (await response.json().catch(() => null)) as {
+        bridgeInstanceId?: string;
+      } | null;
+      if (!isCurrent()) return null;
+      if (payload && typeof payload.bridgeInstanceId === "string") {
+        // Cache the instance id from THIS successful registration so a
+        // later suspected-restart probe (see handleSuspectedBridgeRestart)
+        // can tell a genuinely restarted bridge process apart from the same
+        // process rejecting a stale key. Written only after isCurrent()
+        // passes: an older overlapping request resolving after a newer one
+        // must not overwrite the current attempt's instance id, or the
+        // watchdog misdiagnoses a restart and burns its reload/retry budget.
+        bridgeInstanceIdRef.current = payload.bridgeInstanceId;
+      }
+      bridgeRegistrationRetryAttemptRef.current = 0;
+      if (registrationHandoffKey) {
+        liveEditRegistrationHandoff.set(registrationHandoffKey, Date.now());
+      }
+      // liveEditRestartAttemptRef is intentionally NOT reset here: a
+      // successful registration POST only proves the bridge accepted the
+      // script, not that the live document actually loaded it (that's what
+      // the ready-handshake watchdog below still has to confirm). Resetting
+      // the restart budget on every registration success — rather than only
+      // on a genuine agent-native:editor-chrome-ready — would let a
+      // pathological bridge that keeps minting a new bridgeInstanceId
+      // reregister forever, defeating MAX_LIVE_EDIT_RESTART_ATTEMPTS.
+      setBridgeRegistrationError(null);
+      setBridgeRegistrationFailureKind(null);
+      setBridgeConnectionLostError(null);
+      setConnectingLocalNetworkAccess(false);
+      lateLiveEditReadyRecoveryRef.current = null;
+      setRegisteredLiveEditBridgeKey(liveEditBridgeKey);
+      return true;
+    } catch (error) {
+      if (!isCurrent()) return null;
+      if (registrationHandoffKey) {
+        liveEditRegistrationHandoff.delete(registrationHandoffKey);
+      }
+      console.warn("live-edit bridge registration failed", error);
+      setRegisteredLiveEditBridgeKey(null);
+      setBridgeRegistrationError({
+        bridgeKey: liveEditBridgeKey,
+        message: error instanceof Error ? error.message : String(error),
+      });
+      setConnectingLocalNetworkAccess(false);
+      void classifyBridgeRegistrationFailure().then((kind) => {
+        if (isCurrent()) setBridgeRegistrationFailureKind(kind);
+      });
+      return false;
+    }
+  }, [
+    bridgeUrl,
+    liveEditBridgeKey,
+    liveEditBridgeScript,
+    previewToken,
+    registrationHandoffKey,
+    usesLiveEditInjectedBridge,
+  ]);
   useEffect(() => {
     if (!usesLiveEditInjectedBridge || !bridgeUrl || !previewToken) {
+      // Invalidate any attempt still in flight from before this branch was
+      // entered (previous bridge key/mode) BEFORE clearing state below —
+      // otherwise that stale attempt's isCurrent() check would still pass
+      // when it resolves and could restore registeredLiveEditBridgeKey,
+      // failure state, or handoff data after we've already left this
+      // localhost/bridge configuration.
+      bridgeRegistrationAttemptGenerationRef.current += 1;
       bridgeRegistrationRetryAttemptRef.current = 0;
       liveEditRestartAttemptRef.current = 0;
       liveEditSameInstanceElapsedMsRef.current = 0;
@@ -2157,94 +2373,37 @@ export function DesignCanvas({
       }
       setRegisteredLiveEditBridgeKey(null);
       setBridgeRegistrationError(null);
+      setBridgeRegistrationFailureKind(null);
+      setBridgeConnectionLostError(null);
       setLiveEditSameInstanceStalledError(null);
       lateLiveEditReadyRecoveryRef.current = null;
       return;
     }
-    let cancelled = false;
-    let retryTimer: number | undefined;
     setRegisteredLiveEditBridgeKey((current) =>
       current === liveEditBridgeKey ? current : null,
     );
-    const scheduleRetry = () => {
-      if (cancelled) return;
-      const delay = getSnapshotRetryDelayMs(
-        bridgeRegistrationRetryAttemptRef.current,
-      );
-      bridgeRegistrationRetryAttemptRef.current += 1;
-      retryTimer = window.setTimeout(() => {
-        setBridgeRegistrationRetryNonce((nonce) => nonce + 1);
-      }, delay);
-    };
-    void (async () => {
-      const endpoint = new URL("/live-edit-bridge", bridgeUrl).toString();
-      try {
-        const response = await fetch(endpoint, {
-          method: "POST",
-          headers: {
-            "content-type": "application/json",
-            "x-design-preview-token": previewToken,
-          },
-          body: JSON.stringify({
-            script: liveEditBridgeScript,
-            bridgeKey: liveEditBridgeKey,
-          }),
-        });
-        if (!response.ok) {
-          throw new Error(`Bridge registration failed (${response.status})`);
-        }
-        const payload = (await response.json().catch(() => null)) as {
-          bridgeInstanceId?: string;
-        } | null;
-        if (payload && typeof payload.bridgeInstanceId === "string") {
-          // Cache the instance id from THIS successful registration so a
-          // later suspected-restart probe (see handleSuspectedBridgeRestart)
-          // can tell a genuinely restarted bridge process apart from the same
-          // process rejecting a stale key.
-          bridgeInstanceIdRef.current = payload.bridgeInstanceId;
-        }
-        if (cancelled) return;
-        bridgeRegistrationRetryAttemptRef.current = 0;
-        if (registrationHandoffKey) {
-          liveEditRegistrationHandoff.set(registrationHandoffKey, Date.now());
-        }
-        // liveEditRestartAttemptRef is intentionally NOT reset here: a
-        // successful registration POST only proves the bridge accepted the
-        // script, not that the live document actually loaded it (that's what
-        // the ready-handshake watchdog below still has to confirm). Resetting
-        // the restart budget on every registration success — rather than only
-        // on a genuine agent-native:editor-chrome-ready — would let a
-        // pathological bridge that keeps minting a new bridgeInstanceId
-        // reregister forever, defeating MAX_LIVE_EDIT_RESTART_ATTEMPTS.
-        setBridgeRegistrationError(null);
-        lateLiveEditReadyRecoveryRef.current = null;
-        setRegisteredLiveEditBridgeKey(liveEditBridgeKey);
-      } catch (error) {
-        if (!cancelled) {
-          if (registrationHandoffKey) {
-            liveEditRegistrationHandoff.delete(registrationHandoffKey);
-          }
-          console.warn("live-edit bridge registration failed", error);
-          setRegisteredLiveEditBridgeKey(null);
-          setBridgeRegistrationError({
-            bridgeKey: liveEditBridgeKey,
-            message: error instanceof Error ? error.message : String(error),
-          });
-          scheduleRetry();
-        }
-      }
-    })();
+    let cancelled = false;
+    void attemptBridgeRegistration().then((result) => {
+      // result === false is a definite, still-applicable failure; null means
+      // a newer attempt already superseded this one (see
+      // attemptBridgeRegistration's return-type comment) and must not
+      // schedule a redundant retry.
+      if (result === false && !cancelled) scheduleBridgeRegistrationRetry();
+    });
     return () => {
       cancelled = true;
-      if (retryTimer) window.clearTimeout(retryTimer);
+      if (bridgeRegistrationRetryTimerRef.current !== undefined) {
+        window.clearTimeout(bridgeRegistrationRetryTimerRef.current);
+        bridgeRegistrationRetryTimerRef.current = undefined;
+      }
     };
   }, [
+    attemptBridgeRegistration,
     bridgeRegistrationRetryNonce,
     bridgeUrl,
     liveEditBridgeKey,
-    liveEditBridgeScript,
     previewToken,
-    registrationHandoffKey,
+    scheduleBridgeRegistrationRetry,
     usesLiveEditInjectedBridge,
   ]);
 
@@ -2271,12 +2430,18 @@ export function DesignCanvas({
     lateLiveEditReadyRecoveryRef.current = null;
   }, [liveEditBridgeKey]);
 
-  // Manual retry (offline-state "Retry" button): reset the backoff so the
-  // user-initiated attempt fires immediately, mirroring
-  // handleManualSnapshotRetry below. Also clears the non-destructive
-  // same-instance-id stalled-error card and its escalation state, since a
-  // manual retry (from either error card) should start every counter fresh.
-  const handleManualBridgeRegistrationRetry = useCallback(() => {
+  // Chrome only offers its Local Network Access permission dialog for a
+  // fetch made within an active user-gesture window, so this calls the
+  // SAME attemptBridgeRegistration used by the automatic retry effect
+  // directly and synchronously — not through a nonce bump, which would
+  // defer the actual fetch() past the click's gesture window and lose the
+  // ability to trigger Chrome's permission prompt. Also resets the backoff
+  // and same-instance escalation state, mirroring the offline-state "Retry"
+  // buttons elsewhere in this file, so the user-initiated attempt starts
+  // every counter fresh and any already-scheduled auto-retry doesn't fire a
+  // second, redundant attempt shortly after this one.
+  const handleConnectLocalNetworkAccess = useCallback(() => {
+    setConnectingLocalNetworkAccess(true);
     bridgeRegistrationRetryAttemptRef.current = 0;
     liveEditRestartAttemptRef.current = 0;
     liveEditSameInstanceElapsedMsRef.current = 0;
@@ -2286,8 +2451,23 @@ export function DesignCanvas({
       liveEditSameInstanceRearmTimerRef.current = undefined;
     }
     setLiveEditSameInstanceStalledError(null);
-    setBridgeRegistrationRetryNonce((nonce) => nonce + 1);
-  }, []);
+    if (bridgeRegistrationRetryTimerRef.current !== undefined) {
+      window.clearTimeout(bridgeRegistrationRetryTimerRef.current);
+      bridgeRegistrationRetryTimerRef.current = undefined;
+    }
+    // A failed manual attempt (still-refused permission, dev server still
+    // down) must not silently stop automatic recovery — schedule the same
+    // backoff retry the automatic path uses. null means a newer attempt
+    // (effect-driven or another click) already superseded this one, which
+    // already has its own outcome to handle; only a definite false schedules
+    // here.
+    void attemptBridgeRegistration().then((result) => {
+      if (result === false) scheduleBridgeRegistrationRetry();
+    });
+  }, [attemptBridgeRegistration, scheduleBridgeRegistrationRetry]);
+  const handleDismissLocalNetworkAccessPrompt = useCallback(() => {
+    setLocalNetworkAccessDismissedForKey(liveEditBridgeKey);
+  }, [liveEditBridgeKey]);
 
   // The registered iframe's `src` is a real cross-origin navigation straight
   // to the bridge's authenticated /live-edit URL, so this component can never
@@ -2303,12 +2483,29 @@ export function DesignCanvas({
     if (!bridgeUrl || !previewToken) return;
     if (liveEditRestartInFlightRef.current) return;
     liveEditRestartInFlightRef.current = true;
+    // Captured once per call, not re-read at each checkpoint below: a probe
+    // started against an old screen/key can resolve after a NEW screen has
+    // already registered successfully (bumping this same counter via
+    // attemptBridgeRegistration or the unmount-cleanup effect above) — this
+    // guards every mutating branch below against silently tearing down or
+    // re-registering that newer, unrelated registration.
+    // Deliberately not gated on a one-way "isUnmounted" flag: that shape
+    // never resets, so it would stay stuck true after StrictMode's dev-only
+    // mount→cleanup→mount replay and silently stop every later health probe
+    // from ever resolving (see attemptBridgeRegistration's identical fix
+    // above). The dedicated unmount-cleanup effect there bumps this same
+    // counter on a real
+    // unmount, which isHealthProbeCurrent() already covers correctly.
+    const healthProbeGeneration =
+      bridgeRegistrationAttemptGenerationRef.current;
+    const isHealthProbeCurrent = () =>
+      bridgeRegistrationAttemptGenerationRef.current === healthProbeGeneration;
     try {
       const response = await fetch(healthEndpointUrl(bridgeUrl));
       const payload = (await response.json().catch(() => null)) as {
         bridgeInstanceId?: string;
       } | null;
-      if (isUnmountedRef.current) return;
+      if (!isHealthProbeCurrent()) return;
       const responseBridgeInstanceId =
         payload && typeof payload.bridgeInstanceId === "string"
           ? payload.bridgeInstanceId
@@ -2333,7 +2530,7 @@ export function DesignCanvas({
               }
             : null;
           setRegisteredLiveEditBridgeKey(null);
-          setBridgeRegistrationError({
+          setBridgeConnectionLostError({
             bridgeKey: liveEditBridgeKey,
             message: t("designCanvas.localBridge.confirmationRetryExhausted"),
           });
@@ -2351,7 +2548,7 @@ export function DesignCanvas({
         // re-triggers the registration effect above.
         bridgeInstanceIdRef.current = responseBridgeInstanceId;
         setRegisteredLiveEditBridgeKey(null);
-        setBridgeRegistrationError(null);
+        setBridgeConnectionLostError(null);
         setLiveEditSameInstanceStalledError(null);
         // A genuine restart makes any same-instance-id wait we'd accumulated
         // against the OLD process meaningless — reset the escalation clock so
@@ -2396,7 +2593,7 @@ export function DesignCanvas({
         }
         liveEditSameInstanceRearmTimerRef.current = window.setTimeout(() => {
           liveEditSameInstanceRearmTimerRef.current = undefined;
-          if (isUnmountedRef.current || bridgeReadyRef.current) return;
+          if (bridgeReadyRef.current || !isHealthProbeCurrent()) return;
           void handleSuspectedBridgeRestart();
         }, nextDelay);
         return;
@@ -2417,12 +2614,12 @@ export function DesignCanvas({
           }
         : null;
       setRegisteredLiveEditBridgeKey(null);
-      setBridgeRegistrationError({
+      setBridgeConnectionLostError({
         bridgeKey: liveEditBridgeKey,
         message: t("designCanvas.localBridge.connectionNotConfirmed"),
       });
     } catch (error) {
-      if (isUnmountedRef.current) return;
+      if (!isHealthProbeCurrent()) return;
       // /health itself is unreachable (network error / thrown before a
       // response) — the dev server process is actually down, not just slow.
       // This destructive path (tear down + surface the error) is justified.
@@ -2438,7 +2635,7 @@ export function DesignCanvas({
           }
         : null;
       setRegisteredLiveEditBridgeKey(null);
-      setBridgeRegistrationError({
+      setBridgeConnectionLostError({
         bridgeKey: liveEditBridgeKey,
         message: error instanceof Error ? error.message : String(error),
       });
@@ -2449,8 +2646,8 @@ export function DesignCanvas({
 
   // Manual retry for the NON-destructive same-instance-id stalled card only
   // (see liveEditSameInstanceStalledError below): unlike
-  // handleManualBridgeRegistrationRetry, registeredLiveEditBridgeKey was
-  // never nulled here, so bumping bridgeRegistrationRetryNonce would not
+  // handleConnectLocalNetworkAccess, registeredLiveEditBridgeKey was never
+  // nulled here, so calling attemptBridgeRegistration again would not
   // reschedule a fresh watchdog probe (liveEditBridgeRegistered never flips
   // false→true to rearm that effect). Reset the backoff and probe /health
   // again directly instead.
@@ -2918,9 +3115,14 @@ export function DesignCanvas({
   // the same false-success shape as rendering the snapshot outright: when the
   // swap stalls, the canvas keeps showing a screen that looks correct and
   // responds to nothing. A brief flash is the honest signal.
+  // A raw fallback document (see usingRawFallbackPreview above) never gets an
+  // injected editor-chrome bridge, so it can never post the ready handshake
+  // this waits for — without excluding it here, the fallback iframe would
+  // stay marked "pending" (and thus blocked by the overlay below) forever.
   const liveEditDocumentPending =
     usesLiveEditEditorBridge &&
     Boolean(externalPreviewUrl) &&
+    !usingRawFallbackPreview &&
     readyIframeDocumentIdentity !== iframeDocumentIdentity;
   // A proxied container paints its own app immediately, so without this the
   // canvas looks ready while hover, selection and layers are still dead.
@@ -3073,7 +3275,7 @@ export function DesignCanvas({
               Date.now(),
             );
           }
-          setBridgeRegistrationError((current) =>
+          setBridgeConnectionLostError((current) =>
             current?.bridgeKey === lateReadyRecovery.bridgeKey ? null : current,
           );
           setRegisteredLiveEditBridgeKey(lateReadyRecovery.bridgeKey);
@@ -5440,20 +5642,32 @@ export function DesignCanvas({
           </div>
         </div>
       ) : null}
+      {bridgeRegistrationFailedForCurrentKey &&
+      localNetworkAccessDismissedForKey !== liveEditBridgeKey ? (
+        // Deliberately NOT inside the blocking overlay below: usingRawFallback
+        // Preview means the iframe right underneath is the real running dev
+        // server, so this stays a small, dismissible corner card rather than
+        // hiding working content behind an indefinite "preparing" screen.
+        <LocalNetworkAccessPrompt
+          kind={bridgeRegistrationFailureKind ?? "maybePermissionBlocked"}
+          connecting={connectingLocalNetworkAccess}
+          onConnect={handleConnectLocalNetworkAccess}
+          onDismiss={handleDismissLocalNetworkAccessPrompt}
+        />
+      ) : null}
       {waitingForEditableExternalSnapshot ||
-      waitingForLiveEditBridge ||
+      (waitingForLiveEditBridge && !bridgeRegistrationFailedForCurrentKey) ||
       sameOriginBridgePending ||
       liveEditDocumentPending ? (
         <div className="pointer-events-auto absolute inset-0 z-10 flex items-center justify-center bg-background/85 px-4 text-center text-sm text-muted-foreground">
-          {waitingForLiveEditBridge &&
-          bridgeRegistrationError?.bridgeKey === liveEditBridgeKey ? (
-            // Mirrors the snapshot-fetch offline card below: a stuck
-            // registration used to look identical to ordinary "still
-            // registering" with no explanation and no way to recover short
-            // of a full page reload. Only shown for the CURRENT
-            // liveEditBridgeKey — a stale error from a previous script
-            // revision must not linger after content/mode changes move on
-            // to registering a new one.
+          {bridgeConnectionLostError?.bridgeKey === liveEditBridgeKey ? (
+            // handleSuspectedBridgeRestart's destructive terminal state (see
+            // bridgeConnectionLostError's declaration comment): the
+            // registration itself succeeded, so unlike the floating
+            // LocalNetworkAccessPrompt card above there's no raw dev-server
+            // fallback to show underneath — the live document is what
+            // stopped responding, not the fetch. Keeps its original
+            // full-cover card and copy, unchanged from before this PR.
             <div className="pointer-events-auto flex max-w-[28rem] flex-col items-center gap-2 rounded-md border bg-card px-4 py-3 shadow-sm">
               <div className="flex items-center gap-1.5 font-medium text-foreground">
                 <IconPlugConnectedX className="size-4 shrink-0 text-destructive" />
@@ -5467,13 +5681,13 @@ export function DesignCanvas({
                 }
               </div>
               <div className="w-full truncate rounded bg-muted px-2 py-1 font-mono text-[11px] text-muted-foreground">
-                {bridgeRegistrationError.message}
+                {bridgeConnectionLostError.message}
               </div>
               <Button
                 type="button"
                 variant="outline"
                 size="sm"
-                onClick={handleManualBridgeRegistrationRetry}
+                onClick={handleConnectLocalNetworkAccess}
               >
                 <IconRefresh className="size-3.5" />
                 {"Retry" /* i18n-ignore local dev bridge retry button */}