@forgeax/interface 0.4.1

package/dist/package/browser/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';
+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();
+        };
+    },
+};

package/dist/package/browser/core/extensions/foundation-bus.d.ts

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

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

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

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

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

package/dist/package/browser/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/browser/core/extensions/foundation-storage.d.ts

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

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

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

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

@@ -0,0 +1,18 @@
+import type { AppExtension } from '../app-shell/types';
+export interface FilesRevealArgs {
+    path: string;
+}
+export interface BuildCreateArgs {
+    version: string;
+}
+export interface BuildPlayArgs {
+    version: string;
+}
+export interface HostCommandArgsById {
+    'app.files.reveal': FilesRevealArgs;
+    'app.build.create': BuildCreateArgs;
+    'app.build.play': BuildPlayArgs;
+}
+export type HostCommandId = keyof HostCommandArgsById;
+export type HostCommandArgs<I extends HostCommandId = HostCommandId> = HostCommandArgsById[I];
+export declare const hostCommandsExtension: AppExtension;

package/dist/package/browser/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';
+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/browser/core/extensions/observability.d.ts

@@ -0,0 +1,14 @@
+import type { AppExtension } from '../app-shell/types';
+import type { ConsoleEntry, NetworkEntry, TelemetryRecord } from '../../store';
+export interface ObservabilityApi {
+    readonly consoleLog: readonly ConsoleEntry[];
+    pushConsole(entry: ConsoleEntry): void;
+    clearConsole(): void;
+    readonly networkLog: readonly NetworkEntry[];
+    pushNetwork(entry: NetworkEntry): void;
+    clearNetwork(): void;
+    readonly telemetry: readonly TelemetryRecord[];
+    pushTelemetry(records: TelemetryRecord[]): void;
+    clearTelemetry(): void;
+}
+export declare const observabilityExtension: AppExtension;

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

@@ -0,0 +1,18 @@
+import { useShellStore } from '../../store';
+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);
+    },
+};

package/dist/package/browser/core/extensions/panels-chat.d.ts

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

package/dist/package/browser/core/extensions/panels-chat.js

@@ -0,0 +1,41 @@
+import { buildAssetPill, requestComposerInsert } from '../../lib/composer-bridge';
+export const panelsChatExtension = {
+    id: 'panels.chat',
+    version: '1.0.0',
+    requires: ['commands'],
+    setup(ctx) {
+        const cleanups = [];
+        cleanups.push(ctx.registerCommand({
+            id: 'app.chat.insertPill',
+            title: 'Insert reference pill into chat composer',
+            execute: (args) => {
+                const p = args;
+                if (!p?.pill)
+                    throw new Error('app.chat.insertPill: missing { pill }');
+                requestComposerInsert(p.pill);
+                return { status: 'completed' };
+            },
+        }));
+        // Public reference channel for callers outside interface (e.g. the editor's
+        // page-tab menu): build the asset pill here so the composer-bridge stays an
+        // interface-internal detail and cross-package callers only touch commands.
+        cleanups.push(ctx.registerCommand({
+            id: 'app.chat.referenceAsset',
+            title: 'Reference an asset in the chat composer',
+            execute: (args) => {
+                const a = args;
+                if (!a?.guid)
+                    throw new Error('app.chat.referenceAsset: missing { guid }');
+                requestComposerInsert(buildAssetPill({
+                    guid: a.guid,
+                    ...(a.name ? { name: a.name } : {}),
+                    ...(a.assetKind ? { assetKind: a.assetKind } : {}),
+                    ...(a.packPath ? { packPath: a.packPath } : {}),
+                }));
+                return { status: 'completed' };
+            },
+        }));
+        return () => { for (const c of cleanups)
+            c(); };
+    },
+};

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

@@ -0,0 +1,8 @@
+import type { AppExtension } from '../app-shell/types';
+import type { PanelRenderers } from '../../components/DockShell/panelRenderers';
+export interface PanelsEditorOptions {
+    readonly editorPanelIds?: readonly string[];
+    readonly panels?: PanelRenderers['panels'];
+    readonly surfaces?: PanelRenderers['surfaces'];
+}
+export declare function createPanelsEditorExtension(opts?: PanelsEditorOptions): AppExtension;

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

