@forgeax/interface 0.4.1

package/dist/package/browser/components/ErrorBoundary.js

@@ -0,0 +1,131 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component } from 'react';
+import { t } from '../i18n';
+import { reportError } from '../lib/aegis';
+/**
+ * RecoveryBoundary — a React error boundary with explicit recovery exits.
+ *
+ * A render throw anywhere in the subtree (a bad store selector, a plugin panel)
+ * used to leave the shell stuck on a dead error page forever — fatal in the
+ * Tauri desktop form, which has no address bar to reload from. This catches the
+ * throw and offers three exits:
+ *
+ *   - 重试      — clears the error and re-renders the SAME element tree. Cheapest
+ *                 recovery; works when the throw was a transient state glitch.
+ *   - 重载此区域 — bumps a key so the children subtree fully remounts (fresh
+ *                 component state), without reloading the whole window.
+ *   - 重新加载 Studio — window.location.reload(); last resort, and the ONLY exit
+ *                 a desktop (.app) user has since there's no browser chrome.
+ *
+ * This complements (does not overlap) the T2 iframe fatal banner: that one
+ * handles failures *inside* the cross-origin engine iframe (device-lost / scene
+ * instantiate); THIS one handles the shell's own React render crashing. The two
+ * are different documents — a React boundary cannot see an iframe throw, and the
+ * banner cannot see a shell render throw.
+ *
+ * Kept exported as both `RecoveryBoundary` (new name) and `ErrorBoundary`
+ * (back-compat alias) so existing call sites need no churn.
+ */
+export class RecoveryBoundary extends Component {
+    state = { error: null, info: null, remountKey: 0 };
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    componentDidCatch(error, info) {
+        this.setState({ error, info });
+        // React swallows render throws before they reach window.onerror, so Aegis'
+        // auto JS-error capture never sees them — report explicitly. No-op unless
+        // monitoring is configured + live.
+        reportError(error, info.componentStack, this.props.scope);
+        // Tear down the boot splash so the error is visible (it otherwise sits on
+        // top of this fallback). Lossy by contract — ignored if absent.
+        try {
+            window.__forgeaxBoot?.done();
+        }
+        catch {
+            /* no-op */
+        }
+        // eslint-disable-next-line no-console
+        console.error(`[RecoveryBoundary${this.props.scope ? ` · ${this.props.scope}` : ''}]`, error, info.componentStack);
+    }
+    /** 重试 — clear the error, re-render the same subtree (no remount). */
+    retry = () => {
+        this.setState({ error: null, info: null });
+    };
+    /** 重载此区域 — clear the error AND bump the remount key so the subtree
+     *  remounts with fresh component state. */
+    remountSubtree = () => {
+        this.setState((s) => ({ error: null, info: null, remountKey: s.remountKey + 1 }));
+    };
+    /** 重新加载 Studio — hard reload of the whole window. */
+    reloadWindow = () => {
+        try {
+            window.location.reload();
+        }
+        catch {
+            /* no-op */
+        }
+    };
+    render() {
+        const { error, info, remountKey } = this.state;
+        const { scope, fullscreen = true } = this.props;
+        if (!error) {
+            // `key` forces a remount of the entire subtree when remountSubtree() bumps it.
+            return _jsx(RemountScope, { children: this.props.children }, remountKey);
+        }
+        const btn = (label, onClick, primary = false) => (_jsx("button", { type: "button", onClick: onClick, style: {
+                font: '12px/1.4 ui-sans-serif, system-ui, sans-serif',
+                padding: '6px 14px',
+                borderRadius: 6,
+                cursor: 'pointer',
+                border: '1px solid var(--fx-border, #333)',
+                background: primary ? 'var(--fx-accent, #4f7cff)' : 'var(--fx-bg-elev2, #1d1d1d)',
+                color: primary ? '#fff' : 'var(--fx-fg, #eee)',
+            }, children: label }));
+        const exits = (_jsxs("div", { style: { display: 'flex', gap: 8, flexWrap: 'wrap', margin: '0 0 16px' }, children: [btn(t('errorBoundary.retry'), this.retry, true), btn(t('errorBoundary.reloadRegion'), this.remountSubtree), btn(t('errorBoundary.reloadStudio'), this.reloadWindow)] }));
+        if (!fullscreen) {
+            // Compact inline panel for region-scoped boundaries — keeps the rest of
+            // the shell alive; only this dock region shows the recovery affordance.
+            return (_jsxs("div", { role: "alert", style: {
+                    height: '100%',
+                    overflow: 'auto',
+                    padding: 16,
+                    background: 'var(--fx-bg, #0d0d0d)',
+                    color: 'var(--fx-fg, #fff)',
+                    font: '12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace',
+                }, children: [_jsxs("div", { style: { fontWeight: 600, color: 'var(--fx-danger, #f87171)', marginBottom: 6 }, children: [t('errorBoundary.panelRenderError'), scope ? ` · ${scope}` : ''] }), _jsx("p", { style: { margin: '0 0 12px', color: 'var(--fx-fg-muted, #aaa)' }, children: t('errorBoundary.panelHint') }), exits, _jsx("pre", { style: {
+                            whiteSpace: 'pre-wrap',
+                            wordBreak: 'break-word',
+                            padding: 12,
+                            borderRadius: 6,
+                            border: '1px solid var(--fx-border, #333)',
+                            background: 'var(--fx-bg-elev2, #161616)',
+                            color: 'var(--fx-danger, #f87171)',
+                        }, children: error.message })] }));
+        }
+        return (_jsxs("div", { role: "alert", style: {
+                position: 'fixed',
+                inset: 0,
+                zIndex: 'var(--z-toplevel)',
+                overflow: 'auto',
+                padding: '32px',
+                background: 'var(--fx-bg, #0d0d0d)',
+                color: 'var(--fx-fg, #fff)',
+                font: '13px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace',
+            }, children: [_jsxs("h1", { style: { margin: '0 0 8px', fontSize: 18, color: 'var(--fx-danger, #f87171)' }, children: [t('errorBoundary.fullscreenTitle'), scope ? ` · ${scope}` : ''] }), _jsx("p", { style: { margin: '0 0 16px', color: 'var(--fx-fg-muted, #aaa)' }, children: t('errorBoundary.fullscreenHint') }), exits, _jsxs("pre", { style: {
+                        whiteSpace: 'pre-wrap',
+                        wordBreak: 'break-word',
+                        padding: 16,
+                        borderRadius: 8,
+                        border: '1px solid var(--fx-border, #333)',
+                        background: 'var(--fx-bg-elev2, #161616)',
+                        color: 'var(--fx-danger, #f87171)',
+                    }, children: [error.message, '\n\n', error.stack, info?.componentStack ? `\n\n--- component stack ---${info.componentStack}` : ''] })] }));
+    }
+}
+/** Transparent wrapper whose only job is to carry the remount `key`. */
+function RemountScope({ children }) {
+    return children;
+}
+/** Back-compat alias — existing imports use `ErrorBoundary`. */
+export const ErrorBoundary = RecoveryBoundary;

