@forgeax/interface 0.4.1 → 0.5.0

package/README.md

@@ -2,6 +2,32 @@
 
 forgeax 前端工程（Studio 三栏 UI）。
 
+## Public action registry migration (0.5.0)
+
+> [!IMPORTANT]
+> Action registration and dispatch now belong to `@forgeax/app-shell/application`.
+> Interface no longer exports these functions or their types through `application`
+> or `lib/action-registry`. Consumers must use the same exact App Shell version as
+> Interface so product discovery and external registration share one registry.
+
+```ts
+import {
+  dispatchAction,
+  registerAction,
+  type UiActionDef,
+} from '@forgeax/app-shell/application';
+```
+
+| App Shell owns | Interface retains |
+| :-- | :-- |
+| Registration, replacement-safe disposal and registry notifications | Product action definitions and capability declarations |
+| Dispatch validation, source events and structured results | Handler behavior, permission decisions and visual feedback |
+| Derived action/state snapshots and manifest metadata | DOM discovery, command-palette presentation and bridge wiring |
+
+Application startup, normal/detached shells and global CSS remain Interface
+entrypoints. This change removes the registry implementation, not those product
+dependencies; it adds no compatibility facade or second action registry.
+
 ## 技术栈
 
 - **Bun** runtime · **Vite 6** dev server · **React 19** · **TypeScript**

package/dist/package/browser/application.d.ts

