@aotui/runtime 1.0.0

package/dist/engine/view/snapshot/templates.js

@@ -0,0 +1,317 @@
+/**
+ * TUI Snapshot Templates
+ *
+ * [RFC-007] System Instruction and formatting templates for TUI output.
+ * [RFC-014] Added SYSTEM_INSTRUCTION_PURE for semantic separation.
+ *
+ * @module @aotui/runtime/engine/view/snapshot/templates
+ */
+/**
+ * [RFC-014] Pure System Instruction - 100% Stable Meta Instructions
+ * [RFC-017] Updated to encourage parallel tool calls
+ *
+ * This template contains ONLY:
+ * - Who: Agent's role definition
+ * - Why: Agent's purpose
+ * - How: Operational guidelines
+ *
+ * NO dynamic content (Apps, Logs, State) is included.
+ * This enables maximum LLM KV Cache hit rate.
+ */
+export const SYSTEM_INSTRUCTION_PURE = `# TUI Desktop System Instruction
+
+## Who You Are
+
+You are the **sole operator** of this TUI (Text-based User Interface) Desktop.
+Human users communicate with you **through applications** (e.g., Chat app), not directly.
+
+## Why You Exist
+
+This is a text-based workspace designed for AI Agents to interact with applications and accomplish tasks.
+You have full control over this Desktop: open/close applications, mount/dismount views, and execute tools.
+
+## How You Work
+
+### Function Calling Convention
+
+- App tools: \`{app_id}-{view_id}-{tool_id}\`
+- System tools: \`system-{tool}\`
+
+### Operational Workflow
+
+1. **READ** - Examine the current TUI state (check 'Where You Are' and 'What's Happening')
+2. **DECIDE** - Determine what action to take
+3. **ACT** - Execute tool(s) via Function Call. **Batch independent tools when possible.**
+4. **CHECK** - Review the result in 'What Just Happened'
+5. **LOOP or WAIT** - Continue or end the response without calling any tool
+
+### Parallel Tool Execution
+
+You CAN call **multiple tools in a single response** when:
+
+1. **Independent Tasks** - Tools don't depend on each other's results
+   - ✅ \`send_message\` + \`update_topic\` (independent)
+   - ✅ Multiple \`pin_message\` for different items
+   - ✅ \`open_app\` for multiple apps simultaneously
+
+2. **Batch Operations** - Same tool on multiple targets
+   - ✅ Pin 3 different messages at once
+   - ✅ Close multiple apps at once
+
+You SHOULD execute **sequentially** (one tool per response) when:
+
+- Tool B needs the result from Tool A
+- You're unsure about the state after Tool A
+- The operation involves creating then using a resource
+
+**Examples:**
+
+<example>
+[User: "Pin the last 2 messages and update the topic summary"]
+Agent: Call BOTH 'pin_message' (x2) AND 'update_topic' in ONE response
+</example>
+
+<example>
+[User: "Create a todo and then mark it done"]
+Agent: First call 'create_todo', WAIT for result, then call 'mark_done'
+</example>
+
+### System Tools
+
+| Tool | When to Use |
+|-----------|-------------|
+| \`system-open_app\` | Need an app that's not currently open |
+| \`system-close_app\` | Done with an app, free context space |
+| \`system-dismount_view\` | Remove a specific view to reduce clutter |
+
+### Tone and Style
+
+- Be concise and task-focused. Minimize text output.
+- Never explain what you're about to do - just do it.
+- Never summarize what you just did - move to the next task or wait.
+
+### Proactiveness Rules
+
+- Be **reactive, not proactive**. Wait for signals before acting.
+- When there's nothing to do → end the response without calling any tool.
+- Never invent tasks. If the TUI shows no pending work, wait.
+
+IMPORTANT: Always read the current TUI state before taking any action. Never assume state from memory.
+IMPORTANT: When you have nothing to do, do not call any tool.
+`;
+/**
+ * System Instruction for LLM Agent @opencode
+ *
+ * @deprecated Use SYSTEM_INSTRUCTION_PURE + structured snapshot for RFC-014
+ *
+ * This is the first thing the Agent sees in every snapshot.
+ * It establishes the Agent's role and available operations.
+ */
+export const SYSTEM_INSTRUCTION = `# TUI Desktop System Instruction
+
+You are the **sole operator** of this TUI (Text-based User Interface) Desktop.
+This is a text-based workspace designed for AI Agents to interact with applications and accomplish tasks.
+
+Human users communicate with you **through applications** (e.g., Chat app), not directly.
+You have full control over this Desktop: open/close applications, mount/dismount views, and execute operations.
+
+IMPORTANT: Always read the current TUI state before taking any action. Never assume state from memory.
+IMPORTANT: Each operation you execute is atomic. Check the result before proceeding to the next action.
+IMPORTANT: When you have nothing to do, do not call any tool. Never guess or hallucinate tasks.
+
+## Help & Guidance
+
+If the user asks about system capabilities or how to use the Desktop:
+
+- Refer them to the **Installed Applications** section in 'desktop' to see available apps
+- Each application's View contains an **Application Instruction** section explaining its purpose
+- For technical issues, the user should contact system administrators
+
+## Tone and Style
+
+You operate a TUI Desktop. Your "speech" is minimal - **actions speak louder than words**.
+
+**Core Principles:**
+
+- Be concise and task-focused. Minimize text output.
+- When communicating with users (via Chat app), be helpful but brief.
+- Never explain what you're about to do - just do it.
+- Never summarize what you just did - move to the next task or wait.
+
+IMPORTANT: Your output is logged and consumes tokens. Keep responses short unless the user explicitly asks for detail.
+IMPORTANT: After completing an operation, either continue to the next task or end the response. Do NOT output status updates.
+
+**Examples of appropriate behavior:**
+
+<example>
+[User sends "Hi" via Chat app]
+Agent action: Call 'app_0-view_0-send_message' with '{ "content": "Hello! How can I help you today?" }'
+</example>
+
+<example>
+[User asks "What time is it?"]
+Agent action: Call 'send_message' with '{ "content": "I don't have access to real-time clock. Is there something else I can help with?" }'
+</example>
+
+<example>
+[No new messages, no pending tasks]
+Agent action: End the response without calling any tool
+</example>
+
+<example>
+[TUI shows an error in Last Operation Results]
+Agent action: Check error code, decide recovery strategy, retry or inform user
+</example>
+
+<example>
+[User asks to pin an important message]
+Agent action: Call 'pin_message' with '{ "message": "recent_msgs[0]" }'
+</example>
+
+## Proactiveness
+
+You should be **reactive, not proactive**. Wait for signals before acting. 
+
+**Guidelines:**
+
+1. When the user sends a message → respond appropriately.
+2. When a task is in progress → continue until complete, then wait.
+3. When there's nothing to do → end the response without calling any tool.
+4. Never invent tasks. If the TUI shows no pending work, wait.
+5. Never perform actions "just in case" or "to be helpful".
+6. Never continuously repeat actions.
+
+**The Wait Rule:**
+After each operation, ask yourself: "Is there more work I need to do NOW?"
+
+- YES → Execute the next operation
+- NO → End the response without calling any tool
+
+## Understanding Applications
+
+Each application has its own purpose and operations. Before using an app:
+
+1. **Read the Application Instruction** - Each view has an instruction section explaining:
+   - What the app is for
+   - When to use it
+   - Available operations and their parameters
+
+2. **Check the Application View Tree** - See what views are mounted and what's available
+
+3. **Understand Operation Parameters** - Each operation lists required and optional parameters
+
+**Key Conventions:**
+
+- Never assume an operation exists without seeing it in the current TUI state
+- Never assume parameter values - use data from the TUI (e.g., 'recent_msgs[0]' references)
+- App data is accessed via semantic references like 'pinned_msgs[2]', not by guessing IDs
+
+## Operational Workflow
+
+Follow this loop for all tasks:
+
+**1. READ** - Examine the current TUI state
+
+- Check 'desktop' for installed apps and system logs
+- Check each 'application' for views and operation logs
+- Check each 'view' for content and available operations
+
+**2. DECIDE** - Determine what action to take
+
+- What is the user asking for?
+- Which app/view/operation is appropriate?
+- What parameters are needed?
+
+**3. ACT** - Execute tool(s) via Function Call. **Batch independent tools when possible.**
+
+- System commands: 'system-{tool}'
+- App tools: '{app_id}-{view_id}-{tool}'
+
+**4. CHECK** - Review the result in "Last Operation Results"
+
+- ✅ Success → Continue or wait
+- ❌ Failed → Handle error (retry, inform user, or escalate)
+
+**5. LOOP or WAIT**
+
+- More work to do? → Go to step 1
+- Nothing to do? → End the response without calling any tool
+
+IMPORTANT: Always check operation results. Failed operations need attention.
+IMPORTANT: Never skip the WAIT step. An idle agent should be waiting, not outputting text.
+
+## Operation Policy
+
+**Parallel Tool Execution:**
+
+- You CAN call **multiple tools in a single response** when they are independent
+- Execute sequentially when Tool B depends on Tool A's result
+- Each tool executes atomically; check results before proceeding
+
+**Referencing Data:**
+
+- Use semantic paths like 'recent_msgs[0]' to reference list items
+- Never hardcode IDs or guess values
+- If you need data not visible, mount the relevant view first
+
+**System Operations:**
+
+| Operation | Parameters | When to Use |
+|-----------|------------|-------------|
+| 'system-open_app' | '{ application: "app_id" }' | Need an app that's not currently open |
+| 'system-close_app' | '{ application: "app_id" }' | Done with an app, free context space |
+| 'system-dismount_view' | '{ app_id: "id", view_id: "id" }' | Remove a specific view |
+
+# TUI Structure Reference
+
+**Desktop Structure:**
+
+The content enclosed within the **DESKTOP** XML tag is the TUI Desktop, it includes
+  ## System Instruction (this section)
+  ## Installed Applications (list of apps with status)
+  ## System Logs (recent system events)
+
+The content enclosed within the **APPLICATION** XML tag is the TUI Desktop, it includes multiple **VIEW**s and application info.
+
+The content enclosed within the **VIEW** XML tag is the a view node of the TUI Application.
+
+**Function Call Format:**
+
+\`\`\` json
+{
+  "name": "app_0-view_0-send_message",
+  "arguments": {
+    "content": "Your message here"
+  }
+}
+\`\`\`
+
+**Common Errors and Recovery:**
+
+- 'E_UNKNOWN_OPERATION': Check if the operation exists in current view
+- 'E_INVALID_ARGS': Check parameter requirements in the operation definition
+- 'INDEX_OUT_OF_RANGE': The referenced item doesn't exist, check list length
+- 'E_NOT_FOUND': The referenced app/view/link doesn't exist`;
+/**
+ * Format timestamp to ISO-like readable string
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @returns Formatted string like "2026-01-15 16:00:00"
+ */
+export function formatTimestamp(timestamp) {
+    const date = new Date(timestamp);
+    return date.toISOString().replace('T', ' ').slice(0, 19);
+}
+/**
+ * Format application status for TUI display
+ */
+export function formatAppStatus(status) {
+    switch (status) {
+        case 'running': return 'running';
+        case 'pending': return 'available (not started)';
+        case 'closed': return 'not launched';
+        case 'collapsed': return 'minimized';
+        default: return status;
+    }
+}
+//# sourceMappingURL=templates.js.map

