@aotui/runtime 1.0.0

package/dist/spi/worker-protocol/messages.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Worker Protocol - Message Definitions
+ *
+ * 定义主线程与 Worker 之间的 IPC 消息协议。
+ * 这是 SDK Worker Runtime 和 Runtime AppWorkerHost 的统一契约。
+ *
+ * ## 消息流向
+ *
+ * - **MainToWorkerMessage**: 主线程 → Worker (请求)
+ * - **WorkerToMainMessage**: Worker → 主线程 (响应/推送)
+ *
+ * ## 设计原则
+ *
+ * 1. 所有消息都有 `type` 字段用于区分
+ * 2. 请求消息都有 `requestId` 用于匹配响应
+ * 3. Worker 可以主动推送消息 (如 DOM_UPDATE)
+ *
+ * @module @aotui/runtime/spi/worker-protocol
+ */
+import type { RequestID, AppID, DesktopID, ViewID, OperationID, SnapshotID, DataPayload } from './types.js';
+import type { OperationResult } from '../core/index.js';
+import type { AppLaunchConfig } from '../app/app-config.interface.js';
+export type { WorkerMessageType } from '../runtime/worker-message.interface.js';
+/**
+ * App 初始化消息
+ */
+export interface InitMessage {
+    type: 'INIT';
+    requestId: RequestID;
+    appId: AppID;
+    desktopId: DesktopID;
+    /** App 模块路径 (动态 import) */
+    appModulePath: string;
+    /** 应用启动配置 (Configuration Injection) */
+    config?: AppLaunchConfig;
+}
+/**
+ * App 生命周期消息
+ */
+export interface AppLifecycleMessage {
+    type: 'APP_OPEN' | 'APP_PAUSE' | 'APP_RESUME' | 'APP_CLOSE' | 'APP_DELETE' | 'APP_SHUTDOWN';
+    requestId: RequestID;
+}
+/**
+ * View 生命周期消息
+ */
+export interface ViewLifecycleMessage {
+    type: 'VIEW_DISMOUNT';
+    requestId: RequestID;
+    viewId: ViewID;
+    parentId?: ViewID | null;
+}
+/**
+ * Operation 执行消息
+ */
+export interface OperationMessage {
+    type: 'APP_OPERATION' | 'VIEW_OPERATION';
+    requestId: RequestID;
+    viewId?: ViewID;
+    operation: OperationID;
+    args: Record<string, unknown>;
+    snapshotId: SnapshotID;
+}
+/**
+ * 外部事件消息
+ */
+export interface ExternalEventMessage {
+    type: 'EXTERNAL_EVENT';
+    requestId: RequestID;
+    viewId: ViewID;
+    eventType: string;
+    data: Record<string, unknown>;
+}
+/**
+ * 终止消息
+ */
+export interface TerminateMessage {
+    type: 'TERMINATE';
+}
+/**
+ * 重置 Worker 状态消息 (用于 Worker 池复用)
+ */
+export interface ResetMessage {
+    type: 'RESET';
+    requestId: RequestID;
+}
+/**
+ * [RFC-006] ViewLink Mount 消息
+ */
+export interface ViewMountByLinkMessage {
+    type: 'VIEW_MOUNT_BY_LINK';
+    requestId: RequestID;
+    parentViewId: ViewID;
+    linkId: string;
+}
+/**
+ * [RFC-011] LLM Output Push 消息
+ * [RFC-020] 支持结构化 payload { reasoning?, content? }
+ *
+ * 主线程推送 LLM 输出文本到 Worker，用于 SDK 的 useLLMOutputChannel
+ */
+export interface LLMOutputPushMessage {
+    type: 'LLM_OUTPUT_PUSH';
+    /** [RFC-020] LLM 思考/推理过程 */
+    reasoning?: string;
+    /** LLM 最终回复内容 */
+    content?: string;
+    eventType: 'complete';
+    timestamp: number;
+    meta?: {
+        model?: string;
+        usage?: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+    };
+}
+/**
+ * 主线程 → Worker 消息联合类型
+ */
+export type MainToWorkerMessage = InitMessage | AppLifecycleMessage | ViewLifecycleMessage | ViewMountByLinkMessage | OperationMessage | ExternalEventMessage | TerminateMessage | ResetMessage | LLMOutputPushMessage;
+/**
+ * 错误信息结构
+ */
+export interface WorkerError {
+    code: string;
+    message: string;
+}
+/**
+ * 响应消息基类
+ */
+export interface ResponseBase {
+    requestId: RequestID;
+    success: boolean;
+}
+/**
+ * 初始化完成响应
+ */
+export interface InitResponse extends ResponseBase {
+    type: 'INIT_RESPONSE';
+}
+/**
+ * 生命周期完成响应
+ */
+export interface LifecycleResponse extends ResponseBase {
+    type: 'LIFECYCLE_RESPONSE';
+}
+/**
+ * Operation 结果响应
+ */
+export interface OperationResponse extends ResponseBase {
+    type: 'OPERATION_RESPONSE';
+    result: OperationResult;
+}
+/**
+ * 错误响应
+ */
+export interface ErrorResponse extends ResponseBase {
+    type: 'ERROR_RESPONSE';
+    success: false;
+    error: WorkerError;
+}
+/**
+ * Worker 主动请求: 通知更新
+ */
+export interface UpdateRequest {
+    type: 'REQUEST_UPDATE';
+}
+/**
+ * Worker 主动请求: mount 子 View
+ */
+export interface MountChildRequest {
+    type: 'REQUEST_MOUNT_CHILD';
+    viewId: ViewID;
+}
+/**
+ * Worker 主动请求: dismount 子 View
+ */
+export interface DismountChildRequest {
+    type: 'REQUEST_DISMOUNT_CHILD';
+    viewId: ViewID;
+}
+/**
+ * Worker 主动推送: Snapshot Fragment
+ *
+ * [RFC-001] Worker-Side Transformation
+ * Worker 直接执行 Transformer，推送 Markdown + IndexMap，
+ * 避免主线程 HTML 解析开销。
+ */
+export interface SnapshotFragmentPush {
+    type: 'SNAPSHOT_FRAGMENT';
+    /** App ID */
+    appId: AppID;
+    /** 更新时间戳 (用于去重) */
+    timestamp: number;
+    /** TUI Markdown for this App */
+    markup: string;
+    /** Partial IndexMap (app-scoped paths) */
+    indexMap: Record<string, DataPayload>;
+    /**
+     * View 级片段
+     *
+     * 每个 View 独立维护 timestamp，支持消息按 View 更新时间排序。
+     */
+    views?: Array<{
+        viewId: ViewID;
+        viewType: string;
+        viewName?: string;
+        markup: string;
+        timestamp: number;
+    }>;
+    /**
+     * [RFC-007] View tree markdown for Application Info section
+     *
+     * Format:
+     * ```markdown
+     * ## Application View Tree
+     * - [Chat](view:view_0, mounted)
+     *     ↳ [Detail](link:CD_0)
+     * ```
+     */
+    viewTree?: string;
+    /** Version for incremental updates (future) */
+    version?: number;
+    /**
+     * [RFC-012] Signal Suppression Flag
+     *
+     * When true, main thread should update snapshot cache but NOT emit UpdateSignal.
+     * Used by passive apps (signalPolicy: 'never') to maintain data freshness
+     * without triggering Agent reaction loops.
+     */
+    suppressSignal?: boolean;
+}
+/**
+ * 重置完成响应
+ */
+export interface ResetResponse extends ResponseBase {
+    type: 'RESET_RESPONSE';
+}
+/**
+ * Worker → 主线程消息联合类型
+ */
+export type WorkerToMainMessage = InitResponse | LifecycleResponse | OperationResponse | ErrorResponse | UpdateRequest | MountChildRequest | DismountChildRequest | SnapshotFragmentPush | ResetResponse;
+/**
+ * 检查是否为响应消息
+ */
+export declare function isResponse(msg: WorkerToMainMessage): msg is ResponseBase & WorkerToMainMessage;
+/**
+ * 检查是否为请求消息 (Worker 主动发起)
+ */
+export declare function isRequest(msg: WorkerToMainMessage): boolean;
+/**
+ * 检查是否为 Snapshot Fragment 推送
+ * [RFC-001] Worker-Side Transformation
+ */
+export declare function isSnapshotFragment(msg: WorkerToMainMessage): msg is SnapshotFragmentPush;

