@forgeax/interface 0.4.1

package/dist/package/node/components/DockShell/DockRegion.js

@@ -0,0 +1,315 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { RotateCcw } from 'lucide-react';
+import { DockviewReact, themeAbyss, } from 'dockview';
+
+import { AnchoredResizeHandle, DockLayoutMenu } from '@forgeax/app-shell/react';
+import { createDockLayoutControlState, createDockLayoutPersistence, createDockPanelCommands, createDockReadyActivation, createDockScopeTransition, hasMountedPanelPlacement, installDockLayoutObservation, installDockLayoutReset, installDockPanelCommandSubscriptions, installDockPanelVisibilityTracking, pruneSerializedDockLayout, } from '@forgeax/app-shell/dock';
+import { useTranslation, t as panelT } from '../../i18n/index.js';
+import { BASE_PANEL_COMPONENTS, BASE_PANEL_TITLE, BASE_PANEL_WINDOWING, buildEditorPanelComponents, CORE_PANEL_IDS, OPTIONAL_PANEL_IDS, } from './panelRegistry.js';
+import { usePanelRenderers } from './panelRenderers.js';
+import { DockTab } from './DockTab.js';
+import { iconForDockPanel } from '../../lib/panel-tab-icons.js';
+import { resolveRegion } from './resolveRegion.js';
+import { registerDockRegion, registerDockviewApi } from './dockviewRegistry.js';
+import { auxBarWidthStore, useAuxBarWidth } from './useAuxBarWidth.js';
+import { chatWidthStore, useChatWidth } from '../ChatColumn/useChatWidth.js';
+import { SessionTabStrip } from '../ChatColumn/SessionTabStrip.js';
+import { useHost } from '../../core/app-shell/index.js';
+import { pageLayoutStore, pageLayoutToDockview } from '../../core/page-platform/index.js';
+import { getCurrentProject } from '../../lib/project-context.js';
+import { pageRuntimeOwnsPanel } from './panelWindowing.js';
+import { withDockTitleRestore } from './dockTitle.js';
+import { installEdgeDrawer } from './edgeDrawer.js';
+import { FOOTER_PANEL_IDS } from './footer-panels.js';
+import { isFooterPanelId, isFooterPanelUserVisible, setFooterPanelUserVisible, subscribeFooterPanelVisibility, requestFooterPanelEnsure, } from './footer-panel-visibility.js';
+import { createPanelTabCommands } from './panelTabCommands.js';
+import { createStudioTabContextMenuHandler } from './studioTabMenuProvider.js';
+import { installUeDockDrag } from './ueDrag/controller.js';
+import { pingAnchorRelayout } from '../../lib/surfaceAnchors.js';
+
+const FORGEAX_DOCK_THEME = { ...themeAbyss, name: 'forgeax-abyss', gap: 6 };
+export function DockRegion({ region }) {
+    const host = useHost();
+    const renderers = usePanelRenderers();
+    const editorPanelIds = renderers.editorPanelIds;
+    const auxBarWidth = useAuxBarWidth();
+    const chatWidth = useChatWidth();
+    const pageSession = useSyncExternalStore(host.pages.subscribe, host.pages.getSnapshot, host.pages.getSnapshot);
+    const activePage = pageSession.instances.find((page) => page.encodedKey === pageSession.activeKey);
+    const resolvedPage = activePage ? host.pageRegistry.get(activePage.typeId) : undefined;
+    const pageScope = useMemo(() => {
+        if (region === 'ChatDock' || !activePage || !resolvedPage || resolvedPage.status !== 'available')
+            return null;
+        const layout = 'grid' in resolvedPage.layout
+            ? resolvedPage.layout
+            : pageLayoutToDockview(activePage.typeId, resolvedPage.definition.title, resolvedPage.panels, resolvedPage.layout);
+        return {
+            layoutId: activePage.typeId,
+            identity: { pageTypeId: activePage.typeId, layoutVersion: resolvedPage.definition.layoutVersion ?? 1 },
+            layout,
+            panelIds: resolvedPage.panels.map((panel) => panel.id),
+        };
+    }, [activePage, region, resolvedPage]);
+    const pagePanelIds = useMemo(() => new Set(pageScope?.panelIds ?? []), [pageScope]);
+    const panels = renderers.panels;
+    const isMember = useCallback((id) => {
+        if (id === 'chat')
+            return region === 'ChatDock';
+        if (region === 'ChatDock')
+            return false;
+        if (id.startsWith('ep:') && !editorPanelIds.includes(id.slice(3)))
+            return false;
+        if (pageScope && !pagePanelIds.has(id))
+            return false;
+        const descriptor = panels?.[id];
+        if (descriptor && !(descriptor.when?.() ?? true))
+            return false;
+        return resolveRegion(id, descriptor ?? {}, {}) === region;
+    }, [editorPanelIds, pagePanelIds, pageScope, panels, region]);
+    const isMemberRef = useRef(isMember);
+    useLayoutEffect(() => { isMemberRef.current = isMember; }, [isMember]);
+    const components = useMemo(() => ({
+        ...(resolvedPage?.status === 'available' && activePage
+            ? Object.fromEntries(resolvedPage.panels
+                .filter((placement) => pageRuntimeOwnsPanel(placement.id, new Set(Object.keys(BASE_PANEL_COMPONENTS)), editorPanelIds))
+                .map((placement) => [placement.id, withDockTitleRestore(() => (placement.panelType.runtime.kind === 'iframe'
+                    ? _jsx("iframe", { src: placement.panelType.runtime.src, title: placement.id, style: { width: '100%', height: '100%', border: 0 } })
+                    : placement.panelType.runtime.render({
+                        pageKey: activePage.key,
+                        placementId: placement.id,
+                        pageContext: activePage.context,
+                        initialProps: placement.initialProps,
+                    })))]))
+            : {}),
+        ...BASE_PANEL_COMPONENTS,
+        ...buildEditorPanelComponents(editorPanelIds),
+    }), [activePage, editorPanelIds, resolvedPage]);
+    const componentKeys = useMemo(() => new Set(Object.keys(components)), [components]);
+    const componentKeysRef = useRef(componentKeys);
+    useLayoutEffect(() => { componentKeysRef.current = componentKeys; }, [componentKeys]);
+    /** Stable signature — HMR refreshes panel render fns without changing registered ids. */
+    const componentKeysSignature = useMemo(() => [...componentKeys].sort().join('\0'), [componentKeys]);
+    const pageScopeKey = useMemo(() => {
+        if (!pageScope)
+            return '';
+        return `${pageScope.layoutId}:${pageScope.identity.layoutVersion}:${pageScope.panelIds.join(',')}`;
+    }, [pageScope]);
+    const readyActivation = useMemo(() => createDockReadyActivation(), []);
+    const layoutControl = useMemo(() => createDockLayoutControlState(), []);
+    const applyScopeRef = useRef(() => { });
+    const wrapRef = useRef(null);
+    const [chatMounted, setChatMounted] = useState(true);
+    const storageKey = useCallback((scope) => (`forgeax:project:${getCurrentProject()}:page-layout:${scope.layoutId}:${region}`), [region]);
+    const persistedScope = useCallback((scope) => ({
+        key: storageKey(scope),
+        identity: scope.identity,
+    }), [storageKey]);
+    const layoutPersistence = useMemo(() => createDockLayoutPersistence({
+        load: (key, identity) => pageLayoutStore.load(key, identity),
+        save: (key, identity, layout) => pageLayoutStore.save(key, identity, layout),
+        remove: (key) => pageLayoutStore.remove(key),
+    }), []);
+    const titleFor = useCallback((id) => {
+        const panelId = id.startsWith('ep:') ? id.slice(3) : id;
+        const key = `dockShell.panelTitles.${panelId}`;
+        const localized = panelT(key);
+        return localized !== key ? localized : panels?.[panelId]?.title ?? BASE_PANEL_TITLE[id] ?? id;
+    }, [panels]);
+    const windowingSources = useMemo(() => ({
+        basePanelIds: new Set(Object.keys(BASE_PANEL_COMPONENTS)),
+        baseWindowing: BASE_PANEL_WINDOWING,
+        pageWindowing: {},
+    }), []);
+    const panelTabCommands = useMemo(() => createPanelTabCommands({
+        getApi: () => readyActivation.getCurrent(),
+        titleFor,
+    }), [readyActivation, titleFor]);
+    const getTabContextMenuItems = useMemo(() => createStudioTabContextMenuHandler({
+        region,
+        getWrapEl: () => wrapRef.current,
+        getApi: () => readyActivation.getCurrent(),
+        commands: panelTabCommands,
+        windowingSources,
+    }), [panelTabCommands, region, windowingSources, readyActivation]);
+    const applyScope = useCallback((api, scope) => {
+        if (region === 'ChatDock') {
+            try {
+                api.clear();
+            }
+            catch { /* noop */ }
+            if (componentKeysRef.current.has('chat')) {
+                api.addPanel({ id: 'chat', component: 'chat', title: titleFor('chat') });
+            }
+            return;
+        }
+        if (!scope || region !== 'DockShell') {
+            try {
+                api.clear();
+            }
+            catch { /* noop */ }
+            return;
+        }
+        layoutPersistence.restore(persistedScope(scope), (saved) => {
+            const allowedPanelIds = new Set(scope.panelIds);
+            const candidate = saved ? pruneSerializedDockLayout(saved, componentKeysRef.current, allowedPanelIds) : null;
+            const defaultLayout = pruneSerializedDockLayout(scope.layout, componentKeysRef.current, allowedPanelIds);
+            if (!defaultLayout)
+                return;
+            try {
+                api.clear();
+            }
+            catch { /* noop */ }
+            try {
+                if (candidate) {
+                    api.fromJSON(candidate);
+                    if (hasMountedPanelPlacement(scope.panelIds, new Set(api.panels.map((panel) => panel.id))))
+                        return;
+                    try {
+                        api.clear();
+                    }
+                    catch { /* noop */ }
+                }
+                api.fromJSON(defaultLayout);
+            }
+            catch {
+                try {
+                    api.clear();
+                    api.fromJSON(defaultLayout);
+                }
+                catch { /* invalid contribution stays empty */ }
+            }
+            pingAnchorRelayout();
+        });
+    }, [layoutPersistence, persistedScope, region, titleFor]);
+    useLayoutEffect(() => { applyScopeRef.current = applyScope; }, [applyScope]);
+    const scopeTransition = useMemo(() => createDockScopeTransition({
+        getLive: () => readyActivation.getCurrent(),
+        save: (api, scope) => {
+            if (region === 'DockShell')
+                layoutPersistence.save(persistedScope(scope), api.toJSON());
+        },
+        apply: (api, scope) => applyScopeRef.current(api, scope),
+    }, pageScope), [layoutPersistence, persistedScope, readyActivation, region]);
+    const onReady = useCallback((event) => {
+        const api = event.api;
+        const wrap = wrapRef.current;
+        const activated = readyActivation.replace(api, [
+            () => registerDockviewApi(api),
+            ...(wrap ? [() => registerDockRegion({ viewId: api.id, region, api, wrapEl: wrap })] : []),
+            () => installDockPanelVisibilityTracking(api, {
+                onAdded: (id) => { if (region === 'ChatDock' && id === 'chat')
+                    setChatMounted(true); },
+                onRemoved: (id) => { if (region === 'ChatDock' && id === 'chat')
+                    setChatMounted(false); },
+            }),
+            () => installDockLayoutObservation(api, {
+                getCurrentScope: scopeTransition.getCurrent,
+                ...(region === 'DockShell' ? {
+                    captureAndSave: (scope) => (layoutPersistence.captureAndSave(persistedScope(scope), () => {
+                        const raw = api.toJSON();
+                        const pruned = pruneSerializedDockLayout(raw, componentKeysRef.current, new Set(scope.panelIds));
+                        return pruned ?? raw;
+                    })),
+                } : {}),
+                onCommitted: () => {
+                    layoutControl.refresh();
+                    pingAnchorRelayout();
+                },
+            }),
+            ...(region === 'DockShell' && wrap ? [
+                () => installEdgeDrawer(api, wrap),
+                () => installUeDockDrag(api, wrap, {
+                    region,
+                    moveTo: () => { },
+                    titleFor,
+                }),
+            ] : []),
+        ]);
+        if (activated)
+            scopeTransition.applyCurrent();
+    }, [layoutControl, layoutPersistence, persistedScope, readyActivation, region, scopeTransition, titleFor]);
+    useEffect(() => () => {
+        readyActivation.dispose();
+    }, [readyActivation]);
+    useEffect(() => {
+        scopeTransition.transition(pageScope);
+    }, [componentKeysSignature, pageScope, pageScopeKey, scopeTransition]);
+    const basePanelCommands = useMemo(() => createDockPanelCommands({
+        getPanel: (id) => readyActivation.getCurrent()?.getPanel(id)?.api,
+        addPanel: (options) => { readyActivation.getCurrent()?.addPanel(options); },
+        canOpen: (id) => Boolean(readyActivation.getCurrent() && isMemberRef.current(id) && componentKeysRef.current.has(id)),
+        titleFor,
+        authoredLayout: () => scopeTransition.getCurrent()?.layout,
+        fallbackPanelId: () => readyActivation.getCurrent()?.panels.find((panel) => panel.api.location.type === 'grid')?.id,
+    }), [readyActivation, scopeTransition, titleFor]);
+    const panelCommands = useMemo(() => ({
+        open(id) {
+            if (FOOTER_PANEL_IDS.has(id)) {
+                setFooterPanelUserVisible(id, true);
+                requestFooterPanelEnsure();
+                return basePanelCommands.focus(id) || Boolean(readyActivation.getCurrent()?.getPanel(id));
+            }
+            return basePanelCommands.open(id);
+        },
+        close(id) {
+            if (FOOTER_PANEL_IDS.has(id))
+                setFooterPanelUserVisible(id, false);
+            return basePanelCommands.close(id);
+        },
+        focus(id) {
+            return basePanelCommands.focus(id);
+        },
+        reveal(id) {
+            if (FOOTER_PANEL_IDS.has(id)) {
+                setFooterPanelUserVisible(id, true);
+                requestFooterPanelEnsure();
+                if (!readyActivation.getCurrent()?.getPanel(id))
+                    return true;
+                return basePanelCommands.reveal(id);
+            }
+            return basePanelCommands.reveal(id);
+        },
+    }), [basePanelCommands, readyActivation]);
+    const reopen = useCallback((id) => { panelCommands.open(id); }, [panelCommands]);
+    useEffect(() => installDockPanelCommandSubscriptions({
+        onOpen: (listener) => ({ dispose: host.bus.on('panel:open', ({ id }) => listener(id)) }),
+        onClose: (listener) => ({ dispose: host.bus.on('panel:close', ({ id }) => listener(id)) }),
+        onFocus: (listener) => ({ dispose: host.bus.on('panel:focus', ({ id }) => listener(id)) }),
+        onReveal: (listener) => ({ dispose: host.bus.on('panel:reveal', ({ id }) => listener(id)) }),
+    }, panelCommands), [host, panelCommands]);
+    useEffect(() => installDockLayoutReset({
+        onReset: (listener) => ({ dispose: host.bus.on('dock:reset', listener) }),
+    }, {
+        getCurrentScope: scopeTransition.getCurrent,
+        clear: (scope) => layoutPersistence.clear(persistedScope(scope)),
+        getLive: readyActivation.getCurrent,
+        apply: (api, scope) => applyScope(api, scope),
+    }), [applyScope, host, layoutPersistence, persistedScope, readyActivation, scopeTransition]);
+    const eligible = Object.keys(panels ?? {}).filter(isMember).length;
+    if (region !== 'DockShell' && region !== 'ChatDock' && eligible === 0)
+        return null;
+    const dockview = (_jsx(DockviewReact, { className: "fx-dockshell", theme: FORGEAX_DOCK_THEME, components: components, defaultTabComponent: DockTab, getTabContextMenuItems: getTabContextMenuItems, onReady: onReady, disableFloatingGroups: false, hideBorders: true }));
+    return (_jsxs("div", { className: `fx-dockwrap fx-dockregion fx-dockregion-${region}`, ref: wrapRef, "data-fx-slot": region, style: region === 'AuxBar' ? { width: auxBarWidth } : region === 'ChatDock' ? { width: chatWidth, ...(chatMounted ? {} : { display: 'none' }) } : undefined, children: [region === 'AuxBar' && (_jsx(AnchoredResizeHandle, { orientation: "col", className: "fx-auxbar-resizer", ariaLabel: "Resize auxiliary bar", readSize: auxBarWidthStore.getSnapshot, writeSize: auxBarWidthStore.setSize, resizingBodyClassName: "fx-auxbar-resizing" })), region === 'ChatDock' && (_jsx(AnchoredResizeHandle, { orientation: "col", className: "fx-chat-resizer", ariaLabel: "Resize chat panel", readSize: chatWidthStore.getSnapshot, writeSize: chatWidthStore.setSize, resizingBodyClassName: "fx-chat-resizing" })), region === 'ChatDock' ? (_jsxs("div", { className: "fx-chatdock-inner", style: { width: chatWidth }, children: [_jsx(SessionTabStrip, {}), dockview] })) : dockview, region === 'DockShell' && !pageScope && (_jsx("div", { className: "fx-page-empty", role: "status", children: _jsx("span", { children: panelT('dockShell.emptySurface') }) })), region === 'DockShell' && (_jsx(LayoutControl, { getApi: readyActivation.getCurrent, layoutControl: layoutControl, panels: (pageScope?.panelIds ?? []).map((id) => ({ id, title: titleFor(id) })), onReopen: reopen }))] }));
+}
+function LayoutControl({ getApi, layoutControl, panels, onReopen, }) {
+    const host = useHost();
+    const { t } = useTranslation();
+    const onToggle = useCallback((listener) => ({
+        dispose: host.bus.on('dock:layout-toggle', (payload) => listener(payload.rect)),
+    }), [host]);
+    useEffect(() => subscribeFooterPanelVisibility(() => layoutControl.refresh()), [layoutControl]);
+    const isPanelOpen = useCallback((panelId) => (isFooterPanelId(panelId)
+        ? isFooterPanelUserVisible(panelId)
+        : Boolean(getApi()?.getPanel(panelId))), [getApi]);
+    const closePanel = useCallback((panelId) => {
+        if (isFooterPanelId(panelId))
+            setFooterPanelUserVisible(panelId, false);
+        getApi()?.getPanel(panelId)?.api.close();
+    }, [getApi]);
+    return (_jsx(DockLayoutMenu, { state: layoutControl, onToggle: onToggle, isPanelOpen: isPanelOpen, closePanel: closePanel, reopenPanel: onReopen, onReset: () => { void host.commands.execute('app.dock.reset'); }, resetLabel: t('dockShell.resetLayout'), sectionLabel: t('dockShell.mainPanels'), emptyLabel: t('dockShell.emptySurface'), resetIcon: _jsx(RotateCcw, { size: 12 }), panels: panels.map((panel) => {
+            const Icon = iconForDockPanel(panel.id);
+            return { ...panel, icon: _jsx(Icon, { size: 13 }) };
+        }) }));
+}
+export const PAGE_DOCK_PANEL_IDS = [...CORE_PANEL_IDS, ...OPTIONAL_PANEL_IDS];

