@forgeax/interface 0.4.1 → 0.6.0

package/dist/package/browser/lib/action-registry.d.ts

@@ -1,94 +0,0 @@
-/** action-registry —— UI 语义操作层(产品 AI 化 P0)的单一真值源:
- *  「本产品当前暴露哪些可被人 / AI 调用的功能」。
- *
- *  一张注册表服务三个消费者(压缩公理:消掉「AI 能做的和人能做的是不是同一套?」):
- *    1. 按钮 onClick —— 组件经 `dispatchAction(id, args)` 派发(与 AI 同一条路);
- *    2. 命令面板(P2,cmdk 激活时数据源即本表);
- *    3. AI 工具调用 —— `ui_snapshot` 读清单 / `ui_invoke` 派发,经 lib/ui-bridge.ts
- *       的 perception 往返接到编排层(@forgeax/orchestrator)。
- *
- *  契约形态(评审 2.1):`schema` 的 SSOT 是 **JSON Schema 纯对象**(AI 侧 ToolSpec 与
- *  postMessage 结构化克隆都只吃 JSON;函数永不过 wire)。`available` / `run` 只活在
- *  本模块,manifest(`buildManifest`)只导出可序列化子集。
- *
- *  headless 边界(方案 §5):`surface:'both'` 的 action,UI `run()` 必须调 server 的
- *  同一 HTTP API(server 是行为 SSOT),UI 侧只许加视觉反馈——不许长出独立业务逻辑。
- */
-/** 与编排层 trust-gate 的 Capability 8 类对齐(权限分级的声明值,manifest 里出墙)。 */
-export type UiCapability = 'read' | 'write' | 'delete' | 'exec' | 'network' | 'credential' | 'delegate' | 'other';
-/** 派发结果(评审 2.2 act→observe 合并):
- *  - completed:已完成,`stateDigest` 携带可观察的状态变化(多数场景免掉后续 snapshot);
- *  - accepted:已受理、异步在跑(慢 action 快速返回,勿等勿重试;P0 期完成态靠下次 snapshot 观察);
- *  - rejected:未执行,`reason` 给人话原因(未注册 / 不可用 / 参数校验失败 / run 抛错)。 */
-export interface UiActionResult {
-    status: 'completed' | 'accepted' | 'rejected';
-    reason?: string;
-    stateDigest?: unknown;
-}
-/** JSON Schema 纯对象(不引 zod 类型;zod 只是书写便利,登记时即转换落表)。 */
-export type JsonSchemaObject = Record<string, unknown>;
-export interface UiActionDef {
-    /** 稳定 id,'domain.verb' 形("game.switch" / "panel.toggle_sidebar")。 */
-    id: string;
-    /** 人读标题(菜单 / 命令面板 / 权限卡展示)。 */
-    title: string;
-    /** AI 读说明(manifest 出墙;写清做什么 + 何时用)。 */
-    description?: string;
-    /** 参数契约(JSON Schema 纯对象)。缺省 = 无参数。 */
-    schema?: JsonSchemaObject;
-    /** 权限分级声明 —— 编排层 trust-gate 按此弹卡/直放(delete/credential 会请求用户确认)。 */
-    capability: UiCapability;
-    /** headless 可用性:'ui'(纯视图,须 UI 在线)/ 'server'/'both'(状态型,server 是 SSOT)。 */
-    surface?: 'ui' | 'server' | 'both';
-    /** 预期执行时长(ms)——编排层往返超时据此放宽;慢 action 的正道是快速回 accepted。 */
-    timeoutMs?: number;
-    /** 当前是否可调。返回 string = 不可用 + 人话原因(AI 可读可解释);缺省恒可用。 */
-    available?: () => true | string;
-    /** P1-9 一等工具化:标 true → 编排层从 manifest 派生独立 ToolSpec(ui_act_*)下发
-     *  模型,免一次 snapshot 发现往返。只给高频 action 打标(编排层有数量上限)。 */
-    firstClass?: boolean;
-    /** 「人」界面(命令面板)用的**动态候选值**提供器,按参数名给一列合法取值 —— 让
-     *  自由文本参数(如 game.switch 的 slug)变成下拉,避免瞎填后触发 server 404。
-     *  仅活在客户端(同 run/available,不进 manifest);AI 侧靠 ui_snapshot / 状态片发现,
-     *  不依赖此。静态 `schema.enum` 优先于此(两者都无则退回文本框)。 */
-    choices?: Record<string, () => string[] | Promise<string[]>>;
-    /** 执行体。返回 void 视为 completed;抛错翻成 rejected(fail-soft,不炸往返)。 */
-    run: (args: Record<string, unknown>) => UiActionResult | void | Promise<UiActionResult | void>;
-}
-/** snapshot 状态摘要的一片(评审 2.5:注册式 derive,禁手写台账)。selector 从 store
- *  等真值源读,值必须可序列化(过 JSON.stringify)。 */
-export type StateSliceSelector = () => unknown;
-/** 注册一个 action(同 id 重复注册 = 替换,幂等;HMR 安全)。返回注销函数。 */
-export declare function registerAction(def: UiActionDef): () => void;
-/** 注册一片状态摘要(同 id 替换,幂等)。返回注销函数。 */
-export declare function registerStateSlice(id: string, selector: StateSliceSelector): () => void;
-/** 注册表(action 或 state slice)变更订阅 —— ui-bridge 据此 debounce 重推 manifest。 */
-export declare function onRegistryChange(cb: () => void): () => void;
-export declare function getAction(id: string): UiActionDef | undefined;
-/** AI 派发时打的来源标记;window 事件供 ghost 高亮层(P1)与 telemetry / 轨迹追踪衔接。
- *  detail 形:`{ id, source, args }` —— args 让轨迹追踪(lib/ui-trajectory)记得下「做了啥」,
- *  ghost 高亮只用 id/source(向后兼容,多带的字段无害)。 */
-export declare const UI_ACTION_DISPATCH_EVENT = "forgeax:ui-action-dispatch";
-/** 派发一个 action —— 按钮与 AI 共用的**唯一**执行入口(未注册的 id 拒绝,fail-closed)。 */
-export declare function dispatchAction(id: string, args?: Record<string, unknown>, opts?: {
-    source?: 'human' | 'ai';
-}): Promise<UiActionResult>;
-export interface UiActionSummary {
-    id: string;
-    title: string;
-    available: boolean;
-    reason?: string;
-    /** detail:'schema' 时补上。 */
-    description?: string;
-    inputSchema?: JsonSchemaObject;
-}
-/** ui_snapshot 的 action 视图。分层(评审 2.7):默认轻量清单;detail:'schema' + ids
- *  按需展开 schema 与详细说明(长尾几百 action 也不炸 token)。 */
-export declare function snapshotActions(detail?: string, ids?: string[]): UiActionSummary[];
-/** ui_snapshot 的状态摘要:逐片 derive,单片异常不传染(fail-soft)。 */
-export declare function snapshotState(): Record<string, unknown>;
-/** manifest(POST /:sid/ui-manifest 的 payload)—— 只含可序列化声明,函数永不出墙。
- *  它是编排层 trust-gate 的权限输入:capability 必须如实声明。 */
-export declare function buildManifest(): Array<Record<string, unknown>>;
-/** 测试用:清空注册表(生产代码不要调)。 */
-export declare function __resetRegistryForTest(): void;

