@forgeax/interface 0.4.1

package/dist/package/node/components/StatusBar/healthBridge.js

@@ -0,0 +1,245 @@
+/**
+ * Health bridge — wires every error/health source into the health store.
+ *
+ * Install ONCE at boot (see main.tsx). Idempotent.
+ *
+ * Sources captured here:
+ *   1. The shell itself: window 'error' / 'unhandledrejection' + a console.error
+ *      wrapper → source 'shell'.
+ *   2. iframe-forwarded health: `postMessage({type:'forgeax:health', level,
+ *      source, code, message})` from play / edit / plugin runtimes (cross-origin,
+ *      so this is how their console errors reach the shell at all).
+ *   3. The pre-existing VAG wire: VAG_CONSOLE (error/warn lines) + VAG_DEVICE_LOST.
+ *      These already reach the host window from the runtimes; we map them onto the
+ *      health store too so nothing is missed even before a runtime ships the new
+ *      `forgeax:health` envelope. Source is inferred from the iframe URL.
+ *
+ * We deliberately do NOT import @forgeax/editor here (that would re-create the
+ * interface→editor cycle the panel-renderer split removed). The wire contract is
+ * plain postMessage shapes validated inline.
+ */
+import { installWindowMessageObservation } from '@forgeax/app-shell/react';
+import { pushHealth } from './healthStore.js';
+import { isTrustedMessageOrigin } from '../../lib/trustedOrigins.js';
+import { useShellStore } from '../../store.js';
+let installed = false;
+const CONSOLE_LEVELS = ['log', 'warn', 'error', 'info', 'debug'];
+const BROWSER_CONSOLE_MAX = 500;
+const browserConsole = [];
+function recordBrowserConsole(level, text) {
+    if (text.startsWith('[health]'))
+        return; // 防 pushHealth→console 自捕获回环
+    // 去重:与上一条 level+text 相同 → 折叠成 repeat 计数并刷新 ts,不新增(60Hz 刷屏只留一条)。
+    const last = browserConsole[browserConsole.length - 1];
+    if (last && last.level === level && last.text === text) {
+        last.repeat = (last.repeat ?? 1) + 1;
+        last.ts = Date.now();
+        return;
+    }
+    browserConsole.push({ level, text, ts: Date.now() });
+    if (browserConsole.length > BROWSER_CONSOLE_MAX) {
+        browserConsole.splice(0, browserConsole.length - BROWSER_CONSOLE_MAX);
+    }
+}
+/** console.read{source:'browser'} 读取全量外壳控制台(只读引用,勿改)。 */
+export function getBrowserConsole() {
+    return browserConsole;
+}
+/** 清空外壳控制台缓冲(console.clear{source:'browser'} 用)。 */
+export function clearBrowserConsole() {
+    browserConsole.length = 0;
+}
+function asConsoleLevel(x) {
+    return CONSOLE_LEVELS.includes(String(x)) ? String(x) : 'log';
+}
+function asLevel(x) {
+    switch (x) {
+        case 'success': return 'success';
+        case 'warn':
+        case 'warning': return 'warn';
+        case 'error': return 'error';
+        default: return 'info';
+    }
+}
+function asSource(x) {
+    switch (x) {
+        case 'play': return 'play';
+        case 'edit': return 'edit';
+        case 'plugin': return 'plugin';
+        case 'engine': return 'engine';
+        default: return 'shell';
+    }
+}
+/** Map a console level → health level (log/info/debug collapse to info). */
+function consoleLevelToHealth(level) {
+    if (level === 'error')
+        return 'error';
+    if (level === 'warn')
+        return 'warn';
+    return null; // skip log/info/debug noise — only surface warn+ from iframes.
+}
+/** Best-effort: figure out which region an iframe message came from by its URL. */
+function sourceFromEvent(ev) {
+    try {
+        const win = ev.source;
+        if (win) {
+            const frames = document.querySelectorAll('iframe');
+            for (const f of Array.from(frames)) {
+                if (f.contentWindow === win) {
+                    const src = f.getAttribute('src') ?? '';
+                    // Only /preview (play-runtime) is still a real iframe. The edit surface
+                    // is in-process (single realm) — its health forwards through the shared
+                    // store directly, never an iframe message — so no '/editor' branch.
+                    if (src.includes('/preview'))
+                        return 'play';
+                    return 'plugin';
+                }
+            }
+        }
+    }
+    catch { /* cross-origin / detached */ }
+    // Fall back to URL hints in the message origin.
+    return 'engine';
+}
+/** iframe→shell telemetry postMessage 摄取(VAG_TELEMETRY)。返 true=本消息已消费。
+ *  抽成纯函数,既给 message 监听复用,也便于单测(不必装全局监听,避免跨用例污染)。 */
+export function ingestVagTelemetry(data) {
+    if (data?.type !== 'VAG_TELEMETRY')
+        return false;
+    const recs = data.records;
+    if (!Array.isArray(recs) || recs.length === 0)
+        return true;
+    useShellStore.getState().pushTelemetry(recs);
+    return true;
+}
+export function installHealthBridge() {
+    if (installed)
+        return;
+    installed = true;
+    // ── 1. Shell-self errors ───────────────────────────────────────────────────
+    window.addEventListener('error', (ev) => {
+        // Resource-load errors (img/script) surface as Event w/o .message; skip the
+        // favicon-class noise but keep script errors.
+        const msg = ev.message || (ev.error instanceof Error ? ev.error.message : '');
+        if (!msg)
+            return;
+        pushHealth({
+            level: 'error',
+            source: 'shell',
+            code: 'window-error',
+            message: ev.filename ? `${msg}  (${ev.filename}:${ev.lineno})` : msg,
+        });
+    });
+    window.addEventListener('unhandledrejection', (ev) => {
+        const reason = ev.reason;
+        const msg = reason instanceof Error ? (reason.stack?.split('\n')[0] ?? reason.message) : String(reason);
+        pushHealth({ level: 'error', source: 'shell', code: 'unhandled-rejection', message: `unhandled rejection: ${msg}` });
+    });
+    // Wrap console.* so shell-side logs are captured. ALL levels feed the full-fidelity
+    // browserConsole ring buffer (read by console.read{source:'browser'}); error/warn
+    // ALSO feed the health store (status bar) as before. Original behaviour preserved.
+    // JSON.stringify escapes real newlines (e.g. React's `componentStack`) into
+    // the two literal chars "\n" — which the INFO panel's pre-wrap can't fold and
+    // shows verbatim. Un-escape them back to real line breaks so multi-line object
+    // args (stacks, etc.) render as wrapped lines instead of backslash-n text.
+    const fmtArgs = (args) => args.map((a) => (a instanceof Error ? a.message : typeof a === 'string' ? a : (() => { try {
+        return JSON.stringify(a)?.replace(/\\n/g, '\n') ?? String(a);
+    }
+    catch {
+        return String(a);
+    } })())).join(' ');
+    const wrapConsole = (level, orig, toHealth) => (...args) => {
+        orig(...args);
+        try {
+            const text = fmtArgs(args);
+            if (text.startsWith('[health]'))
+                return; // skip this bridge's own pushHealth→console (avoid loops)
+            recordBrowserConsole(level, text);
+            if (toHealth)
+                pushHealth({ level: toHealth, source: 'shell', code: `console-${level}`, message: text });
+        }
+        catch { /* never let logging throw */ }
+    };
+    // error/warn → health feed (status bar) + browser buffer; log/info/debug → buffer only
+    // (keep the status bar's signal from drowning in info/log noise).
+    console.error = wrapConsole('error', console.error.bind(console), 'error');
+    console.warn = wrapConsole('warn', console.warn.bind(console), 'warn');
+    console.log = wrapConsole('log', console.log.bind(console), null);
+    console.info = wrapConsole('info', console.info.bind(console), null);
+    console.debug = wrapConsole('debug', console.debug.bind(console), null);
+    // ── 2 + 3. iframe-forwarded messages ───────────────────────────────────────
+    const onMessage = (ev) => {
+        if (!isTrustedMessageOrigin(ev.origin))
+            return; // foreign-origin guard
+        const data = ev.data;
+        const type = data?.type;
+        if (typeof type !== 'string')
+            return;
+        // New explicit health envelope (preferred path from the runtimes).
+        if (type === 'forgeax:health') {
+            const d = data;
+            const message = typeof d.message === 'string' ? d.message : '';
+            if (!message)
+                return;
+            pushHealth({
+                level: asLevel(d.level),
+                // Trust the runtime's self-declared source; fall back to URL inference.
+                source: d.source ? asSource(d.source) : sourceFromEvent(ev),
+                code: typeof d.code === 'string' ? d.code : undefined,
+                message,
+            });
+            return;
+        }
+        // Legacy VAG wire fallback — only used for sources that DON'T yet ship the
+        // `forgeax:health` envelope (e.g. plugin iframes). The play iframe (PlaySurface)
+        // and the in-process edit viewport forward their own forgeax:health, so mapping
+        // VAG_CONSOLE for them would double-log; skip those, keep plugin/unknown frames.
+        if (type === 'VAG_CONSOLE') {
+            const payload = data?.payload;
+            const text = typeof payload?.text === 'string' ? payload.text : '';
+            if (!text)
+                return;
+            // Console panel: the FULL stream (all levels, all sources). Play/Edit
+            // surfaces re-forward their nested engine iframe's VAG_CONSOLE up to here,
+            // so this is the single point that feeds store.consoleLog.
+            useShellStore.getState().pushConsole({
+                level: asConsoleLevel(payload?.level),
+                text,
+                ts: typeof payload?.ts === 'number' ? payload.ts : Date.now(),
+            });
+            // Health feed: only error/warn, and only from plugin/unknown frames —
+            // play/edit forward their own forgeax:health for errors (avoid double-log).
+            const src = sourceFromEvent(ev);
+            if (src !== 'play' && src !== 'edit') {
+                const lvl = consoleLevelToHealth(String(payload?.level));
+                if (lvl)
+                    pushHealth({ level: lvl, source: src, code: 'vag-console', message: text });
+            }
+            return;
+        }
+        // Network panel feed — Play/Edit surfaces re-forward their engine iframe's
+        // VAG_NETWORK up to here (the single point that feeds store.networkLog).
+        if (type === 'VAG_NETWORK') {
+            const p = data?.payload;
+            if (!p || typeof p.url !== 'string')
+                return;
+            useShellStore.getState().pushNetwork({
+                kind: ['fetch', 'xhr', 'ws'].includes(p.kind) ? p.kind : 'fetch',
+                method: typeof p.method === 'string' ? p.method : 'GET',
+                url: p.url,
+                status: typeof p.status === 'number' ? p.status : 0,
+                ms: typeof p.ms === 'number' ? p.ms : 0,
+                ok: Boolean(p.ok),
+                ts: typeof p.ts === 'number' ? p.ts : Date.now(),
+            });
+            return;
+        }
+        // Telemetry (trace+log) postMessage信道 — iframe-produced spans/logs forwarded
+        // up to the shell (same VAG family as VAG_CONSOLE/VAG_NETWORK). Feeds the SAME
+        // store.telemetry slice as the node-side `{type:'telemetry'}` WS path, so one
+        // viewer sees both. Records carry their own `kind` discriminator.
+        if (ingestVagTelemetry(data))
+            return;
+    };
+    void installWindowMessageObservation({ target: window, onMessage });
+}