package/dist/package/browser/components/ExtensionHost/ExtensionIframeHost.d.ts

@@ -0,0 +1,28 @@
+import { type ReactElement } from 'react';
+import { type EditorAssetImportSourceHandler } from '../DockShell/panelRenderers';
+export interface ExtensionIframeHostProps {
+    extensionId: string;
+    src: string;
+    allowedOrigin?: string;
+    pane?: 'left' | 'center';
+    active?: boolean;
+    onNavigate?: (targetPluginId: string, payload?: Record<string, unknown>) => void;
+    onChatPost?: (event: {
+        text: string;
+        attachments?: unknown[];
+    }) => void;
+    onEditorAssetImport?: EditorAssetImportSourceHandler;
+    onToolCall?: (call: {
+        toolId: string;
+        args?: unknown;
+    }) => Promise<{
+        ok: true;
+        result?: unknown;
+    } | {
+        ok: false;
+        error: string;
+        code?: string;
+    }>;
+    loadErrorText: (error: string) => string;
+}
+export declare function ExtensionIframeHost({ extensionId, src, allowedOrigin, pane, active, onNavigate, onChatPost, onEditorAssetImport, onToolCall, loadErrorText, }: ExtensionIframeHostProps): ReactElement;

package/dist/package/browser/components/ExtensionHost/ExtensionIframeHost.js