package/dist/spi/worker-protocol/messages.js

@@ -0,0 +1,42 @@
+/**
+ * Worker Protocol - Message Definitions
+ *
+ * 定义主线程与 Worker 之间的 IPC 消息协议。
+ * 这是 SDK Worker Runtime 和 Runtime AppWorkerHost 的统一契约。
+ *
+ * ## 消息流向
+ *
+ * - **MainToWorkerMessage**: 主线程 → Worker (请求)
+ * - **WorkerToMainMessage**: Worker → 主线程 (响应/推送)
+ *
+ * ## 设计原则
+ *
+ * 1. 所有消息都有 `type` 字段用于区分
+ * 2. 请求消息都有 `requestId` 用于匹配响应
+ * 3. Worker 可以主动推送消息 (如 DOM_UPDATE)
+ *
+ * @module @aotui/runtime/spi/worker-protocol
+ */
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * 检查是否为响应消息
+ */
+export function isResponse(msg) {
+    return 'requestId' in msg && 'success' in msg;
+}
+/**
+ * 检查是否为请求消息 (Worker 主动发起)
+ */
+export function isRequest(msg) {
+    return msg.type.startsWith('REQUEST_');
+}
+/**
+ * 检查是否为 Snapshot Fragment 推送
+ * [RFC-001] Worker-Side Transformation
+ */
+export function isSnapshotFragment(msg) {
+    return msg.type === 'SNAPSHOT_FRAGMENT';
+}
+//# sourceMappingURL=messages.js.map