package/dist/package/node/components/DockShell/DockTab.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Custom dockview tab — the default tab with a leading Lucide panel icon.
+//
+// Wired as `<DockviewReact defaultTabComponent={DockTab} />`, so every dock tab
+// (static, ep:*, page-mode) gets an icon without touching per-panel registration.
+//
+// This is a faithful re-implementation of dockview's `DockviewDefaultTab`
+// (node_modules/dockview .../dockview/defaultTab.js): it forwards the pointer
+// handlers dockview injects for drag/activate and preserves the exact
+// `.dv-default-tab` / `.dv-default-tab-content` / `.dv-default-tab-action` DOM
+// hooks the stylesheets and `edgeDrawer.ts`'s click routing key off. The
+// additions are a leading `.fx-dock-tab-icon` (inside `.dv-default-tab`, so the
+// whole tab stays draggable/clickable), a Lucide `X` close glyph (design-system
+// on-brand, avoids a deep `dockview/.../svg` import), and a Lucide `Pin` that
+// takes the X's place on edge-strip tabs (see `useEdgePin` below).
+//
+// CLOSE BUTTON: React synthetic events and native mousedown/click are
+// unreliable here because calling preventDefault() on pointerdown (needed to
+// prevent tab activation) suppresses subsequent mousedown/click per the W3C
+// Pointer Events spec. The public App Shell interaction hook owns that native
+// pointerdown and the matching middle-button session; this file only injects
+// Dockview close policy and forwards Dockview's tab handlers.
+import { useCallback, useMemo, } from 'react';
+import { DockTabAction, DockTabFrame, DockTabIcon, DockTabStatusSummary, DockTabTitle, useLiveTabPlacement, useLiveTabTitle, useTabPinnedState, useTabCloseInteractions, } from '@forgeax/app-shell/react';
+import { Pin, X } from 'lucide-react';
+import { barePanelId, iconForDockPanel } from '../../lib/panel-tab-icons.js';
+import { EDGE_PIN_CLASS, edgePinStateSource } from './edgePinStore.js';
+import { useTranslation } from '../../i18n/index.js';
+import { useHealthStore } from '../StatusBar/healthStore.js';
+const EMPTY_HEALTH_ENTRIES = Object.freeze([]);
+/** Track the live tab title (dockview mutates it via `api.setTitle`). */
+function useTitle(api) {
+    const source = useMemo(() => ({
+        getTitle: () => api.title,
+        subscribe: (listener) => {
+            const disposable = api.onDidTitleChange(listener);
+            return () => disposable.dispose();
+        },
+    }), [api]);
+    return useLiveTabTitle(source);
+}
+/**
+ * The displayed tab name is DERIVED at render — never read from the persisted
+ * layout. Same shape as the icon (`iconForDockPanel(api.id)`): the panel id is
+ * the key, i18n is the lookup. `dockShell.panelTitles.<bareId>` wins and is
+ * locale-reactive (useTranslation re-renders on language change), so a stored
+ * `api.title` baked into the dockview layout JSON is ignored for keyed panels.
+ * Panels without a catalog key (host-injected editor/extension panels) fall
+ * back to the live `api.title` the host set at mount — their own name, as-is.
+ */
+function useDockTabName(api) {
+    const stored = useTitle(api);
+    const { t } = useTranslation();
+    const key = `dockShell.panelTitles.${barePanelId(api.id)}`;
+    const localized = t(key);
+    return localized !== key ? localized : stored;
+}
+function useInfoIssueCounts(panelId) {
+    const entries = useHealthStore((s) => (barePanelId(panelId) === 'info' ? s.entries : EMPTY_HEALTH_ENTRIES));
+    return useMemo(() => {
+        if (barePanelId(panelId) !== 'info')
+            return null;
+        let error = 0;
+        let warn = 0;
+        for (const entry of entries) {
+            if (entry.level === 'error')
+                error++;
+            else if (entry.level === 'warn')
+                warn++;
+        }
+        return { error, warn };
+    }, [entries, panelId]);
+}
+/**
+ * Edge-strip tabs show a per-tab Pin toggle where a grid tab shows close (X) —
+ * see edgeDrawer.ts for the rules. Both bits are DERIVED from live dockview
+ * state, so the first paint after a refresh is already correct:
+ * `onDidLocationChange` fires on any group change (dockviewPanelApi sets it from
+ * the `group` setter), which covers dragging a panel into or out of a strip.
+ */
+function useEdgePin(api) {
+    const source = useMemo(() => ({
+        getPlacement: () => ({
+            isEdge: api.location.type === 'edge',
+            groupId: api.group.id,
+        }),
+        subscribe: (listener) => {
+            const disposable = api.onDidLocationChange(listener);
+            return () => disposable.dispose();
+        },
+    }), [api]);
+    const home = useLiveTabPlacement(source) ?? {
+        isEdge: false,
+        groupId: api.group.id,
+    };
+    const pinned = useTabPinnedState(edgePinStateSource, home.groupId, api.id);
+    return { isEdge: home.isEdge, pinned };
+}
+export function DockTab({ api, containerApi: _containerApi, params: _params, hideClose, closeActionOverride, onPointerDown, onPointerUp, onPointerLeave, tabLocation: _tabLocation, ...rest }) {
+    const title = useDockTabName(api);
+    const infoIssueCounts = useInfoIssueCounts(api.id);
+    const Icon = iconForDockPanel(api.id);
+    const { isEdge, pinned } = useEdgePin(api);
+    const close = useCallback(() => {
+        if (closeActionOverride)
+            closeActionOverride();
+        else
+            api.close();
+    }, [api, closeActionOverride]);
+    const closeInteractions = useTabCloseInteractions({
+        close,
+        disabled: hideClose,
+        onPointerDown,
+        onPointerUp,
+        onPointerLeave,
+    });
+    const onBtnPointerDown = useCallback((event) => event.preventDefault(), []);
+    const infoStatusItems = infoIssueCounts === null
+        ? []
+        : [
+            ...(infoIssueCounts.error > 0
+                ? [{ id: 'errors', tone: 'error', icon: '✖', value: infoIssueCounts.error }]
+                : []),
+            ...(infoIssueCounts.warn > 0
+                ? [{ id: 'warnings', tone: 'warning', icon: '⚠', value: infoIssueCounts.warn }]
+                : []),
+        ];
+    const action = hideClose
+        ? undefined
+        : isEdge
+            ? (
+            // The toggle itself is driven by edgeDrawer's capture-phase click
+            // handler (it must preventDefault dockview's native expand before the
+            // event ever reaches React), so this renders state and carries the
+            // panel id that handler reads back — no onClick of its own.
+            _jsx(DockTabAction, { className: `${EDGE_PIN_CLASS}${pinned ? ` ${EDGE_PIN_CLASS}--on` : ''}`, "data-fx-edge-pin-panel": api.id, role: "button", "aria-pressed": pinned, "aria-label": pinned ? 'Unpin tab' : 'Pin tab', title: pinned ? 'Unpin' : 'Pin', onPointerDown: onBtnPointerDown, children: _jsx(Pin, { className: "fx-edge-pin-icon", size: 12, "aria-hidden": true }) }))
+            : (_jsx(DockTabAction, { ref: closeInteractions.closeRef, children: _jsx(X, { size: 14, "aria-hidden": true }) }));
+    return (_jsxs(DockTabFrame, { "data-testid": "dockview-dv-default-tab", ...rest, onPointerDown: closeInteractions.onPointerDown, onPointerUp: closeInteractions.onPointerUp, onPointerLeave: closeInteractions.onPointerLeave, leading: (_jsx(DockTabIcon, { children: _jsx(Icon, { size: 14, "aria-hidden": true }) })), action: action, children: [_jsx(DockTabTitle, { children: title }), infoIssueCounts !== null && infoStatusItems.length > 0 && (_jsx(DockTabStatusSummary, { "aria-label": `${infoIssueCounts.error} errors, ${infoIssueCounts.warn} warnings`, items: infoStatusItems }))] }));
+}

