@forgeax/interface 0.4.1

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

@@ -0,0 +1,37 @@
+// SSOT for "which tab is pinned in which edge group".
+//
+// edgeDrawer OWNS the rules (at most one pin per edge group; a pinned active tab
+// defeats auto-dismiss) and writes here. DockTab READS here to render the Pin
+// toggle. The split exists so the glyph is a RENDER of state rather than a
+// runtime overwrite of React's own output: edgeDrawer used to do
+// `action.innerHTML = PIN_SVG` on dockview events, which raced React's portal
+// commit (on a fresh page the tab had no pin until some unrelated dockview event
+// happened to re-run the swap) and had no inverse, so a panel dragged out of a
+// strip kept a Pin glyph and a dead close button.
+//
+// Module-scoped adapter: App Shell owns the generic state while only the
+// DockShell region supplies concrete Dockview group/panel identities.
+import { createEdgePinStore } from '@forgeax/app-shell/window';
+/** DOM contract between the two halves: DockTab stamps it on the toggle,
+ *  edgeDrawer's capture-phase click handler `closest()`s for it. (The CSS in
+ *  DockShell.css / GlobalStatusBar.css spells it literally, as CSS must.) */
+export const EDGE_PIN_CLASS = 'fx-edge-pin';
+const edgePins = createEdgePinStore();
+export const edgePinStateSource = {
+    pinnedIn: edgePins.pinnedIn,
+    subscribe: edgePins.onChange,
+};
+export function subscribeEdgePins(onChange) {
+    return edgePins.onChange(onChange);
+}
+export function pinnedPanelIdIn(groupId) {
+    return edgePins.pinnedIn(groupId);
+}
+/** `panelId === undefined` unpins the group. No-ops (and stays silent) when the
+ *  state already matches, so callers can fire it from reconcilers. */
+export function setEdgePin(groupId, panelId) {
+    edgePins.setPinned(groupId, panelId);
+}
+export function clearEdgePins() {
+    edgePins.clear();
+}

package/dist/package/node/components/DockShell/extension-editor-bridge.js