package/dist/package/node/components/StatusBar/healthStore.js

@@ -0,0 +1,129 @@
+/**
+ * Health / INFO store — Blender-style status feed for the studio shell.
+ *
+ * Why this exists: the engine runs inside cross-origin iframes (Play :15173 /
+ * Edit :15280) and plugin panels. When a scene fails to instantiate, the GPU
+ * device is lost, a module is missing, or WebGPU init fails, the only signal
+ * today lands in the *iframe's* DevTools console — which the shell can't read
+ * and the user never sees (they stare at a black / empty viewport and guess).
+ *
+ * This module is the single sink for every health signal in the shell:
+ *   - the shell's own window.onerror / unhandledrejection / console.error
+ *   - iframe-forwarded `forgeax:health` postMessages (play / edit / plugin)
+ *   - the existing VAG_CONSOLE / VAG_DEVICE_LOST wire (bridged in)
+ *
+ * It is a tiny standalone zustand store (not folded into the 3k-line app
+ * store.ts) so the status bar stays decoupled and cheap. The shell shows a
+ * scrolling severity-tagged log + a fatal banner per Play/Edit region.
+ */
+import { create } from 'zustand';
+import { recordLog } from '../../lib/logSink.js';
+/**
+ * Codes we treat as FATAL for a region — they black/empty the viewport and
+ * the user needs an explicit "what broke + retry" affordance, not just a log
+ * line. Matched against entry.code OR substring-matched against the message
+ * text (the engine's existing console output is plain text, not coded).
+ */
+export const FATAL_CODES = new Set([
+    'device-lost',
+    'context-lost',
+    'scene-instantiate-failed',
+    'webgpu-init-failed',
+    'module-missing',
+    'load-timeout',
+    'createApp-failed',
+]);
+/** Heuristic text patterns that mark a console error as a fatal region failure. */
+const FATAL_TEXT_PATTERNS = [
+    /scene\s+instantiate\s+failed/i,
+    /device\s*lost/i,
+    /context\s*lost/i,
+    /createApp\s+failed/i,
+    /engine\s+init\s+failed/i,
+    /no\s+usable\s+backend/i,
+    /webgpu\s+(adapter|unavailable|requires)/i,
+    /failed\s+to\s+resolve\s+(import|module)/i,
+    /does\s+not\s+provide\s+an\s+export/i,
+    /loadByGuid.*fail/i,
+];
+const MAX_ENTRIES = 400;
+let _seq = 1;
+function isFatal(level, code, message) {
+    if (level !== 'error')
+        return false;
+    if (code && FATAL_CODES.has(code))
+        return true;
+    return FATAL_TEXT_PATTERNS.some((re) => re.test(message));
+}
+export const useHealthStore = create((set) => ({
+    entries: [],
+    collapsed: true,
+    fatal: { play: null, edit: null, plugin: null, shell: null, engine: null },
+    push: (e) => set((s) => {
+        const entry = {
+            id: _seq++,
+            ts: e.ts ?? Date.now(),
+            level: e.level,
+            source: e.source,
+            code: e.code,
+            message: e.message,
+        };
+        recordLog('info', entry); // mirror to disk (.forgeax/logs/info.jsonl)
+        const next = s.entries.length >= MAX_ENTRIES
+            ? [...s.entries.slice(s.entries.length - (MAX_ENTRIES - 1)), entry]
+            : [...s.entries, entry];
+        // Promote fatal region failures into the banner channel.
+        if (isFatal(entry.level, entry.code, entry.message)) {
+            return {
+                entries: next,
+                fatal: {
+                    ...s.fatal,
+                    [entry.source]: {
+                        level: entry.level,
+                        code: entry.code,
+                        message: entry.message,
+                        ts: entry.ts,
+                    },
+                },
+            };
+        }
+        return { entries: next };
+    }),
+    clear: () => set({ entries: [] }),
+    toggleCollapsed: () => set((s) => ({ collapsed: !s.collapsed })),
+    setCollapsed: (v) => set({ collapsed: v }),
+    clearFatal: (source) => set((s) => ({ fatal: { ...s.fatal, [source]: null } })),
+}));
+/** Imperative push for non-React call sites (boot hooks, message listeners). */
+export function pushHealth(e) {
+    useHealthStore.getState().push(e);
+}
+/**
+ * Fold consecutive identical entries (same source + same message; ts ignored)
+ * into one CollapsedEntry carrying a count. Non-consecutive repeats are NOT
+ * merged (Blender behaviour) — only a contiguous flood collapses, so a
+ * PickError firing 14 frames in a row shows as a single `×14` row.
+ */
+export function collapseEntries(entries) {
+    const out = [];
+    for (const e of entries) {
+        const prev = out[out.length - 1];
+        if (prev && prev.entry.source === e.source && prev.entry.message === e.message) {
+            prev.count += 1;
+            prev.entry = e; // keep latest ts/id for "last seen"
+        }
+        else {
+            out.push({ entry: e, count: 1, key: e.id });
+        }
+    }
+    return out;
+}
+/** Full, copy-friendly one-line text for an entry (source · time · message). */
+export function entryToText(e, count = 1) {
+    const d = new Date(e.ts);
+    const p = (n) => String(n).padStart(2, '0');
+    const time = `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+    const tag = `[${e.level.toUpperCase()}] ${e.source}${e.code ? `/${e.code}` : ''}`;
+    const rep = count > 1 ? ` (×${count})` : '';
+    return `${time} ${tag}${rep}: ${e.message}`;
+}

package/dist/package/node/components/StatusBar/useStatusItem.js

@@ -0,0 +1,35 @@
+// packages/interface/src/components/StatusBar/useStatusItem.ts
+//
+// ADR-0030 §2.2 — the ergonomic successor to the retired `useStatusBarItem`.
+// Same human feel ("drop a chip onto the footer from any component, live data
+// flows, auto-cleanup on unmount") but WITHOUT a parallel module store: it
+// writes through host.contributeStatusItem → the single panels contribution
+// registry. So it is owner-neutral yet reversible, and cross-realm-consistent.
+//
+// Live data: the render closure is read through a ref, so the chip always
+// reflects the owner's latest state WITHOUT re-registering on every render
+// (the old store re-`upsert`ed each render — this contributes once per id and
+// lets the rendered node re-render itself).
+import { useEffect, useRef } from 'react';
+import { useHost } from '../../core/app-shell/index.js';
+/** Register a live status-bar chip for this component's lifetime. */
+export function useStatusItem(id, location, render, opts) {
+    const host = useHost();
+    const renderRef = useRef(render);
+    renderRef.current = render;
+    const whenRef = useRef(opts?.when);
+    whenRef.current = opts?.when;
+    const priority = opts?.priority;
+    useEffect(() => {
+        const off = host.contributeStatusItem({
+            kind: 'status-item',
+            id,
+            location,
+            priority,
+            when: () => (whenRef.current ? whenRef.current() : true),
+            item: { type: 'custom', render: () => renderRef.current() },
+        });
+        // Cleanup allows void|Promise<void>; useEffect's Destructor does not — wrap.
+        return () => { void off(); };
+    }, [host, id, location, priority]);
+}

package/dist/package/node/components/Surfaces/SurfaceKeepAliveLayer.js

@@ -0,0 +1,218 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// SurfaceKeepAliveLayer — always-mounted owner of the Viewport surface.
+//
+// THE FIX for the Viewport↔AI freeze. Viewport / AI are separate dockview
+// *workspaces*; switching tabs rebuilds the dock tree, which previously destroyed +
+// cold-rebooted the heavy viewport on EVERY switch (full WebGPU init + the
+// editor's top-level-await boot → intermittent WKWebView wedge = the freeze).
+//
+// 2026-06-30: 'preview'/'edit' merged into single 'viewport'. Only the edit
+// surface is kept alive across workspace switches. The play-runtime (/preview)
+// is now a standalone fullscreen-only entry point (AC-14).
+//
+// React mounts this layer through a portal on `document.body` (see return) so
+// keep-alive surfaces escape the studio shell's fixed containing block. It still
+// conceptually tracks DockShell anchors from App.tsx and never unmounts. On a switch
+// we only:
+//   - position the ACTIVE surface over its dockview anchor's rect, visible;
+//   - park the others off-screen + visibility:hidden, which trips the in-process
+//     viewport's OWN IntersectionObserver (installVisibilityPause in edit-runtime)
+//     → editorApp.pause() in the background (context preserved).
+// Switching back is a one-frame composite: zero reload, zero boot, FPS resumes.
+//
+// Single realm: the edit surface is an in-process React component (ViewportComponent),
+// not an iframe. Stays editor-agnostic: the real surface comes from PanelRenderers
+// context (studio injects @forgeax/editor's SceneEditor); interface keeps ZERO
+// editor imports.
+import { useEffect, useReducer, useRef } from 'react';
+import { createPortal } from 'react-dom';
+import { createCoalescedFrameTaskLifecycle, createRestartableTimeoutTaskLifecycle, installElementResizeObservation, installViewportResizeObservation, installViewportScrollObservation, SurfacePlaceholder, SurfaceRegion, } from '@forgeax/app-shell/react';
+import { useHost } from '../../core/app-shell/index.js';
+import { usePanelRenderers } from '../DockShell/panelRenderers.js';
+import { FatalBanner } from '../StatusBar/FatalBanner.js';
+import { useFloatingSurfaces } from '../../lib/platform/index.js';
+import { mapViewportRectToOverlayRoot } from '../../lib/surfaceKeepAliveLayout.js';
+import { getAnchor, subscribeAnchors, subscribeRelayout, } from '../../lib/surfaceAnchors.js';
+
+// AppMode = shell workspace mode. The engine's edit-time surface kind is still
+// 'edit' (see SurfaceKind in ../../lib/surfaceAnchors); the page-id / mode-id
+// 'edit' was renamed to 'scene' by the v9 page-schema migration.
+const ALL_KINDS = ['edit'];
+// The keep-alive surface lives in a fixed overlay OUTSIDE dockview's DOM tree, so
+// clicking it never reaches dockview's group-focus machinery (doSetGroupActive via
+// tab pointerdown / content onDidFocus). Result: the previously-focused panel group
+// keeps its `dv-active-group` focus accent (the lime bar) even after you click into
+// the viewport. Map each surface kind back to its in-dock panel id so a pointerdown
+// on the surface can re-emit `panel:focus` and hand dock focus to the viewport.
+const PANEL_ID_FOR_KIND = {
+    edit: 'viewport',
+};
+export function SurfaceKeepAliveLayer() {
+    // Derived from the active workspace (SSOT); 'scene' workspace → edit surface,
+    // every other workspace → no kept-alive surface.
+    const host = useHost();
+    const { surfaces } = usePanelRenderers();
+    const SceneEditor = surfaces?.SceneEditor;
+    const floatingSurfaces = useFloatingSurfaces();
+    const viewportFloating = Boolean(floatingSurfaces['panel:viewport']);
+    const activeKind = viewportFloating ? null : 'edit';
+    // Visited set only grows — a surface, once mounted, is never torn down. Seeded
+    // with the boot mode's kind so the first surface mounts immediately; later kinds
+    // are added (and re-rendered) the first time their workspace becomes active.
+    const visitedRef = useRef(new Set(activeKind ? [activeKind] : []));
+    const [, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => {
+        if (activeKind && !visitedRef.current.has(activeKind)) {
+            visitedRef.current.add(activeKind);
+            bump();
+        }
+    }, [activeKind]);
+    // Portal overlay root + per-kind item DOM nodes — styled imperatively so dock
+    // resize/drag ticks don't churn React.
+    const rootRef = useRef(null);
+    const itemRefs = useRef(new Map());
+    // Imperative layout sync: overlay the active surface on its anchor's rect; hide
+    // the rest. Cheap enough to call on every resize/relayout tick.
+    const syncLayout = () => {
+        const overlayRoot = rootRef.current;
+        for (const kind of ALL_KINDS) {
+            const el = itemRefs.current.get(kind);
+            if (!el)
+                continue;
+            const anchor = kind === activeKind ? getAnchor(kind) : null;
+            if (!anchor) {
+                // Inactive, or active-but-no-anchor (page mode / panel closed / popped
+                // to an OS window). DO NOT use display:none — on WKWebView (the desktop
+                // Studio app) display:none on a WebGPU <canvas> DROPS the GPU device, so
+                // flipping back finds a dead context and the re-create wedges WKWebView's
+                // GPU process (the "switching back and forth freezes" Play↔Edit bug).
+                // Instead park the
+                // surface OFF-SCREEN + visibility:hidden: the GPU context stays alive, the
+                // surface is invisible + click-through, and being outside the viewport still
+                // trips the surface's IntersectionObserver so its render loop pauses (no
+                // double-render). Switch-back just moves it back onto the anchor — no
+                // context re-create, so no wedge. Keep a real (non-zero) size so the
+                // swap-chain stays valid while parked.
+                el.style.display = 'flex';
+                el.style.visibility = 'hidden';
+                el.style.pointerEvents = 'none';
+                el.style.top = '0px';
+                el.style.left = '-100000px';
+                if (!el.style.width || el.style.width === '0px')
+                    el.style.width = '1280px';
+                if (!el.style.height || el.style.height === '0px')
+                    el.style.height = '720px';
+                continue;
+            }
+            const mapped = mapViewportRectToOverlayRoot(anchor.getBoundingClientRect(), overlayRoot);
+            el.style.display = 'flex';
+            el.style.visibility = 'visible';
+            el.style.pointerEvents = '';
+            el.style.top = `${mapped.top}px`;
+            el.style.left = `${mapped.left}px`;
+            el.style.width = `${mapped.width}px`;
+            el.style.height = `${mapped.height}px`;
+        }
+    };
+    // Re-sync on: active-kind change (mode), anchor add/remove, dock relayout ping,
+    // window resize/scroll, and ResizeObserver of whichever anchors currently exist.
+    useEffect(() => {
+        syncLayout();
+        const layoutFrameTask = createCoalescedFrameTaskLifecycle({
+            task: syncLayout,
+        });
+        const scheduleSync = layoutFrameTask.schedule;
+        // macOS Chrome throttles rAF during live window drag, so a single rAF after
+        // `resize` often runs before dockview finishes its final reflow — the overlay
+        // gets sized to a stale (smaller) anchor rect and the dock's near-black
+        // --dv-background-color bleeds through on the right/bottom. Schedule a short
+        // settle burst after each resize so the final reflow is caught.
+        const SETTLE_TICKS = 4;
+        const SETTLE_STEP_MS = 60;
+        const settleTimers = Array.from({ length: SETTLE_TICKS }, (_, index) => createRestartableTimeoutTaskLifecycle({
+            task: scheduleSync,
+            delayMs: (index + 1) * SETTLE_STEP_MS,
+        }));
+        const cancelSettle = () => {
+            for (const timer of settleTimers)
+                timer.cancel();
+        };
+        const onWin = () => {
+            scheduleSync();
+            cancelSettle();
+            for (const timer of settleTimers)
+                timer.schedule();
+        };
+        const disposeWindowResizeObservation = installViewportResizeObservation({
+            target: window,
+            onResize: onWin,
+        });
+        const disposeViewportScrollObservation = installViewportScrollObservation({
+            target: window,
+            onScroll: onWin,
+        });
+        const visualViewport = window.visualViewport;
+        const disposeVisualViewportResizeObservation = visualViewport
+            ? installViewportResizeObservation({
+                target: visualViewport,
+                onResize: onWin,
+            })
+            : () => { };
+        const disposeAnchorResizeObservation = installElementResizeObservation({
+            getElements: () => ALL_KINDS.map(getAnchor).filter((anchor) => anchor !== null),
+            subscribeElements: subscribeAnchors,
+            onResize: scheduleSync,
+            onElementsChanged: syncLayout,
+        });
+        const offRelayout = subscribeRelayout(scheduleSync);
+        // A short rAF burst right after a switch catches the dockview rebuild settling
+        // (anchor mounts a frame or two after the workspace flips) without a permanent
+        // loop. Each tick is a single getBoundingClientRect — negligible.
+        let frames = 0;
+        const burstFrameTask = createCoalescedFrameTaskLifecycle({
+            task: () => {
+                syncLayout();
+                if (++frames < 30)
+                    burstFrameTask.schedule();
+            },
+        });
+        burstFrameTask.schedule();
+        return () => {
+            disposeWindowResizeObservation();
+            disposeViewportScrollObservation();
+            disposeVisualViewportResizeObservation();
+            for (const timer of settleTimers)
+                timer.dispose();
+            disposeAnchorResizeObservation();
+            offRelayout();
+            layoutFrameTask.dispose();
+            burstFrameTask.dispose();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [activeKind]);
+    const renderSurface = (kind) => {
+        // Single-kind surface today ('edit'); the preview/edit merge (2026-06-30)
+        // collapsed both into one viewport. Kept the kind-switch so future modes
+        // (play, debug) can add sibling branches without restructuring.
+        if (kind !== 'edit')
+            return _jsx(NoEditor, { kind: kind });
+        return SceneEditor ? (_jsx("div", { "data-fx-slot": "SceneEditor", style: { display: 'contents' }, children: _jsx(SceneEditor, {}) })) : (_jsx(NoEditor, { kind: "edit" }));
+    };
+    const layer = (_jsx("div", { ref: rootRef, className: "fx-surface-keepalive-root", "aria-hidden": activeKind ? undefined : true, children: [...visitedRef.current].map((kind) => (
+        // Stable key + stable parent → the in-process surface is reconciled in
+        // place across every render: never remounted, never reloaded.
+        _jsx(SurfaceRegion, { ref: (el) => { itemRefs.current.set(kind, el); }, className: "fx-surface-keepalive-item", "data-surface-kind": kind, style: { display: 'none' }, overlay: _jsx(FatalBanner, { source: "edit" }), 
+            // Capture-phase so it fires before the surface's own handlers, and never
+            // preventDefault/stopPropagation — we only mirror the click as dock focus.
+            // Moves `dv-active-group` (the lime focus accent) onto the viewport group,
+            // clearing the stale highlight left on whatever tab was focused before.
+            onPointerDownCapture: () => {
+                const panelId = PANEL_ID_FOR_KIND[kind];
+                if (panelId)
+                    host.bus.emit('panel:focus', { id: panelId });
+            }, children: kind === 'edit' && viewportFloating ? null : renderSurface(kind) }, kind))) }));
+    return createPortal(layer, document.body);
+}
+function NoEditor({ kind }) {
+    return _jsx(SurfacePlaceholder, { title: "No editor configured", className: `surface-placeholder--${kind}` });
+}