package/dist/package/node/components/DockShell/ExtensionHostPanel.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { lazy, Suspense } from 'react';
+import { useTranslation } from '../../i18n/index.js';
+import { pickLang } from '../../lib/extension-api.js';
+import { useExtensionManifest } from '../../lib/use-extension-manifest.js';
+import { useShellStore } from '../../store.js';
+import { usePanelRenderers } from './panelRenderers.js';
+import { ExtensionRuntimeFrame } from './ExtensionRuntimeFrame.js';
+import { isExtensionHostExtension, useExtensionCatalogEntry } from './extensionRuntime.js';
+import { usesExternalIframeRuntime } from './extension-runtime-selection.js';
+import { NativeExtensionHost } from '../ExtensionHost/NativeExtensionHost.js';
+// Keep Extension Platform transport out of standalone DockShell's static import graph. Catalog
+// Pages load this runtime only when an iframe-backed placement is mounted.
+const StandaloneExtensionIframe = lazy(() => import('../MainArea/StandaloneExtensionIframe.js').then((module) => ({
+    default: module.StandaloneExtensionIframe,
+})));
+function LegacyStandalonePanel({ manifest, pane, }) {
+    const { t } = useTranslation();
+    return (_jsx("div", { className: "page-dock-panel page-dock-standalone", children: _jsx(Suspense, { fallback: _jsx("div", { className: "page-dock-loading", children: t('extensionDock.loadingExtensionGeneric') }), children: _jsx(StandaloneExtensionIframe, { plugin: manifest, pane: pane, active: true }) }) }));
+}
+function HostedExtensionRuntimePanel({ extensionId, pane, onEditorAssetImport, }) {
+    const { t } = useTranslation();
+    const activeGameSlug = useShellStore((state) => state.activeGameSlug);
+    const activeGameResolved = useShellStore((state) => state.activeGameResolved);
+    const runtime = useExtensionCatalogEntry(extensionId, activeGameSlug, activeGameResolved);
+    if (runtime.loading) {
+        return _jsx("div", { className: "page-dock-loading", children: t('extensionDock.loadingExtensionHost') });
+    }
+    if (runtime.error) {
+        return (_jsxs("div", { className: "page-dock-loading page-dock-error", role: "alert", children: [_jsx("div", { children: t('extensionDock.extensionHostFailed', { error: runtime.error.message }) }), _jsx("button", { type: "button", onClick: runtime.retry, children: t('extensionDock.retry') })] }));
+    }
+    if (runtime.descriptor && activeGameSlug) {
+        return (_jsx("div", { className: "page-dock-panel page-dock-standalone", children: _jsx(ExtensionRuntimeFrame, { descriptor: runtime.descriptor, gameId: activeGameSlug, pane: pane, onEditorAssetImport: onEditorAssetImport }) }));
+    }
+    return (_jsxs("div", { className: "page-dock-loading page-dock-error", role: "alert", children: [_jsx("div", { children: activeGameSlug
+                    ? t('extensionDock.extensionExtensionMissing', { extensionId })
+                    : t('extensionDock.extensionGameRequired') }), _jsx("button", { type: "button", onClick: runtime.retry, children: t('extensionDock.retry') })] }));
+}
+/** Render one Page placement for a Extension extension. The Page owns panel
+ * availability and position; `pane` only selects the extension's content mode. */
+export function ExtensionHostPanel({ extensionId, pane }) {
+    const { t, i18n } = useTranslation();
+    const manifest = useExtensionManifest(extensionId);
+    const { extensionPanels, editor } = usePanelRenderers();
+    const InlinePanel = extensionPanels?.[extensionId];
+    if (InlinePanel) {
+        return (_jsx("div", { className: "page-dock-panel page-dock-inline", children: _jsx(InlinePanel, {}) }));
+    }
+    if (!manifest || manifest === 'loading') {
+        return (_jsx("div", { className: "page-dock-panel", children: _jsx("div", { className: "page-dock-loading", children: t('extensionDock.loadingExtension', { extensionId }) }) }));
+    }
+    const label = pickLang(manifest.displayName, i18n.language, manifest.id);
+    if (manifest.runtimeMode === 'native-module'
+        && manifest.moduleUrl) {
+        return (_jsx("div", { className: "page-dock-panel page-dock-standalone", children: _jsx(NativeExtensionHost, { extensionId: manifest.id, moduleUrl: manifest.moduleUrl, allowedOrigin: manifest.allowedOrigin, generation: manifest.registryGeneration ?? 0, active: true }) }));
+    }
+    // Explicit legacy runtimes are iframe-backed even though their persisted Studio
+    // manifest intentionally contains no standalone process command/port. The
+    // Host-projected frontendUrl is the authority for this externally-owned mode.
+    if (usesExternalIframeRuntime(manifest)) {
+        if (!isExtensionHostExtension(manifest.id)) {
+            return _jsx(LegacyStandalonePanel, { manifest: manifest, pane: pane });
+        }
+        return (_jsx(HostedExtensionRuntimePanel, { extensionId: extensionId, pane: pane, onEditorAssetImport: editor?.importAssetSource }));
+    }
+    const description = pickLang(manifest.description ?? '', i18n.language, '');
+    return (_jsxs("div", { className: "page-dock-panel page-dock-placeholder", children: [_jsx("div", { className: "page-dock-name", children: label }), description && _jsx("div", { className: "page-dock-desc", children: description }), _jsx("div", { className: "page-dock-id", children: manifest.id })] }));
+}