package/dist/engine/view/snapshot/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../../src/engine/view/snapshot/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgFtC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4DAwL0B,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,MAAsD;IACpF,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,SAAS,CAAC,CAAC,OAAO,SAAS,CAAC;QACjC,KAAK,SAAS,CAAC,CAAC,OAAO,yBAAyB,CAAC;QACjD,KAAK,QAAQ,CAAC,CAAC,OAAO,cAAc,CAAC;QACrC,KAAK,WAAW,CAAC,CAAC,OAAO,WAAW,CAAC;QACrC,OAAO,CAAC,CAAC,OAAO,MAAM,CAAC;IACzB,CAAC;AACH,CAAC"}

package/dist/engine/view/transformer/__tests__/visitors/test-utils.d.ts

@@ -0,0 +1 @@
+export declare function createMockElement(html: string): Element;

package/dist/engine/view/transformer/__tests__/visitors/test-utils.js

@@ -0,0 +1,14 @@
+import { parseHTML } from 'linkedom';
+export function createMockElement(html) {
+    const { document } = parseHTML(`<!DOCTYPE html><html><body>${html}</body></html>`);
+    const el = document.body.firstElementChild;
+    if (!el) {
+        // Fallback if linkedom behaving weirdly, check root
+        const rootEl = document.querySelector('div, application, view');
+        if (rootEl)
+            return rootEl;
+        throw new Error(`Failed to create mock element from: ${html}`);
+    }
+    return el;
+}
+//# sourceMappingURL=test-utils.js.map

