@aotui/runtime 1.0.0

package/dist/spi/app/public-types.d.ts

@@ -0,0 +1,309 @@
+/**
+ * SPI App Layer - Public Types for App Developers
+ *
+ * [P4/P5 FIX] 类型定义碎片化修复
+ *
+ * 这些接口是 App 开发者可见的公共 API。
+ * SDK 应该 re-export 这些类型，而不是定义自己的版本。
+ *
+ * 设计原则:
+ * 1. 使用 string 替代 Branded Types (AppID, ViewID 等) - 降低开发者心智负担
+ * 2. 只暴露 App 开发者需要的最小接口 - 接口隔离原则 (ISP)
+ * 3. 作为 SSOT (Single Source of Truth) - SDK 和应用层都从这里导入
+ *
+ * @module @aotui/runtime/spi/app/public-types
+ */
+import type { IView } from './view.interface.js';
+/**
+ * View 元数据接口 - App 开发者的公共 API
+ *
+ * 这是 App 开发者通过 `useViewContext()` 获取的上下文类型。
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *     const ctx = useViewContext();
+ *     console.log('Current view:', ctx.viewId);
+ *     console.log('Desktop:', ctx.desktopId);
+ *
+ *     // 标记 View 需要更新
+ *     ctx.markDirty();
+ * }
+ * ```
+ */
+export interface IViewMeta {
+    /** 当前 View 的唯一标识符 */
+    readonly viewId: string;
+    /**
+     * 当前View的类型 (用于Tool聚合)
+     *
+     * @optional
+     */
+    readonly viewType?: string;
+    /** 父 App 的唯一标识符 */
+    readonly appId: string;
+    /** Desktop 的唯一标识符 (用于加载相关数据，如历史记录) */
+    readonly desktopId: string;
+    /**
+     * 标记 View 为 dirty，触发 UpdateSignal
+     *
+     * 数据链路: markDirty() → Preact render → MutationObserver → UpdateSignal
+     */
+    markDirty(): void;
+}
+/**
+ * Ref 注册表接口 - App 开发者的公共 API
+ *
+ * 用于 `useArrayRef` 等 Hooks 内部注册数据引用。
+ * App 开发者通常不直接使用此接口，而是通过 Hooks。
+ *
+ * @internal 主要供 SDK Hooks 使用
+ */
+export interface IRefRegistry {
+    /**
+     * 注册数据引用
+     *
+     * @param refId - 引用 ID (View 内唯一)
+     * @param data - 绑定的数据对象
+     */
+    registerRef(refId: string, data: object): void;
+    /**
+     * 注销数据引用
+     *
+     * @param refId - 要注销的引用 ID
+     */
+    unregisterRef(refId: string): void;
+}
+/**
+ * Type Tool 定义
+ *
+ * Type Tool 是绑定到 View Type 而非 View 实例的工具。
+ * 例如: FileDetail 类型的所有 View 共享同一组 LSP tools。
+ */
+export interface TypeToolDefinition {
+    /** 工具描述,发送给 LLM */
+    description: string;
+    /** 参数定义 (可选) */
+    params?: unknown;
+    /** 工具处理函数 */
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Type Tool 注册表接口
+ *
+ * [RFC-020] Type Tool Aggregation
+ *
+ * **设计背景**:
+ * - 原方案使用 DOM 事件注册,但 LinkedOM 的事件冒泡机制不可靠
+ * - 改为直接 API 调用,与 IRefRegistry 架构一致
+ *
+ * **核心价值**:
+ * - 避免重复注册: 10个 FileDetailView 只注册 8 个 LSP tools (不是 80 个)
+ * - 动态加载: 根据条件 (如 activeFiles.length > 0) 注册/注销
+ * - 职责分离: Root View 管理 Type Tools, Child View 专注业务逻辑
+ *
+ * **使用场景**:
+ * ```tsx
+ * // WorkspaceContent.tsx (Root View)
+ * const hasFiles = activeFiles.length > 0;
+ *
+ * useViewTypeTool('FileDetail', 'lsp_hover', {
+ *   description: `Get type info for: ${activeFiles.join(', ')}`,
+ *   params: lspHoverParams,
+ *   enabled: hasFiles  // 条件注册
+ * }, handler);
+ * ```
+ *
+ * @internal 主要供 SDK Hooks (useViewTypeTool) 使用
+ */
+export interface ITypeToolRegistry {
+    /**
+     * 注册 Type Tool
+     *
+     * **重要**: 同一个 (viewType, toolName) 组合只能注册一次。
+     * 重复注册会抛出错误,确保工具定义的唯一性。
+     *
+     * @param viewType - View 类型 (e.g., "FileDetail", "SearchResult")
+     * @param toolName - 工具名称 (e.g., "lsp_hover", "close_search_view")
+     * @param toolDef - 工具定义 (description, params, handler)
+     *
+     * @throws Error 如果该 Type Tool 已被注册
+     *
+     * @example
+     * ```ts
+     * registry.registerTypeTool('FileDetail', 'lsp_hover', {
+     *   description: 'Get type information at cursor position',
+     *   params: defineParams({ line: { type: 'number', required: true } }),
+     *   handler: async ({ line }) => { ... }
+     * });
+     * ```
+     */
+    registerTypeTool(viewType: string, toolName: string, toolDef: TypeToolDefinition): void;
+    /**
+     * 注销 Type Tool
+     *
+     * 通常在组件卸载或条件不满足时调用。
+     * 如果工具不存在,静默忽略 (幂等操作)。
+     *
+     * @param viewType - View 类型
+     * @param toolName - 工具名称
+     *
+     * @example
+     * ```ts
+     * // useEffect cleanup
+     * return () => {
+     *   registry.unregisterTypeTool('FileDetail', 'lsp_hover');
+     * };
+     * ```
+     */
+    unregisterTypeTool(viewType: string, toolName: string): void;
+    /**
+     * 获取所有已注册的 Type Tools
+     *
+     * **内部使用**: 供 Worker Runtime 生成 Snapshot 时调用。
+     * App 开发者通常不需要直接调用此方法。
+     *
+     * @returns Map<viewType, Map<toolName, toolDef>>
+     *
+     * @internal
+     */
+    getAllTypeTools(): Map<string, Map<string, TypeToolDefinition>>;
+}
+/**
+ * ViewLink 注册选项
+ */
+export interface RegisterLinkOptions {
+    /**
+     * LinkID 前缀 (用于列表)
+     *
+     * SDK 会自动生成: `${prefix}_${index}`
+     * 不提供时使用 viewType 作为前缀
+     */
+    prefix?: string;
+    /**
+     * 显示标签
+     */
+    label?: string;
+}
+/**
+ * ViewLink 注册表接口 - App 开发者的公共 API
+ *
+ * [RFC-006] ViewLink 机制，用于创建可导航的子 View 链接。
+ *
+ * @example
+ * ```tsx
+ * function TopicList() {
+ *     const topics = [...];
+ *     return (
+ *         <ul>
+ *             {topics.map(topic => (
+ *                 <li key={topic.id}>
+ *                     <ViewLink
+ *                         uniqueId={topic.id}
+ *                         view={TopicDetailView}
+ *                         props={{ topicId: topic.id }}
+ *                     >
+ *                         {topic.title}
+ *                     </ViewLink>
+ *                 </li>
+ *             ))}
+ *         </ul>
+ *     );
+ * }
+ * ```
+ */
+export interface IViewLinkRegistry {
+    /**
+     * 注册一个 ViewLink
+     *
+     * @param uniqueId - 业务唯一标识 (跨快照稳定)
+     * @param viewType - View 类型名称
+     * @param factory - View 工厂函数
+     * @param props - 传递给 View 的 Props
+     * @param options - 注册选项
+     * @returns 分配的 LinkID
+     */
+    registerLink?(uniqueId: string, viewType: string, factory: (viewId: string, props?: Record<string, unknown>) => IView, props?: Record<string, unknown>, options?: RegisterLinkOptions): string;
+    /**
+     * 注销一个 ViewLink
+     *
+     * @param linkId - 要注销的 LinkID
+     */
+    unregisterLink?(linkId: string): void;
+    /**
+     * 获取已绑定的 ViewID (如果有)
+     *
+     * @param viewType - View 类型名称
+     * @param uniqueId - 业务唯一标识
+     * @returns ViewID 或 undefined
+     */
+    getBoundViewId?(viewType: string, uniqueId: string): string | undefined;
+}
+/**
+ * @deprecated 使用 IViewLinkRegistry 替代
+ */
+export type IMountableViewRegistry = IViewLinkRegistry;
+import type { OperationResult } from '../core/operations.js';
+/**
+ * 简化的 Operation Handler 类型
+ *
+ * 用于内部 Context 注册，不包含类型推断。
+ * 公共 API 请使用 `OperationHandler` from '@aotui/sdk'。
+ */
+export type SimpleOperationHandler = (args: Record<string, unknown>) => Promise<OperationResult> | OperationResult;
+/**
+ * Operation 注册表接口 - App 开发者的公共 API
+ *
+ * 用于 SDK Hooks 内部注册操作处理器。
+ * App 开发者通常不直接使用此接口，而是通过 Hooks。
+ *
+ * @internal 主要供 SDK Hooks 使用
+ */
+export interface IOperationRegistry {
+    /**
+     * 注册 Operation handler
+     *
+     * @param name - 操作名称
+     * @param handler - 操作处理函数
+     */
+    registerOperation(name: string, handler: SimpleOperationHandler): void;
+    /**
+     * 注销 Operation handler
+     *
+     * @param name - 要注销的操作名称
+     */
+    unregisterOperation(name: string): void;
+}
+/**
+ * 动态子视图注册表接口
+ *
+ * 用于动态创建和销毁子 View。
+ *
+ * @internal 主要供 SDK 内部使用
+ */
+export interface IDynamicViewRegistry {
+    /**
+     * 注册动态子视图
+     *
+     * @param view - IView 实例
+     * @returns 分配的 ViewID
+     */
+    registerChildView(view: IView): string;
+    /**
+     * 注销动态子视图
+     *
+     * @param viewId - 要注销的 ViewID
+     */
+    unregisterChildView(viewId: string): void;
+}
+/**
+ * 应用配置接口
+ *
+ * 通过 `useAppEnv` Hook 获取环境变量。
+ */
+export interface IAppConfig {
+    /** 环境变量 */
+    env?: Record<string, string | number | boolean>;
+    /** 初始状态 */
+    initialState?: Record<string, unknown>;
+}

package/dist/spi/app/public-types.js

@@ -0,0 +1,17 @@
+/**
+ * SPI App Layer - Public Types for App Developers
+ *
+ * [P4/P5 FIX] 类型定义碎片化修复
+ *
+ * 这些接口是 App 开发者可见的公共 API。
+ * SDK 应该 re-export 这些类型，而不是定义自己的版本。
+ *
+ * 设计原则:
+ * 1. 使用 string 替代 Branded Types (AppID, ViewID 等) - 降低开发者心智负担
+ * 2. 只暴露 App 开发者需要的最小接口 - 接口隔离原则 (ISP)
+ * 3. 作为 SSOT (Single Source of Truth) - SDK 和应用层都从这里导入
+ *
+ * @module @aotui/runtime/spi/app/public-types
+ */
+export {};
+//# sourceMappingURL=public-types.js.map

package/dist/spi/app/public-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-types.js","sourceRoot":"","sources":["../../../src/spi/app/public-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/spi/app/ref-exporter.interface.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Ref Exporter Interface
+ *
+ * Defines the contract for registering and exporting Refs between SDK and Runtime.
+ * This replaces the global __AOTUI_REF_REGISTRY__ with an explicit interface.
+ *
+ * [RFC-002] Ref Registry Refactoring
+ */
+export interface IRefExporter {
+    /**
+     * Register a Ref data object
+     * @param viewId The View ID
+     * @param refId The Ref ID (unique within the View)
+     * @param data The data object
+     */
+    registerRef(viewId: string, refId: string, data: object): void;
+    /**
+     * Unregister a Ref
+     * @param viewId The View ID
+     * @param refId The Ref ID
+     */
+    unregisterRef(viewId: string, refId: string): void;
+}

package/dist/spi/app/ref-exporter.interface.js

@@ -0,0 +1,10 @@
+/**
+ * Ref Exporter Interface
+ *
+ * Defines the contract for registering and exporting Refs between SDK and Runtime.
+ * This replaces the global __AOTUI_REF_REGISTRY__ with an explicit interface.
+ *
+ * [RFC-002] Ref Registry Refactoring
+ */
+export {};
+//# sourceMappingURL=ref-exporter.interface.js.map

package/dist/spi/app/ref-exporter.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-exporter.interface.js","sourceRoot":"","sources":["../../../src/spi/app/ref-exporter.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/spi/app/store.interface.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SPI Layer - App Context
+ *
+ * App 运行上下文定义。
+ *
+ * [C3 简化] 移除了 IAppStore/IAppStoreFactory。
+ * AOTUI 是 de-visualized TUI，App 无独立状态。
+ * 业务数据持久化由 Product Layer 负责。
+ */
+import type { DesktopID, AppID } from '../core/types.js';
+/**
+ * App 运行上下文
+ *
+ * 在 App.onOpen() 时由 Desktop 创建并传入。
+ * 提供 App 运行所需的环境信息和能力。
+ *
+ * [设计说明]
+ * - AOTUI App 的状态 = DOM 内容，由 Desktop.serialize() 管理
+ * - 业务数据持久化由 Product Layer 负责 (如 messageService)
+ * - 不再提供 per-app store，简化 API
+ */
+export interface AppContext {
+    /** 所属 Desktop ID */
+    readonly desktopId: DesktopID;
+    /** 当前 App ID */
+    readonly appId: AppID;
+    /**
+     * [Option D] 标记该 App 需要更新
+     *
+     * 不立即触发 UpdateSignal，而是等待 DOM_UPDATE 到达后才发送。
+     * 这解决了 signal 变化 → notifyUpdate → snapshot 读取旧 DOM 的竞态问题。
+     *
+     * [Approach D] 同时触发 forceRender 回调进行同步渲染。
+     */
+    markDirty(): void;
+    /**
+     * [Approach D] 注册渲染回调
+     *
+     * ViewBasedApp 在 onOpen 时注册此回调，当 markDirty() 被调用时
+     * Worker 会同步调用此回调以强制 Preact 重渲染。
+     *
+     * @param callback 渲染回调函数 (通常是 renderAllViews)
+     */
+    onRender(callback: () => void): void;
+}

package/dist/spi/app/store.interface.js

@@ -0,0 +1,11 @@
+/**
+ * SPI Layer - App Context
+ *
+ * App 运行上下文定义。
+ *
+ * [C3 简化] 移除了 IAppStore/IAppStoreFactory。
+ * AOTUI 是 de-visualized TUI，App 无独立状态。
+ * 业务数据持久化由 Product Layer 负责。
+ */
+export {};
+//# sourceMappingURL=store.interface.js.map

package/dist/spi/app/store.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.interface.js","sourceRoot":"","sources":["../../../src/spi/app/store.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/spi/app/view-context-core.interface.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Level 1: ViewContext Core Contract
+ *
+ * Defines the minimal contract between Runtime and App (SDK).
+ * This is the stable foundation for cross-boundary communication.
+ */
+import type { AppID, DesktopID, ViewID } from '../core/types.js';
+import type { AppLaunchConfig } from './app-config.interface.js';
+export interface IViewContextCore {
+    /** The App ID this view belongs to */
+    readonly appId: AppID;
+    /** The Desktop ID (used for loading related data, e.g. history) */
+    readonly desktopId: DesktopID;
+    /** This View's unique ID */
+    readonly viewId: ViewID;
+    /**
+     * The DOM container for this View.
+     *
+     * Created by the App within its DOM tree. The View renders its content into this container.
+     * Ensures "One App = One DOM".
+     */
+    readonly container: HTMLElement;
+    /**
+     * The App's Document object.
+     *
+     * SDK uses this to create DOM elements, ensuring they belong to the correct Document.
+     * Solves cross-Document operation issues (e.g. linkedom).
+     */
+    readonly document: Document;
+    /**
+     * App 启动配置
+     *
+     * 由 Runtime 在 App 启动时注入，包含环境变量和初始状态。
+     * SDK 通过此字段显式获取配置，而非依赖 globalThis。
+     *
+     * @example
+     * ```tsx
+     * const ctx = useViewContext();
+     * const topicId = ctx.appConfig?.env?.AOTUI_TopicID;
+     * ```
+     */
+    readonly appConfig?: AppLaunchConfig;
+    /**
+     * Ref Exporter (Refactoring: Explicit Dependency)
+     *
+     * Allows SDK to register refs to the Runtime without relying on globals.
+     * [RFC-002] Ref Registry Refactoring
+     */
+    readonly refExporter?: import('./ref-exporter.interface.js').IRefExporter;
+}

package/dist/spi/app/view-context-core.interface.js

@@ -0,0 +1,8 @@
+/**
+ * Level 1: ViewContext Core Contract
+ *
+ * Defines the minimal contract between Runtime and App (SDK).
+ * This is the stable foundation for cross-boundary communication.
+ */
+export {};
+//# sourceMappingURL=view-context-core.interface.js.map

package/dist/spi/app/view-context-core.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-context-core.interface.js","sourceRoot":"","sources":["../../../src/spi/app/view-context-core.interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/spi/app/view-context-ext.interface.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Level 3: ViewContext Extension Contract
+ *
+ * [RFC-006] ViewLink/View ID 解耦设计
+ *
+ * Defines extension capabilities for advanced features (e.g., Mountable Views, Re-indexing).
+ * These are optional capabilities that a Context implementation MAY support.
+ */
+import type { ViewID } from '../core/types.js';
+import type { IView } from './view.interface.js';
+/**
+ * ViewLink 注册选项
+ */
+export interface RegisterLinkOptions {
+    /**
+     * LinkID 前缀 (用于列表)
+     *
+     * SDK 会自动生成: `${prefix}_${index}`
+     * 不提供时使用 viewType 作为前缀
+     */
+    prefix?: string;
+    /**
+     * 显示标签
+     */
+    label?: string;
+}
+/**
+ * Extension for ViewLink mechanism (Mountable Views).
+ *
+ * [RFC-006] 重新设计的 ViewLink API：
+ * - registerLink: 注册 ViewLink (返回 linkId)
+ * - unregisterLink: 注销 ViewLink
+ * - 保留旧 API 用于向后兼容
+ */
+export interface IViewContextMountable {
+    /**
+     * 注册一个 ViewLink
+     *
+     * @param uniqueId - 业务唯一标识 (跨快照稳定)
+     * @param viewType - View 类型名称 (IViewFactory.displayName)
+     * @param factory - View 工厂函数
+     * @param props - 传递给 View 的 Props
+     * @param options - 注册选项
+     * @returns 分配的 LinkID (父 View 内唯一)
+     */
+    registerLink(uniqueId: string, viewType: string, factory: (viewId: string, props?: Record<string, unknown>) => IView, props?: Record<string, unknown>, options?: RegisterLinkOptions): string;
+    /**
+     * 注销一个 ViewLink
+     *
+     * @param linkId - 要注销的 LinkID
+     */
+    unregisterLink(linkId: string): void;
+    /**
+     * 获取已绑定的 ViewID (如果有)
+     *
+     * 用于 ViewLink 渲染时检查是否已有 mount 的 View
+     *
+     * @param viewType - View 类型名称
+     * @param uniqueId - 业务唯一标识
+     * @returns ViewID 或 undefined
+     */
+    getBoundViewId(viewType: string, uniqueId: string): ViewID | undefined;
+    /**
+     * @deprecated Use registerLink instead
+     */
+    registerMountableView(factory: (viewId: string, props?: Record<string, unknown>) => IView, props?: Record<string, unknown>, label?: string): string;
+    /**
+     * @deprecated Use unregisterLink instead
+     */
+    unregisterMountableView(viewId: string): void;
+    /**
+     * @deprecated No longer supported in V2
+     */
+    subscribeToReindex(callback: (idMapping: Map<string, string>) => void): () => void;
+}
+/**
+ * Type guard to check if a context supports Mountable View extensions.
+ */
+export declare function hasMountableSupport(ctx: unknown): ctx is IViewContextMountable;

package/dist/spi/app/view-context-ext.interface.js

@@ -0,0 +1,19 @@
+/**
+ * Level 3: ViewContext Extension Contract
+ *
+ * [RFC-006] ViewLink/View ID 解耦设计
+ *
+ * Defines extension capabilities for advanced features (e.g., Mountable Views, Re-indexing).
+ * These are optional capabilities that a Context implementation MAY support.
+ */
+/**
+ * Type guard to check if a context supports Mountable View extensions.
+ */
+export function hasMountableSupport(ctx) {
+    return (typeof ctx === 'object' &&
+        ctx !== null &&
+        typeof ctx.registerLink === 'function' &&
+        typeof ctx.unregisterLink === 'function' &&
+        typeof ctx.getBoundViewId === 'function');
+}
+//# sourceMappingURL=view-context-ext.interface.js.map

package/dist/spi/app/view-context-ext.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-context-ext.interface.js","sourceRoot":"","sources":["../../../src/spi/app/view-context-ext.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0GH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC5C,OAAO,CACH,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,OAAQ,GAAW,CAAC,YAAY,KAAK,UAAU;QAC/C,OAAQ,GAAW,CAAC,cAAc,KAAK,UAAU;QACjD,OAAQ,GAAW,CAAC,cAAc,KAAK,UAAU,CACpD,CAAC;AACN,CAAC"}

package/dist/spi/app/view-factory.interface.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SPI Layer - IViewFactory Interface
+ *
+ * View Factory 接口，由 SDK 提供，
+ * 用于创建 IView 实例。
+ *
+ * [方案 B] 从 SDK 提升到 SPI 层，使 Runtime 可以引用此类型
+ * 而不依赖 SDK 具体实现。
+ *
+ * @module @aotui/runtime/spi/app
+ */
+import type { IView } from './view.interface.js';
+/**
+ * View Factory Interface
+ *
+ * 工厂函数，用于创建 IView 实例。
+ * SDK 返回符合此接口的工厂。
+ *
+ * @example
+ * ```typescript
+ * // SDK 端
+ * const ChatView = (viewId: string) => new ChatViewImpl(viewId);
+ *
+ * // Runtime 端
+ * const view: IView = ChatView('view_0');
+ * ```
+ */
+export interface IViewFactory {
+    /**
+     * 创建 View 实例
+     * @param viewId - View 唯一标识符
+     * @param props - 可选的初始属性
+     * @returns IView 实例
+     */
+    (viewId: string, props?: Record<string, unknown>): IView;
+    /**
+     * View 显示名称
+     * 用于 ViewTree 输出和调试信息
+     */
+    displayName?: string;
+    /**
+     * 可选：统一工厂接口
+     * 与直接调用等价：factory.create(id) === factory(id)
+     */
+    create?: (viewId: string, props?: Record<string, unknown>) => IView;
+}

package/dist/spi/app/view-factory.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=view-factory.interface.js.map

package/dist/spi/app/view-factory.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-factory.interface.js","sourceRoot":"","sources":["../../../src/spi/app/view-factory.interface.ts"],"names":[],"mappings":""}