package/dist/package/node/components/DockShell/ExtensionRuntimeFrame.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef } from 'react';
+import { ExtensionFrame } from '@forgeax/extension-host/react';
+import { getLocale } from '../../i18n/index.js';
+import { attachExtensionEditorAssetImportBridge } from './extension-editor-bridge.js';
+import { EXTENSION_API_BASE } from './extensionRuntime.js';
+export const TRUSTED_EXTENSION_SANDBOX = 'allow-scripts allow-same-origin';
+export function extensionRuntimeUrl(runtimeUrl, pane) {
+    if (!pane)
+        return runtimeUrl;
+    const url = new URL(runtimeUrl, window.location.href);
+    url.searchParams.set('pane', pane);
+    return url.origin === window.location.origin
+        ? `${url.pathname}${url.search}${url.hash}`
+        : url.toString();
+}
+export function extensionFrameContext(descriptor, gameId) {
+    const runtimeId = encodeURIComponent(descriptor.runtimeId);
+    const encodedGameId = encodeURIComponent(gameId);
+    return {
+        extensionId: descriptor.extensionId,
+        runtimeId: descriptor.runtimeId,
+        gameId,
+        locale: getLocale(),
+        theme: 'dark',
+        endpoints: {
+            toolCall: `${EXTENSION_API_BASE}tools/call`,
+            gamePackage: `${EXTENSION_API_BASE}games/${encodedGameId}/package?runtimeId=${runtimeId}`,
+            extensionApi: `${EXTENSION_API_BASE}extension/${runtimeId}?gameId=${encodedGameId}`,
+            gameVersions: `${EXTENSION_API_BASE}games/${encodedGameId}/versions`,
+            gameComponents: `${EXTENSION_API_BASE}games/${encodedGameId}/components`,
+        },
+        capabilities: ['tools.call', 'project.files', 'game.package', 'media', 'versioning', 'extension.http'],
+    };
+}
+export function ExtensionRuntimeFrame({ descriptor, gameId, pane, onEditorAssetImport, }) {
+    const frameRef = useRef(null);
+    const importHandlerRef = useRef(onEditorAssetImport);
+    importHandlerRef.current = onEditorAssetImport;
+    const onFrameLoad = useCallback((event) => {
+        frameRef.current = event.currentTarget;
+    }, []);
+    useEffect(() => {
+        return attachExtensionEditorAssetImportBridge({
+            ownerWindow: window,
+            frameWindow: () => frameRef.current?.contentWindow ?? null,
+            importAssetSource: (request) => {
+                const handler = importHandlerRef.current;
+                return handler
+                    ? handler(request)
+                    : { ok: false, error: '当前 Studio 没有可用的 Editor Gateway' };
+            },
+        });
+    }, []);
+    return (_jsx(ExtensionFrame, { runtimeUrl: extensionRuntimeUrl(descriptor.runtimeUrl, pane), context: extensionFrameContext(descriptor, gameId), sandbox: TRUSTED_EXTENSION_SANDBOX, title: pane ? `${descriptor.title} — ${pane}` : descriptor.title, "data-extension-runtime": descriptor.extensionId, "data-extension-pane": pane, style: { display: 'block', width: '100%', height: '100%', border: 0 }, onLoad: onFrameLoad }));
+}

package/dist/package/node/components/DockShell/PanelWindowingBoundary.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useTranslation } from '../../i18n/index.js';
+import { useFloatingSurfaces } from '../../lib/platform/index.js';
+import { DetachedPanelBoundary, SurfacePlaceholder } from '@forgeax/app-shell/react';
+export function PanelWindowingBoundary({ capability, children, }) {
+    const { t } = useTranslation();
+    const floatingSurfaces = useFloatingSurfaces();
+    return (_jsx(DetachedPanelBoundary, { capability: capability, floatingSurfaces: floatingSurfaces, placeholder: (_jsx(SurfacePlaceholder, { title: t('dockShell.detachedWindowPlaceholder') })), children: children }));
+}