package/dist/engine/view/transformer/__tests__/visitors/test-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.js","sourceRoot":"","sources":["../../../../../../src/engine/view/transformer/__tests__/visitors/test-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC1C,MAAM,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC,8BAA8B,IAAI,gBAAgB,CAAC,CAAC;IACnF,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC;IAC3C,IAAI,CAAC,EAAE,EAAE,CAAC;QACN,oDAAoD;QACpD,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,wBAAwB,CAAC,CAAC;QAChE,IAAI,MAAM;YAAE,OAAO,MAAiB,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,EAAa,CAAC;AACzB,CAAC"}

package/dist/engine/view/transformer/helpers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Transformer Helpers (Pure Functions)
+ *
+ * Shared utility functions for DOM traversal and payload sanitization.
+ * Extracted from pure.ts to support Visitor Pattern refactoring.
+ */
+/** DOM Node union type for type-safe traversal */
+export type DOMNode = Node | Element | Text | Comment | DocumentFragment;
+/** Type guard: Check if node is an Element */
+export declare function isElement(node: DOMNode): node is Element;
+/** Type guard: Check if node is a Text node */
+/**
+ * Type guard: Check if node is a Text node
+ */
+export declare function isText(node: DOMNode): node is Text;
+/**
+ * Decode HTML entities for JSON parsing
+ */
+export declare function decodeHtmlEntities(str: string): string;

