@aotui/runtime 1.0.0

package/dist/spi/core/snapshot.d.ts

@@ -0,0 +1,77 @@
+/**
+ * SPI Layer - Snapshot Types
+ *
+ * 定义快照相关的类型。
+ */
+import type { SnapshotID, IndexMap } from './types.js';
+/**
+ * [RFC-014] App 状态片段
+ *
+ * 单个 App 的渲染内容，用于语义分离的多消息结构
+ */
+export interface AppStateFragment {
+    appId: string;
+    appName: string;
+    markup: string;
+    timestamp?: number;
+    /** [RFC-014] 消息角色 (user/assistant) */
+    role?: 'user' | 'assistant';
+}
+/**
+ * View 状态片段
+ *
+ * 用于 View 级别的消息粒度与时间排序。
+ */
+export interface ViewStateFragment {
+    appId: string;
+    appName: string;
+    viewId: string;
+    viewType: string;
+    viewName?: string;
+    markup: string;
+    timestamp?: number;
+    /** [RFC-014] 消息角色 (user/assistant) */
+    role?: 'user' | 'assistant';
+}
+/**
+ * [RFC-014] 结构化快照 - 语义分离的内容片段
+ *
+ * 将 TUI 状态按语义分离为：
+ * - Who/Why/How (systemInstruction) - 100% 稳定的元指令
+ * - Where (desktopState) - Desktop 状态
+ * - When (appStates) - 各 App 的当前状态
+ */
+export interface StructuredSnapshot {
+    /** Who/Why/How - 100% 稳定的元指令 */
+    systemInstruction: string;
+    /** Where - Desktop 状态 (Apps 列表, System Logs) */
+    desktopState: string;
+    /** When - 各 App 的当前状态 */
+    appStates: AppStateFragment[];
+    /** When - 各 View 的当前状态（细粒度） */
+    viewStates?: ViewStateFragment[];
+}
+/**
+ * 缓存的快照
+ */
+export interface CachedSnapshot {
+    id: SnapshotID;
+    /** [向后兼容] 完整的 markup (Desktop + Apps) */
+    markup: string;
+    /** [RFC-014] 结构化内容，用于语义分离的多消息 Prompt */
+    structured?: StructuredSnapshot;
+    indexMap: IndexMap;
+    createdAt: number;
+    refCount: number;
+    /** Time-to-live in milliseconds. Snapshot should be invalidated after expiry. */
+    ttl?: number;
+    /** Absolute expiration timestamp. Computed as createdAt + ttl. */
+    expiresAt?: number;
+}
+/**
+ * 检查快照是否已过期
+ *
+ * @param snapshot - 要检查的快照
+ * @returns 如果已过期返回 true，如果没有 TTL 则返回 false（永不过期）
+ */
+export declare function isSnapshotExpired(snapshot: CachedSnapshot): boolean;

package/dist/spi/core/snapshot.js