package/dist/package/browser/lib/action-registry.js

@@ -1,210 +0,0 @@
-/** action-registry —— UI 语义操作层(产品 AI 化 P0)的单一真值源:
- *  「本产品当前暴露哪些可被人 / AI 调用的功能」。
- *
- *  一张注册表服务三个消费者(压缩公理:消掉「AI 能做的和人能做的是不是同一套?」):
- *    1. 按钮 onClick —— 组件经 `dispatchAction(id, args)` 派发(与 AI 同一条路);
- *    2. 命令面板(P2,cmdk 激活时数据源即本表);
- *    3. AI 工具调用 —— `ui_snapshot` 读清单 / `ui_invoke` 派发,经 lib/ui-bridge.ts
- *       的 perception 往返接到编排层(@forgeax/orchestrator)。
- *
- *  契约形态(评审 2.1):`schema` 的 SSOT 是 **JSON Schema 纯对象**(AI 侧 ToolSpec 与
- *  postMessage 结构化克隆都只吃 JSON;函数永不过 wire)。`available` / `run` 只活在
- *  本模块,manifest(`buildManifest`)只导出可序列化子集。
- *
- *  headless 边界(方案 §5):`surface:'both'` 的 action,UI `run()` 必须调 server 的
- *  同一 HTTP API(server 是行为 SSOT),UI 侧只许加视觉反馈——不许长出独立业务逻辑。
- */
-// ─── 注册表本体(模块级 Map,页级单例)────────────────────────────────────────
-const actions = new Map();
-const stateSlices = new Map();
-const changeListeners = new Set();
-function notifyChange() {
-    for (const cb of changeListeners) {
-        try {
-            cb();
-        }
-        catch {
-            /* listener 异常不传染 */
-        }
-    }
-}
-/** 注册一个 action(同 id 重复注册 = 替换,幂等;HMR 安全)。返回注销函数。 */
-export function registerAction(def) {
-    actions.set(def.id, def);
-    notifyChange();
-    return () => {
-        if (actions.get(def.id) === def) {
-            actions.delete(def.id);
-            notifyChange();
-        }
-    };
-}
-/** 注册一片状态摘要(同 id 替换,幂等)。返回注销函数。 */
-export function registerStateSlice(id, selector) {
-    stateSlices.set(id, selector);
-    notifyChange();
-    return () => {
-        if (stateSlices.get(id) === selector) {
-            stateSlices.delete(id);
-            notifyChange();
-        }
-    };
-}
-/** 注册表(action 或 state slice)变更订阅 —— ui-bridge 据此 debounce 重推 manifest。 */
-export function onRegistryChange(cb) {
-    changeListeners.add(cb);
-    return () => changeListeners.delete(cb);
-}
-export function getAction(id) {
-    return actions.get(id);
-}
-// ─── 派发单入口(评审 2.4:data-* 只做发现,执行永远走这里)──────────────────
-/** AI 派发时打的来源标记;window 事件供 ghost 高亮层(P1)与 telemetry / 轨迹追踪衔接。
- *  detail 形:`{ id, source, args }` —— args 让轨迹追踪(lib/ui-trajectory)记得下「做了啥」,
- *  ghost 高亮只用 id/source(向后兼容,多带的字段无害)。 */
-export const UI_ACTION_DISPATCH_EVENT = 'forgeax:ui-action-dispatch';
-/** 极简 JSON Schema 参数校验(P0:required + 顶层 properties 的原始类型)。
- *  不引 ajv——契约漂移由编排层契约测试兜,这里挡住明显错参即可(Fail Fast)。 */
-function validateArgs(schema, args) {
-    if (!schema)
-        return true;
-    const required = Array.isArray(schema.required) ? schema.required : [];
-    for (const k of required) {
-        if (typeof k === 'string' && !(k in args))
-            return `missing required arg "${k}"`;
-    }
-    const props = schema.properties && typeof schema.properties === 'object'
-        ? schema.properties
-        : {};
-    for (const [k, v] of Object.entries(args)) {
-        const p = props[k];
-        if (!p)
-            continue; // 未声明的多余参数放过(向前兼容),由 run 自行忽略
-        const t = p.type;
-        if (typeof t === 'string') {
-            const actual = Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v;
-            const okType = (t === 'string' && actual === 'string') ||
-                (t === 'number' && actual === 'number') ||
-                (t === 'integer' && actual === 'number' && Number.isInteger(v)) ||
-                (t === 'boolean' && actual === 'boolean') ||
-                (t === 'object' && actual === 'object') ||
-                (t === 'array' && actual === 'array');
-            if (!okType)
-                return `arg "${k}" should be ${t}, got ${actual}`;
-        }
-        if (Array.isArray(p.enum) && !p.enum.includes(v)) {
-            return `arg "${k}" must be one of ${JSON.stringify(p.enum)}`;
-        }
-    }
-    return true;
-}
-/** 派发一个 action —— 按钮与 AI 共用的**唯一**执行入口(未注册的 id 拒绝,fail-closed)。 */
-export async function dispatchAction(id, args = {}, opts = {}) {
-    const src = opts.source ?? 'human';
-    // [fx-action-trace] 定位「点了/调了没反应」的最小充分打点:
-    //   ① entry —— 派发是否发生 + args/source(缺此行 = 根本没触发 dispatch)。
-    //   ② terminal —— 唯一终态行:completed/accepted 带 stateDigest(判「到底改了啥」),
-    //      rejected 带 reason(未注册/不可用/参数错/run 抛错 已统一收敛进 reason)。
-    // 两行即可定位:有 entry 无 terminal = 卡在 run();rejected+reason = 为何被拒;
-    // completed 但 stateDigest 没变 = action 效果与 UI 脱节。故只留这两点(+抛错补栈)。
-    console.info(`%c[fx-action]%c ▶ ${id} (${src})`, 'color:#818cf8;font-weight:bold', 'color:inherit', { args });
-    const done = (r) => {
-        if (r.status === 'rejected') {
-            console.warn(`[fx-action] ✗ ${id} rejected: ${r.reason ?? ''}`);
-        }
-        else {
-            console.info(`%c[fx-action]%c ✔ ${id} → ${r.status}`, 'color:#34d399;font-weight:bold', 'color:inherit', r.stateDigest !== undefined ? { stateDigest: r.stateDigest } : {});
-        }
-        return r;
-    };
-    const def = actions.get(id);
-    if (!def)
-        return done({ status: 'rejected', reason: `unknown action "${id}" (not in the registry)` });
-    const avail = def.available ? safeAvailable(def) : true;
-    if (avail !== true)
-        return done({ status: 'rejected', reason: avail });
-    const valid = validateArgs(def.schema, args);
-    if (valid !== true)
-        return done({ status: 'rejected', reason: valid });
-    try {
-        window.dispatchEvent(new CustomEvent(UI_ACTION_DISPATCH_EVENT, { detail: { id, source: src, args } }));
-    }
-    catch {
-        /* SSR / no window — ignore */
-    }
-    try {
-        const out = await def.run(args);
-        return done(out ?? { status: 'completed' });
-    }
-    catch (e) {
-        console.error(`[fx-action] ✗ ${id} threw`, e); // 抛错补一行栈(定位真异常)
-        return done({ status: 'rejected', reason: `action "${id}" threw: ${e instanceof Error ? e.message : String(e)}` });
-    }
-}
-function safeAvailable(def) {
-    try {
-        return def.available();
-    }
-    catch (e) {
-        return `availability check threw: ${e instanceof Error ? e.message : String(e)}`;
-    }
-}
-/** ui_snapshot 的 action 视图。分层(评审 2.7):默认轻量清单;detail:'schema' + ids
- *  按需展开 schema 与详细说明(长尾几百 action 也不炸 token)。 */
-export function snapshotActions(detail, ids) {
-    const expand = detail === 'schema' ? new Set(ids ?? []) : null;
-    const out = [];
-    for (const def of actions.values()) {
-        const avail = def.available ? safeAvailable(def) : true;
-        const row = {
-            id: def.id,
-            title: def.title,
-            available: avail === true,
-            ...(avail === true ? {} : { reason: avail }),
-        };
-        if (expand?.has(def.id)) {
-            if (def.description)
-                row.description = def.description;
-            row.inputSchema = def.schema ?? { type: 'object', properties: {} };
-        }
-        out.push(row);
-    }
-    return out;
-}
-/** ui_snapshot 的状态摘要:逐片 derive,单片异常不传染(fail-soft)。 */
-export function snapshotState() {
-    const out = {};
-    for (const [id, selector] of stateSlices) {
-        try {
-            out[id] = selector();
-        }
-        catch (e) {
-            out[id] = { error: `state slice threw: ${e instanceof Error ? e.message : String(e)}` };
-        }
-    }
-    return out;
-}
-/** manifest(POST /:sid/ui-manifest 的 payload)—— 只含可序列化声明,函数永不出墙。
- *  它是编排层 trust-gate 的权限输入:capability 必须如实声明。 */
-export function buildManifest() {
-    const out = [];
-    for (const def of actions.values()) {
-        out.push({
-            id: def.id,
-            title: def.title,
-            ...(def.description ? { description: def.description } : {}),
-            inputSchema: def.schema ?? { type: 'object', properties: {} },
-            capability: def.capability,
-            ...(def.surface ? { surface: def.surface } : {}),
-            ...(def.timeoutMs ? { timeoutMs: def.timeoutMs } : {}),
-            ...(def.firstClass ? { firstClass: true } : {}),
-        });
-    }
-    return out;
-}
-/** 测试用:清空注册表(生产代码不要调)。 */
-export function __resetRegistryForTest() {
-    actions.clear();
-    stateSlices.clear();
-    changeListeners.clear();
-}

package/dist/package/node/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.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();
-        };
-    },
-};