@@ -0,0 +1,179 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { installWindowMessageObservation } from '@forgeax/app-shell/react';
+import { getLocale, subscribeLocale } from '../../i18n';
+import { useHost } from '../../core/app-shell';
+import { requestComposerInsert } from '../../lib/composer-bridge';
+import { removeExtensionSurfaces, upsertSurface } from '../../lib/surface-store';
+import { usePanelRenderers, } from '../DockShell/panelRenderers';
+import { attachExtensionEditorAssetImportBridge } from '../DockShell/extension-editor-bridge';
+// The Content Browser lives in the global footer under this id (see
+// DockShell footer contribution registry (GLOBAL_FOOTER_EXTRA_IDS).
+const CONTENT_BROWSER_PANEL_ID = 'ep:assets';
+// Sanitize an untrusted iframe payload into the neutral reveal contract. A
+// target without an identity is dropped (the Content Browser would no-op).
+function revealTargetFromMessage(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const str = (v) => typeof v === 'string' && v.trim() ? v.trim() : undefined;
+    const path = str(r.path);
+    const guid = str(r.guid);
+    if (!path && !guid)
+        return null;
+    const packPath = str(r.packPath);
+    const assetKind = str(r.assetKind);
+    const name = str(r.name);
+    return {
+        ...(guid ? { guid } : {}),
+        ...(path ? { path, pathKind: r.pathKind === 'dir' ? 'dir' : 'file' } : {}),
+        ...(packPath ? { packPath } : {}),
+        ...(assetKind ? { assetKind } : {}),
+        ...(name ? { name } : {}),
+    };
+}
+export function ExtensionIframeHost({ extensionId, src, allowedOrigin, pane, active = true, onNavigate, onChatPost, onEditorAssetImport, onToolCall, loadErrorText, }) {
+    const { extensionTransport } = usePanelRenderers();
+    const host = useHost();
+    const createExtensionPort = extensionTransport?.createExtensionPort;
+    const createWindowTransport = extensionTransport?.createWindowTransport;
+    const iframeRef = useRef(null);
+    const [error, setError] = useState(null);
+    const portRef = useRef(null);
+    const activeRef = useRef(active);
+    const messageOrigin = allowedOrigin ?? new URL(src, window.location.href).origin;
+    useEffect(() => {
+        const iframe = iframeRef.current;
+        if (!iframe || !src)
+            return;
+        if (!createExtensionPort || !createWindowTransport)
+            return;
+        let port = null;
+        const onRawMessage = (ev) => {
+            if (ev.source !== iframe.contentWindow)
+                return;
+            if (ev.origin !== messageOrigin) {
+                return;
+            }
+            const d = ev.data;
+            if (!d)
+                return;
+            if (d.type === 'FORGEAX_NAVIGATE' && d.targetPluginId) {
+                onNavigate?.(d.targetPluginId, d.payload);
+                return;
+            }
+            // Plugin → host chat composer prefill (e.g. page-video-game「添加到对话」).
+            // Prefills the caret without auto-sending; the author reviews then sends.
+            if (d.type === 'FORGEAX_COMPOSER_INSERT' && typeof d.text === 'string' && d.text.trim()) {
+                const text = d.text.trim();
+                requestComposerInsert({
+                    kind: 'paste',
+                    display: text.length > 48 ? `${text.slice(0, 48)}…` : text,
+                    detail: text,
+                    tooltip: {
+                        title: text.length > 64 ? `${text.slice(0, 64)}…` : text,
+                        lines: [text.length > 200 ? `${text.slice(0, 200)}…` : text],
+                    },
+                });
+                return;
+            }
+            // Plugin → host "locate this file in the Content Browser". Mirrors the
+            // editor page tab's locate action: reveal the footer panel first (it may be
+            // a collapsed drawer), then hand the target to whichever Content Browser is
+            // mounted over the neutral bus. The double rAF gives a freshly-expanded
+            // drawer a frame to mount + subscribe before the target arrives.
+            if (d.type === 'FORGEAX_CONTENT_BROWSER_REVEAL') {
+                const target = revealTargetFromMessage(d.target);
+                if (!target)
+                    return;
+                void host.commands
+                    .execute('app.panel.reveal', { id: CONTENT_BROWSER_PANEL_ID })
+                    .catch(() => { })
+                    .finally(() => {
+                    requestAnimationFrame(() => requestAnimationFrame(() => {
+                        host.bus.emit('content-browser:reveal', { target });
+                    }));
+                });
+                return;
+            }
+        };
+        const disposeWindowMessageObservation = installWindowMessageObservation({
+            onMessage: onRawMessage,
+        });
+        const detachEditorAssetImportBridge = attachExtensionEditorAssetImportBridge({
+            ownerWindow: window,
+            frameWindow: () => iframe.contentWindow,
+            importAssetSource: onEditorAssetImport,
+            isTrustedEvent: (event) => event.origin === messageOrigin,
+        });
+        const onLoad = () => {
+            const win = iframe.contentWindow;
+            if (!win) {
+                setError('iframe contentWindow unavailable');
+                return;
+            }
+            const transport = createWindowTransport({
+                target: win,
+                targetOrigin: messageOrigin,
+                expectedOrigin: messageOrigin,
+                expectedSource: () => iframe.contentWindow,
+            });
+            port = createExtensionPort({
+                extensionId,
+                transport,
+                initial: {
+                    locale: getLocale(),
+                    theme: 'dark',
+                    pane: pane ?? 'center',
+                },
+                onInvalid: (_, reason) => {
+                    if (import.meta.env.DEV) {
+                        // eslint-disable-next-line no-console
+                        console.warn('[ExtensionIframeHost] invalid envelope:', reason);
+                    }
+                },
+            });
+            if (onChatPost)
+                port.onChat(onChatPost);
+            if (onToolCall)
+                port.onToolCall(onToolCall);
+            port.surface.subscribe((s) => {
+                upsertSurface({
+                    extensionId,
+                    surfaceId: s.surfaceId,
+                    actions: s.actions,
+                    snapshot: s.snapshot,
+                    updatedAt: Date.now(),
+                });
+            });
+            if (onNavigate)
+                port.onNavigate((e) => onNavigate(e.targetPluginId, e.payload));
+            portRef.current = port;
+            port.setVisibility(activeRef.current);
+        };
+        iframe.addEventListener('load', onLoad);
+        return () => {
+            iframe.removeEventListener('load', onLoad);
+            disposeWindowMessageObservation();
+            detachEditorAssetImportBridge();
+            port?.close();
+            portRef.current = null;
+            removeExtensionSurfaces(extensionId);
+        };
+    }, [extensionId, src, messageOrigin, pane, createExtensionPort, createWindowTransport, onNavigate, onChatPost, onToolCall, onEditorAssetImport, host]);
+    useEffect(() => {
+        activeRef.current = active;
+        portRef.current?.setVisibility(active);
+    }, [active]);
+    // Host locale → keep-alive plugin iframes (SDK theme.changed + legacy postMessage).
+    useEffect(() => {
+        return subscribeLocale((loc) => {
+            portRef.current?.setTheme({ locale: loc });
+            const win = iframeRef.current?.contentWindow;
+            if (win) {
+                win.postMessage({ type: 'forgeax:locale-changed', locale: loc }, messageOrigin);
+            }
+        });
+    }, [messageOrigin]);
+    return (_jsxs("div", { className: "page-plugin-iframe-wrap", "data-active": active ? 'true' : 'false', style: active ? undefined : { visibility: 'hidden', pointerEvents: 'none' }, "aria-hidden": active ? undefined : true, children: [error ? _jsx("div", { style: { padding: 20, color: '#c44' }, children: loadErrorText(error) }) : null, _jsx("iframe", { ref: iframeRef, src: src, title: extensionId, style: { width: '100%', height: '100%', border: 0, display: 'block' }, sandbox: "allow-scripts allow-same-origin allow-forms allow-popups allow-modals allow-downloads" })] }));
+}