@@ -0,0 +1,26 @@
+import { DEFAULT_EDITOR_PANEL_IDS } from '../../components/DockShell/panelRenderers';
+export function createPanelsEditorExtension(opts = {}) {
+    return {
+        id: 'panels.editor', version: '1.0.0',
+        requires: ['commands'],
+        contributes: {
+            panels: {
+                editorPanelIds: opts.editorPanelIds ?? DEFAULT_EDITOR_PANEL_IDS,
+                panels: opts.panels,
+                surfaces: opts.surfaces,
+            },
+        },
+        setup(ctx) {
+            return ctx.registerCommand({
+                id: 'app.editor.focus',
+                title: 'Focus an editor panel by short id (hierarchy / assets / mesh / ...)',
+                execute: (args) => {
+                    const p = args;
+                    if (!p?.panel)
+                        throw new Error('app.editor.focus: missing { panel }');
+                    return ctx.host.commands.execute('app.panel.focus', { id: `ep:${p.panel}` });
+                },
+            });
+        },
+    };
+}

package/dist/package/browser/core/extensions/panels-viewport.d.ts

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

package/dist/package/browser/core/extensions/panels-viewport.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ViewportPanel } from '../../components/MainArea/SurfacePanels';
+export const panelsViewportExtension = {
+    id: 'panels.viewport',
+    version: '1.0.0',
+    contributes: {
+        panels: {
+            panels: {
+                viewport: {
+                    title: 'Viewport',
+                    order: 0,
+                    header: { visible: true, showTitle: false },
+                    content: { padding: 'none', scroll: 'none', tone: 'tool' },
+                    dockChrome: { singleTab: 'hideTitle' },
+                    render: () => _jsx(ViewportPanel, {}),
+                },
+            },
+        },
+    },
+};

package/dist/package/browser/core/extensions/session-client.d.ts

@@ -0,0 +1,29 @@
+import type { AppExtension } from '../app-shell/types';
+import type { SessionClient } from '../../store-parts/session-client';
+import type { ChatTab, CloseSessionResult, RefreshSessionsResult } from '../../store';
+export interface SessionCapability {
+    /** Low-level session client (REST + WS). Same instance
+     *  `getSessionClient()` returns everywhere else. */
+    readonly client: SessionClient;
+    /** Snapshot of `useShellStore.getState().tabs`. */
+    readonly tabs: readonly ChatTab[];
+    /** Snapshot of `useShellStore.getState().activeSid`. */
+    readonly activeSid: string | null;
+    /** Snapshot of the server-authoritative active game projection. */
+    readonly activeGameSlug: string | null;
+    switchToSession(sid: string): Promise<void>;
+    /** Wraps `useShellStore.getState().createNewSession`. Returns `null` on
+     *  failure to mirror the store's contract. */
+    createSession(opts?: {
+        displayName?: string;
+        scope?: string;
+        providerOverride?: string | null;
+    }): Promise<{
+        sid: string;
+    } | null>;
+    closeSession(sid: string): Promise<CloseSessionResult>;
+    renameTab(sid: string, displayName: string): void;
+    refreshSessions(): Promise<RefreshSessionsResult>;
+    setActiveGame(slug: string): Promise<void>;
+}
+export declare const sessionClientExtension: AppExtension;

package/dist/package/browser/core/extensions/session-client.js

