@forgeax/interface 0.5.0 → 0.6.0

package/dist/package/node/lib/global-shortcuts.js

@@ -10,7 +10,7 @@
  *   Ctrl+/        focus chat composer
  *   Ctrl+Shift+H  open Settings → Changelog (was Ctrl+H before 2026-08-04 —
  *                 UE-parity editor hide claimed Ctrl+H for "show all hidden")
- *   Esc           stop viewport Play; otherwise close current overlay
+ *   Esc           close current overlay (higher-priority owners may claim it)
  *                 (Settings → Dashboard → Fullscreen)
  *
  * IME 安全:
@@ -77,16 +77,9 @@ function mod(e) {
 }
 // Is the scene editor the surface the user is currently looking at?
 //
-// The remaining legacy `edit` group (Ctrl+D / viewport W-E-R-F …) is injected
-// globally at boot and still dispatches against module-level editor selection /
-// viewport state. This coarse surface gate lets those keys escape whenever the editor is
-// not the foreground surface. Two facts, both interface-local (no editor
-// import, no focus/DOM resolver — that larger redesign is ADR-0029 scope; this
-// is its Phase 0 short-term mitigation):
-//   1. an overlay (Dashboard / Settings) is covering the shell, or
-//   2. the editor Page anchor is not currently visible.
-// Read live at event time (cached snapshot — cheap) so switching tab / opening
-// an overlay takes effect immediately.
+// Contributions classified as edit use the product shell's existing surface
+// identity and visibility policy. Read at event time so page/overlay changes
+// take effect without rebuilding the host or listener.
 export function isEditorSurfaceActive() {
     if (useShellStore.getState().activeOverlay)
         return false;
@@ -95,7 +88,6 @@ export function isEditorSurfaceActive() {
         : document.querySelector('[data-surface-anchor="edit"]');
     return Boolean(anchor && anchor.getClientRects().length > 0);
 }
-let routerDeps = null;
 const transientKeydownHandlers = new Set();
 export function registerGlobalKeydownHandler(handler) {
     transientKeydownHandlers.add(handler);
@@ -108,204 +100,9 @@ export function dispatchGlobalKeydownHandlers(event) {
     }
     return false;
 }
-/** Inject the editor-side callbacks the router needs. Called once at host boot
- *  (forgeax-editor standalone/main.tsx) BEFORE the App mounts (useGlobalShortcuts
- *  reads this at effect time, which is after mount, so registration first is safe). */
-export function registerKeyboardRouterDeps(deps) {
-    routerDeps = deps;
-}
-/** Read the currently injected router deps. Returns null until the host has
- *  called registerKeyboardRouterDeps() at boot. Command-bus wrappers
- *  (editor-commands extension) resolve deps lazily via this getter so they
- *  stay editor-agnostic and boot-order-safe. */
-export function getKeyboardRouterDeps() {
-    return routerDeps;
-}
-// Build the edit-domain shortcut list from injected deps. Pure dispatcher: every
-// branch routes through a dep callback (which the editor maps onto gateway ops),
-// so this file stays editor-agnostic. Three-layer guards (IME / typing-target /
-// play-mode) are enforced by the host's onKey wrapper (isComposing / isTypingTarget)
-// plus the per-op play-mode checks below.
-function editShortcuts(deps) {
-    const routeCtrlD = () => {
-        const domain = deps.getLastSelectionDomain() ?? 'entity';
-        if (domain === 'asset') {
-            for (const a of deps.getAssetSelection())
-                deps.duplicateAsset(a.guid, a.packPath);
-            return true;
-        }
-        const ids = deps.getEntitySelection();
-        if (ids.length > 0) {
-            deps.duplicateEntities(ids);
-            return true;
-        }
-        return false;
-    };
-    // UE-parity editor hide (docs 2026-08-04-editor-hide-ue-parity-plan M2):
-    // H hides the selection, Ctrl+H shows every hidden entity, Shift+H hides
-    // the unselected (isolate). Entity-domain only; under Play the game keeps
-    // its keys (same guard as entity Delete).
-    const routeH = () => {
-        if (deps.isPlayMode())
-            return false;
-        const ids = deps.getEntitySelection();
-        if (ids.length === 0)
-            return false;
-        deps.hideEntities(ids);
-        return true;
-    };
-    const routeShiftH = () => {
-        if (deps.isPlayMode())
-            return false;
-        if (deps.getEntitySelection().length === 0)
-            return false;
-        deps.hideUnselected();
-        return true;
-    };
-    const routeCtrlH = () => {
-        if (deps.isPlayMode())
-            return false;
-        deps.showAllHidden();
-        return true;
-    };
-    // Viewport Game View toggle. Plain G is editor-only while not playing so a
-    // running game retains its gameplay binding; Shift+G remains the explicit
-    // Play shortcut and is also available in Edit Viewport.
-    const routeShiftG = () => {
-        deps.dispatch({ kind: 'setDisplay', display: deps.getDisplay() === 'game' ? 'scene' : 'game' }, 'human');
-        return true;
-    };
-    const routeEditorOwnedPlayKey = (e) => {
-        if (!e)
-            return true;
-        deps.handleViewportKeyDown(e);
-        return true;
-    };
-    const routeViewportInput = (e) => {
-        if (!e)
-            return false;
-        if (deps.getInputTarget() === 'game')
-            return false;
-        deps.handleViewportKeyDown(e);
-        return true;
-    };
-    return [
-        {
-            combo: 'Ctrl+D',
-            group: 'edit',
-            label: t('shortcuts.duplicateSelection'),
-            match: (e) => mod(e) && !e.shiftKey && !e.altKey
-                && (e.code === 'KeyD' || safeKeyLower(e) === 'd'),
-            run: routeCtrlD,
-        },
-        {
-            combo: 'H',
-            group: 'edit',
-            label: t('shortcuts.hideSelected'),
-            match: (e) => !mod(e) && !e.shiftKey && !e.altKey && e.code === 'KeyH',
-            run: routeH,
-        },
-        {
-            combo: 'Shift+H',
-            group: 'edit',
-            label: t('shortcuts.hideUnselected'),
-            match: (e) => !mod(e) && e.shiftKey && !e.altKey && e.code === 'KeyH',
-            run: routeShiftH,
-        },
-        {
-            combo: 'Ctrl+H',
-            group: 'edit',
-            label: t('shortcuts.showAllHidden'),
-            match: (e) => mod(e) && !e.shiftKey && !e.altKey && e.code === 'KeyH',
-            run: routeCtrlH,
-        },
-        {
-            combo: 'Shift+G',
-            group: 'edit',
-            label: t('shortcuts.toggleViewportGameView'),
-            match: (e) => !mod(e) && e.shiftKey && !e.altKey
-                && (e.key === 'g' || e.key === 'G'),
-            run: routeShiftG,
-        },
-        {
-            combo: 'G',
-            group: 'edit',
-            label: t('shortcuts.toggleViewportGameView'),
-            match: (e) => !mod(e) && !e.shiftKey && !e.altKey
-                && !deps.isPlayMode() && deps.getInputTarget() !== 'game'
-                && (e.key === 'g' || e.key === 'G'),
-            run: routeShiftG,
-        },
-        {
-            combo: 'Ctrl+Z',
-            group: 'edit',
-            label: t('shortcuts.undo'),
-            allowInInput: true,
-            match: (e) => mod(e) && !e.altKey && !e.shiftKey && (e.code === 'KeyZ' || safeKeyLower(e) === 'z'),
-            run: () => { deps.undo(); return true; },
-        },
-        {
-            combo: 'Ctrl+Shift+Z',
-            group: 'edit',
-            label: t('shortcuts.redo'),
-            allowInInput: true,
-            match: (e) => mod(e) && !e.altKey && e.shiftKey && (e.code === 'KeyZ' || safeKeyLower(e) === 'z'),
-            run: () => { deps.redo(); return true; },
-        },
-        {
-            combo: 'Ctrl+Y',
-            group: 'edit',
-            label: t('shortcuts.redo'),
-            allowInInput: true,
-            match: (e) => mod(e) && !e.altKey && !e.shiftKey && (e.code === 'KeyY' || safeKeyLower(e) === 'y'),
-            run: () => { deps.redo(); return true; },
-        },
-        {
-            combo: 'Ctrl+S',
-            group: 'edit',
-            label: t('shortcuts.save'),
-            // Must fire while typing in Input Map / MI fields (⌘/Ctrl+S is a document
-            // command, not a text-editing key). Without this, focus inside `.im-editor`
-            // makes isTypingTarget true and silently drops save.
-            allowInInput: true,
-            match: (e) => mod(e) && !e.altKey && !e.shiftKey && (e.code === 'KeyS' || safeKeyLower(e) === 's'),
-            run: () => { deps.save(); return true; },
-        },
-        {
-            combo: 'Viewport camera and fly input',
-            group: 'edit',
-            label: t('shortcuts.viewportNavigation'),
-            match: (e) => {
-                if (deps.getInputTarget() === 'game')
-                    return false;
-                const key = safeKeyLower(e);
-                if (!key)
-                    return false;
-                // UE-style view presets (Alt+G/H/J/K) route to the viewport handler,
-                // which owns the camera. All other Alt combos stay excluded here.
-                if (e.altKey) {
-                    return !mod(e) && !e.shiftKey && ['g', 'h', 'j', 'k'].includes(key);
-                }
-                const plainCameraKey = !mod(e)
-                    && (['w', 'e', 'r', 'f', 'a', 's', 'd', 'q', 'v', 'z', 'c', 'escape', 'shift'].includes(key)
-                        || /^[1-9]$/.test(key));
-                const bookmarkKey = mod(e) && !e.shiftKey && /^[1-9]$/.test(key);
-                return plainCameraKey || bookmarkKey;
-            },
-            run: routeViewportInput,
-        },
-        {
-            combo: 'Play editor input shield',
-            group: 'edit',
-            label: t('shortcuts.shieldGameInput'),
-            match: () => deps.isPlayMode() && deps.getInputTarget() !== 'game',
-            run: routeEditorOwnedPlayKey,
-        },
-    ];
-}
-// Build the shortcut registry. Each match() / run() is plain JS so we can
-// drive them from a Settings table later (or a Command Palette).
-export function buildShortcuts() {
+// Build the Settings list in product order, not event-routing priority order.
+// Exact duplicate descriptions share a row, but remain separate runtime owners.
+export function buildShortcuts(contributions) {
     const store = useShellStore.getState;
     const shortcuts = [
         // ── Layout (collapse / fullscreen) ──
@@ -394,13 +191,6 @@ export function buildShortcuts() {
             allowInInput: true,
             match: (e) => e.key === 'Escape' && !mod(e) && !e.shiftKey && !e.altKey,
             run: () => {
-                // Escape is a Play-only viewport shortcut: stop the transient play
-                // session and return to edit mode. The listener stays in the single
-                // global router; outside Play this branch is inactive.
-                if (routerDeps?.isPlayMode()) {
-                    routerDeps.dispatch({ kind: 'stop' }, 'human');
-                    return true;
-                }
                 const s = store();
                 // Browser fullscreen exits automatically on Esc — but be defensive
                 // in case some browser swallows the event before reaching the native
@@ -460,18 +250,29 @@ export function buildShortcuts() {
             },
         },
     ];
-    // Inject the host editor's remaining edit-domain shortcuts when deps were
-    // registered at boot. Focus-owned F2/Delete/Mod+A live in host.keybindings.
-    if (routerDeps)
-        shortcuts.push(...editShortcuts(routerDeps));
     shortcuts.push({
+        priority: -20,
         combo: 'Ctrl+K',
         group: 'general',
         label: t('shortcuts.toggleCommandPalette'),
         match: (e) => mod(e) && !e.altKey && !e.shiftKey && (e.code === 'KeyK' || safeKeyLower(e) === 'k'),
         run: () => { toggleCommandPalette(); return true; },
     });
-    return shortcuts;
+    const shell = shortcuts.map((shortcut) => ({ priority: 10, ...shortcut }));
+    const rowKey = ({ combo, group, label }) => JSON.stringify([combo, group, label]);
+    const seen = new Set(shell.map(rowKey));
+    const contributedRows = [];
+    for (const shortcut of contributions?.snapshot() ?? []) {
+        const key = rowKey(shortcut);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        contributedRows.push(shortcut);
+    }
+    return [...shell.slice(0, -1), ...contributedRows, ...shell.slice(-1)];
+}
+function orderShortcuts(shell, contributions) {
+    return [...shell, ...(contributions?.snapshot() ?? [])].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
 }
 /**
  * Mount once at App root. Returns nothing — purely an effect.
@@ -481,9 +282,9 @@ export function buildShortcuts() {
  * Ctrl+Shift+1/2/3 (which Chrome maps to tab switching only WITHOUT Shift,
  * so we're safe, but we preventDefault anyway).
  */
-export function useGlobalShortcuts(keybindings) {
+export function useGlobalShortcuts(keybindings, contributions) {
     useEffect(() => {
-        const shortcuts = buildShortcuts();
+        const shell = buildShortcuts();
         const onKey = (e) => {
             // 0. IME composing — bail. Never intercept Chinese pinyin chord.
             if (isComposing(e))
@@ -499,11 +300,11 @@ export function useGlobalShortcuts(keybindings) {
             // 2. The contextual resolver gets first refusal inside the ONE capture
             // listener. A handled or disabled-but-claimed binding must not fall into
             // legacy application shortcuts; passthrough/unclaimed continues below.
-            const contextual = keybindings?.handle(e);
+            const contextual = keybindings.handle(e);
             if (contextual?.status === 'handled' || contextual?.status === 'claimed-disabled')
                 return;
-            // 3. Find first matching legacy shortcut.
-            for (const s of shortcuts) {
+            // 3. Read live host contributions after contextual first refusal.
+            for (const s of orderShortcuts(shell, contributions)) {
                 // A focused preview owns camera/fly keys locally. Keep non-edit global
                 // shortcuts available, but never route preview input to the main editor.
                 if (shouldSkipGlobalShortcut(e, s))
@@ -532,7 +333,7 @@ export function useGlobalShortcuts(keybindings) {
             onKeyDown: onKey,
         });
         return disposeKeydownObservation;
-    }, [keybindings]);
+    }, [keybindings, contributions]);
 }
 // macOS pretty-printing for shortcut combos shown in Settings.
 // Returns the canonical UI string. When platform is omitted, auto-detects macOS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/interface",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "ForgeaX product interface shell and application composition boundary.",
   "license": "Apache-2.0",
@@ -92,7 +92,7 @@
     "lint:dep": "depcruise -c .dependency-cruiser.cjs src"
   },
   "dependencies": {
-    "@forgeax/app-shell": "0.86.0",
+    "@forgeax/app-shell": "0.87.1",
     "@forgeax/extension-host": "0.3.2",
     "@forgeax/extension-platform": "0.5.0",
     "@forgeax/toolkit": "0.1.2",

package/dist/package/browser/core/extensions/editor-commands.d.ts

@@ -1,2 +0,0 @@
-import type { AppExtension } from '../app-shell/types';
-export declare const editorCommandsExtension: AppExtension;

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

@@ -1,182 +0,0 @@
-// 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';
-import { getKeyboardRouterDeps } from '../../lib/global-shortcuts';
-import { executeFocusedTextEditAction } from '../../lib/text-edit-actions';
-/** 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();
-        };
-    },
-};