@molecule/app-ide-react 1.9.0 → 1.10.0

package/dist/components/PreviewPanel.d.ts

@@ -59,7 +59,7 @@ import type { PreviewPanelProps } from '../types.js';
  * @param props - Component props.
  * @returns The rendered preview panel element.
  */
-export declare function PreviewPanel({ loadingIndicator, restartingIndicator, className, onPreviewError, onPreviewStuck, onRenderState, uiCommand, onUiResult, fileChangeTick, buildingHint, isBuilding, wakeAt, }: PreviewPanelProps): JSX.Element;
+export declare function PreviewPanel({ loadingIndicator, restartingIndicator, className, onPreviewError, onPreviewStuck, onRestartBackend, onRenderState, uiCommand, onUiResult, fileChangeTick, buildingHint, isBuilding, wakeAt, }: PreviewPanelProps): JSX.Element;
 export declare namespace PreviewPanel {
     var displayName: string;
 }

package/dist/components/PreviewPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PreviewPanel.d.ts","sourceRoot":"","sources":["../../src/components/PreviewPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,KAAK,GAAG,EAA4C,MAAM,OAAO,CAAA;AAW1E,OAAO,KAAK,EAAE,iBAAiB,EAAuC,MAAM,aAAa,CAAA;AA8SzF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,gBAAgB,EAChB,mBAAmB,EACnB,SAAS,EACT,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,UAAU,EACV,cAAc,EACd,YAAY,EACZ,UAAU,EACV,MAAM,GACP,EAAE,iBAAiB,GAAG,GAAG,CAAC,OAAO,CAwoDjC;yBArpDe,YAAY"}
+{"version":3,"file":"PreviewPanel.d.ts","sourceRoot":"","sources":["../../src/components/PreviewPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,KAAK,GAAG,EAA4C,MAAM,OAAO,CAAA;AAW1E,OAAO,KAAK,EAAE,iBAAiB,EAAuC,MAAM,aAAa,CAAA;AAoWzF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,gBAAgB,EAChB,mBAAmB,EACnB,SAAS,EACT,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,UAAU,EACV,cAAc,EACd,YAAY,EACZ,UAAU,EACV,MAAM,GACP,EAAE,iBAAiB,GAAG,GAAG,CAAC,OAAO,CA81DjC;yBA52De,YAAY"}

package/dist/components/PreviewPanel.js

@@ -73,6 +73,23 @@ const ORIENTATION_STORAGE_KEY = 'molecule.ide.preview.orientation';
 // --- Polling constants (exponential backoff, never gives up) ---
 /** Initial poll interval when waiting for the server. */
 const POLL_INITIAL_MS = 500;
+/**
+ * How long the FIRST-mount server-up poll may run without the server answering
+ * before the panel surfaces the actionable "Preview can't load here" notice
+ * (ms). The poll itself keeps running underneath — the notice self-clears the
+ * moment a poll succeeds and mounts the iframe — so this is honesty, not a
+ * give-up: it hands the user Reload / Open-in-new-tab instead of an unbounded
+ * spinner. Before this existed the pre-mount poll was the one path with NO
+ * actionable escape at all: it "never gives up" by design, and the absolute
+ * ceiling that should have backstopped it fired once, stood down inside the
+ * wake window, and never re-checked — a viewer's fresh page load against a
+ * never-answering preview sat on "Loading preview…" indefinitely with no modal
+ * (observed 2026-08-31). Sized past a proxy cold-start + dev-server relaunch so
+ * a normal slow boot still resolves silently.
+ */
+const PREMOUNT_GIVEUP_MS = 45_000;
+/** Re-check gap for the absolute readiness ceiling when it stands down for a benign hold (ms). */
+const ABSOLUTE_STUCK_RECHECK_MS = 10_000;
 /** Maximum poll interval after backoff. */
 const POLL_MAX_MS = 5000;
 /** Backoff multiplier applied after each failed poll. */
@@ -102,6 +119,38 @@ const STUCK_BACKOFF_FACTOR = 1.6;
  * instead of remounting indefinitely — the old `longRetry()` looped forever.
  */
 const MAX_RECOVERY_CYCLES = 3;
+/**
+ * Max probe-driven automatic recoveries per dead-end episode. Every actionable
+ * notice ("Preview can't load here", "the preview is blank") used to be a true
+ * dead end: all in-budget retries had already run, and only a human clicking
+ * Reload could try again. But the server those retries ran against may simply
+ * not be up YET — an E2B resume of a long-paused sandbox pulls its snapshot
+ * from cold storage and can take minutes, outliving wake patience AND every
+ * retry budget (observed 2026-08-31: a 24h-asleep sandbox woke fine, but the
+ * panel had given up and a manual "Reload preview" was needed — which worked,
+ * because by then the server was serving). So while a dead-end notice is up
+ * over a DEAD document, the panel keeps probing the preview URL and, the
+ * moment the server answers, runs exactly the manual-retry path itself. This
+ * cap bounds that per episode so a server that answers probes but serves a
+ * broken app cannot ping-pong give-up → auto-retry forever; a confirmed render
+ * (or a human retry) resets the budget.
+ */
+const MAX_DEAD_END_AUTO_RECOVERS = 3;
+// --- Backend-restart escalation (see PreviewPanelProps.onRestartBackend) ---
+/**
+ * How long the app may sit with NO confirmed render before the panel may escalate
+ * to a backend dev-server restart (ms). Deliberately generous: it must outlast a
+ * heavy cold compile, wake patience, and multiple dead-end reload attempts, so a
+ * restart is only ever the answer when reloading has already been tried against a
+ * SERVING host and provably changed nothing (the poisoned-module-cache class —
+ * a document reload reuses the dev server's immutable `?v=` module URLs, so only
+ * a server restart, which mints a new version hash, can clear it).
+ */
+const BACKEND_RESTART_AFTER_MS = 180_000;
+/** Cooldown between backend-restart escalations (ms) — one restart gets one full recovery cycle. */
+const BACKEND_RESTART_COOLDOWN_MS = 600_000;
+/** Cadence of the escalation watchdog's cheap pre-checks (ms). */
+const BACKEND_RESTART_CHECK_MS = 10_000;
 /**
  * Absolute upper bound (ms) on how long the preview may sit on the loading overlay
  * without ever CONFIRMING a render (`molecule:ready`), while not mid-build. A pure
@@ -346,7 +395,7 @@ async function isServerUp(url, externalSignal) {
  * @param props - Component props.
  * @returns The rendered preview panel element.
  */
-export function PreviewPanel({ loadingIndicator, restartingIndicator, className, onPreviewError, onPreviewStuck, onRenderState, uiCommand, onUiResult, fileChangeTick, buildingHint, isBuilding, wakeAt, }) {
+export function PreviewPanel({ loadingIndicator, restartingIndicator, className, onPreviewError, onPreviewStuck, onRestartBackend, onRenderState, uiCommand, onUiResult, fileChangeTick, buildingHint, isBuilding, wakeAt, }) {
     const cm = getClassMap();
     const { state, setUrl, refresh, setDevice, openExternal, recordNavigation, back, forward } = usePreview();
     const iframeRef = useRef(null);
@@ -476,6 +525,9 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
     const pollEpochRef = useRef(0);
     // AbortController for the in-flight server-up probe, so cleanup can cancel it.
     const pollAbortRef = useRef(null);
+    // Deadline for the first-mount poll to surface the actionable notice while it
+    // keeps polling (see PREMOUNT_GIVEUP_MS). Cleared with the poll chain.
+    const pollGiveUpTimerRef = useRef(null);
     const urlRef = useRef(state.url);
     urlRef.current = state.url;
     // The preview's live location (client-side route included), read by the stuck/freeze
@@ -499,6 +551,17 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
     // True once the cap of recovery cycles is hit — stops the loop and shows the
     // themed "Preview can't load here" panel (loop breaker) instead of thrashing.
     const [previewGaveUp, setPreviewGaveUp] = useState(false);
+    // Probe-driven automatic recoveries fired this dead-end episode (see
+    // MAX_DEAD_END_AUTO_RECOVERS) — reset on a confirmed render or a manual retry.
+    const deadEndAutoRecoversRef = useRef(0);
+    // --- Backend-restart escalation state (see the escalation watchdog effect) ---
+    // When the current "no confirmed render" stretch began. Pushed forward by any
+    // confirm-state change, a new load target, and a wake — so the escalation clock
+    // only measures genuinely-stuck time, never healthy time or granted patience.
+    const notConfirmedSinceRef = useRef(Date.now());
+    // One escalation per broken episode; re-armed only by a confirmed render.
+    const backendRestartUsedRef = useRef(false);
+    const lastBackendRestartAtRef = useRef(0);
     // Mirror iframeReady to a ref so timer callbacks read current value
     const iframeReadyRef = useRef(iframeReady);
     iframeReadyRef.current = iframeReady;
@@ -620,6 +683,9 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
         setBlankPostBuild(false);
         setPreviewGaveUp(false);
         setStuckRetryCount(0);
+        // A wake grants a fresh escalation clock too — the relaunching server owes
+        // no restart while its own cold path plays out.
+        notConfirmedSinceRef.current = Date.now();
         if (neverRendered && urlRef.current) {
             setIframeSrc(withCacheBuster(urlRef.current));
         }
@@ -659,6 +725,10 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
             pollAbortRef.current.abort();
             pollAbortRef.current = null;
         }
+        if (pollGiveUpTimerRef.current) {
+            clearTimeout(pollGiveUpTimerRef.current);
+            pollGiveUpTimerRef.current = null;
+        }
     }, []);
     // --- Clear stuck timer ---
     const clearStuckTimer = useCallback(() => {
@@ -668,7 +738,10 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
         }
     }, []);
     // --- Poll until server is up, then mount the iframe ---
