@forgeax/interface 0.4.1

package/dist/package/browser/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';
+import { isTrustedMessageOrigin } from '../../lib/trustedOrigins';
+import { useShellStore } from '../../store';
+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/browser/components/StatusBar/healthStore.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+export type HealthLevel = 'info' | 'success' | 'warn' | 'error';
+export type HealthSource = 'play' | 'edit' | 'plugin' | 'shell' | 'engine';
+export interface HealthEntry {
+    id: number;
+    ts: number;
+    level: HealthLevel;
+    source: HealthSource;
+    /** Machine-readable code when known (e.g. 'device-lost', 'scene-instantiate-failed'). */
+    code?: string;
+    message: string;
+}
+/**
+ * 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 declare const FATAL_CODES: Set<string>;
+export interface FatalState {
+    level: HealthLevel;
+    code?: string;
+    message: string;
+    ts: number;
+}
+interface HealthStore {
+    entries: HealthEntry[];
+    collapsed: boolean;
+    /** Latest fatal per region, surfaced as a banner over Play / Edit. null = clear. */
+    fatal: Record<HealthSource, FatalState | null>;
+    push: (e: Omit<HealthEntry, 'id' | 'ts'> & {
+        ts?: number;
+    }) => void;
+    clear: () => void;
+    toggleCollapsed: () => void;
+    setCollapsed: (v: boolean) => void;
+    clearFatal: (source: HealthSource) => void;
+}
+export declare const useHealthStore: import("zustand").UseBoundStore<import("zustand").StoreApi<HealthStore>>;
+/** Imperative push for non-React call sites (boot hooks, message listeners). */
+export declare function pushHealth(e: Omit<HealthEntry, 'id' | 'ts'> & {
+    ts?: number;
+}): void;
+/** A run of consecutive identical entries (same source+message), folded to one
+ *  row with a repeat count — like Blender's INFO editor folds repeated ops. */
+export interface CollapsedEntry {
+    /** The most-recent entry in the run (we render its ts as "last seen"). */
+    entry: HealthEntry;
+    /** How many consecutive identical entries this row represents (>= 1). */
+    count: number;
+    /** Stable key for React — the id of the FIRST entry in the run. */
+    key: number;
+}
+/**
+ * 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 declare function collapseEntries(entries: HealthEntry[]): CollapsedEntry[];
+/** Full, copy-friendly one-line text for an entry (source · time · message). */
+export declare function entryToText(e: HealthEntry, count?: number): string;
+export {};

package/dist/package/browser/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';
+/**
+ * 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/browser/components/StatusBar/useStatusItem.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+import type { StripLocationId } from '../../core/panels';
+export interface UseStatusItemOptions {
+    /** Higher = anchored; lower = rotates in the carousel on overflow. Default 0. */
+    readonly priority?: number;
+    /** Conditional visibility, re-evaluated by StripHostView. */
+    readonly when?: () => boolean;
+}
+/** Register a live status-bar chip for this component's lifetime. */
+export declare function useStatusItem(id: string, location: StripLocationId, render: () => ReactNode, opts?: UseStatusItemOptions): void;

package/dist/package/browser/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';
+/** 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/browser/components/Surfaces/SurfaceKeepAlive.css

@@ -0,0 +1,34 @@
+/* Keep-alive surface layer — the Play/Edit viewports mounted once, kept alive,
+ * and overlaid on their dockview anchors. See SurfaceKeepAliveLayer.tsx. */
+
+/* The anchor placeholder inside the dockview preview/edit panels. It only reserves
+ * the cell; the live (fixed) surface is drawn on top of it by the keep-alive layer. */
+.surface-anchor {
+  flex: 1 1 auto;
+  min-height: 0;
+  width: 100%;
+  height: 100%;
+}
+
+/* Portal-mounted viewport overlay root: fixed to the layout viewport so children
+ * can use absolute coords derived from anchor getBoundingClientRect() without
+ * inheriting a shifted fixed containing block from the studio shell tree. */
+.fx-surface-keepalive-root {
+  position: fixed;
+  inset: 0;
+  width: auto;
+  height: auto;
+  pointer-events: none;
+  z-index: 40;
+}
+
+/* Each kept-alive surface. position:absolute inside the viewport overlay root.
+ * Inactive items are visibility:hidden (set inline) → their IntersectionObserver
+ * pauses the engine. z-index sits above in-flow dock content but below dock pop-out
+ * affordances (200), popovers (1000), detached-surface (9000), and modals/menus. */
+.fx-surface-keepalive-item {
+  position: absolute;
+  z-index: 1;
+  pointer-events: auto;
+  /* `display` (none/flex) + top/left/width/height are owned by syncLayout(). */
+}

package/dist/package/browser/components/Surfaces/SurfaceKeepAliveLayer.d.ts

@@ -0,0 +1,3 @@
+import { type ReactNode } from 'react';
+import './SurfaceKeepAlive.css';
+export declare function SurfaceKeepAliveLayer(): ReactNode;