@@ -31,5 +31,3 @@ export declare function startInterfaceApplication(overrides?: AppHostBootstrapOv
 export type { AppHostBootstrapOverrides } from './appHostBootstrap';
 export type { KeyboardRouterDeps } from './lib/global-shortcuts';
 export { configureStudioDomainClients, type StudioDomainClients, } from './store-parts/domain-clients';
-export { dispatchAction, registerAction } from './lib/action-registry';
-export type { JsonSchemaObject, UiActionDef, UiActionResult, UiCapability, } from './lib/action-registry';

package/dist/package/browser/application.js

@@ -61,4 +61,3 @@ export async function startInterfaceApplication(overrides = {}, options = {}) {
 // Product boot injects the existing domain authority without importing store
 // internals. This is the same configuration function, not another client registry.
 export { configureStudioDomainClients, } from './store-parts/domain-clients';
-export { dispatchAction, registerAction } from './lib/action-registry';

package/dist/package/browser/components/CommandPalette/CommandPalette.js

@@ -12,7 +12,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Command } from 'cmdk';
 import { createRestartableTimeoutTaskLifecycle } from '@forgeax/app-shell/react';
-import { dispatchAction, getAction, snapshotActions, } from '../../lib/action-registry';
+import { dispatchAction, getAction, snapshotActions, } from '@forgeax/app-shell/application';
 import { setCommandPaletteOpen, useCommandPaletteOpen } from '../../lib/command-palette-store';
 import './CommandPalette.css';
 /** 从 action 的 JSON Schema 派生顶层参数清单(与 registry 的 validateArgs 同口径)。 */

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

@@ -1,4 +1,4 @@
-import { registerAction, registerStateSlice } from '../../lib/action-registry';
+import { registerAction, registerStateSlice } from '@forgeax/app-shell/application';
 import { TRAJECTORY_MAX, clearTrajectory, readTrajectory, startTrajectoryRecording, } from '../../lib/ui-trajectory';
 /** 随每次 ui_snapshot 内联出墙的尾部条数(压 token;更多靠 trajectory.read 拉)。 */
 const SNAPSHOT_TAIL = 20;

package/dist/package/browser/lib/action-dom-discovery.js

@@ -12,7 +12,7 @@
  *    data-fx-capability   权限分级(8 类之一;缺省 'other'。危险按钮**务必**标
  *                         delete/credential,编排层会据此弹确认卡)
  */
-import { registerAction } from './action-registry';
+import { registerAction } from '@forgeax/app-shell/application';
 const VALID_CAPS = new Set([
     'read', 'write', 'delete', 'exec', 'network', 'credential', 'delegate', 'other',
 ]);

package/dist/package/browser/lib/ai-intents.js

@@ -1,4 +1,4 @@
-import { getAction } from './action-registry';
+import { getAction } from '@forgeax/app-shell/application';
 /** 按 RefDescriptor.kind 的专属 intent(SSOT:每类可引用单元的 AI 动作都列在这里)。 */
 const KIND_INTENTS = {
     'console-row': [

package/dist/package/browser/lib/builtin-actions.js

@@ -8,7 +8,7 @@
  *  surface 口径(方案 §5):纯视图操作 'ui';背后是 server REST 的标 'both'(headless
  *  等价路径 P1 接线,声明先行,UI run() 已经就是调同一 HTTP API,server 是行为 SSOT)。
  */
-import { registerAction, registerStateSlice } from './action-registry';
+import { registerAction, registerStateSlice } from '@forgeax/app-shell/application';
 import { getSessionClient } from '../store-parts/session-client';
 import { useShellStore, tabLabel } from '../store';
 import { openExtensionPage, resolveRegisteredOverlayId } from '../core/page-navigation';

package/dist/package/browser/lib/ui-action-highlight.js

@@ -7,7 +7,7 @@
  *  纯 DOM overlay,零 store 依赖,装不上(SSR)静默跳过;观测层绝不影响派发主流程。
  */
 import { installCustomEventObservation } from '@forgeax/app-shell/react';
-import { UI_ACTION_DISPATCH_EVENT, getAction } from './action-registry';
+import { UI_ACTION_DISPATCH_EVENT, getAction } from '@forgeax/app-shell/application';
 const STYLE_ID = 'fx-ui-action-highlight-style';
 const BADGE_ID = 'fx-ui-action-badge';
 const HIGHLIGHT_CSS = `

package/dist/package/browser/lib/ui-bridge.js

@@ -13,7 +13,7 @@
  */
 import { installWindowMessageObservation } from '@forgeax/app-shell/react';
 import { getSessionClient, hasSessionClient } from '../store-parts/session-client';
-import { buildManifest, dispatchAction, onRegistryChange, snapshotActions, snapshotState, } from './action-registry';
+import { buildManifest, dispatchAction, onRegistryChange, snapshotActions, snapshotState, } from '@forgeax/app-shell/application';
 import { registerBuiltinActions } from './builtin-actions';
 import { startActionDomDiscovery } from './action-dom-discovery';
 import { installUiActionHighlight } from './ui-action-highlight';

package/dist/package/browser/lib/ui-trajectory.js

@@ -9,7 +9,7 @@
  *  可序列化:entry 只含原始标量 / 浅裁剪后的 args,过得了 snapshotState 的 JSON 出墙。
  *  隐私:credential 级 action 的 args 整体打码(不把密钥类入参喂进 AI 上下文)。 */
 import { installCustomEventObservation } from '@forgeax/app-shell/react';
-import { getAction, UI_ACTION_DISPATCH_EVENT } from './action-registry';
+import { getAction, UI_ACTION_DISPATCH_EVENT } from '@forgeax/app-shell/application';
 // 环形缓冲容量 == `trajectory.read` 单次可拉上限(readTrajectory 用它收敛 limit)。
 // 二者本就相等,故一个常量封两处:内存占用,以及 AI 一次拉取的**最坏上下文体积**
 // (SNAPSHOT_TAIL 20 条随每次 ui_snapshot 出墙不受此限;这里管的是按需 read 的天花板)。

package/dist/package/browser/lib/vag-action-bridge.js

@@ -15,7 +15,7 @@
  *  是 host 半边,协议以此为准)。
  */
 import { installWindowMessageObservation } from '@forgeax/app-shell/react';
-import { registerAction } from './action-registry';
+import { registerAction } from '@forgeax/app-shell/application';
 import { isTrustedMessageOrigin } from './trustedOrigins';
 const VALID_CAPS = new Set([
     'read', 'write', 'delete', 'exec', 'network', 'credential', 'delegate', 'other',

package/dist/package/node/application.js

@@ -61,4 +61,3 @@ export async function startInterfaceApplication(overrides = {}, options = {}) {
 // Product boot injects the existing domain authority without importing store
 // internals. This is the same configuration function, not another client registry.
 export { configureStudioDomainClients, } from './store-parts/domain-clients.js';
-export { dispatchAction, registerAction } from './lib/action-registry.js';

package/dist/package/node/components/CommandPalette/CommandPalette.js

@@ -12,7 +12,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Command } from 'cmdk';
 import { createRestartableTimeoutTaskLifecycle } from '@forgeax/app-shell/react';
-import { dispatchAction, getAction, snapshotActions, } from '../../lib/action-registry.js';
+import { dispatchAction, getAction, snapshotActions, } from '@forgeax/app-shell/application';
 import { setCommandPaletteOpen, useCommandPaletteOpen } from '../../lib/command-palette-store.js';
 
 /** 从 action 的 JSON Schema 派生顶层参数清单(与 registry 的 validateArgs 同口径)。 */

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

@@ -1,4 +1,4 @@
-import { registerAction, registerStateSlice } from '../../lib/action-registry.js';
+import { registerAction, registerStateSlice } from '@forgeax/app-shell/application';
 import { TRAJECTORY_MAX, clearTrajectory, readTrajectory, startTrajectoryRecording, } from '../../lib/ui-trajectory.js';
 /** 随每次 ui_snapshot 内联出墙的尾部条数(压 token;更多靠 trajectory.read 拉)。 */
 const SNAPSHOT_TAIL = 20;

package/dist/package/node/lib/action-dom-discovery.js

@@ -12,7 +12,7 @@
  *    data-fx-capability   权限分级(8 类之一;缺省 'other'。危险按钮**务必**标
  *                         delete/credential,编排层会据此弹确认卡)
  */
-import { registerAction } from './action-registry.js';
+import { registerAction } from '@forgeax/app-shell/application';
 const VALID_CAPS = new Set([
     'read', 'write', 'delete', 'exec', 'network', 'credential', 'delegate', 'other',
 ]);

package/dist/package/node/lib/ai-intents.js

@@ -1,4 +1,4 @@
-import { getAction } from './action-registry.js';
+import { getAction } from '@forgeax/app-shell/application';
 /** 按 RefDescriptor.kind 的专属 intent(SSOT:每类可引用单元的 AI 动作都列在这里)。 */
 const KIND_INTENTS = {
     'console-row': [

package/dist/package/node/lib/builtin-actions.js

@@ -8,7 +8,7 @@
  *  surface 口径(方案 §5):纯视图操作 'ui';背后是 server REST 的标 'both'(headless
  *  等价路径 P1 接线,声明先行,UI run() 已经就是调同一 HTTP API,server 是行为 SSOT)。
  */
-import { registerAction, registerStateSlice } from './action-registry.js';
+import { registerAction, registerStateSlice } from '@forgeax/app-shell/application';
 import { getSessionClient } from '../store-parts/session-client.js';
 import { useShellStore, tabLabel } from '../store.js';
 import { openExtensionPage, resolveRegisteredOverlayId } from '../core/page-navigation.js';

package/dist/package/node/lib/ui-action-highlight.js

@@ -7,7 +7,7 @@
  *  纯 DOM overlay,零 store 依赖,装不上(SSR)静默跳过;观测层绝不影响派发主流程。
  */
 import { installCustomEventObservation } from '@forgeax/app-shell/react';
-import { UI_ACTION_DISPATCH_EVENT, getAction } from './action-registry.js';
+import { UI_ACTION_DISPATCH_EVENT, getAction } from '@forgeax/app-shell/application';
 const STYLE_ID = 'fx-ui-action-highlight-style';
 const BADGE_ID = 'fx-ui-action-badge';
 const HIGHLIGHT_CSS = `

package/dist/package/node/lib/ui-bridge.js

@@ -13,7 +13,7 @@
  */
 import { installWindowMessageObservation } from '@forgeax/app-shell/react';
 import { getSessionClient, hasSessionClient } from '../store-parts/session-client.js';
-import { buildManifest, dispatchAction, onRegistryChange, snapshotActions, snapshotState, } from './action-registry.js';
+import { buildManifest, dispatchAction, onRegistryChange, snapshotActions, snapshotState, } from '@forgeax/app-shell/application';
 import { registerBuiltinActions } from './builtin-actions.js';
 import { startActionDomDiscovery } from './action-dom-discovery.js';
 import { installUiActionHighlight } from './ui-action-highlight.js';

package/dist/package/node/lib/ui-trajectory.js

@@ -9,7 +9,7 @@
  *  可序列化:entry 只含原始标量 / 浅裁剪后的 args,过得了 snapshotState 的 JSON 出墙。
  *  隐私:credential 级 action 的 args 整体打码(不把密钥类入参喂进 AI 上下文)。 */
 import { installCustomEventObservation } from '@forgeax/app-shell/react';
-import { getAction, UI_ACTION_DISPATCH_EVENT } from './action-registry.js';
+import { getAction, UI_ACTION_DISPATCH_EVENT } from '@forgeax/app-shell/application';
 // 环形缓冲容量 == `trajectory.read` 单次可拉上限(readTrajectory 用它收敛 limit)。
 // 二者本就相等,故一个常量封两处:内存占用,以及 AI 一次拉取的**最坏上下文体积**
 // (SNAPSHOT_TAIL 20 条随每次 ui_snapshot 出墙不受此限;这里管的是按需 read 的天花板)。

package/dist/package/node/lib/vag-action-bridge.js

@@ -15,7 +15,7 @@
  *  是 host 半边,协议以此为准)。
  */
 import { installWindowMessageObservation } from '@forgeax/app-shell/react';
-import { registerAction } from './action-registry.js';
+import { registerAction } from '@forgeax/app-shell/application';
 import { isTrustedMessageOrigin } from './trustedOrigins.js';
 const VALID_CAPS = new Set([
     'read', 'write', 'delete', 'exec', 'network', 'credential', 'delegate', 'other',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/interface",
-  "version": "0.4.1",
+  "version": "0.5.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.84.0",
+    "@forgeax/app-shell": "0.86.0",
     "@forgeax/extension-host": "0.3.2",
     "@forgeax/extension-platform": "0.5.0",
     "@forgeax/toolkit": "0.1.2",

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/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();
-}