@forgeax/interface 0.4.1

package/dist/package/node/core/extensions/builtin-menus.js

@@ -0,0 +1,252 @@
+// packages/interface/src/core/extensions/builtin-menus.ts
+//
+// Declares the built-in top-menu-bar items via `menu-registry.registerMenuItem`.
+// One extension declaratively populates BRAND / FILE / EDIT / WINDOW / BUILD /
+// SELECT / HELP so the web renderer (T6/T7) and the Tauri native bridge (T5)
+// share the exact same SSOT (menu-registry) — same UI, one place to edit.
+//
+// An item WITHOUT a `commandId` is intentionally disabled — it renders as a
+// greyed-out placeholder for a capability we haven't wired yet (the registry
+// defaults `enabled` to `!!commandId`, so no explicit `enabled: () => false`
+// is needed). Once the underlying command lands, the only change is adding
+// `commandId` here — the item will light up automatically.
+//
+// Mirrors the style of `builtin-commands.ts`: a single `AppExtension` whose
+// `setup(ctx)` calls the registrar for every item, collects the cleanups, and
+// returns a reverse-order cleanup runner.
+import { registerMenuItem } from '../../lib/menu-registry.js';
+import { isDockPanelVisible } from '@forgeax/app-shell/dock';
+import { useShellStore } from '../../store.js';
+import { getRecentGames } from '../../lib/recent-games.js';
+// Window-menu `checked()` predicates read from App Shell's shared visibility
+// registry, kept in sync by DockRegion's Dockview lifecycle subscriptions.
+// Non-reactive is fine: Radix rebuilds
+// dropdown content on every open, so `checked()` runs at open-time and
+// reflects the current state.
+const isVisible = (id) => () => isDockPanelVisible(id);
+// Chat panel visibility lives in the store slice; the panel itself is always
+// mounted, `chatpanelCollapsed` flips its collapsed state — invert for
+// "checked = visible".
+const isChatpanelOpen = () => !useShellStore.getState().chatpanelCollapsed;
+export const builtinMenusExtension = {
+    id: 'builtin-menus',
+    version: '1.0.0',
+    setup() {
+        const cleanups = [];
+        // Every item to register — sorted by menu / group / order so the shape
+        // reads top-to-bottom the way it renders. The registrar itself re-sorts
+        // by group-first-seen then `order`, so declaration order below is
+        // documentation only (except for stable in-group tie-breaks).
+        const items = [
+            // ─── BRAND ────────────────────────────────────────────────────────────
+            { id: 'brand.settings', menu: 'brand', group: 'app', order: 10,
+                labelKey: 'menu.brand.settings', icon: 'settings',
+                commandId: 'overlay.open', args: { id: 'settings' } },
+            { id: 'brand.about', menu: 'brand', group: 'about', order: 10,
+                labelKey: 'menu.brand.about', icon: 'info',
+                commandId: 'overlay.open', args: { id: 'settings', param: 'about' } },
+            { id: 'brand.checkUpdate', menu: 'brand', group: 'about', order: 20,
+                labelKey: 'menu.brand.checkUpdate', icon: 'refresh-cw' },
+            // ─── FILE ─────────────────────────────────────────────────────────────
+            // A game is the user-facing unit. The host's private instance root is
+            // intentionally absent from this menu.
+            // 打开最近 → a hover submenu of recent games (dynamicChildren, derived from
+            // the recent-games cache by mtime); each row switches to that game via
+            // game.pick. Closing a game stays unimplemented (disabled).
+            { id: 'file.newGame', menu: 'file', group: 'game', order: 10,
+                labelKey: 'menu.file.newGame', commandId: 'game.new', icon: 'file-plus' },
+            { id: 'file.openGameDirectory', menu: 'file', group: 'game', order: 20,
+                labelKey: 'menu.file.openGameDirectory', commandId: 'game.open-directory', icon: 'folder-open' },
+            { id: 'file.openRecent', menu: 'file', group: 'game', order: 30,
+                labelKey: 'menu.file.openRecent', icon: 'clock',
+                // 事实:每个动态子项都执行 game.pick,子项 id = file.openRecent.<slug>。
+                // 门对账靠它把 catalog 的 game.switch(别名 game.pick)解析到这条链,
+                // 无需展开动态列表。
+                dynamicChildCommandId: 'game.pick', dynamicChildIdFromArg: 'slug',
+                // Dynamic submenu: recent games (mtime-desc). Label uses the raw game
+                // name as the i18n key — `t()` falls back to the key when unmatched, so
+                // the display name shows as-is (same fallback the top-menu titles rely
+                // on). Clicking dispatches game.pick with the slug (→ store.setActiveGame).
+                dynamicChildren: () => getRecentGames().map((g) => ({
+                    id: `file.openRecent.${g.slug}`,
+                    menu: 'file', group: 'recent', order: 0,
+                    labelKey: (typeof g.name === 'string' && g.name) ? g.name : g.slug,
+                    commandId: 'game.pick', args: { slug: g.slug },
+                })) },
+            { id: 'file.closeGame', menu: 'file', group: 'game', order: 40,
+                labelKey: 'menu.file.closeGame', icon: 'x' },
+            { id: 'file.save', menu: 'file', group: 'file', order: 10,
+                labelKey: 'menu.file.save', icon: 'save',
+                commandId: 'editor.save', keybinding: 'Ctrl+S' },
+            { id: 'file.saveAll', menu: 'file', group: 'file', order: 20,
+                labelKey: 'menu.file.saveAll', icon: 'save-all', keybinding: 'Ctrl+Shift+S' },
+            // reveal + import: capabilities not confirmed wired yet — leave DISABLED
+            // per task brief; flip on `commandId` when T4 confirms.
+            { id: 'file.reveal', menu: 'file', group: 'file', order: 30,
+                labelKey: 'menu.file.reveal', icon: 'folder-search' },
+            { id: 'file.import', menu: 'file', group: 'io', order: 10,
+                labelKey: 'menu.file.import', icon: 'upload' },
+            { id: 'file.export', menu: 'file', group: 'io', order: 20,
+                labelKey: 'menu.file.export', icon: 'package' },
+            { id: 'file.package', menu: 'file', group: 'io', order: 30,
+                labelKey: 'menu.file.package', icon: 'globe' },
+            // ─── EDIT ─────────────────────────────────────────────────────────────
+            { id: 'edit.undo', menu: 'edit', group: 'history', order: 10,
+                labelKey: 'menu.edit.undo', icon: 'undo-2',
+                commandId: 'editor.undo', keybinding: 'Ctrl+Z' },
+            { id: 'edit.redo', menu: 'edit', group: 'history', order: 20,
+                labelKey: 'menu.edit.redo', icon: 'redo-2',
+                commandId: 'editor.redo', keybinding: 'Ctrl+Shift+Z' },
+            { id: 'edit.cut', menu: 'edit', group: 'clipboard', order: 10,
+                labelKey: 'menu.edit.cut', icon: 'scissors',
+                commandId: 'text.cut', keybinding: 'Ctrl+X' },
+            { id: 'edit.copy', menu: 'edit', group: 'clipboard', order: 20,
+                labelKey: 'menu.edit.copy', icon: 'copy',
+                commandId: 'text.copy', keybinding: 'Ctrl+C' },
+            { id: 'edit.paste', menu: 'edit', group: 'clipboard', order: 30,
+                labelKey: 'menu.edit.paste', icon: 'clipboard',
+                commandId: 'text.paste', keybinding: 'Ctrl+V' },
+            { id: 'edit.delete', menu: 'edit', group: 'clipboard', order: 40,
+                labelKey: 'menu.edit.delete', icon: 'trash-2', danger: true,
+                commandId: 'editor.delete' },
+            { id: 'edit.copyPath', menu: 'edit', group: 'clipboard', order: 50,
+                labelKey: 'menu.edit.copyPath', icon: 'copy' },
+            { id: 'edit.copyGuid', menu: 'edit', group: 'clipboard', order: 60,
+                labelKey: 'menu.edit.copyGuid', icon: 'hash' },
+            { id: 'edit.find', menu: 'edit', group: 'find', order: 10,
+                labelKey: 'menu.edit.find', icon: 'search', keybinding: 'Ctrl+F' },
+            { id: 'edit.rollback', menu: 'edit', group: 'version', order: 10,
+                labelKey: 'menu.edit.rollback', icon: 'rotate-ccw' },
+            // ─── WINDOW ───────────────────────────────────────────────────────────
+            // Runtime dock ids: editor sub-panels live under `ep:*` (see panelRegistry
+            // `buildEditorPanelComponents`), so the toggle args + `checked()` mirror
+            // those exact ids. `viewport` is an interface-owned core panel with a bare
+            // id. `chat` uses a dedicated store toggle instead of dock-visibility.
+            { id: 'window.outline', menu: 'window', group: 'panels', order: 10,
+                labelKey: 'menu.window.outline',
+                commandId: 'app.panel.toggle', args: { id: 'ep:hierarchy' },
+                checked: isVisible('ep:hierarchy') },
+            { id: 'window.inspector', menu: 'window', group: 'panels', order: 20,
+                labelKey: 'menu.window.inspector',
+                commandId: 'app.panel.toggle', args: { id: 'ep:inspector' },
+                checked: isVisible('ep:inspector') },
+            { id: 'window.files', menu: 'window', group: 'panels', order: 30,
+                labelKey: 'menu.window.files',
+                commandId: 'app.panel.toggle', args: { id: 'ep:assets' },
+                checked: isVisible('ep:assets') },
+            { id: 'window.timeline', menu: 'window', group: 'panels', order: 40,
+                labelKey: 'menu.window.timeline' },
+            { id: 'window.runtime', menu: 'window', group: 'panels', order: 50,
+                labelKey: 'menu.window.runtime' },
+            { id: 'window.viewport', menu: 'window', group: 'panels', order: 60,
+                labelKey: 'menu.window.viewport',
+                commandId: 'app.panel.toggle', args: { id: 'viewport' },
+                checked: isVisible('viewport') },
+            { id: 'window.chat', menu: 'window', group: 'panels', order: 70,
+                labelKey: 'menu.window.chat',
+                commandId: 'panel.toggle_chatpanel',
+                checked: isChatpanelOpen },
+            { id: 'window.resetLayout', menu: 'window', group: 'layout', order: 10,
+                labelKey: 'menu.window.resetLayout', icon: 'layout-grid',
+                commandId: 'app.dock.reset' },
+            { id: 'window.fullscreen', menu: 'window', group: 'layout', order: 20,
+                labelKey: 'menu.window.fullscreen', icon: 'maximize',
+                commandId: 'app.set_fullscreen', args: { value: true } },
+            // ─── BUILD ────────────────────────────────────────────────────────────
+            { id: 'build.play', menu: 'build', group: 'run', order: 10,
+                labelKey: 'menu.build.play', icon: 'play',
+                commandId: 'editor.play' },
+            { id: 'build.stop', menu: 'build', group: 'run', order: 20,
+                labelKey: 'menu.build.stop', icon: 'square',
+                commandId: 'editor.stop' },
+            { id: 'build.editScene', menu: 'build', group: 'run', order: 30,
+                labelKey: 'menu.build.editScene', icon: 'pencil',
+                commandId: 'editor.toggleDisplay' },
+            // reload: `editor.reloadPreview` currently only emits `preview:reload` on
+            // the bus with no consumer wired — clicking would silently no-op (a
+            // mock-success path, forbidden by the no-silent-fallback rule). Leave the
+            // menu item DISABLED (no commandId) until a listener lands in a standalone-application owner.
+            { id: 'build.reload', menu: 'build', group: 'run', order: 40,
+                labelKey: 'menu.build.reload', icon: 'refresh-cw' },
+            { id: 'build.export', menu: 'build', group: 'export', order: 10,
+                labelKey: 'menu.build.export', icon: 'package' },
+            { id: 'build.settings', menu: 'build', group: 'export', order: 20,
+                labelKey: 'menu.build.settings', icon: 'settings' },
+            // ─── SELECT ───────────────────────────────────────────────────────────
+            { id: 'select.all', menu: 'select', group: 'basic', order: 10,
+                labelKey: 'menu.select.all', icon: 'box-select',
+                commandId: 'editor.selectAll', keybinding: 'Ctrl+A' },
+            { id: 'select.none', menu: 'select', group: 'basic', order: 20,
+                labelKey: 'menu.select.none', icon: 'square-dashed',
+                commandId: 'editor.deselect' },
+            { id: 'select.invert', menu: 'select', group: 'basic', order: 30,
+                labelKey: 'menu.select.invert', icon: 'flip-horizontal-2' },
+            { id: 'select.byType', menu: 'select', group: 'byCond', order: 10,
+                labelKey: 'menu.select.byType', icon: 'shapes',
+                children: [
+                    { id: 'select.byType.mesh', menu: 'select', group: 'byCond', order: 10,
+                        labelKey: 'menu.select.byType.mesh' },
+                    { id: 'select.byType.light', menu: 'select', group: 'byCond', order: 20,
+                        labelKey: 'menu.select.byType.light' },
+                    { id: 'select.byType.camera', menu: 'select', group: 'byCond', order: 30,
+                        labelKey: 'menu.select.byType.camera' },
+                    { id: 'select.byType.collider', menu: 'select', group: 'byCond', order: 40,
+                        labelKey: 'menu.select.byType.collider' },
+                ] },
+            { id: 'select.marquee', menu: 'select', group: 'byCond', order: 20,
+                labelKey: 'menu.select.marquee', icon: 'scan' },
+            { id: 'select.frame', menu: 'select', group: 'view', order: 10,
+                labelKey: 'menu.select.frame', icon: 'focus',
+                commandId: 'editor.frameSelected' },
+            // ─── HELP ─────────────────────────────────────────────────────────────
+            { id: 'help.docs', menu: 'help', group: 'docs', order: 10,
+                labelKey: 'menu.help.docs', icon: 'book-open',
+                commandId: 'app.open_url', args: { url: 'https://forgeax.github.io/docs' } },
+            { id: 'help.tutorials', menu: 'help', group: 'docs', order: 20,
+                labelKey: 'menu.help.tutorials', icon: 'graduation-cap',
+                commandId: 'app.open_url', args: { url: 'https://forgeax.github.io/tutorials' } },
+            { id: 'help.examples', menu: 'help', group: 'docs', order: 30,
+                labelKey: 'menu.help.examples', icon: 'code',
+                commandId: 'app.open_url', args: { url: 'https://forgeax.github.io/examples' } },
+            { id: 'help.blog', menu: 'help', group: 'docs', order: 40,
+                labelKey: 'menu.help.blog', icon: 'newspaper',
+                commandId: 'app.open_url', args: { url: 'https://forgeax.github.io/blog' } },
+            { id: 'help.games', menu: 'help', group: 'resources', order: 10,
+                labelKey: 'menu.help.games', icon: 'gamepad-2',
+                commandId: 'app.open_url', args: { url: 'https://forgeax.github.io/games' } },
+            { id: 'help.marketplace', menu: 'help', group: 'resources', order: 20,
+                labelKey: 'menu.help.marketplace', icon: 'store',
+                commandId: 'app.open_url', args: { url: 'https://forgeax.github.io/marketplace' } },
+            { id: 'help.changelog', menu: 'help', group: 'resources', order: 30,
+                labelKey: 'menu.help.changelog', icon: 'scroll-text',
+                commandId: 'app.open_url', args: { url: 'https://forgeax.github.io/changelog' } },
+            { id: 'help.shortcuts', menu: 'help', group: 'app', order: 10,
+                labelKey: 'menu.help.shortcuts', icon: 'keyboard',
+                commandId: 'overlay.open', args: { id: 'settings', param: 'shortcuts' } },
+            { id: 'help.askAi', menu: 'help', group: 'app', order: 20,
+                labelKey: 'menu.help.askAi', icon: 'sparkles',
+                commandId: 'app.open_url', args: { url: 'https://forgeax.github.io/' } },
+            { id: 'help.github', menu: 'help', group: 'about', order: 10,
+                labelKey: 'menu.help.github', icon: 'github',
+                commandId: 'app.open_url', args: { url: 'https://github.com/ForgeaX-Games' } },
+            { id: 'help.report', menu: 'help', group: 'about', order: 20,
+                labelKey: 'menu.help.report', icon: 'message-circle',
+                commandId: 'feedback.open' },
+            { id: 'help.about', menu: 'help', group: 'about', order: 30,
+                labelKey: 'menu.help.about', icon: 'info',
+                commandId: 'overlay.open', args: { id: 'settings', param: 'about' } },
+            { id: 'help.license', menu: 'help', group: 'about', order: 40,
+                labelKey: 'menu.help.license', icon: 'scale',
+                commandId: 'app.open_url', args: { url: 'https://www.apache.org/licenses/LICENSE-2.0' } },
+        ];
+        for (const def of items)
+            cleanups.push(registerMenuItem(def));
+        return () => {
+            // Reverse order so first-registered is torn down last — same pattern
+            // as builtin-commands.ts; `.slice()` clones the array so a repeat unload
+            // doesn't mutate the closed-over `cleanups`.
+            for (const c of cleanups.slice().reverse())
+                c();
+        };
+    },
+};