@@ -0,0 +1,42 @@
+// packages/interface/src/core/extensions/session-client.ts
+//
+// host.session capability — bridges the legacy useShellStore session slice so
+// non-React callers (event handlers, module-level code, other plugins) can
+// reach session state/methods through the AppHost instead of importing the
+// store directly.
+//
+// This is a thin capability object, NOT a reactivity source: read-getters
+// snapshot `useShellStore.getState()` on each access; components that need to
+// re-render on session changes must keep subscribing to useShellStore. The
+// per-callsite migration (and eventual slice deletion) lands in T24.
+import { useShellStore } from '../../store';
+import { getSessionClient, hasSessionClient } from '../../store-parts/session-client';
+export const sessionClientExtension = {
+    id: 'session-client',
+    version: '1.0.0',
+    provides: ['session'],
+    setup(ctx) {
+        // Graceful degradation: interface-alone / standalone-editor hosts have no
+        // forgeax-server, so the composition root never configures a client. Skip
+        // providing host.session (consumers already narrow with `if (host.session)`)
+        // instead of throwing the shell boot into console.error.
+        if (!hasSessionClient()) {
+            ctx.log.info('[session-client] no client configured — host.session skipped (studio-only capability)');
+            return;
+        }
+        const client = getSessionClient();
+        const cap = {
+            client,
+            get tabs() { return useShellStore.getState().tabs; },
+            get activeSid() { return useShellStore.getState().activeSid; },
+            get activeGameSlug() { return useShellStore.getState().activeGameSlug; },
+            switchToSession: (sid) => useShellStore.getState().switchToSession(sid),
+            createSession: (opts) => useShellStore.getState().createNewSession(opts),
+            closeSession: (sid) => useShellStore.getState().closeSession(sid),
+            renameTab: (sid, n) => useShellStore.getState().renameTab(sid, n),
+            refreshSessions: () => useShellStore.getState().refreshSessions(),
+            setActiveGame: async (slug) => { await useShellStore.getState().setActiveGame(slug); },
+        };
+        ctx.host.extend('session', cap);
+    },
+};

package/dist/package/browser/core/extensions/slots-corner-agent-picker.d.ts

@@ -0,0 +1,5 @@
+import type React from 'react';
+import type { AppExtension } from '../app-shell/types';
+export declare function createSlotsCornerAgentPickerExtension(CornerAgentPicker: React.ComponentType<{
+    preferredAgentExtensionId?: string;
+}>): AppExtension;

package/dist/package/browser/core/extensions/slots-corner-agent-picker.js

@@ -0,0 +1,6 @@
+export function createSlotsCornerAgentPickerExtension(CornerAgentPicker) {
+    return {
+        id: 'slots.corner-agent-picker', version: '1.0.0',
+        contributes: { panels: { slots: { CornerAgentPicker } } },
+    };
+}

package/dist/package/browser/core/extensions/slots-main-area-body.d.ts

@@ -0,0 +1,3 @@
+import type React from 'react';
+import type { AppExtension } from '../app-shell/types';
+export declare function createSlotsMainAreaBodyExtension(MainAreaBody: React.ComponentType): AppExtension;

package/dist/package/browser/core/extensions/slots-main-area-body.js

@@ -0,0 +1,6 @@
+export function createSlotsMainAreaBodyExtension(MainAreaBody) {
+    return {
+        id: 'slots.main-area-body', version: '1.0.0',
+        contributes: { panels: { slots: { MainAreaBody } } },
+    };
+}

package/dist/package/browser/core/extensions/slots-sidebar-agents.d.ts

@@ -0,0 +1,3 @@
+import type React from 'react';
+import type { AppExtension } from '../app-shell/types';
+export declare function createSlotsSidebarAgentsExtension(SidebarAgents: React.ComponentType): AppExtension;

package/dist/package/browser/core/extensions/slots-sidebar-agents.js

@@ -0,0 +1,6 @@
+export function createSlotsSidebarAgentsExtension(SidebarAgents) {
+    return {
+        id: 'slots.sidebar-agents', version: '1.0.0',
+        contributes: { panels: { slots: { SidebarAgents } } },
+    };
+}

package/dist/package/browser/core/extensions/studio-domain-clients.d.ts

@@ -0,0 +1,12 @@
+import type { AppExtension } from '../app-shell/types';
+import type { AgentCatalogClient, StudioBuildClient, StudioProjectClient } from '../../store-parts/domain-clients';
+export interface AgentCatalogCapability {
+    readonly client: AgentCatalogClient;
+}
+export interface ProjectCapability {
+    readonly client: StudioProjectClient;
+}
+export interface BuildCapability {
+    readonly client: StudioBuildClient;
+}
+export declare const studioDomainClientsExtension: AppExtension;

package/dist/package/browser/core/extensions/studio-domain-clients.js