package/dist/package/browser/components/ExtensionHost/NativeExtensionHost.d.ts

@@ -0,0 +1,14 @@
+import { type ReactElement } from 'react';
+interface Props {
+    extensionId: string;
+    moduleUrl: string;
+    allowedOrigin?: string;
+    generation: number;
+    active?: boolean;
+    onChatPost?: (event: {
+        text: string;
+        attachments?: unknown[];
+    }) => void;
+}
+export declare function NativeExtensionHost({ extensionId, moduleUrl, allowedOrigin, generation, active, onChatPost, }: Props): ReactElement;
+export {};

package/dist/package/browser/components/ExtensionHost/NativeExtensionHost.js

@@ -0,0 +1,152 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { getLocale, subscribeLocale } from '../../i18n';
+import { removeExtensionSurfaces, upsertSurface } from '../../lib/surface-store';
+function moduleSpecifier(moduleUrl, generation) {
+    const url = new URL(moduleUrl, window.location.href);
+    url.searchParams.set('fxg', String(generation));
+    return url.href;
+}
+export function NativeExtensionHost({ extensionId, moduleUrl, allowedOrigin, generation, active = true, onChatPost, }) {
+    const containerRef = useRef(null);
+    const activeRef = useRef(active);
+    const visibilitySubscribers = useRef(new Set());
+    const themeSubscribers = useRef(new Set());
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        activeRef.current = active;
+        for (const subscriber of visibilitySubscribers.current)
+            subscriber({ visible: active });
+    }, [active]);
+    useEffect(() => subscribeLocale((locale) => {
+        for (const subscriber of themeSubscribers.current)
+            subscriber({ locale, theme: 'dark' });
+    }), []);
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        let disposed = false;
+        const effects = [];
+        let view;
+        let viewRoot = container;
+        let closed = false;
+        const disposeEffects = async () => {
+            closed = true;
+            const errors = [];
+            while (effects.length) {
+                try {
+                    await effects.pop()?.();
+                }
+                catch (cause) {
+                    errors.push(cause);
+                }
+            }
+            view?.dispose();
+            view = undefined;
+            viewRoot = container;
+            removeExtensionSurfaces(extensionId);
+            visibilitySubscribers.current.clear();
+            themeSubscribers.current.clear();
+            if (errors.length)
+                console.error('[NativeExtensionHost] cleanup failed', new AggregateError(errors));
+        };
+        const activate = async () => {
+            try {
+                const expectedOrigin = allowedOrigin ?? window.location.origin;
+                const parsedModuleUrl = new URL(moduleUrl, window.location.href);
+                if (parsedModuleUrl.origin !== expectedOrigin || new URL(expectedOrigin).origin !== expectedOrigin) {
+                    throw new Error('moduleUrl does not match the registered allowedOrigin');
+                }
+                const loaded = await import(/* @vite-ignore */ moduleSpecifier(moduleUrl, generation));
+                if (disposed)
+                    return;
+                if (!loaded.extension || typeof loaded.extension.apply !== 'function') {
+                    throw new Error('extension module does not export extension.apply');
+                }
+                if (typeof loaded.createView !== 'function') {
+                    throw new Error('extension artifact does not provide its standard view renderer');
+                }
+                view = loaded.createView(container);
+                viewRoot = view.root ?? container;
+                const dispatchSubscribers = new Set();
+                const flashSubscribers = new Set();
+                const host = {
+                    async handshake() { return { protocol: 1, mode: 'platform', extensionId }; },
+                    chat: { post: (text, attachments) => onChatPost?.({ text, attachments: attachments ? [...attachments] : undefined }) },
+                    surface: {
+                        expose(surfaceId, payload) {
+                            upsertSurface({
+                                extensionId,
+                                surfaceId,
+                                actions: payload.actions,
+                                snapshot: payload.snapshot,
+                                updatedAt: Date.now(),
+                            });
+                        },
+                        onDispatch(handler) { dispatchSubscribers.add(handler); return () => { dispatchSubscribers.delete(handler); }; },
+                    },
+                    theme: {
+                        subscribe(handler) {
+                            themeSubscribers.current.add(handler);
+                            handler({ locale: getLocale(), theme: 'dark' });
+                            return () => { themeSubscribers.current.delete(handler); };
+                        },
+                    },
+                    visibility: {
+                        subscribe(handler) {
+                            visibilitySubscribers.current.add(handler);
+                            handler({ visible: activeRef.current });
+                            return () => { visibilitySubscribers.current.delete(handler); };
+                        },
+                    },
+                    ui: {
+                        flashElement(target, durationMs = 1000) {
+                            const element = typeof target === 'string' ? viewRoot.querySelector(target) : target;
+                            element?.classList.add('forgeax-host-flash');
+                            if (element)
+                                setTimeout(() => element.classList.remove('forgeax-host-flash'), durationMs);
+                        },
+                        onFlash(handler) { flashSubscribers.add(handler); return () => { flashSubscribers.delete(handler); }; },
+                    },
+                    close() { closed = true; dispatchSubscribers.clear(); flashSubscribers.clear(); },
+                };
+                const services = new Map([['host', host], ['view', view]]);
+                const missing = loaded.extension.inject?.filter((name) => !services.has(name)) ?? [];
+                if (missing.length)
+                    throw new Error(`extension requires unavailable services: ${missing.join(', ')}`);
+                const context = {
+                    effect(setup) {
+                        if (closed || disposed)
+                            throw new Error('cannot register an effect after deactivation');
+                        const cleanup = setup();
+                        if (cleanup)
+                            effects.push(cleanup);
+                    },
+                    get: (name) => services.get(name),
+                    logger: (name) => ({
+                        debug: (message, ...details) => console.debug(`[${extensionId}:${name}] ${message}`, ...details),
+                        info: (message, ...details) => console.info(`[${extensionId}:${name}] ${message}`, ...details),
+                        warn: (message, ...details) => console.warn(`[${extensionId}:${name}] ${message}`, ...details),
+                        error: (message, ...details) => console.error(`[${extensionId}:${name}] ${message}`, ...details),
+                    }),
+                };
+                await loaded.extension.apply(context, {});
+                if (disposed)
+                    await disposeEffects();
+            }
+            catch (cause) {
+                await disposeEffects();
+                if (!disposed)
+                    setError(cause instanceof Error ? cause.message : String(cause));
+            }
+        };
+        setError(null);
+        void activate();
+        return () => {
+            disposed = true;
+            void disposeEffects();
+        };
+    }, [allowedOrigin, extensionId, generation, moduleUrl, onChatPost]);
+    return (_jsxs("div", { className: "page-plugin-iframe-wrap", "data-active": active ? 'true' : 'false', children: [error ? _jsx("div", { role: "alert", style: { padding: 20, color: '#c44' }, children: error }) : null, _jsx("div", { ref: containerRef, style: { width: '100%', height: '100%' } })] }));
+}