package/dist/engine/view/transformer/helpers.js

@@ -0,0 +1,32 @@
+/**
+ * Transformer Helpers (Pure Functions)
+ *
+ * Shared utility functions for DOM traversal and payload sanitization.
+ * Extracted from pure.ts to support Visitor Pattern refactoring.
+ */
+/** Type guard: Check if node is an Element */
+export function isElement(node) {
+    return node.nodeType === 1;
+}
+/** Type guard: Check if node is a Text node */
+/**
+ * Type guard: Check if node is a Text node
+ */
+export function isText(node) {
+    return node.nodeType === 3;
+}
+// ============================================================================
+// Helper Functions (Pure)
+// ============================================================================
+/**
+ * Decode HTML entities for JSON parsing
+ */
+export function decodeHtmlEntities(str) {
+    return str
+        .replace(/"/g, '"')
+        .replace(/'/g, "'")
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&');
+}
+//# sourceMappingURL=helpers.js.map

package/dist/engine/view/transformer/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../src/engine/view/transformer/helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,8CAA8C;AAC9C,MAAM,UAAU,SAAS,CAAC,IAAa;IACnC,OAAO,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,+CAA+C;AAC/C;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,IAAa;IAChC,OAAO,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC1C,OAAO,GAAG;SACL,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAChC,CAAC"}

package/dist/engine/view/transformer/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Transformer (Compatibility Layer)
+ *
+ * 保持向后兼容的类形式 API。
+ * 内部委托给纯函数实现，无状态共享。
+ *
+ * @example
+ * ```typescript
+ * const transformer = new Transformer();
+ * const { markup, indexMap } = transformer.transform(dom);
+ * ```
+ *
+ * @see pure.ts 纯函数实现
+ */
+import type { IndexMap } from '../../../spi/index.js';
+import type { ITransformer } from '../../../spi/runtime/transformer.interface.js';
+export type { TransformResult, TransformContext } from './types.js';
+/**
+ * Transformer Class (Compatibility Wrapper)
+ *
+ * 这个类现在是无状态的，所有调用都委托给纯函数。
+ * 可以安全地在多个 Desktop 之间共享同一实例。
+ */
+export declare class Transformer implements ITransformer {
+    /**
+     * Transforms full DOM (Window or Document) to TUI Markup
+     */
+    transform(dom: unknown): {
+        markup: string;
+        indexMap: IndexMap;
+    };
+    /**
+     * Transform a single Element (e.g., app container) to TUI Markup
+     */
+    transformElement(element: Element, appId?: string): {
+        markup: string;
+        indexMap: IndexMap;
+    };
+}
+export { transformDOM, transformElement } from './pure.js';

package/dist/engine/view/transformer/index.js

@@ -0,0 +1,38 @@
+/**
+ * Transformer (Compatibility Layer)
+ *
+ * 保持向后兼容的类形式 API。
+ * 内部委托给纯函数实现，无状态共享。
+ *
+ * @example
+ * ```typescript
+ * const transformer = new Transformer();
+ * const { markup, indexMap } = transformer.transform(dom);
+ * ```
+ *
+ * @see pure.ts 纯函数实现
+ */
+import { transformDOM, transformElement as transformElementPure } from './pure.js';
+/**
+ * Transformer Class (Compatibility Wrapper)
+ *
+ * 这个类现在是无状态的，所有调用都委托给纯函数。
+ * 可以安全地在多个 Desktop 之间共享同一实例。
+ */
+export class Transformer {
+    /**
+     * Transforms full DOM (Window or Document) to TUI Markup
+     */
+    transform(dom) {
+        return transformDOM(dom);
+    }
+    /**
+     * Transform a single Element (e.g., app container) to TUI Markup
+     */
+    transformElement(element, appId) {
+        return transformElementPure(element, appId);
+    }
+}
+// Re-export pure functions for direct use
+export { transformDOM, transformElement } from './pure.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/view/transformer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/engine/view/transformer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,YAAY,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAKnF;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACpB;;OAEG;IACH,SAAS,CAAC,GAAY;QAClB,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,OAAgB,EAAE,KAAc;QAC7C,OAAO,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAChD,CAAC;CACJ;AAED,0CAA0C;AAC1C,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/engine/view/transformer/pure.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure Function Transformer
+ *
+ * Refactored to use Visitor Pattern (RFC-005).
+ * Stateless, thread-safe, and extensible.
+ *
+ * @module @aotui/runtime/engine/transformer/pure
+ */
+import type { TransformResult } from './types.js';
+/**
+ * Transform full DOM (Window or Document) to TUI Markup
+ */
+export declare function transformDOM(dom: unknown): TransformResult;
+/**
+ * Transform a single Element to TUI Markup
+ */
+export declare function transformElement(element: Element, appId?: string): TransformResult;

package/dist/engine/view/transformer/pure.js

@@ -0,0 +1,124 @@
+/**
+ * Pure Function Transformer
+ *
+ * Refactored to use Visitor Pattern (RFC-005).
+ * Stateless, thread-safe, and extensible.
+ *
+ * @module @aotui/runtime/engine/transformer/pure
+ */
+import { createTransformContext } from './types.js';
+import { isElement, isText } from './helpers.js';
+import { DEFAULT_VISITORS } from './visitors/index.js';
+/**
+ * Type guard for multi-sandbox structure
+ */
+function isDesktopDOM(dom) {
+    return (typeof dom === 'object' &&
+        dom !== null &&
+        'desktopId' in dom &&
+        'apps' in dom &&
+        dom.apps instanceof Map);
+}
+/**
+ * Transform full DOM (Window or Document) to TUI Markup
+ */
+export function transformDOM(dom) {
+    // Handle multi-sandbox structure
+    if (isDesktopDOM(dom)) {
+        return transformDesktopDOM(dom);
+    }
+    // Legacy: Single Window/Document
+    const ctx = createTransformContext();
+    let doc = dom;
+    if (dom.document) {
+        doc = dom.document;
+    }
+    const markup = traverse(doc.body, ctx);
+    return {
+        markup,
+        indexMap: ctx.indexMap
+    };
+}
+/**
+ * Transform a single Element to TUI Markup
+ */
+export function transformElement(element, appId) {
+    const ctx = createTransformContext(appId);
+    const markup = traverse(element, ctx);
+    return {
+        markup,
+        indexMap: ctx.indexMap
+    };
+}
+// ============================================================================
+// Internal Implementation
+// ============================================================================
+/**
+ * Transform Desktop DOM structure
+ */
+function transformDesktopDOM(desktop) {
+    const ctx = createTransformContext();
+    const parts = [];
+    // Traverse each App's Document
+    for (const [appId, doc] of desktop.apps) {
+        const container = doc.body.querySelector(`[data-app-id="${appId}"]`);
+        if (container) {
+            const appMarkup = traverse(container, ctx);
+            if (appMarkup.trim()) {
+                parts.push(appMarkup);
+            }
+        }
+    }
+    return {
+        markup: parts.join('\n'),
+        indexMap: ctx.indexMap
+    };
+}
+/**
+ * Core Traversal Function (Visitor Pattern)
+ */
+function traverse(node, ctx, visitors = DEFAULT_VISITORS) {
+    // 1. Text Nodes
+    if (isText(node)) {
+        return node.data.trim();
+    }
+    // 2. Element Check
+    if (!isElement(node))
+        return '';
+    const el = node;
+    // 3. Global Checks
+    const state = el.getAttribute('data-state');
+    if (state === 'hidden')
+        return '';
+    // [RFC-007] Ignore ViewTree container (sent separately)
+    if (el.hasAttribute('data-view-tree'))
+        return '';
+    // 4. Find Matching Visitor
+    // Visitors are strict priority ordered. The first match wins.
+    const visitor = visitors.find(v => v.matches(el, ctx));
+    if (visitor) {
+        // Log visitor usage for debug?
+        // console.log(`[Visitor] ${visitor.name} matched ${el.tagName}`);
+        // [RFC-FIX] Provide both ChildrenTraverser and ElementTraverser to visitors
+        // - ChildrenTraverser: traverse child nodes (existing behavior)
+        // - ElementTraverser: traverse a single element with full Visitor Chain
+        const childrenTraverser = (el, ctx) => traverseChildren(el, ctx, visitors);
+        const elementTraverser = (el, ctx) => traverse(el, ctx, visitors);
+        return visitor.transform(el, ctx, childrenTraverser, elementTraverser);
+    }
+    // 5. Fallback (Should be handled by HtmlVisitor if configured correctly, but as safety)
+    return traverseChildren(el, ctx, visitors).join(' ');
+}
+/**
+ * Child Traverser Helper
+ */
+function traverseChildren(el, ctx, visitors = DEFAULT_VISITORS) {
+    const results = [];
+    for (const child of Array.from(el.childNodes)) {
+        const text = traverse(child, ctx, visitors);
+        if (text)
+            results.push(text);
+    }
+    return results;
+}
+//# sourceMappingURL=pure.js.map

package/dist/engine/view/transformer/pure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pure.js","sourceRoot":"","sources":["../../../../src/engine/view/transformer/pure.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAW,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAevD;;GAEG;AACH,SAAS,YAAY,CAAC,GAAY;IAC9B,OAAO,CACH,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,WAAW,IAAI,GAAG;QAClB,MAAM,IAAI,GAAG;QACZ,GAAkB,CAAC,IAAI,YAAY,GAAG,CAC1C,CAAC;AACN,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACrC,iCAAiC;IACjC,IAAI,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,iCAAiC;IACjC,MAAM,GAAG,GAAG,sBAAsB,EAAE,CAAC;IAErC,IAAI,GAAG,GAAG,GAAe,CAAC;IAC1B,IAAK,GAAW,CAAC,QAAQ,EAAE,CAAC;QACxB,GAAG,GAAI,GAAW,CAAC,QAAoB,CAAC;IAC5C,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAEvC,OAAO;QACH,MAAM;QACN,QAAQ,EAAE,GAAG,CAAC,QAAQ;KACzB,CAAC;AACN,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,KAAc;IAC7D,MAAM,GAAG,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAEtC,OAAO;QACH,MAAM;QACN,QAAQ,EAAE,GAAG,CAAC,QAAQ;KACzB,CAAC;AACN,CAAC;AAED,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E;;GAEG;AACH,SAAS,mBAAmB,CAAC,OAAmB;IAC5C,MAAM,GAAG,GAAG,sBAAsB,EAAE,CAAC;IACrC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,+BAA+B;IAC/B,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,iBAAiB,KAAK,IAAI,CAAC,CAAC;QACrE,IAAI,SAAS,EAAE,CAAC;YACZ,MAAM,SAAS,GAAG,QAAQ,CAAC,SAA+B,EAAE,GAAG,CAAC,CAAC;YACjE,IAAI,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;gBACnB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC1B,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO;QACH,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QACxB,QAAQ,EAAE,GAAG,CAAC,QAAQ;KACzB,CAAC;AACN,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CACb,IAAa,EACb,GAAqB,EACrB,WAA8B,gBAAgB;IAE9C,gBAAgB;IAChB,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED,mBAAmB;IACnB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAEhC,MAAM,EAAE,GAAG,IAAI,CAAC;IAEhB,mBAAmB;IACnB,MAAM,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;IAC5C,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAElC,wDAAwD;IACxD,IAAI,EAAE,CAAC,YAAY,CAAC,gBAAgB,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjD,2BAA2B;IAC3B,8DAA8D;IAC9D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAEvD,IAAI,OAAO,EAAE,CAAC;QACV,+BAA+B;QAC/B,kEAAkE;QAElE,4EAA4E;QAC5E,gEAAgE;QAChE,wEAAwE;QACxE,MAAM,iBAAiB,GAAG,CAAC,EAAW,EAAE,GAAqB,EAAE,EAAE,CAAC,gBAAgB,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QACtG,MAAM,gBAAgB,GAAG,CAAC,EAAW,EAAE,GAAqB,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QAE7F,OAAO,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;IAC3E,CAAC;IAED,wFAAwF;IACxF,OAAO,gBAAgB,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CACrB,EAAW,EACX,GAAqB,EACrB,WAA8B,gBAAgB;IAE9C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC5C,IAAI,IAAI;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC"}

package/dist/engine/view/transformer/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Transformer Types
+ *
+ * 共享类型定义，供纯函数和兼容层使用
+ */
+import type { IndexMap } from '../../../spi/index.js';
+/**
+ * Transform 结果
+ */
+export interface TransformResult {
+    markup: string;
+    indexMap: IndexMap;
+}
+/**
+ * Transform 上下文 (纯函数内部状态)
+ *
+ * 这些数据在单次 transform 调用中积累，
+ * 但不跨调用共享，保证线程安全。
+ */
+export interface TransformContext {
+    /** 累积的 IndexMap */
+    indexMap: IndexMap;
+    /** 当前 App ID 上下文 */
+    currentAppId: string | null;
+    /** 当前 View ID 上下文 */
+    currentViewId: string | null;
+}
+/**
+ * 创建新的 TransformContext
+ */
+export declare function createTransformContext(appId?: string): TransformContext;