@@ -0,0 +1,18 @@
+/**
+ * SPI Layer - Snapshot Types
+ *
+ * 定义快照相关的类型。
+ */
+/**
+ * 检查快照是否已过期
+ *
+ * @param snapshot - 要检查的快照
+ * @returns 如果已过期返回 true，如果没有 TTL 则返回 false（永不过期）
+ */
+export function isSnapshotExpired(snapshot) {
+    if (snapshot.expiresAt === undefined) {
+        return false; // No TTL means never expires
+    }
+    return Date.now() > snapshot.expiresAt;
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/spi/core/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../src/spi/core/snapshot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA8EH;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAwB;IACtD,IAAI,QAAQ,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC,CAAC,6BAA6B;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC;AAC3C,CAAC"}

package/dist/spi/core/tool-call.d.ts

@@ -0,0 +1,60 @@
+/**
+ * LLM Tool Call Types
+ *
+ * OpenAI 兼容的 Tool Call 格式定义
+ *
+ * 注意：这些类型从 adapters/llm/types.ts 移动到 SPI 层，
+ * 因为 IAgentSession 需要使用它们。
+ */
+/** LLM Tool 定义 (OpenAI Function Calling 格式) */
+export interface Tool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: "object";
+            properties: Record<string, {
+                type: string;
+                description?: string;
+                enum?: string[];
+            }>;
+            required: string[];
+        };
+    };
+}
+/** LLM Tool Call 请求 (OpenAI 兼容格式) */
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** Tool Call 执行结果 */
+export interface ToolCallResult {
+    tool_call_id: string;
+    success: boolean;
+    data?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** Operation 参数定义 (从 IndexMap 提取) */
+export interface OperationParamDef {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+    refType?: string;
+}
+/** Operation 定义 (从 IndexMap 提取) */
+export interface OperationDef {
+    id: string;
+    appId: string;
+    viewId: string;
+    description?: string;
+    params: OperationParamDef[];
+}

package/dist/spi/core/tool-call.js

@@ -0,0 +1,10 @@
+/**
+ * LLM Tool Call Types
+ *
+ * OpenAI 兼容的 Tool Call 格式定义
+ *
+ * 注意：这些类型从 adapters/llm/types.ts 移动到 SPI 层，
+ * 因为 IAgentSession 需要使用它们。
+ */
+export {};
+//# sourceMappingURL=tool-call.js.map

package/dist/spi/core/tool-call.js.map

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

package/dist/spi/core/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * SPI Layer - Foundation Types
+ *
+ * 最基础的类型定义，零依赖。
+ * 这些类型是整个 Runtime 的"语言"。
+ */
+/**
+ * 用于创建 Branded Types 的 unique symbol。
+ *
+ * Branded Types 在编译期区分不同的 ID 类型，防止混用。
+ * 例如：`getDesktop(appId)` 会在编译时报错。
+ *
+ * @internal
+ */
+declare const __brand: unique symbol;
+/** 快照唯一标识 (Branded Type) */
+export type SnapshotID = string & {
+    readonly [__brand]: 'SnapshotID';
+};
+/** 桌面唯一标识 (Branded Type) */
+export type DesktopID = string & {
+    readonly [__brand]: 'DesktopID';
+};
+/** 应用唯一标识 (Branded Type) */
+export type AppID = string & {
+    readonly [__brand]: 'AppID';
+};
+/** 视图唯一标识 (Branded Type) */
+export type ViewID = string & {
+    readonly [__brand]: 'ViewID';
+};
+/** 操作唯一标识 (Branded Type) */
+export type OperationID = string & {
+    readonly [__brand]: 'OperationID';
+};
+/** 通用数据载荷 */
+export type DataPayload = Record<string, unknown>;
+/** 快照数据索引映射 */
+export interface IndexMap {
+    [path: string]: DataPayload;
+}
+/** Desktop 状态 */
+export type DesktopStatus = 'active' | 'suspended' | 'serialized';
+/** App 状态 */
+export interface AppState {
+    appId: AppID;
+    name?: string;
+    html: string;
+    /** [RFC-014] 增加 'pending' 状态用于懒加载 */
+    status: 'pending' | 'running' | 'closed' | 'collapsed';
+    installedAt: number;
+}
+/** Desktop 序列化状态 */
+export interface DesktopState {
+    id: DesktopID;
+    status: DesktopStatus;
+    createdAt: number;
+    serializedAt?: number;
+    apps: AppState[];
+}
+/** App 配置 */
+export interface AppConfig {
+    /** 应用名称 (语义名称, 必填) */
+    name: string;
+    /** 应用 HTML 内容 */
+    html: string;
+}
+export {};

package/dist/spi/core/types.js

@@ -0,0 +1,8 @@
+/**
+ * SPI Layer - Foundation Types
+ *
+ * 最基础的类型定义，零依赖。
+ * 这些类型是整个 Runtime 的"语言"。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/spi/core/types.js.map

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

package/dist/spi/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * SPI Layer - Public API
+ *
+ * AOTUI 框架的契约层。
+ *
+ * ## 分层结构
+ *
+ * - **core**: 基础类型 (AppID, ViewID, OperationResult, etc.)
+ * - **app**: App 开发者接口 (IView, IViewContext, IAOTUIApp, etc.)
+ * - **runtime**: Runtime 内部接口 (IKernel, IDesktop, etc.) - 不对外公开
+ *
+ * ## 使用方式
+ *
+ * App 开发者应通过 `@aotui/sdk` 导入，而非直接使用此模块。
+ *
+ * ```typescript
+ * // ✅ 正确：通过 SDK 导入
+ * import { View, Operation, type OperationResult } from '@aotui/sdk';
+ *
+ * // ❌ 错误：直接导入 SPI
+ * import type { IView } from '@aotui/runtime/spi';
+ * ```
+ *
+ * @module @aotui/runtime/spi
+ */
+export * from './core/index.js';
+export * from './app/index.js';
+export * from './runtime/index.js';
+export * from './bridge/index.js';
+export * from './worker-protocol/index.js';
+export * from './component-factory.interface.js';

package/dist/spi/index.js

@@ -0,0 +1,57 @@
+/**
+ * SPI Layer - Public API
+ *
+ * AOTUI 框架的契约层。
+ *
+ * ## 分层结构
+ *
+ * - **core**: 基础类型 (AppID, ViewID, OperationResult, etc.)
+ * - **app**: App 开发者接口 (IView, IViewContext, IAOTUIApp, etc.)
+ * - **runtime**: Runtime 内部接口 (IKernel, IDesktop, etc.) - 不对外公开
+ *
+ * ## 使用方式
+ *
+ * App 开发者应通过 `@aotui/sdk` 导入，而非直接使用此模块。
+ *
+ * ```typescript
+ * // ✅ 正确：通过 SDK 导入
+ * import { View, Operation, type OperationResult } from '@aotui/sdk';
+ *
+ * // ❌ 错误：直接导入 SPI
+ * import type { IView } from '@aotui/runtime/spi';
+ * ```
+ *
+ * @module @aotui/runtime/spi
+ */
+// ============================================================================
+// Core Layer - Foundation Types (Public)
+// ============================================================================
+export * from './core/index.js';
+// ============================================================================
+// App Layer - App Developer Interfaces (Public)
+// ============================================================================
+export * from './app/index.js';
+// ============================================================================
+// Runtime Layer - Internal Interfaces (Public for Product Layer)
+// ============================================================================
+// Note: These are intentionally exported for Product Layer (Server) usage.
+// SDK developers should NOT use these directly.
+export * from './runtime/index.js';
+// ============================================================================
+// Bridge Layer - Agent I/O Boundary (Public for AgentDriver)
+// ============================================================================
+// IBridge is the only interface Agents should interact with.
+// Product Layer creates Bridge instances and passes to AgentDriver.
+export * from './bridge/index.js';
+// ============================================================================
+// Worker Protocol - IPC Message Contract
+// ============================================================================
+// Contract between AppWorkerHost (main thread) and Worker Runtime (worker thread).
+// Used by both Runtime and SDK Worker.
+export * from './worker-protocol/index.js';
+// ============================================================================
+// Component Factory - SDK-Runtime Contract (RFC-027-C)
+// ============================================================================
+// Factory Injection Pattern for complete decoupling
+export * from './component-factory.interface.js';
+//# sourceMappingURL=index.js.map

package/dist/spi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/spi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,+EAA+E;AAC/E,yCAAyC;AACzC,+EAA+E;AAC/E,cAAc,iBAAiB,CAAC;AAEhC,+EAA+E;AAC/E,gDAAgD;AAChD,+EAA+E;AAC/E,cAAc,gBAAgB,CAAC;AAE/B,+EAA+E;AAC/E,iEAAiE;AACjE,+EAA+E;AAC/E,2EAA2E;AAC3E,gDAAgD;AAChD,cAAc,oBAAoB,CAAC;AAEnC,+EAA+E;AAC/E,6DAA6D;AAC7D,+EAA+E;AAC/E,6DAA6D;AAC7D,oEAAoE;AACpE,cAAc,mBAAmB,CAAC;AAElC,+EAA+E;AAC/E,yCAAyC;AACzC,+EAA+E;AAC/E,mFAAmF;AACnF,uCAAuC;AACvC,cAAc,4BAA4B,CAAC;AAE3C,+EAA+E;AAC/E,uDAAuD;AACvD,+EAA+E;AAC/E,oDAAoD;AACpD,cAAc,kCAAkC,CAAC"}

package/dist/spi/runtime/app-host.interface.d.ts

@@ -0,0 +1,142 @@
+/**
+ * SPI Layer - App Host Service Interface
+ *
+ * 抽象 App 的安装、执行和状态查询。
+ * 实现可以是 Worker-based, WASM-based, 或 Remote-based。
+ *
+ * @module @aotui/runtime/spi
+ */
+import type { AppID, DesktopID, ViewID } from '../core/types.js';
+import type { OperationPayload } from '../core/operations.js';
+import type { AppLaunchConfig } from '../app/app-config.interface.js';
+/**
+ * Snapshot Fragment (Worker 端渲染结果)
+ *
+ * 当 Worker 端执行 Transformer 时，返回的局部渲染结果。
+ * Kernel 会将多个 Fragment 聚合为完整的 Snapshot。
+ */
+export interface SnapshotFragment {
+    /** App ID */
+    appId: AppID;
+    /** Markdown 渲染结果 */
+    markup: string;
+    /** 索引映射表 (用于 Operation 参数解析) */
+    indexMap: Record<string, unknown>;
+    /** View 级片段（可选） */
+    views?: Array<{
+        viewId: ViewID;
+        viewType: string;
+        viewName?: string;
+        markup: string;
+        timestamp: number;
+    }>;
+    /** 更新时间戳 (用于排序) */
+    timestamp?: number;
+}
+/**
+ * App 安装选项
+ */
+export interface AppInstallOptions {
+    /** 自定义 App ID (默认自动生成) */
+    appId?: AppID;
+    /** App 显示名称 */
+    name?: string;
+    /** App 启动配置 (环境变量、初始状态等) */
+    config?: AppLaunchConfig;
+    /** Worker 脚本路径 (可选，默认使用 Runtime 内置) */
+    workerScriptPath?: string;
+    /** [Fix] App 角色 */
+    promptRole?: 'user' | 'assistant';
+}
+/**
+ * App 托管服务接口
+ *
+ * 抽象 App 的安装、执行和状态查询。
+ *
+ * 设计原则:
+ * - 接口隔离: 仅暴露 Kernel 需要的能力
+ * - 依赖反转: Kernel 依赖此接口，不依赖具体实现
+ * - 可替换性: 支持 Worker、WASM、Remote 等多种托管策略
+ *
+ * @example
+ * ```typescript
+ * // Worker-based implementation
+ * const appHost: IAppHostService = new WorkerAppHostService();
+ *
+ * const appId = await appHost.install(desktopId, './my-app.js');
+ * await appHost.executeOperation(desktopId, appId, operationPayload);
+ * const fragments = appHost.getSnapshotFragments(desktopId);
+ * ```
+ */
+export interface IAppHostService {
+    /**
+     * 安装 App
+     *
+     * @param desktopId - 目标 Desktop
+     * @param modulePath - App 模块路径 (ESM)
+     * @param options - 安装选项
+     * @returns 分配的 App ID
+     * @throws {Error} E_NOT_FOUND 如果 Desktop 不存在
+     */
+    install(desktopId: DesktopID, modulePath: string, options?: AppInstallOptions): Promise<AppID>;
+    /**
+     * 执行操作
+     *
+     * 将操作载荷发送到指定 App 执行。
+     *
+     * @param desktopId - Desktop ID
+     * @param appId - 目标 App ID
+     * @param payload - 操作载荷
+     * @throws {Error} E_NOT_FOUND 如果 App 不存在
+     */
+    executeOperation(desktopId: DesktopID, appId: AppID, payload: OperationPayload): Promise<void>;
+    /**
+     * 挂载 View
+     */
+    /**
+     * 卸载 View
+     */
+    dismountView(desktopId: DesktopID, appId: AppID, viewId: ViewID): Promise<void>;
+    /**
+     * 获取所有 App 的 Snapshot Fragments
+     *
+     * @param desktopId - Desktop ID
+     * @returns 所有 App 的渲染片段
+     */
+    getSnapshotFragments(desktopId: DesktopID): SnapshotFragment[];
+    /**
+     * 获取 App 信息
+     *
+     * @param desktopId - Desktop ID
+     * @param appId - App ID
+     * @returns App 元信息 (name 等) 或 undefined
+     */
+    getAppInfo(desktopId: DesktopID, appId: AppID): {
+        name?: string;
+    } | undefined;
+    /**
+     * 检查 App 是否存在
+     */
+    hasApp(desktopId: DesktopID, appId: AppID): boolean;
+    /**
+     * 暂停指定 Desktop 的所有 App
+     */
+    pauseAll(desktopId: DesktopID): Promise<void>;
+    /**
+     * 恢复指定 Desktop 的所有 App
+     */
+    resumeAll(desktopId: DesktopID): Promise<void>;
+    /**
+     * 关闭指定 Desktop 的所有 App 并释放资源
+     */
+    closeAll(desktopId: DesktopID): Promise<void>;
+    /**
+     * 设置 Signal 发射器
+     *
+     * 当 App 需要触发 UI 更新信号时 (如 DOM 变化)，
+     * 通过此回调通知上层。
+     *
+     * @param emitter - Signal 发射函数
+     */
+    setSignalEmitter(emitter: (desktopId: DesktopID, reason: string) => void): void;
+}

package/dist/spi/runtime/app-host.interface.js

@@ -0,0 +1,10 @@
+/**
+ * SPI Layer - App Host Service Interface
+ *
+ * 抽象 App 的安装、执行和状态查询。
+ * 实现可以是 Worker-based, WASM-based, 或 Remote-based。
+ *
+ * @module @aotui/runtime/spi
+ */
+export {};
+//# sourceMappingURL=app-host.interface.js.map

package/dist/spi/runtime/app-host.interface.js.map

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

package/dist/spi/runtime/app-installer.interface.d.ts

@@ -0,0 +1,33 @@
+import type { DesktopID, AppID } from '../core/types.js';
+import type { AppLaunchConfig } from '../app/app-config.interface.js';
+/**
+ * App 安装服务接口
+ *
+ * 职责: 在 Desktop 上安装 App
+ * 消费者: Kernel, Product Layer
+ *
+ * 可替换场景: 不同的 App 加载策略 (Worker/InProcess/Remote)
+ */
+export interface IAppInstaller {
+    /**
+     * [Worker-Only] 安装 App
+     *
+     * App 运行在独立的 Worker Thread 中。
+     *
+     * [C1 Fix] workerScriptPath 现在是可选的，默认使用 Runtime 内置的 worker-runtime
+     *
+     * @param desktopId - Desktop ID
+     * @param appModulePath - App 模块路径
+     * @param options - 安装选项
+     */
+    installDynamicWorkerApp(desktopId: DesktopID, appModulePath: string, options?: {
+        workerScriptPath?: string;
+        appId?: string;
+        name?: string;
+        /** [RFC-013] App description for Agent */
+        description?: string;
+        whatItIs?: string;
+        whenToUse?: string;
+        config?: AppLaunchConfig;
+    }): Promise<AppID>;
+}

package/dist/spi/runtime/app-installer.interface.js

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

package/dist/spi/runtime/app-installer.interface.js.map

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

package/dist/spi/runtime/context.interface.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runtime Context
+ *
+ * [RFC-026] Standardized Context Injection
+ * Provides environment awareness for the Runtime and Apps.
+ */
+export interface IRuntimeContext {
+    /** Environment Variables (Project Path, User Info, etc.) */
+    env: Record<string, string | number | boolean>;
+}

package/dist/spi/runtime/context.interface.js

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

package/dist/spi/runtime/context.interface.js.map

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

package/dist/spi/runtime/desktop-context.interface.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SPI Layer - Desktop Context Interface
+ *
+ * Desktop 的不可变数据容器。
+ * 不包含行为，仅作为 Service 调用时的身份标识。
+ *
+ * @module @aotui/runtime/spi
+ */
+import type { DesktopID, DesktopStatus } from '../core/types.js';
+/**
+ * Desktop 上下文 (只读数据)
+ *
+ * 不包含行为，仅作为 Service 调用时的身份标识。
+ *
+ * 设计原则:
+ * - 不可变性: 所有属性为 readonly
+ * - 最小化: 仅包含必要的身份和状态信息
+ * - 可序列化: 可安全地跨边界传递
+ *
+ * @example
+ * ```typescript
+ * const ctx: DesktopContext = {
+ *     id: 'desktop_123',
+ *     createdAt: Date.now(),
+ *     status: 'active'
+ * };
+ *
+ * // 传递给 Service
+ * await appHostService.install(ctx.id, './app.js');
+ * ```
+ */
+export interface DesktopContext {
+    /** Desktop 唯一标识符 */
+    readonly id: DesktopID;
+    /** 创建时间戳 */
+    readonly createdAt: number;
+    /** 当前状态 */
+    readonly status: DesktopStatus;
+}
+/**
+ * Desktop Context Factory
+ *
+ * 创建 DesktopContext 实例的工厂函数类型。
+ */
+export type DesktopContextFactory = (id?: DesktopID) => DesktopContext;

package/dist/spi/runtime/desktop-context.interface.js

@@ -0,0 +1,10 @@
+/**
+ * SPI Layer - Desktop Context Interface
+ *
+ * Desktop 的不可变数据容器。
+ * 不包含行为，仅作为 Service 调用时的身份标识。
+ *
+ * @module @aotui/runtime/spi
+ */
+export {};
+//# sourceMappingURL=desktop-context.interface.js.map

package/dist/spi/runtime/desktop-context.interface.js.map

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

package/dist/spi/runtime/desktop-dom.interface.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SPI Layer - IDesktopDOM Interface
+ *
+ * [C2 FIX] 从 AppManager 提取的接口，定义 Engine 层模块与 Desktop 交互的最小契约。
+ *
+ * 设计原则:
+ * - Interface Segregation: 只暴露 AppManager 等模块真正需要的方法
+ * - Stable Dependency: Engine 层模块依赖此 SPI 接口，而非具体 Desktop 实现
+ *
+ * @module @aotui/runtime/spi
+ */
+import type { DesktopID, AppID } from '../core/types.js';
+/**
+ * Desktop DOM 操作接口
+ *
+ * Engine 层模块（如 AppManager, ViewManager）通过此接口与 Desktop 交互，
+ * 而非直接依赖 Desktop 类。这实现了依赖反转，使模块可独立测试。
+ *
+ * @example
+ * ```typescript
+ * class AppManager {
+ *     constructor(private readonly desktop: IDesktopDOM) {}
+ *
+ *     async installStatic(name: string, html: string): Promise<AppID> {
+ *         const doc = this.desktop.getDocument();
+ *         // ...
+ *     }
+ * }
+ * ```
+ */
+export interface IDesktopDOM {
+    /** Desktop 唯一标识 */
+    readonly id: DesktopID;
+    /** 获取 Document 对象 (用于 DOM 操作) */
+    getDocument(): Document;
+    /** 获取 Window 对象 (linkedom Window) */
+    getWindow(): any;
+    /** 发送更新信号 */
+    emitSignal(reason: string): void;
+    /** 记录系统日志 */
+    logSystem(message: string, level?: 'info' | 'warn' | 'error'): void;
+    /** 记录 App 操作日志 */
+    logAppOperation(appId: AppID, message: string, level?: 'info' | 'warn' | 'error'): void;
+    /** [A1] 观察 App 沙箱的 DOM 变化 */
+    observeAppDOM(appId: AppID, window: any): void;
+    /** [A1] 停止观察 App 沙箱 */
+    stopObservingApp(appId: AppID): void;
+}