-    // Uses exponential backoff: POLL_INITIAL_MS → POLL_MAX_MS. Never gives up.
+    // Uses exponential backoff: POLL_INITIAL_MS → POLL_MAX_MS. The poll itself never
+    // stops, but past PREMOUNT_GIVEUP_MS it surfaces the actionable notice while it
+    // keeps polling — the user always has a way out (Reload / Open in new tab), and a
+    // late success still mounts + withdraws the notice by itself.
     const startPolling = useCallback((url) => {
         // clearPoll() bumps the epoch + aborts the prior chain; capture the fresh
         // epoch + a new AbortController so THIS chain is the only live one. Any older
@@ -683,6 +756,21 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
         // A (re)load hasn't confirmed content yet — the overlay governs until it does.
         setConfirmedContent(false);
         setBlankPostBuild(false);
+        // The poll never stops on its own, so past this deadline it surfaces the
+        // actionable notice (Reload / Open in new tab) INSTEAD of an unbounded
+        // spinner — and keeps polling underneath; a later success mounts the
+        // iframe and withdraws the notice. This was the one preview path with no
+        // escape hatch at all (see PREMOUNT_GIVEUP_MS).
+        pollGiveUpTimerRef.current = setTimeout(() => {
+            pollGiveUpTimerRef.current = null;
+            if (pollEpochRef.current !== epoch)
+                return;
+            // Deliberate breadcrumb: this state means the preview host never answered a
+            // probe for the whole deadline — the console line is the forensic trail for
+            // the next live debug of a "stuck on Loading preview" report.
+            console.warn(`[preview] server at ${url} has not answered for ${Math.round(PREMOUNT_GIVEUP_MS / 1000)}s — showing the reload notice, still polling`);
+            setPreviewGaveUp(true);
+        }, PREMOUNT_GIVEUP_MS);
         let interval = POLL_INITIAL_MS;
         const poll = async () => {
             if (pollEpochRef.current !== epoch || urlRef.current !== url)
@@ -691,6 +779,11 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
             if (pollEpochRef.current !== epoch || urlRef.current !== url)
                 return;
             if (up) {
+                if (pollGiveUpTimerRef.current) {
+                    clearTimeout(pollGiveUpTimerRef.current);
+                    pollGiveUpTimerRef.current = null;
+                }
+                setPreviewGaveUp(false);
                 setEverLoaded(true);
                 // Atomic remount (fresh <iframe> element + src in one commit), like the
                 // proven manual-reload/navigation paths: if `setUrl` was called more than
@@ -736,6 +829,8 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
         // it patiently (reveal on ready, no premature blank/give-up) until ITS first molecule:ready.
         hasEverRenderedRef.current = false;
         lastLoadAtRef.current = 0;
+        // Fresh escalation clock for the new target.
+        notConfirmedSinceRef.current = Date.now();
         // A new load target hasn't confirmed content yet.
         setConfirmedContent(false);
         setBlankPostBuild(false);
@@ -812,8 +907,10 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
         if (iframeReady) {
             setFadingOut(true);
             // Content is showing again — tear down the loop-breaker panel so a later good render
-            // always clears it.
+            // always clears it, and refund the dead-end auto-recovery budget (the episode ended
+            // in a working preview, so the next outage starts with a full budget).
             setPreviewGaveUp(false);
+            deadEndAutoRecoversRef.current = 0;
             // Clear fadingOut when the fade finishes. The overlay's onTransitionEnd is the primary
             // trigger, but it never fires if the overlay unmounts mid-fade, the transition is disabled
             // (prefers-reduced-motion), or in a non-rendering env — so a timer matched to the fade is
@@ -849,6 +946,19 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
                 // fallback; do not interrupt a progressing load with a remount.
                 if (iframeLoadedRef.current)
                     return;
+                // A heartbeating document is ALIVE and MID-LOAD: the inline bridge runs
+                // from HTML parse, long before a large module graph finishes (a
+                // multi-repo import behind a microVM edge takes ~30s for ~250 modules —
+                // observed live 2026-08-31). Reloading it aborts every in-flight module
+                // fetch, and the next document races onto the aborted entries and
+                // memoizes spurious failures — the recovery loop MURDERS the loads it
+                // guards ("stuck on Loading preview" while a fresh tab loads fine).
+                // Keep watching instead; a dead doc (no heartbeat) still recovers, and
+                // window `load` never firing at all is bounded by the ceilings.
+                if (Date.now() - lastHeartbeatRef.current < FREEZE_THRESHOLD_MS) {
+                    scheduleNext();
+                    return;
+                }
                 cycleCount += 1;
                 setStuckRetryCount(cycleCount);
                 if (cycleCount <= MAX_RECOVERY_CYCLES) {
@@ -876,35 +986,46 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
     }, [iframeSrc, iframeReady, previewGaveUp, onPreviewStuck, clearStuckTimer]);
     // --- Absolute readiness ceiling (backstop: never stuck on the overlay forever) ---
     // Independent of every intermediate flag (onLoad / iframeReady / stuck cycles): anchored
-    // to the load, it fires ONCE after ABSOLUTE_STUCK_MS and — if the app still hasn't
-    // confirmed a render and a build isn't running — surfaces the actionable loop-breaker
-    // panel. This is the guarantee that no combination of failed sub-paths can leave the
-    // preview spinning forever. Read live refs (not stale closures); a `molecule:ready` that
-    // lands later clears `previewGaveUp` via the confirm effect, so an early trip is harmless.
+    // to the load, it first checks at ABSOLUTE_STUCK_MS and — if the app still hasn't
+    // confirmed a render and no benign hold applies — surfaces the actionable loop-breaker
+    // panel; a benign hold defers the CHECK, never disarms it. This is the guarantee that no
+    // combination of failed sub-paths can leave the preview spinning forever. Read live refs
+    // (not stale closures); a `molecule:ready` that lands later clears `previewGaveUp` via
+    // the confirm effect, so an early trip is harmless.
     useEffect(() => {
         if (!state.url)
             return;
-        const timer = setTimeout(() => {
-            // Fire ONLY when still on a bare spinner. iframeReady is the key addition: the onLoad
-            // grace already revealed a loaded document, so the give-up panel must never cover it —
-            // the panel is reserved for a preview that genuinely never loaded (onLoad never fired).
-            // A confirmed render, an active build, or the actionable blank notice also mean not-stuck.
-            if (confirmedContentRef.current ||
-                iframeReadyRef.current ||
-                isBuildingRef.current ||
-                blankPostBuildRef.current ||
-                // The app is ALIVE (heartbeating) — a cold boot in progress, not a stuck load. Never show
-                // "Preview can't load here" over an app that's still starting; the cold-boot evaluator
-                // surfaces an honest notice only if it stays alive-but-unmounted past COLD_BOOT_PATIENCE_MS.
-                Date.now() - lastHeartbeatRef.current < FREEZE_THRESHOLD_MS ||
-                // A just-woken server is expected to serve a dead/transient document for a while —
-                // stand down; the cold-boot evaluator's ceiling still guarantees an eventual way out.
-                inWakeWindow())
-                return;
-            onPreviewStuck?.({ reason: 'load-timeout', url: currentLocationRef.current });
-            setPreviewGaveUp(true);
-        }, ABSOLUTE_STUCK_MS);
-        return () => clearTimeout(timer);
+        let timer = null;
+        const arm = (delay) => {
+            timer = setTimeout(() => {
+                // A revealed or confirmed preview is healthy — this load needs no ceiling.
+                if (confirmedContentRef.current || iframeReadyRef.current)
+                    return;
+                // Fire ONLY when still on a bare spinner. iframeReady above is the key gate: the
+                // onLoad grace already revealed a loaded document, so the give-up panel must never
+                // cover it — the panel is reserved for a preview that genuinely never loaded.
+                // A benign hold — an active build, the actionable blank notice already showing, an
+                // ALIVE (heartbeating) cold boot, or a just-woken server's patience window — does
+                // NOT disarm the ceiling: it RE-CHECKS after a beat. The old one-shot timer stood
+                // down permanently on any of these, so a wake window that swallowed the single
+                // firing left a never-answering preview on the spinner forever with no notice
+                // (the "no reload modal ever popped up" report, 2026-08-31).
+                if (isBuildingRef.current ||
+                    blankPostBuildRef.current ||
+                    Date.now() - lastHeartbeatRef.current < FREEZE_THRESHOLD_MS ||
+                    inWakeWindow()) {
+                    arm(ABSOLUTE_STUCK_RECHECK_MS);
+                    return;
+                }
+                onPreviewStuck?.({ reason: 'load-timeout', url: currentLocationRef.current });
+                setPreviewGaveUp(true);
+            }, delay);
+        };
+        arm(ABSOLUTE_STUCK_MS);
+        return () => {
+            if (timer)
+                clearTimeout(timer);
+        };
         // Re-armed per load (url change or refresh/back-forward via loadNonce); a successful
         // render before the ceiling is honored by the live-ref check in the callback.
     }, [state.url, state.loadNonce, onPreviewStuck, inWakeWindow]);
@@ -1330,6 +1451,16 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
     // stop. Origin-Agent-Cluster isolation keeps that freeze off the IDE's thread, so
     // the IDE can notice the silence and offer a reload — a frozen frame can't recover
     // on its own. Auto-clears if heartbeats resume (transient jank, not a hard lock).
+    //
+    // VISIBILITY-AWARE, deliberately: in a hidden tab the browser throttles BOTH
+    // sides — the iframe's heartbeats stop being delivered AND this interval only
+    // wakes about once a minute — so every throttle wake used to read as an
+    // 18–58s "freeze": the banner popped and the frozen report (with its alert
+    // tone) fired once per minute for as long as the tab stayed backgrounded
+    // (observed live 2026-08-29; forensics showed heap flat + thread idle, i.e.
+    // pure throttling, no real freeze). A hidden tab renders nothing, so there is
+    // nothing to accuse: skip checks while hidden and re-baseline on return to
+    // the foreground so the hidden gap can never count against the app.
     useEffect(() => {
         if (!iframeReady || fadingOut || !state.url) {
             setPreviewFrozen(false);
@@ -1338,9 +1469,23 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
         // Baseline so a stale value from a prior load can't trip us immediately.
         lastHeartbeatRef.current = Date.now();
         const timer = setInterval(() => {
+            if (document.visibilityState === 'hidden')
+                return;
             setPreviewFrozen(Date.now() - lastHeartbeatRef.current > FREEZE_THRESHOLD_MS);
         }, FREEZE_CHECK_INTERVAL_MS);
-        return () => clearInterval(timer);
+        const onVisibility = () => {
+            if (document.visibilityState !== 'visible')
+                return;
+            // Fresh grace window: heartbeats resume with the foreground; the gap that
+            // accumulated while hidden was throttling, not the app.
+            lastHeartbeatRef.current = Date.now();
+            setPreviewFrozen(false);
+        };
+        document.addEventListener('visibilitychange', onVisibility);
+        return () => {
+            clearInterval(timer);
+            document.removeEventListener('visibilitychange', onVisibility);
+        };
     }, [iframeReady, fadingOut, state.url]);
     // --- Freeze → host report ---
     // A frozen preview is the worst case the iframe CANNOT self-report (its thread is
@@ -1480,6 +1625,139 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
             setIframeSrc(withCacheBuster(state.url));
         }
     }, [state.url]);
+    // A HUMAN retry is a fresh episode — refund the probe-driven budget so the
+    // panel keeps auto-recovering alongside them.
+    const handleUserRetry = useCallback(() => {
+        deadEndAutoRecoversRef.current = 0;
+        handleManualRetry();
+    }, [handleManualRetry]);
+    // --- Dead-end auto-recovery: probe while an actionable notice is up, retry when the server answers ---
+    // Both dead-end notices (the give-up loop-breaker and the blank notice) mean every
+    // in-budget retry already ran — against a server that may simply not have been up YET
+    // (the motivating case: an E2B resume pulling a long-paused snapshot from cold storage
+    // takes minutes; see MAX_DEAD_END_AUTO_RECOVERS). So instead of waiting for a human to
+    // click Reload, keep asking the preview host whether it is serving — sequentially, one
+    // probe at a time, exactly like the steady-state health check — and when it finally
+    // answers, run the manual-retry path automatically. Gated on the document being DEAD
+    // (no recent heartbeat): a heartbeating app behind the blank notice is an app that runs
+    // but renders nothing — an app bug a reload cannot fix, and auto-reloading it would
+    // just flicker the actionable notice the user is reading. isServerUp prefers the
+    // readable /__mol/preview-status (the mlcl.dev proxy reports the UPSTREAM truthfully,
+    // so an edge answering FOR a down sandbox does not read as "up").
+    useEffect(() => {
+        if (!state.url || confirmedContent)
+            return undefined;
+        if (!previewGaveUp && !blankPostBuild)
+            return undefined;
+        const aborter = new AbortController();
+        let timer = null;
+        const tick = async () => {
+            if (aborter.signal.aborted)
+                return;
+            if (deadEndAutoRecoversRef.current >= MAX_DEAD_END_AUTO_RECOVERS)
+                return;
+            if (Date.now() - lastHeartbeatRef.current < FREEZE_THRESHOLD_MS) {
+                // Alive behind the notice — not our case; re-check later in case it dies.
+                timer = setTimeout(() => void tick(), HEALTH_POLL_MS);
+                return;
+            }
+            const up = await isServerUp(urlRef.current, aborter.signal);
+            if (aborter.signal.aborted)
+                return;
+            if (up) {
+                deadEndAutoRecoversRef.current += 1;
+                handleManualRetry();
+                return;
+            }
+            timer = setTimeout(() => void tick(), HEALTH_POLL_MS);
+        };
+        timer = setTimeout(() => void tick(), HEALTH_POLL_MS);
+        return () => {
+            aborter.abort();
+            if (timer)
+                clearTimeout(timer);
+        };
+    }, [previewGaveUp, blankPostBuild, confirmedContent, state.url, handleManualRetry]);
+    // The escalation clock measures CONTINUOUS unconfirmed time: any change of the
+    // confirm verdict (healthy→broken or broken→healthy) restarts it, so a stretch
+    // of healthy rendering can never count toward a restart, and a confirmed render
+    // re-arms the once-per-episode escalation budget.
+    useEffect(() => {
+        notConfirmedSinceRef.current = Date.now();
+        if (confirmedContent)
+            backendRestartUsedRef.current = false;
+    }, [confirmedContent]);
+    // --- Backend-restart escalation watchdog (see PreviewPanelProps.onRestartBackend) ---
+    // The one recovery a document reload can NEVER perform: when the dev server's
+    // module state is poisoned (observed live 2026-08-31: module failures memoized
+    // against vite's immutable `?v=`-hashed URLs — every reload, manual and
+    // automatic, rebuilt the same broken graph with zero errors anywhere), only a
+    // SERVER restart mints new module URLs. Escalates at most once per broken
+    // episode, and only when every cheaper explanation is exhausted:
+    //   • the app has confirmed nothing for BACKEND_RESTART_AFTER_MS straight
+    //     (clock reset by confirms, new targets, and wakes — patience is honored),
+    //   • at least one dead-end auto-reload already ran (so a plain cold boot,
+    //     which never engages the dead-end machinery, can never trip this),
+    //   • the server answers probes RIGHT NOW (a down server needs waking/time,
+    //     not a restart — the dead-end probe loop owns that case),
+    //   • no build is running (the executor owns the sandbox during a turn).
+    // The host may DECLINE (return false: wrong role, hidden tab, sandbox not
+    // running) — nothing is burned and the watchdog may ask again later.
+    useEffect(() => {
+        if (!state.url || !onRestartBackend)
+            return undefined;
+        const aborter = new AbortController();
+        let inFlight = false;
+        const interval = setInterval(() => {
+            if (inFlight)
+                return;
+            inFlight = true;
+            void (async () => {
+                try {
+                    if (confirmedContentRef.current || isBuildingRef.current)
+                        return;
+                    if (deadEndAutoRecoversRef.current < 1)
+                        return;
+                    if (backendRestartUsedRef.current)
+                        return;
+                    const now = Date.now();
+                    if (now - notConfirmedSinceRef.current < BACKEND_RESTART_AFTER_MS)
+                        return;
+                    if (now - lastBackendRestartAtRef.current < BACKEND_RESTART_COOLDOWN_MS)
+                        return;
+                    const up = await isServerUp(urlRef.current, aborter.signal);
+                    if (aborter.signal.aborted || !up)
+                        return;
+                    // Re-check the fast-moving gates after the await.
+                    if (confirmedContentRef.current || isBuildingRef.current)
+                        return;
+                    const outcome = await onRestartBackend();
+                    if (aborter.signal.aborted || outcome === false)
+                        return;
+                    backendRestartUsedRef.current = true;
+                    lastBackendRestartAtRef.current = Date.now();
+                    notConfirmedSinceRef.current = Date.now();
+                    // The restarted server deserves a fresh reload budget so the dead-end
+                    // probe (or the wake reload) can bring the recovered app in.
+                    deadEndAutoRecoversRef.current = 0;
+                    // Deliberate breadcrumb — names the escalation in the console so a
+                    // "the preview restarted itself" report is traceable.
+                    console.warn('[preview] escalated to a backend dev-server restart — reloads could not produce a render against a serving host');
+                }
+                catch (_error) {
+                    // Escalation is strictly best-effort: a failed probe or a host error
+                    // must never break the panel; the next check re-evaluates.
+                }
+                finally {
+                    inFlight = false;
+                }
+            })();
+        }, BACKEND_RESTART_CHECK_MS);
+        return () => {
+            aborter.abort();
+            clearInterval(interval);
+        };
+    }, [state.url, onRestartBackend]);
     // --- Reload a frozen preview ---
     // Remounts the iframe (fresh load re-runs the app, clearing the locked thread).
     const handleReloadFrozen = useCallback(() => {
@@ -1547,8 +1825,8 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
     // Fully opaque + interactive whenever it is standing in for missing content (only the
     // ready-then-fading-out state animates to transparent).
     const overlaySolid = !iframeReady || blankPostBuild || buildingUnconfirmed;
-    const overlayContent = blankPostBuild ? (_jsx(PreviewBlankNotice, { onReload: handleManualRetry, onOpenExternal: openExternal })) : isBuilding || building ? (_jsx(DefaultLoadingIndicator, { hint: buildingHint, retryCount: stuckRetryCount, onManualRetry: handleManualRetry })) : everLoaded ? ((restartingIndicator ??
-        loadingIndicator ?? (_jsx(DefaultLoadingIndicator, { retryCount: stuckRetryCount, onManualRetry: handleManualRetry })))) : ((loadingIndicator ?? (_jsx(DefaultLoadingIndicator, { retryCount: stuckRetryCount, onManualRetry: handleManualRetry }))));
+    const overlayContent = blankPostBuild ? (_jsx(PreviewBlankNotice, { onReload: handleUserRetry, onOpenExternal: openExternal })) : isBuilding || building ? (_jsx(DefaultLoadingIndicator, { hint: buildingHint, retryCount: stuckRetryCount, onManualRetry: handleUserRetry })) : everLoaded ? ((restartingIndicator ??
+        loadingIndicator ?? (_jsx(DefaultLoadingIndicator, { retryCount: stuckRetryCount, onManualRetry: handleUserRetry })))) : ((loadingIndicator ?? (_jsx(DefaultLoadingIndicator, { retryCount: stuckRetryCount, onManualRetry: handleUserRetry }))));
     return (_jsxs("div", { className: cm.cn(cm.flex({ direction: 'col' }), cm.h('full'), cm.surface, className), children: [_jsx("div", { className: cm.cn(cm.sp('px', 3), cm.sp('py', 2), cm.shrink0, cm.borderB), children: _jsxs("div", { className: cm.cn(cm.flex({ direction: 'row', align: 'center', gap: 'xs' })), children: [_jsxs("div", { "data-mol-id": "preview-url-field", className: cm.cn(cm.flex({ direction: 'row', align: 'center', gap: 'xs' }), cm.sp('px', 2), cm.surface), style: {
                                 flex: 1,
                                 // On phone-width viewports the field keeps an 80px floor (the
@@ -1686,7 +1964,7 @@ export function PreviewPanel({ loadingIndicator, restartingIndicator, className,
                             zIndex: 2,
                             padding: '24px',
                             textAlign: 'center',
-                        }, children: [_jsx(Icon, { name: "x-circle", size: 28, className: cm.textMuted, "aria-hidden": "true" }), _jsx("div", { className: cm.cn(cm.textSize('sm')), style: { color: 'var(--mol-color-text, #333)', fontWeight: 600 }, children: t('ide.preview.loadFailed', {}, { defaultValue: "Preview can't load here" }) }), _jsx("div", { className: cm.cn(cm.textSize('xs'), cm.textMuted), style: { maxWidth: '320px' }, children: t('ide.preview.loadFailedHint', {}, { defaultValue: 'Try reloading, or open the preview in a new tab.' }) }), _jsxs("div", { style: { display: 'flex', gap: '8px' }, children: [_jsx("button", { type: "button", "data-mol-id": "preview-load-failed-reload", onClick: handleManualRetry, className: cm.cn(cm.button({ variant: 'solid', color: 'primary', size: 'sm' }), cm.touchTarget), children: t('ide.preview.reloadPreview', {}, { defaultValue: 'Reload preview' }) }), _jsx("button", { type: "button", "data-mol-id": "preview-load-failed-open", onClick: openExternal, className: cm.cn(cm.button({ variant: 'ghost', size: 'sm' }), cm.touchTarget), children: t('ide.preview.openNewTab', {}, { defaultValue: 'Open in new tab' }) })] })] })), !state.url && (_jsx("div", { className: cm.cn(cm.textMuted, cm.textSize('sm')), style: {
+                        }, children: [_jsx(Icon, { name: "x-circle", size: 28, className: cm.textMuted, "aria-hidden": "true" }), _jsx("div", { className: cm.cn(cm.textSize('sm')), style: { color: 'var(--mol-color-text, #333)', fontWeight: 600 }, children: t('ide.preview.loadFailed', {}, { defaultValue: "Preview can't load here" }) }), _jsx("div", { className: cm.cn(cm.textSize('xs'), cm.textMuted), style: { maxWidth: '320px' }, children: t('ide.preview.loadFailedHint', {}, { defaultValue: 'Try reloading, or open the preview in a new tab.' }) }), _jsxs("div", { style: { display: 'flex', gap: '8px' }, children: [_jsx("button", { type: "button", "data-mol-id": "preview-load-failed-reload", onClick: handleUserRetry, className: cm.cn(cm.button({ variant: 'solid', color: 'primary', size: 'sm' }), cm.touchTarget), children: t('ide.preview.reloadPreview', {}, { defaultValue: 'Reload preview' }) }), _jsx("button", { type: "button", "data-mol-id": "preview-load-failed-open", onClick: openExternal, className: cm.cn(cm.button({ variant: 'ghost', size: 'sm' }), cm.touchTarget), children: t('ide.preview.openNewTab', {}, { defaultValue: 'Open in new tab' }) })] })] })), !state.url && (_jsx("div", { className: cm.cn(cm.textMuted, cm.textSize('sm')), style: {
                             display: 'flex',
                             alignItems: 'center',
                             justifyContent: 'center',