@@ -0,0 +1,100 @@
+import { installWindowMessageObservation } from '@forgeax/app-shell/react';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function parseRequest(value) {
+    if (!isRecord(value) || value.type !== 'extension:editor-asset-import')
+        return null;
+    const requestId = value.requestId;
+    const base64 = value.base64;
+    const destPath = value.destPath;
+    const sourceName = value.sourceName;
+    if (typeof requestId !== 'string' || requestId.trim() === ''
+        || typeof base64 !== 'string' || base64.trim() === ''
+        || typeof destPath !== 'string' || destPath.trim() === ''
+        || typeof sourceName !== 'string' || sourceName.trim() === '')
+        return null;
+    return {
+        requestId: requestId.trim(),
+        base64,
+        destPath: destPath.trim(),
+        sourceName: sourceName.trim(),
+    };
+}
+function failureHint(value) {
+    if (!isRecord(value) || value.ok !== false)
+        return null;
+    if (typeof value.error === 'string')
+        return value.error;
+    if (isRecord(value.error) && typeof value.error.hint === 'string')
+        return value.error.hint;
+    return 'Editor asset import failed';
+}
+/**
+ * Attach the one host-side bridge used by both standalone and formal
+ * Page iframes. It owns only the message envelope; the injected callback
+ * remains the Studio-side Editor Gateway implementation.
+ */
+export function attachExtensionEditorAssetImportBridge(options) {
+    let disposed = false;
+    const onMessage = (event) => {
+        if (disposed)
+            return;
+        if (options.isTrustedEvent && !options.isTrustedEvent(event))
+            return;
+        const source = options.frameWindow();
+        if (!source || event.source !== source)
+            return;
+        const request = parseRequest(event.data);
+        if (!request) {
+            if (isRecord(event.data) && event.data.type === 'extension:editor-asset-import') {
+                source.postMessage({
+                    type: 'extension:editor-asset-import-result',
+                    requestId: typeof event.data.requestId === 'string' ? event.data.requestId : '',
+                    ok: false,
+                    error: '导入请求格式无效',
+                }, '*');
+            }
+            return;
+        }
+        const reply = (message) => {
+            if (disposed)
+                return;
+            source.postMessage(message, '*');
+        };
+        const handler = options.importAssetSource;
+        if (!handler) {
+            reply({
+                type: 'extension:editor-asset-import-result',
+                requestId: request.requestId,
+                ok: false,
+                error: '当前 Studio 没有可用的 Editor Gateway',
+            });
+            return;
+        }
+        void Promise.resolve(handler(request)).then((result) => {
+            const error = failureHint(result);
+            reply({
+                type: 'extension:editor-asset-import-result',
+                requestId: request.requestId,
+                ok: error === null,
+                ...(error === null ? { result } : { error }),
+            });
+        }).catch((error) => {
+            reply({
+                type: 'extension:editor-asset-import-result',
+                requestId: request.requestId,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    };
+    const disposeWindowMessageObservation = installWindowMessageObservation({
+        target: options.ownerWindow,
+        onMessage,
+    });
+    return () => {
+        disposed = true;
+        disposeWindowMessageObservation();
+    };
+}

package/dist/package/node/components/DockShell/extension-runtime-selection.js

@@ -0,0 +1,6 @@
+export function usesExternalIframeRuntime(manifest) {
+    return Boolean(manifest.frontendUrl
+        || manifest.entry?.standalone
+        || manifest.entry?.frontend
+        || manifest.runtimeMode === 'embedded');
+}

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

@@ -0,0 +1,84 @@
+import { useCallback, useEffect, useState } from 'react';
+import { createExtensionBrowserClient, } from '@forgeax/extension-host/browser';
+export const EXTENSION_API_BASE = '/__extension__/v1/';
+const EXTENSION_HOST_EXTENSION_IDS = new Set([
+    '@forgeax-extension/video-game',
+    '@forgeax-extension/game-video',
+]);
+const catalogRequests = new Map();
+export function isExtensionHostExtension(extensionId) {
+    return EXTENSION_HOST_EXTENSION_IDS.has(extensionId);
+}
+export async function loadExtensionCatalog(gameId, fetcher, signal) {
+    return createExtensionBrowserClient({
+        baseUrl: EXTENSION_API_BASE,
+        gameId,
+        ...(fetcher ? { fetch: fetcher } : {}),
+    }).catalog(signal);
+}
+/** A Page can mount left and center placements for the same extension. Keep the
+ * catalog request shared so both panels resolve one authoritative runtime. */
+export function loadSharedExtensionCatalog(gameId, fetcher) {
+    const current = catalogRequests.get(gameId);
+    if (current)
+        return current;
+    const request = loadExtensionCatalog(gameId, fetcher).catch((error) => {
+        if (catalogRequests.get(gameId) === request)
+            catalogRequests.delete(gameId);
+        throw error;
+    });
+    catalogRequests.set(gameId, request);
+    return request;
+}
+export function invalidateExtensionCatalog(gameId) {
+    if (gameId)
+        catalogRequests.delete(gameId);
+    else
+        catalogRequests.clear();
+}
+export function useExtensionCatalogEntry(extensionId, gameId, gameResolved) {
+    const [attempt, setAttempt] = useState(0);
+    const [state, setState] = useState({
+        descriptor: null,
+        loading: true,
+        error: null,
+    });
+    useEffect(() => {
+        if (!gameResolved) {
+            setState({ descriptor: null, loading: true, error: null });
+            return;
+        }
+        if (!gameId) {
+            setState({ descriptor: null, loading: false, error: null });
+            return;
+        }
+        let cancelled = false;
+        setState({ descriptor: null, loading: true, error: null });
+        void loadSharedExtensionCatalog(gameId)
+            .then((entries) => {
+            if (cancelled)
+                return;
+            setState({
+                descriptor: entries.find((entry) => entry.extensionId === extensionId) ?? null,
+                loading: false,
+                error: null,
+            });
+        })
+            .catch((error) => {
+            if (cancelled)
+                return;
+            setState({
+                descriptor: null,
+                loading: false,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        });
+        return () => { cancelled = true; };
+    }, [attempt, extensionId, gameId, gameResolved]);
+    const retry = useCallback(() => {
+        if (gameId)
+            invalidateExtensionCatalog(gameId);
+        setAttempt((value) => value + 1);
+    }, [gameId]);
+    return { ...state, retry };
+}

package/dist/package/node/components/DockShell/footer-panel-visibility.js

@@ -0,0 +1,43 @@
+import { FOOTER_PANEL_ID_LIST, FOOTER_PANEL_IDS } from './footer-panels.js';
+/** User intent for footer chrome tabs (Content Browser, Info, …). Distinct from
+ *  dockview mount state: `ensureFooterPanels` must not resurrect panels the user
+ *  hid via the layout menu or `app.panel.toggle`. */
+const visibleById = new Map(FOOTER_PANEL_ID_LIST.map((id) => [id, true]));
+const listeners = new Set();
+let ensureMounted = null;
+function notify() {
+    for (const listener of listeners)
+        listener();
+}
+/** edgeDrawer registers the routine that mounts visible footer tabs. */
+export function registerFooterPanelEnsure(fn) {
+    ensureMounted = fn;
+    return () => {
+        if (ensureMounted === fn)
+            ensureMounted = null;
+    };
+}
+export function requestFooterPanelEnsure() {
+    ensureMounted?.();
+}
+export function isFooterPanelId(panelId) {
+    return FOOTER_PANEL_IDS.has(panelId);
+}
+export function isFooterPanelUserVisible(panelId) {
+    if (!isFooterPanelId(panelId))
+        return true;
+    return visibleById.get(panelId) ?? true;
+}
+export function setFooterPanelUserVisible(panelId, visible) {
+    if (!isFooterPanelId(panelId))
+        return;
+    const prev = visibleById.get(panelId) ?? true;
+    if (prev === visible)
+        return;
+    visibleById.set(panelId, visible);
+    notify();
+}
+export function subscribeFooterPanelVisibility(listener) {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+}

package/dist/package/node/components/DockShell/footer-panels.js

@@ -0,0 +1,7 @@
+export const FOOTER_PANEL_ID_LIST = [
+    'ep:assets',
+    'info',
+    'checkpoints',
+    'events',
+];
+export const FOOTER_PANEL_IDS = new Set(FOOTER_PANEL_ID_LIST);

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

@@ -0,0 +1,126 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Sidebar } from '../Sidebar/Sidebar.js';
+import { MainArea } from '../MainArea/MainArea.js';
+import { FilesPanel } from '../Sidebar/FilesPanel.js';
+import { ConsolePanel } from '../MainArea/ConsolePanel.js';
+import { TelemetryViewer } from '../MainArea/TelemetryViewer.js';
+import { InfoPanel } from '../StatusBar/InfoPanel.js';
+import { CheckpointsDrawer } from '../StatusBar/footer/CheckpointsDrawer.js';
+import { EventsDrawer } from '../StatusBar/footer/EventsDrawer.js';
+import { RecoveryBoundary } from '../ErrorBoundary.js';
+// Editor panel bodies resolve through the runtime PanelRenderers context so
+// interface stays editor-agnostic (no `@forgeax/editor*` import).
+import { usePanelRenderers } from './panelRenderers.js';
+import { DockPanelHost } from './DockPanelHost.js';
+import { withDockTitleRestore } from './dockTitle.js';
+import { t as panelT } from '../../i18n/index.js';
+import { SurfacePlaceholder } from '@forgeax/app-shell/react';
+// Agents panel body — injected by Studio from `@forgeax/chat`.
+// When absent (interface-alone / standalone editor) render a neutral placeholder
+// so the dock/pop-out slot stays valid. Exported so Sidebar can reuse the same
+// placeholder path (consistent UX between dock-panel and sidebar mount).
+export function AgentsPanelSlot() {
+    const SidebarAgents = usePanelRenderers().slots?.SidebarAgents;
+    if (SidebarAgents)
+        return _jsx("div", { "data-fx-slot": "SidebarAgents", style: { display: 'contents' }, children: _jsx(SidebarAgents, {}) });
+    return _jsx(SurfacePlaceholder, { title: "No agents app configured" });
+}
+function panelWindowing(id, fallbackTitle, size = { width: 480, height: 680 }, dockBehavior = 'close') {
+    return {
+        createTarget: () => {
+            const key = `dockShell.panelTitles.${id}`;
+            const localized = panelT(key);
+            return {
+                surface: { kind: 'panel', id },
+                title: localized === key ? fallbackTitle : localized,
+                ...size,
+                dockBehavior,
+            };
+        },
+    };
+}
+// ── core + optional panels ───────────────────────────────────────────────────
+// Order within each array is the order the layout menu lists them.
+export const CORE_PANELS = [
+    // Tools is a single-panel group (nav moved to the shell ActivityRail), so its
+    // dockview tab bar is redundant — the `hideTitle` single-tab marker collapses it.
+    { id: 'tools', title: 'Tools', group: 'core', windowing: panelWindowing('tools', 'Tools'), tourId: 'sidebar', render: () => (_jsx("div", { className: "fx-panel", "data-dock-single-tab": "hideTitle", children: _jsx(Sidebar, {}) })) },
+    // 'main' is the plugin-launcher / catalog panel (formerly titled 'Page',
+    // which was redundant with the top-level page tab strip). It renders MainArea.
+    // Single-panel group → hide its dockview tab bar (like tools) so the in-panel
+    // plugin header (CenterExtensionLayer) sits at the very top of the column.
+    { id: 'main', title: 'Studio', group: 'core', windowing: panelWindowing('main', 'Studio'), render: () => (_jsx("div", { className: "fx-panel", "data-dock-single-tab": "hideTitle", children: _jsx(MainArea, {}) })) },
+    // In flat-architecture mode 'viewport' is the combined panel (engine canvas +
+    // gizmo). Its body is contributed via panels.viewport, same as chat/ep:*
+    // panels; the descriptor renders the anchor tracked by SurfaceKeepAliveLayer.
+    { id: 'viewport', title: 'Viewport', group: 'core', windowing: panelWindowing('viewport', 'Viewport', { width: 1280, height: 800 }, 'keep-anchor'), tourId: 'preview', render: () => _jsx(DockPanelHost, { id: "viewport" }) },
+    // R4: chat body comes from the studio-injected panels['chat'] registry.
+    { id: 'chat', title: 'ForgeaX CLI', group: 'core', windowing: panelWindowing('chat', 'ForgeaX CLI'), tourId: 'chat', render: () => _jsx(DockPanelHost, { id: "chat" }) },
+];
+export const OPTIONAL_PANELS = [
+    { id: 'agents', title: 'Agents', group: 'optional', windowing: panelWindowing('agents', 'Agents'), render: () => _jsx(DockPanelHost, { id: "agents" }) },
+    { id: 'files', title: 'Files', group: 'optional', windowing: panelWindowing('files', 'Files'), render: () => _jsx(FilesPanel, {}) },
+    { id: 'console', title: 'Console', group: 'optional', windowing: panelWindowing('console', 'Console'), render: () => _jsx(ConsolePanel, {}) },
+    // Observability (trace + log) feed — trace waterfall + log stream, fed by the
+    // unified store.telemetry slice (node WS `{type:'telemetry'}` + iframe
+    // `VAG_TELEMETRY`). See MainArea/TelemetryViewer.tsx.
+    { id: 'telemetry', title: 'Telemetry', group: 'optional', windowing: panelWindowing('telemetry', 'Telemetry'), render: () => _jsx(TelemetryViewer, {}) },
+    // Footer chrome panels — Info (Blender-INFO-style health/log feed), Checkpoints
+    // (session rewind timeline) and Events (gateway feed). Formerly a bottom-drawer
+    // launcher (ADR-0030 §2.3); now real dockview panels that DEFAULT into the
+    // footer-merged bottom EDGE group (see the default layouts' `edgeGroups.bottom`
+    // + edgeDrawer relocation). Tab titles localize via dockShell.panelTitles.*.
+    { id: 'info', title: 'Info', group: 'optional', render: () => _jsx(InfoPanel, {}) },
+    { id: 'checkpoints', title: 'Checkpoints', group: 'optional', render: () => _jsx(CheckpointsDrawer, {}) },
+    { id: 'events', title: 'Events', group: 'optional', render: () => _jsx(EventsDrawer, {}) },
+];
+// ── derived lookup maps (DockShell consumes these; never edit by hand) ────────
+const ALL_PANELS = [...CORE_PANELS, ...OPTIONAL_PANELS];
+/** Wrap a panel renderer in a region-scoped RecoveryBoundary so a render throw
+ *  in ONE dock panel (a bad selector, a plugin panel) shows a retry/reload
+ *  affordance for that panel only — instead of taking down the whole shell. The
+ *  inline (non-fullscreen) variant keeps the surrounding dock layout intact. */
+function withBoundary(scope, render) {
+    return () => _jsx(RecoveryBoundary, { scope: scope, fullscreen: false, children: render() });
+}
+// Tour anchors for editor (`ep:*`) panels. The default Scene workspace's left
+// column is Hierarchy (scene outline) over Inspector (object properties), and
+// its content browser is the Assets panel — the onboarding tour highlights both
+// by these ids. Keyed by bare panel id (buildEditorPanelComponents prefixes
+// `ep:`); a panel absent here simply renders without a tour marker.
+const EP_TOUR_IDS = {
+    hierarchy: 'hierarchy',
+    inspector: 'inspector',
+    assets: 'assets',
+};
+function tourWrap(tourId, render) {
+    if (!tourId)
+        return render;
+    // Layout-neutral tour anchor: render the panel body UNCHANGED (no wrapper in
+    // the flow) and append an out-of-flow, zero-size marker. The TourOverlay reads
+    // the marker's PARENT rect (the dockview content box = the panel's real area),
+    // so highlighting never perturbs the panel's own layout.
+    return () => (_jsxs(_Fragment, { children: [render(), _jsx("span", { "data-tour-id": tourId, "data-tour-anchor-parent": "1", "aria-hidden": "true", style: { position: 'absolute', width: 0, height: 0, pointerEvents: 'none' } })] }));
+}
+/** Static, interface-owned dockview component map. Host-owned editor panels
+ *  are added at runtime by buildEditorPanelComponents(). */
+export const BASE_PANEL_COMPONENTS = Object.fromEntries(ALL_PANELS.map((p) => [
+    p.id,
+    withDockTitleRestore(withBoundary(`panel:${p.id}`, tourWrap(p.tourId, p.render))),
+]));
+/** Static titles for interface-owned panels only. */
+export const BASE_PANEL_TITLE = Object.fromEntries(ALL_PANELS.map((p) => [p.id, p.title]));
+/** Runtime editor panel component map. The host injects the bare ids from its
+ *  editor manifest, so the interface never owns a business panel list. */
+export function buildEditorPanelComponents(editorPanelIds) {
+    return Object.fromEntries(editorPanelIds.map((id) => [
+        `ep:${id}`,
+        withDockTitleRestore(withBoundary(`ep:${id}`, tourWrap(EP_TOUR_IDS[id], () => _jsx(DockPanelHost, { id: id })))),
+    ]));
+}
+/** Core panel ids offered in the layout menu's main-panels section (excludes 'main' alias). */
+export const CORE_PANEL_IDS = ['tools', 'viewport', 'chat'];
+/** Optional panel ids (layout menu more-panels section). */
+export const OPTIONAL_PANEL_IDS = OPTIONAL_PANELS.map((p) => p.id);
+/** Interface-owned detached-window declarations, derived from PanelDef. */
+export const BASE_PANEL_WINDOWING = Object.fromEntries(ALL_PANELS.flatMap((panel) => (panel.windowing ? [[panel.id, panel.windowing]] : [])));

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

@@ -0,0 +1,25 @@
+// Panel renderer injection — keeps the interface shell business-agnostic.
+//
+// The DockShell renders generic chrome (page / preview / edit / chat /
+// ep:* editor panels), but the actual edit & preview SURFACES belong to an
+// app (today: the editor). To avoid interface importing `@forgeax/editor*`
+// (which created the studio → interface → editor → interface cycle), the
+// host injects the editor-specific render slots through this context.
+//
+// - interface ALONE renders neutral placeholders (no editor present).
+// - studio injects real renderers built from `@forgeax/editor/{edit,play}`.
+//
+// This is the same shape as the existing extension panel merge: DockShell owns
+// the docking mechanics, the host supplies the panel bodies.
+import { createContext, useContext } from 'react';
+// Interface-alone hosts do not expose editor panels. Editor hosts inject their
+// own manifest through PanelRenderers.editorPanelIds.
+export const DEFAULT_EDITOR_PANEL_IDS = [];
+export const DEFAULT_PANEL_RENDERERS = {
+    editorPanelIds: DEFAULT_EDITOR_PANEL_IDS,
+};
+const PanelRenderersContext = createContext(DEFAULT_PANEL_RENDERERS);
+export const PanelRenderersProvider = PanelRenderersContext.Provider;
+export function usePanelRenderers() {
+    return useContext(PanelRenderersContext);
+}

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

@@ -0,0 +1,133 @@
+import { getSurfaceWindowingController } from '../../lib/platform/surface-windowing.js';
+import { getDockRegions } from './dockviewRegistry.js';
+import { setDockTitleHidden } from './dockTitle.js';
+import { openPanelWindow } from './panelWindowing.js';
+import { setFooterPanelUserVisible, isFooterPanelId } from './footer-panel-visibility.js';
+function dockRegionTransferApi(api) {
+    return api;
+}
+export function createPanelTabCommands(deps) {
+    const { getApi, titleFor } = deps;
+    return {
+        close(panel) {
+            if (isFooterPanelId(panel.id))
+                setFooterPanelUserVisible(panel.id, false);
+            try {
+                panel.api.close();
+            }
+            catch { /* noop */ }
+        },
+        closeOthers(active, group) {
+            for (const panel of group.panels) {
+                if (panel.id === active.id)
+                    continue;
+                try {
+                    panel.api.close();
+                }
+                catch { /* noop */ }
+            }
+        },
+        moveToEdge(panel, side) {
+            const api = getApi();
+            if (!api)
+                return;
+            const edgeApi = api.getEdgeGroup(side);
+            if (!edgeApi)
+                return;
+            const edgeGroup = api.groups.find((group) => group.api.id === edgeApi.id);
+            if (!edgeGroup)
+                return;
+            try {
+                api.setEdgeGroupVisible(side, true);
+            }
+            catch { /* noop */ }
+            edgeGroup.element.classList.remove('fx-edge-empty');
+            try {
+                panel.api.moveTo({ group: edgeGroup, position: 'center' });
+            }
+            catch { /* noop */ }
+            try {
+                edgeGroup.api.collapse();
+            }
+            catch { /* noop */ }
+            try {
+                panel.api.setActive();
+            }
+            catch { /* noop */ }
+        },
+        moveOffEdge(panel) {
+            const api = getApi();
+            if (!api)
+                return;
+            const gridGroup = api.groups.find((group) => group.api.location.type === 'grid');
+            if (!gridGroup)
+                return;
+            const loc = panel.api.location;
+            const fromSide = loc.type === 'edge' && (loc.position === 'left' || loc.position === 'right')
+                ? loc.position
+                : 'left';
+            try {
+                panel.api.moveTo({ group: gridGroup, position: fromSide });
+            }
+            catch { /* noop */ }
+            try {
+                panel.api.setActive();
+            }
+            catch { /* noop */ }
+        },
+        setTitleBarHidden(groupEl, hidden) {
+            setDockTitleHidden(groupEl, hidden);
+        },
+        transferToRegion(panelId, targetRegion) {
+            const regions = getDockRegions();
+            const target = regions.find((entry) => entry.region === targetRegion);
+            if (!target)
+                return;
+            const targetApi = dockRegionTransferApi(target.api);
+            const source = regions.find((entry) => dockRegionTransferApi(entry.api).getPanel(panelId));
+            if (source?.region === targetRegion)
+                return;
+            const sourcePanel = source ? dockRegionTransferApi(source.api).getPanel(panelId) : undefined;
+            if (sourcePanel) {
+                const component = panelId;
+                const title = sourcePanel.api.title || titleFor(panelId);
+                const params = sourcePanel.params;
+                try {
+                    sourcePanel.api.close();
+                }
+                catch { /* noop */ }
+                try {
+                    targetApi.addPanel({
+                        id: panelId,
+                        component,
+                        title,
+                        params,
+                    });
+                }
+                catch { /* noop */ }
+                return;
+            }
+            if (targetApi.getPanel(panelId))
+                return;
+            try {
+                targetApi.addPanel({
+                    id: panelId,
+                    component: panelId,
+                    title: titleFor(panelId),
+                });
+            }
+            catch { /* noop */ }
+        },
+        detach(panel, capability) {
+            void openPanelWindow(panel.id, capability, {
+                detachSurface: getSurfaceWindowingController().detachSurface,
+                closeDockPanel: () => {
+                    try {
+                        panel.api.close();
+                    }
+                    catch { /* noop */ }
+                },
+            });
+        },
+    };
+}

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

@@ -0,0 +1,42 @@
+import { canOpenPanelWindow, createPanelWindowingController, shouldShowDetachedPlaceholder, } from '@forgeax/app-shell/window';
+export { canOpenPanelWindow, shouldShowDetachedPlaceholder };
+const panelWindowing = createPanelWindowingController();
+/** Dockview prefixes editor placements with ep:, while injected descriptors use bare ids. */
+export function injectedPanelDescriptorId(panelId) {
+    return panelId.startsWith('ep:') ? panelId.slice(3) : panelId;
+}
+/** Whether the Page runtime survives the later BASE/editor component spreads. */
+export function pageRuntimeOwnsPanel(panelId, basePanelIds, editorPanelIds) {
+    if (basePanelIds.has(panelId))
+        return false;
+    return !(panelId.startsWith('ep:') && editorPanelIds.includes(panelId.slice(3)));
+}
+/**
+ * Resolve capability with the same ownership precedence as DockRegion's final
+ * component map: editor ep:* uses its injected descriptor; BASE wins even when
+ * it deliberately has no capability; only unclaimed ids may fall through
+ * Page → injected.
+ */
+export function resolvePanelWindowing(panelId, sources) {
+    if (panelId.startsWith('ep:'))
+        return sources.injectedWindowing;
+    if (sources.basePanelIds.has(panelId))
+        return sources.baseWindowing[panelId];
+    return sources.pageWindowing[panelId] ?? sources.injectedWindowing;
+}
+/**
+ * The one high-level panel pop-out action used by every shell affordance.
+ * It constructs the target, opens the physical carrier, and only then removes
+ * an ordinary dock tab only when the target explicitly requests that behavior.
+ */
+export async function openPanelWindow(panelId, capability, options) {
+    return panelWindowing.openPanelWindow(panelId, capability, options);
+}
+/**
+ * Resolve the dock placement restored by a window-close event. This is a lookup,
+ * not a consume: every DockRegion receives the same close notification and the
+ * region that owns the placement must be allowed to handle it.
+ */
+export function detachedDockPanelForSurface(surface) {
+    return panelWindowing.panelForClosedSurface(surface);
+}

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

@@ -0,0 +1 @@
+export { DOCK_REGIONS, REGIONS, isDockRegion, } from '@forgeax/app-shell/dock';

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

@@ -0,0 +1 @@
+export { resolveRegion, } from '@forgeax/app-shell/dock';

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

@@ -0,0 +1,46 @@
+/** Retired viewport panel keys from the pre-2026-06-30 edit/preview split. */
+const RETIRED_VIEWPORT_KEYS = new Set(['edit', 'preview']);
+function remapGridViews(node) {
+    if (!node || typeof node !== 'object')
+        return;
+    const n = node;
+    if (n.type === 'leaf' && n.data && typeof n.data === 'object') {
+        const leaf = n.data;
+        if (Array.isArray(leaf.views)) {
+            leaf.views = leaf.views.map((v) => (RETIRED_VIEWPORT_KEYS.has(v) ? 'viewport' : v));
+        }
+        if (leaf.activeView && RETIRED_VIEWPORT_KEYS.has(leaf.activeView)) {
+            leaf.activeView = 'viewport';
+        }
+        return;
+    }
+    if (n.type === 'branch' && Array.isArray(n.data)) {
+        for (const child of n.data)
+            remapGridViews(child);
+    }
+}
+/** Rewrite legacy `edit`/`preview` dock keys to `viewport` before `api.fromJSON`. */
+export function sanitizeRetiredDockLayout(layout) {
+    const out = structuredClone(layout);
+    if (out.grid?.root)
+        remapGridViews(out.grid.root);
+    if (out.panels) {
+        for (const key of Object.keys(out.panels)) {
+            const panel = out.panels[key];
+            if (!panel)
+                continue;
+            if (RETIRED_VIEWPORT_KEYS.has(panel.contentComponent ?? '')) {
+                panel.contentComponent = 'viewport';
+            }
+            if (RETIRED_VIEWPORT_KEYS.has(key)) {
+                const migrated = { ...panel, id: 'viewport', contentComponent: 'viewport' };
+                out.panels.viewport = migrated;
+                delete out.panels[key];
+            }
+            else if (panel.id && RETIRED_VIEWPORT_KEYS.has(panel.id)) {
+                panel.id = 'viewport';
+            }
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1 @@
+export { isOnSideEdge, nearerSideEdge, } from '@forgeax/app-shell/dock';