package/dist/spi/worker-protocol/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/spi/worker-protocol/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkSH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAwB;IAC/C,OAAO,WAAW,IAAI,GAAG,IAAI,SAAS,IAAI,GAAG,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,GAAwB;IAC9C,OAAO,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AAC3C,CAAC;AAID;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAwB;IACvD,OAAO,GAAG,CAAC,IAAI,KAAK,mBAAmB,CAAC;AAC5C,CAAC"}

package/dist/spi/worker-protocol/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Worker Protocol - Type Definitions
+ *
+ * 基础类型定义，用于 Worker IPC 通信。
+ *
+ * [架构原则] 这里重新导出 SPI 中已有的类型，保持单一来源。
+ *
+ * @module @aotui/runtime/spi/worker-protocol
+ */
+import type { AppID, DesktopID, ViewID, OperationID, SnapshotID, DataPayload, IndexMap } from '../core/index.js';
+export type { AppID, DesktopID, ViewID, OperationID, SnapshotID, DataPayload, IndexMap };
+export { type RequestID, generateRequestId, type IWorkerMessage, type IWorkerRequest, type IWorkerResponse, type IWorkerError, } from '../runtime/worker-message.interface.js';

package/dist/spi/worker-protocol/types.js

@@ -0,0 +1,16 @@
+/**
+ * Worker Protocol - Type Definitions
+ *
+ * 基础类型定义，用于 Worker IPC 通信。
+ *
+ * [架构原则] 这里重新导出 SPI 中已有的类型，保持单一来源。
+ *
+ * @module @aotui/runtime/spi/worker-protocol
+ */
+// ============================================================================
+// Re-export from existing worker-message.interface (Single Source of Truth)
+// ============================================================================
+// Note: WorkerMessageType is defined in messages.ts with additional types (RESET, RESET_RESPONSE)
+// so we don't re-export it here to avoid conflicts.
+export { generateRequestId, } from '../runtime/worker-message.interface.js';
+//# sourceMappingURL=types.js.map

package/dist/spi/worker-protocol/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/spi/worker-protocol/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,kGAAkG;AAClG,oDAAoD;AAEpD,OAAO,EAEH,iBAAiB,GAKpB,MAAM,wCAAwC,CAAC"}

package/dist/worker-runtime/app-kernel/AppKernel.d.ts