package/dist/package/node/core/extensions/chrome-drawer.js

@@ -0,0 +1,45 @@
+export const EDGE_DRAWER_EVENT = 'forgeax:edge-drawer';
+function dispatchEdgeDrawer(action, id) {
+    window.dispatchEvent(new CustomEvent(EDGE_DRAWER_EVENT, { detail: { action, id } }));
+}
+export const chromeDrawerExtension = {
+    id: 'chrome.drawer',
+    version: '2.0.0',
+    requires: ['commands'],
+    setup(ctx) {
+        const cleanups = [];
+        const idOf = (args) => args?.id;
+        cleanups.push(ctx.registerCommand({
+            id: 'app.drawer.toggle',
+            title: 'Toggle a footer bottom-edge panel by id',
+            execute: (args) => {
+                const id = idOf(args);
+                if (!id)
+                    throw new Error('app.drawer.toggle: missing { id }');
+                dispatchEdgeDrawer('toggle', id);
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(ctx.registerCommand({
+            id: 'app.drawer.open',
+            title: 'Open (expand) a footer bottom-edge panel by id',
+            execute: (args) => {
+                const id = idOf(args);
+                if (!id)
+                    throw new Error('app.drawer.open: missing { id }');
+                dispatchEdgeDrawer('open', id);
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(ctx.registerCommand({
+            id: 'app.drawer.close',
+            title: 'Collapse the footer bottom-edge drawer',
+            execute: () => {
+                dispatchEdgeDrawer('close');
+                return { status: 'completed' };
+            },
+        }));
+        return () => { for (const c of cleanups.reverse())
+            c(); };
+    },
+};

package/dist/package/node/core/extensions/chrome-statusbar.js

@@ -0,0 +1,26 @@
+import { surfaceOverlayStatusItem } from '../../components/Surfaces/SurfaceOverlay.js';
+import { pulseStatusItems } from '../../components/StatusBar/feeds/PulseFeeds.js';
+import { forgeaxBuildVersionStatusItem } from '../../components/StatusBar/footer/ForgeaxBuildPopover.js';
+import { diagnosticsStatusItem } from '../../components/StatusBar/footer/DiagnosticsPopover.js';
+/** Fold an ordered list of status items into the keyed `stripItems` record the
+ *  derive step sub-merges per id. Exported so product assemblers reuse it. */
+export function toStripItems(items) {
+    const out = {};
+    for (const it of items)
+        out[it.id] = it;
+    return out;
+}
+export const chromeStatusBarExtension = {
+    id: 'chrome.statusbar',
+    version: '1.0.0',
+    contributes: {
+        panels: {
+            stripItems: toStripItems([
+                forgeaxBuildVersionStatusItem,
+                diagnosticsStatusItem,
+                surfaceOverlayStatusItem,
+                ...pulseStatusItems,
+            ]),
+        },
+    },
+};

package/dist/package/node/core/extensions/detached-agents-browser.js

@@ -0,0 +1,9 @@
+import { createAppSurfaceExtension } from '../app-shell/surface-extension.js';
+export function createDetachedAgentsBrowserExtension(AgentsBrowser) {
+    return createAppSurfaceExtension({
+        id: 'detached.agents-browser',
+        title: 'Agents Browser',
+        surface: 'detached',
+        components: { AgentsBrowser },
+    });
+}

package/dist/package/node/core/extensions/detached-files-browser.js

@@ -0,0 +1,6 @@
+export function createDetachedFilesBrowserExtension(FilesBrowser) {
+    return {
+        id: 'detached.files-browser', version: '1.0.0',
+        contributes: { panels: { detached: { FilesBrowser } } },
+    };
+}

package/dist/package/node/core/extensions/editor-commands.js

@@ -0,0 +1,182 @@
+// packages/interface/src/core/extensions/editor-commands.ts
+//
+// Command-bus wrappers for editor-domain actions (Play/Stop/Save/Undo/Redo/
+// select-all/delete/frame/toggle-display/deselect/…). These commands are the
+// single entry point the top menu bar (builtin-menus.ts) and the keyboard
+// router share so palette/menu/shortcut hit the same call path.
+//
+// The interface package is editor-agnostic (lint:agnostic forbids importing
+// @forgeax/editor), so every command routes through the injected
+// KeyboardRouterDeps — the host editor (studio/main.tsx) calls
+// registerKeyboardRouterDeps() at boot BEFORE <App> mounts, and each execute
+// resolves the deps LAZILY via getKeyboardRouterDeps(). Capture-at-setup
+// would freeze deps to null since setup runs during bootstrapAppHost() which
+// happens before main.tsx has finished mounting <App>; lazy resolution keeps
+// this file boot-order-safe regardless of whether registration happened first.
+//
+// import + reveal: NOT registered. Content-browser import and OS file-reveal
+// live outside KeyboardRouterDeps and can't be reached editor-agnostically
+// from the interface foundation. The corresponding menu items in builtin-menus.ts carry no
+// commandId and stay disabled — the correct signal for a not-yet-wired
+// capability. Flip them on when a dep or command later lands.
+//
+// reloadPreview: registered as a best-effort event emit (`preview:reload` on
+// ctx.bus). No listener consumes it yet — the Play iframe self-reload lives
+// in @forgeax/editor/PlaySurface which the interface foundation cannot import. Emitting the event
+// keeps the menu item live and gives a future HMR/preview owner a stable hook
+// to subscribe to without touching this file.
+import { APPLICATION_KEYBINDING_SCOPE } from '../contextual-keybindings.js';
+import { getKeyboardRouterDeps } from '../../lib/global-shortcuts.js';
+import { executeFocusedTextEditAction } from '../../lib/text-edit-actions.js';
+/** Resolve the injected router deps or throw a clear error naming the missing
+ *  wiring — makes a mis-boot fail loudly at command-invoke time instead of
+ *  silently no-op'ing. */
+function requireDeps() {
+    const deps = getKeyboardRouterDeps();
+    if (!deps)
+        throw new Error('editor-commands: editor deps not injected (host must call registerKeyboardRouterDeps before invoking editor.* commands)');
+    return deps;
+}
+export const editorCommandsExtension = {
+    id: 'editor-commands',
+    version: '1.0.0',
+    requires: ['commands', 'keybindings'],
+    setup(ctx) {
+        const { registerCommand, host } = ctx;
+        const cleanups = [];
+        cleanups.push(registerCommand({
+            id: 'editor.play',
+            title: '开始预览 (Play)',
+            execute: () => {
+                requireDeps().dispatch({ kind: 'play' }, 'human');
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.stop',
+            title: '停止预览 (Stop)',
+            execute: () => {
+                requireDeps().dispatch({ kind: 'stop' }, 'human');
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.toggleDisplay',
+            title: '切换 Scene / Game 视图',
+            execute: () => {
+                const deps = requireDeps();
+                const next = deps.getDisplay() === 'scene' ? 'game' : 'scene';
+                deps.dispatch({ kind: 'setDisplay', display: next }, 'human');
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.undo',
+            title: '撤销',
+            execute: () => {
+                requireDeps().undo();
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.redo',
+            title: '重做',
+            execute: () => {
+                requireDeps().redo();
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.save',
+            title: '保存',
+            execute: () => {
+                requireDeps().save();
+                return { status: 'completed' };
+            },
+        }));
+        // Application-scoped Mod+S runs before legacy edit shortcuts and is not
+        // gated on the viewport surface anchor. Material / Texture / other asset
+        // document pages replace the viewport dock layout, so isEditorSurfaceActive()
+        // is false there — without this binding Ctrl+S falls through to the browser
+        // "save page" dialog instead of editor.save → material-first save diversion.
+        cleanups.push(host.keybindings.register({
+            commandId: 'editor.save',
+            keys: 'Mod+S',
+            scope: APPLICATION_KEYBINDING_SCOPE,
+            allowInEditable: true,
+            priority: 100,
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.selectAll',
+            title: '全选实体',
+            execute: async () => {
+                if (await executeFocusedTextEditAction('selectAll')) {
+                    return { status: 'completed' };
+                }
+                requireDeps().selectAllEntities();
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.deselect',
+            title: '清除选择',
+            execute: () => {
+                requireDeps().dispatch({ kind: 'setSelection', id: null }, 'human');
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.frameSelected',
+            title: '聚焦所选',
+            execute: () => {
+                requireDeps().dispatch({ kind: 'requestFrame' }, 'human');
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.delete',
+            title: '删除所选实体',
+            execute: () => {
+                const deps = requireDeps();
+                const ids = deps.getEntitySelection();
+                if (ids.length > 0)
+                    deps.deleteEntities(ids);
+                return { status: 'completed' };
+            },
+        }));
+        // Partial: bus event only, no listener wired yet (see file header). A
+        // future preview/HMR owner in a standalone application subscribes to 'preview:reload'
+        // and forwards to the Play iframe self-reload. `ctx.bus.emit` is typed
+        // against AppBusEventMap which extends Record<string, unknown>, so an
+        // ad-hoc topic name is accepted with an `unknown` payload.
+        cleanups.push(registerCommand({
+            id: 'editor.reloadPreview',
+            title: '重载预览 (partial: 事件已发,尚无消费者)',
+            execute: () => {
+                // Not calling requireDeps() — reloadPreview is decoupled from the
+                // editor gateway; the current path is a bus-event handoff, and a
+                // future consumer may not even need the router deps.
+                ctx.bus.emit('preview:reload', {});
+                return { status: 'completed' };
+            },
+        }));
+        cleanups.push(registerCommand({
+            id: 'editor.restartPreview',
+            title: '重建预览运行时',
+            execute: () => {
+                const restart = requireDeps().restartPreview;
+                if (!restart)
+                    throw new Error('editor.restartPreview: host did not provide restartPreview');
+                restart();
+                return { status: 'completed' };
+            },
+        }));
+        return () => {
+            // Reverse order so first-registered is torn down last — same pattern
+            // as builtin-commands.ts; `.slice()` clones the array so a repeat
+            // unload doesn't mutate the closed-over `cleanups`.
+            for (const c of cleanups.slice().reverse())
+                c();
+        };
+    },
+};

package/dist/package/node/core/extensions/foundation-bus.js

@@ -0,0 +1,3 @@
+export const foundationBusExtension = {
+    id: 'foundation.bus', version: '1.0.0', provides: [], setup() { },
+};

package/dist/package/node/core/extensions/foundation-commands.js

@@ -0,0 +1,6 @@
+export const foundationCommandsExtension = {
+    id: 'foundation.commands',
+    version: '1.0.0',
+    provides: [], // commands is a BASE capability; we do not re-provide.
+    setup() { },
+};

package/dist/package/node/core/extensions/foundation-storage.js

@@ -0,0 +1,3 @@
+export const foundationStorageExtension = {
+    id: 'foundation.storage', version: '1.0.0', provides: [], setup() { },
+};

package/dist/package/node/core/extensions/host-commands.js

@@ -0,0 +1,52 @@
+// Host-side command contracts for chat task-flow actions.
+//
+// Interface owns registration and typed dispatch only. Editor/resource-editor
+// owners subscribe to the AppHost bus and provide the concrete side effects.
+import { publish } from '../../lib/bus.js';
+function requiredString(commandId, args, key) {
+    const value = args?.[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${commandId}: missing { ${key} }`);
+    }
+    return value.trim();
+}
+export const hostCommandsExtension = {
+    id: 'host-commands',
+    version: '1.0.0',
+    requires: ['commands'],
+    setup(ctx) {
+        const cleanups = [];
+        cleanups.push(ctx.registerCommand({
+            id: 'app.files.reveal',
+            title: 'Reveal a file in the resource editor',
+            execute: (args) => {
+                const path = requiredString('app.files.reveal', args, 'path');
+                publish('resource-editor:open-file', { path });
+                ctx.bus.emit('files:reveal', { path });
+                return { status: 'completed', path };
+            },
+        }));
+        cleanups.push(ctx.registerCommand({
+            id: 'app.build.create',
+            title: 'Create a game build',
+            execute: (args) => {
+                const version = requiredString('app.build.create', args, 'version');
+                ctx.bus.emit('build:create', { version });
+                return { status: 'completed', version };
+            },
+        }));
+        cleanups.push(ctx.registerCommand({
+            id: 'app.build.play',
+            title: 'Play a game build',
+            execute: (args) => {
+                const version = requiredString('app.build.play', args, 'version');
+                ctx.bus.emit('build:play', { version });
+                return { status: 'completed', version };
+            },
+        }));
+        return () => {
+            for (const cleanup of cleanups.slice().reverse())
+                cleanup();
+        };
+    },
+};

package/dist/package/node/core/extensions/observability.js

@@ -0,0 +1,18 @@
+import { useShellStore } from '../../store.js';
+export const observabilityExtension = {
+    id: 'observability', version: '1.0.0', provides: ['observability'],
+    setup(ctx) {
+        const cap = {
+            get consoleLog() { return useShellStore.getState().consoleLog; },
+            pushConsole: (e) => useShellStore.getState().pushConsole(e),
+            clearConsole: () => useShellStore.getState().clearConsole(),
+            get networkLog() { return useShellStore.getState().networkLog; },
+            pushNetwork: (e) => useShellStore.getState().pushNetwork(e),
+            clearNetwork: () => useShellStore.getState().clearNetwork(),
+            get telemetry() { return useShellStore.getState().telemetry; },
+            pushTelemetry: (rs) => useShellStore.getState().pushTelemetry(rs),
+            clearTelemetry: () => useShellStore.getState().clearTelemetry(),
+        };
+        ctx.host.extend('observability', cap);
+    },
+};