@@ -0,0 +1,15 @@
+import { getAgentCatalogClient, getStudioBuildClient, getStudioProjectClient, hasStudioDomainClients, } from '../../store-parts/domain-clients';
+export const studioDomainClientsExtension = {
+    id: 'studio-domain-clients',
+    version: '1.0.0',
+    provides: ['agentCatalog', 'projects', 'builds'],
+    setup(ctx) {
+        if (!hasStudioDomainClients()) {
+            ctx.log.info('[studio-domain-clients] no clients configured; standalone hosts keep domain capabilities absent');
+            return;
+        }
+        ctx.host.extend('agentCatalog', { client: getAgentCatalogClient() });
+        ctx.host.extend('projects', { client: getStudioProjectClient() });
+        ctx.host.extend('builds', { client: getStudioBuildClient() });
+    },
+};

package/dist/package/browser/core/extensions/surfaces-scene-editor.d.ts

@@ -0,0 +1,3 @@
+import type React from 'react';
+import type { AppExtension } from '../app-shell/types';
+export declare function createSurfacesSceneEditorExtension(SceneEditor: React.ComponentType): AppExtension;

package/dist/package/browser/core/extensions/surfaces-scene-editor.js

@@ -0,0 +1,6 @@
+export function createSurfacesSceneEditorExtension(SceneEditor) {
+    return {
+        id: 'surfaces.scene-editor', version: '1.0.0',
+        contributes: { panels: { surfaces: { SceneEditor } } },
+    };
+}

package/dist/package/browser/core/extensions/trajectory.d.ts

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

package/dist/package/browser/core/extensions/trajectory.js

@@ -0,0 +1,50 @@
+import { registerAction, registerStateSlice } from '../../lib/action-registry';
+import { TRAJECTORY_MAX, clearTrajectory, readTrajectory, startTrajectoryRecording, } from '../../lib/ui-trajectory';
+/** 随每次 ui_snapshot 内联出墙的尾部条数(压 token;更多靠 trajectory.read 拉)。 */
+const SNAPSHOT_TAIL = 20;
+export const trajectoryExtension = {
+    id: 'trajectory',
+    version: '1.0.0',
+    setup() {
+        const stopRecording = startTrajectoryRecording();
+        // ① 观察上下文:最近 N 条操作随每次 ui_snapshot 自动出墙。
+        const offSlice = registerStateSlice('ui.trajectory', () => readTrajectory({ limit: SNAPSHOT_TAIL }).entries);
+        // ② 按需读取(firstClass:模型直接看到这条工具,免一次 snapshot 发现往返)。
+        const offRead = registerAction({
+            id: 'trajectory.read',
+            title: '读取操作轨迹',
+            description: 'Read the recent trajectory of UI operations performed on the page by BOTH the human and the AI, ordered oldest→newest. Every operation dispatched through the action registry is recorded (page mode switches, panel toggles, session/game/role/extension ops, etc.). Use this to understand what the user just did before asking you something. Params: limit (default 50, max ' +
+                TRAJECTORY_MAX +
+                '), source ("human"|"ai" to filter by who performed it). Returns { total, count, entries:[{seq,ts,id,title,source,capability,args}] } in the result.',
+            schema: {
+                type: 'object',
+                properties: {
+                    limit: { type: 'number' },
+                    source: { type: 'string', enum: ['human', 'ai'] },
+                },
+            },
+            capability: 'read',
+            firstClass: true,
+            surface: 'ui',
+            run: (args) => {
+                const limit = typeof args.limit === 'number' ? args.limit : undefined;
+                const source = args.source === 'human' || args.source === 'ai' ? args.source : undefined;
+                return { status: 'completed', stateDigest: readTrajectory({ limit, source }) };
+            },
+        });
+        const offClear = registerAction({
+            id: 'trajectory.clear',
+            title: '清空操作轨迹',
+            description: 'Clear the recorded UI operation trajectory buffer. Returns { cleared } — how many entries were removed.',
+            capability: 'write',
+            surface: 'ui',
+            run: () => ({ status: 'completed', stateDigest: { cleared: clearTrajectory() } }),
+        });
+        return () => {
+            stopRecording();
+            offSlice();
+            offRead();
+            offClear();
+        };
+    },
+};

package/dist/package/browser/core/page-navigation.d.ts

@@ -0,0 +1 @@
+export { extensionPageMatches, installPageNavigation, openExtensionPage, openPageType, openResource, resolveRegisteredOverlayId, } from '@forgeax/app-shell/application';