@@ -0,0 +1,178 @@
+/**
+ * AOTUI Runtime - App Kernel
+ *
+ * [方案 B] 从 @aotui/sdk 迁移到 @aotui/runtime/worker-runtime。
+ *
+ * Worker 内的 App 执行引擎，负责：
+ * - App 生命周期管理 (onOpen, onClose...)
+ * - ViewTree 状态管理 (SSOT)
+ * - 系统事件处理 (Runtime Bridge)
+ * - Operation 路由
+ * - Type-level Tools 管理
+ *
+ * @module @aotui/runtime/worker-runtime/app-kernel
+ */
+import type { AppID, ViewID, OperationID, OperationResult, OperationContext, AppContext, IAOTUIApp, AppKernelConfig, IRefExporter } from '../../spi/index.js';
+import type { DataPayload, IndexMap } from '../../spi/worker-protocol/index.js';
+/** Type Tool Definition (for registration) */
+export interface TypeToolDefinition {
+    description: string;
+    params: Record<string, unknown>;
+    handler: (params: Record<string, unknown>) => Promise<unknown>;
+}
+/** Type Tool (stored in registry) */
+export interface TypeTool {
+    id: string;
+    name: string;
+    viewType: string;
+    description: string;
+    params: Record<string, unknown>;
+    handler: (params: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * App Kernel Implementation
+ *
+ * 运行在 Worker 内的 App 执行引擎。
+ * 实现 IAOTUIApp 接口，供 Worker Runtime 调用。
+ */
+export declare class AppKernel implements IAOTUIApp, IRefExporter {
+    private _id;
+    readonly name: string;
+    private readonly toolAppName;
+    private config;
+    private context;
+    private container;
+    /**
+     * [RFC-B2] ViewRegistry - 轻量级View管理
+     * 替代ViewTree,只管理组件模式View
+     */
+    private viewRegistry;
+    private viewIdCounter;
+    /** [RFC-002] Ref Registry Storage */
+    private refRegistry;
+    /** [RFC-027] View Registry for component mode (viewKey -> viewId) */
+    private viewKeyToId;
+    /** Type-level Tools Registry */
+    private typeTools;
+    constructor(config: AppKernelConfig);
+    private resolveToolAppName;
+    /**
+     * Tool 前缀语义名（供 Worker 侧导出 Tool Key）
+     */
+    getToolAppName(): string;
+    get id(): AppID;
+    setId(id: AppID): void;
+    onOpen(context: AppContext, container: HTMLElement): Promise<void>;
+    onClose(): Promise<void>;
+    /**
+     * [RFC-015] App Delete Lifecycle
+     */
+    onDelete(): Promise<void>;
+    onPause(): Promise<void>;
+    onResume(): Promise<void>;
+    /**
+     * Handle system events from Desktop
+     *
+     * [RFC-B2] Removed mount/dismount/ViewLink system events
+     * View lifecycle is now managed via Operations
+     */
+    onSystemEvent(event: string, payload: DataPayload): Promise<void>;
+    /**
+     * Handle DOM-based system events from worker runtime.
+     * Used to request view close in component mode.
+     */
+    private handleSystemEvent;
+    /**
+     * Execute Operation
+     *
+     * Routes the operation to the appropriate view or app-level handler.
+     */
+    onOperation(context: OperationContext, operation: OperationID, args: Record<string, unknown>): Promise<OperationResult>;
+    /**
+     * Handle ref-register event from DOM
+     */
+    private handleRefRegister;
+    /**
+     * Handle ref-unregister event from DOM
+     */
+    private handleRefUnregister;
+    /**
+     * Export ref from view
+     */
+    exportRef<T extends object>(viewId: ViewID, key: string, data: T): void;
+    /**
+     * Unexport ref from view
+     */
+    unexportRef(viewId: ViewID, key: string): void;
+    /**
+     * [IRefExporter] Alias for exportRef
+     */
+    registerRef(viewId: string, refId: string, data: object): void;
+    /**
+     * [IRefExporter] Alias for unexportRef
+     */
+    unregisterRef(viewId: string, refId: string): void;
+    /**
+     * Export all registered refs to IndexMap
+     * Called by Worker Runtime during snapshot generation
+     */
+    exportRefsToIndexMap(): IndexMap;
+    /**
+     * Unregister Type Tool
+     */
+    unregisterTypeTool(viewType: string, toolName: string): void;
+    /**
+     * Handle type-tool-register event from DOM
+     */
+    private handleTypeToolRegister;
+    /**
+     * Handle type-tool-unregister event from DOM
+     */
+    private handleTypeToolUnregister;
+    /**
+     * [RFC-B2] Render View Tree to Markdown
+     *
+     * Component mode: Parse from DOM instead of ViewTree
+     */
+    renderViewTree(): string;
+    private initializeDOMStructure;
+    /**
+     * [RFC-027-C] Component初始化 (Factory Injection Pattern)
+     */
+    private componentRenderer?;
+    private initializeFromComponent;
+    private renderAllViews;
+    private generateViewId;
+    /**
+     * Allocate viewId for component mode
+     * Uses view key (name or name_uniqueId) to ensure consistent ID assignment
+     */
+    private allocateViewId;
+    /**
+     * [RFC-B2] Register IView instance from component mode
+     */
+    private registerView;
+    /**
+     * [RFC-B2] Unregister IView instance
+     */
+    private unregisterView;
+    /**
+     * Register a Type-level Tool
+     * Tool ID format: `${appId}-${viewType}-${toolName}`
+     */
+    registerTypeTool(viewType: string, toolName: string, tool: TypeToolDefinition): void;
+    /**
+     * Call a Type-level Tool - LLM must provide view_id in params
+     */
+    callTypeTool(viewType: string, toolName: string, params: Record<string, unknown>): Promise<OperationResult>;
+    /**
+     * Get all Type Tools for a specific view type
+     */
+    getTypeTools(viewType: string): TypeTool[];
+    /**
+     * Get all registered Type Tools (all types)
+     */
+    getAllTypeTools(): Map<string, TypeTool[]>;
+    private resolveTypeToolArgs;
+    private resolveRefId;
+}