diff --git a/docs/research/README.md b/docs/research/README.md
new file mode 100644
index 0000000..34b2348
--- /dev/null
+++ b/docs/research/README.md
@@ -0,0 +1,52 @@
+# UJSX Research Index
+
+All research documents for the `@alkdev/ujsx` rewrite. This project is a universal JSX IR that treats JSX as an intermediate representation for multi-target rendering (markdown primary, graph/HTML/etc. future).
+
+## Architecture & Design
+
+| Doc | Description |
+|-----|-------------|
+| [agent-hud-architecture.md](./agent-hud-architecture.md) | Full HUD architecture: event log, adaptive density, cache-aware system prompt, plugin integration |
+| [ujsx-v2-typebox-rewrite.md](./ujsx-v2-typebox-rewrite.md) | The rewrite plan: TypeBox-schema-driven UJSX, bi-directional transforms, JSX syntax, HTML-agnostic core |
+| [signals-ujsx-reactive-pipeline.md](./signals-ujsx-reactive-pipeline.md) | Preact Signals integration: `computed()` components, reactive transform pipeline, signals+TypeBox interaction |
+
+## Ecosystem & Feasibility
+
+| Doc | Description |
+|-----|-------------|
+| [unist-ecosystem-jsx-to-markdown.md](./unist-ecosystem-jsx-to-markdown.md) | hast/mdast/syntax-tree ecosystem, pipeline feasibility, element mappings, alternative approaches |
+| [hono-jsx-ssr-llm-hud.md](./hono-jsx-ssr-llm-hud.md) | Hono JSXNode internals, SSR pipeline, custom walker feasibility for markdown rendering |
+
+## TypeBox Patterns
+
+| Doc | Description |
+|-----|-------------|
+| [typebox-module-type-registry.md](./typebox-module-type-registry.md) | `Type.Module` as type registry, `Import` mechanics, runtime schema access, implications for UJSX |
+| [typebox-module-valuepointer.md](./typebox-module-valuepointer.md) | `TModule` + `ValuePointer` API, `ComputeModuleProperties`, Function types, practical patterns |
+
+## Prior Art & Source Reference
+
+| Doc | Description |
+|-----|-------------|
+| [prior-poc-source-reference.md](./prior-poc-source-reference.md) | Code from `/workspace/aui/ujsx` POC: what to preserve, what to remove/rewrite, TypeBox research examples |
+
+## External Resources
+
+| Location | Description |
+|----------|-------------|
+| `/workspace/aui/ujsx/` | Prior POC: core types, h() factory, HostConfig, Graphology host, TransformRegistry, StreamingTransformer |
+| `/workspace/aui/SUMMARY.md` | POC summary with architecture, strengths, gaps, recommendations |
+| `/workspace/research/typebox_research/ujsx/` | TypeBox Module examples: `unist.ts` (unist schema), `ujsx.ts` (UJSX schema draft) |
+| `/workspace/@alkdev/typebox/` | TypeBox fork source: Module, ValuePointer, Value system |
+| `/workspace/signals/packages/core/` | Preact Signals core: signal, computed, effect, batch, createModel |
+| `/workspace/conversations/research/` | Original research docs from conversation session |
+
+## Key Decisions from Prior Discussion
+
+1. **TypeBox Module IS the type registry** — no separate registry needed. `ValuePointer.Get/Set` for runtime access, `Module.Import` for resolved schemas.
+2. **Signals for reactivity** — `computed()` wrapping component functions so unchanged inputs skip re-evaluation. NOT in the registry, but in the transformation process.
+3. **Bi-directional transforms** — same registry, `direction` parameter. UJSX↔mdast, UJSX↔hast. Rules match on TypeBox schemas, not string tags.
+4. **HTML-agnostic core** — no onClick, className, aria-* in UniversalProps. Hosts handle platform specifics.
+5. **Actual JSX syntax** — `jsxImportSource: "@alkdev/ujsx"` with jsx-runtime exports.
+6. **HostConfig preserved** — same reconciler pattern from POC, but mount-only → full reconciliation.
+7. **Platform agnostic** — no Deno/Node-specific APIs in core. Published as `@alkdev/ujsx`.
\ No newline at end of file
diff --git a/docs/research/agent-hud-architecture.md b/docs/research/agent-hud-architecture.md
new file mode 100644
index 0000000..5ddea32
--- /dev/null
+++ b/docs/research/agent-hud-architecture.md
@@ -0,0 +1,675 @@
+# Agent HUD: A Context Management Architecture for LLM Agents
+
+## Research → Design Synthesis
+
+This document synthesizes findings from six research areas into a concrete architecture for an agent HUD system that replaces ad-hoc compaction with structured, cache-aware context management.
+
+**See also**: [`ujsx-v2-typebox-rewrite.md`](./ujsx-v2-typebox-rewrite.md) — The UJSX v2 rewrite plan, replacing the existing POC at `/workspace/aui` with a TypeBox-schema-driven universal JSX IR that supports actual JSX syntax, bi-directional transforms, and component schemas as tool schemas.
+
+---
+
+## The Problem
+
+Current LLM agent interfaces have a fundamental flaw: **context is managed as a monolithic conversation log that grows until it must be violently compacted**. This creates several pathologies:
+
+1. **Information cliff**: Compaction replaces rich conversation with a lossy summary. Everything before the compaction boundary is gone — the agent can't even know what it lost.
+
+2. **Reactive, not proactive**: OpenCode's compaction fires at ~92% context usage. There's no budgeting — system prompt, tool definitions, and conversation history compete for the same fixed space with no allocation strategy.
+
+3. **Cognitive waste**: The agent sees the full conversation log every turn, including messages that are no longer relevant. Early messages about setup, resolved errors, and abandoned approaches consume tokens without providing value.
+
+4. **Cognitive strain**: The agent has no ambient awareness of its own state. It must explicitly call tools to check context usage, search history, or understand where it is in a task. Each tool call costs a turn and consumes context.
+
+5. **No provider-cache alignment**: OpenCode's 2-part system prompt split (`llm.ts:115-126`) is the only cache-aware structure. The rest of the context — messages, tool results, the full conversation — has no cache segmentation.
+
+The key insight: **the "agent frame" — what the LLM sees in a single turn — should be treated as a composition problem, not an append-only log problem.**
+
+---
+
+## The Leverage Point
+
+OpenCode's `llm.ts:115-126` reveals the critical pattern:
+
+```typescript
+// rejoin to maintain 2-part structure for caching if header unchanged
+if (system.length > 2 && system[0] === header) {
+ const rest = system.slice(1)
+ system.length = 0
+ system.push(header, rest.join("\n"))
+}
+```
+
+This splits the system prompt into:
+- **Part 0** (cached, stable): Agent prompt, provider prompt — changes rarely, benefits from prompt caching
+- **Part 1** (dynamic, re-cached each call): Environment, skills, instructions — changes often
+
+The plugin system pushes to `output.system[]` which gets merged into Part 1. The open-memory plugin injects context status (~50 tokens) into this dynamic part.
+
+**This 2-part pattern generalizes.** We can extend it to a multi-part context composition with different cache characteristics:
+
+| Part | Content | Changes | Cache Value |
+|------|---------|---------|-------------|
+| 0 | Agent identity, core instructions | Rarely | Highest (static across turns) |
+| 1 | HUD static layer (task, key decisions) | On agent action | High (stable within a task phase) |
+| 2 | HUD dynamic layer (notes, recent events) | Every turn | Medium (re-cached each call) |
+| 3 | Conversation messages | Every turn | Low (grows monotonically) |
+
+---
+
+## Architecture: The Agent HUD
+
+### Core Concept
+
+The HUD is a **structured markdown document** that the agent sees at the top of every turn, injected via the `experimental.chat.system.transform` plugin hook. Unlike compaction (which discards information), the HUD is:
+- **Composed**: Built from components, not a flat log
+- **Bidirectional**: The agent can update it via tools
+- **Cache-aware**: Structured so static parts benefit from provider caching
+- **Adaptive**: Automatically adjusts density based on context pressure
+
+### The "Agent Frame" Model
+
+Instead of treating the conversation as an append-only log, think of each agent turn as a **frame** composed of:
+
+```
+┌─────────────────────────────────────┐
+│ System Prompt Part 0 (cached) │ ← Agent identity, core instructions
+│ [never changes within a session] │
+├─────────────────────────────────────┤
+│ System Prompt Part 1 (re-cached) │ ← HUD rendered to markdown
+│ ┌─────────────────────────────────┐ │
+│ │ # Task │ │ ← Static HUD (changes on action)
+│ │ Implement auth module │ │
+│ │ │ │
+│ │ ## Context │ │ ← Adaptive density
+│ │ 67% used (134k/200k tokens) │ │ ← Context status
+│ │ Trend: growing rapidly │ │
+│ │ │ │
+│ │ ## Key Decisions │ │ ← Agent-maintained state
+│ │ • Using JWT over sessions │ │
+│ │ • bcrypt for password hashing │ │
+│ │ │ │
+│ │ ## Active Files │ │ ← Derived from tool calls
+│ │ • src/auth/mod.ts (editing) │ │
+│ │ • src/auth/jwt.ts (referenced) │ │
+│ │ │ │
+│ │ ## Next Steps │ │ ← Agent's own plan
+│ │ 1. Add refresh token rotation │ │
+│ │ 2. Write auth middleware │ │
+│ │ 3. Add tests │ │
+│ │ │ │
+│ │ ## Notes │ │ ← Agent's scratchpad
+│ │ • DB schema: users, sessions │ │
+│ │ • Rate limit: 100/min default │ │
+│ └─────────────────────────────────┘ │
+├─────────────────────────────────────┤
+│ Conversation Messages │ ← Standard message history
+│ [filtered by compaction boundary] │
+└─────────────────────────────────────┘
+```
+
+### The Append-Only Event Log
+
+Underlying the HUD is an **append-only event log** — similar to Yjs/CRDT event streams but simpler because we're single-author (one agent per session). This is the "source of truth" that the HUD renders from.
+
+```typescript
+interface HudEvent {
+ id: string // UUID
+ type: HudEventType // discriminated union
+ timestamp: number // Unix ms
+ sessionId: string // opencode session ID
+ turn: number // which agent turn
+ payload: unknown // type-specific data
+}
+
+type HudEventType =
+ | "task.set" // Agent sets the current task description
+ | "task.update" // Agent refines the task
+ | "decision.record" // Agent records a key decision
+ | "note.add" // Agent adds a note
+ | "note.update" // Agent updates a note
+ | "note.remove" // Agent removes a note
+ | "file.open" // Agent reads a file (derived from tool calls)
+ | "file.edit" // Agent edits a file (derived from tool calls)
+ | "file.close" // File falls out of recent context
+ | "step.complete" // Agent marks a step complete
+ | "step.add" // Agent adds a next step
+ | "step.reorder" // Agent reorders steps
+ | "error.encountered" // Agent encounters an error
+ | "error.resolved" // Agent resolves an error
+ | "blocker.add" // Agent identifies a blocker
+ | "blocker.remove" // Agent removes a blocker
+ | "context.snapshot" // Context window usage snapshot (auto-generated)
+ | "compact.before" // Pre-compaction state snapshot
+ | "compact.after" // Post-compaction state + summary
+```
+
+The event log is persisted and append-only. It replaces the "conversation log as only state" model with "conversation log as one input to the HUD, alongside structured state."
+
+### Rendering Pipeline: UJSX → MDAST → Markdown
+
+The HUD uses the **UJSX v2** universal JSX IR (see [`ujsx-v2-typebox-rewrite.md`](./ujsx-v2-typebox-rewrite.md)) built on TypeBox schemas. The existing POC at `/workspace/aui` already implements UJSX → mdast → markdown with a `TransformRegistry` and `mdast-util-to-markdown`. The v2 rewrite adds:
+
+- Actual JSX syntax (via `jsxImportSource: "@ade/ujsx"`)
+- TypeBox schema-driven node types (schemas ARE types, schemas ARE tool parameter schemas)
+- Bi-directional transforms (UJSX ↔ mdast, UJSX ↔ hast, etc.)
+- HTML-agnostic core (no `onClick`, `className` in universal props)
+
+```
+HUD Components (.tsx with JSX syntax)
+ │
+ ▼
+h() factory / JSX transform → UElement tree (TypeBox-schema-validated)
+ │
+ ▼ TransformRegistry (direction: 'ujsx->mdast')
+ │ Rules match on TypeBox schemas, not string tags
+ │
+mdast tree
+ │
+ ▼ mdast-util-to-markdown + mdast-util-gfm
+ │
+Markdown String
+ │
+ ▼ Injected via experimental.chat.system.transform
+ │
+System Prompt Part 1
+```
+
+**Why UJSX (not Hono JSXNode, not hast→mdast)?**
+
+1. **Schema-driven**: TypeBox schemas serve triple duty — TypeScript types, runtime validation, and tool parameter schemas. Component props = tool input schemas. Zero duplication.
+2. **Bi-directional**: Rules convert both UJSX→mdast AND mdast→UJSX. Parse existing markdown (notes, AGENTS.md) back into the IR.
+3. **HTML-agnostic**: No `onClick`, `className`, `aria-*` in the core. The IR isn't pretending to be HTML.
+4. **HostConfig preserved**: The same component tree renders to graphology, markdown, or future targets.
+5. **Actual JSX syntax**: With `jsxImportSource`, write `` not `h('TaskSection', { task: state.task, density: 'compact' })`.
+
+### HUD Component Architecture
+
+```tsx
+// The root HUD component
+function HUD({ state, contextInfo }: { state: HudState, contextInfo: ContextInfo }) {
+ const density = getDensity(contextInfo.percentage)
+
+ return (
+
+
+
+ {density !== 'minimal' && }
+ {density !== 'minimal' && }
+
+ {density === 'full' && }
+ {contextInfo.percentage > 85 && }
+
+ )
+}
+
+// Adaptive density: renders differently based on context pressure
+type Density = 'full' | 'compact' | 'minimal'
+
+function getDensity(percentage: number): Density {
+ if (percentage < 70) return 'full'
+ if (percentage < 85) return 'compact'
+ return 'minimal'
+}
+
+// Example adaptive component
+function DecisionsList({ decisions, density }: { decisions: Decision[], density: Density }) {
+ if (density === 'compact') {
+ return {`## Decisions (${decisions.length})\n` + decisions.map(d => `- ${d.summary}`).join('\n')}
+ }
+ return (
+
+ {decisions.map(d => )}
+
+ )
+}
+```
+
+### Cache-Aware System Prompt Structure
+
+The key extension of OpenCode's 2-part pattern:
+
+```
+System Message 0 (cached, stable):
+ - Agent identity prompt
+ - Provider-specific prompt
+ — Never changes within a session
+
+System Message 1 (re-cached each call):
+ - HUD static layer (task, decisions, next steps)
+ - HUD dynamic layer (context bar, notes, active files)
+ - Environment info, skills, instructions
+ — Changes based on agent actions and context pressure
+```
+
+The **static layer** of the HUD should change only when the agent explicitly updates it (task change, decision recorded, step completed). The **dynamic layer** changes every turn (context percentage, recent files, notes).
+
+For Anthropic's `cache_control`, we mark:
+- System message 0 → `cacheControl: { type: "ephemeral" }` (already done by opencode)
+- System message 1 → `cacheControl: { type: "ephemeral" }` (already done by opencode)
+
+The savings come from keeping message 0 stable (0.1x cost on cache hits) and making message 1 as small as possible while still providing full situational awareness.
+
+### HUD State and Event Log Storage
+
+The event log uses the same SQLite database opencode already has, with a new table:
+
+```sql
+CREATE TABLE hud_event (
+ id TEXT PRIMARY KEY,
+ session_id TEXT NOT NULL REFERENCES session(id),
+ type TEXT NOT NULL, -- HudEventType
+ turn INTEGER NOT NULL, -- agent turn number
+ timestamp INTEGER NOT NULL, -- Unix ms
+ payload TEXT NOT NULL, -- JSON
+ created_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX idx_hud_event_session ON hud_event(session_id, timestamp);
+CREATE INDEX idx_hud_event_type ON hud_event(session_id, type);
+```
+
+The **HUD state** is derived from the event log by projectors (similar to opencode's existing event sourcing pattern):
+
+```typescript
+interface HudState {
+ task: { description: string; updatedAt: number } | null
+ decisions: Array<{ id: string; summary: string; details: string; recordedAt: number }>
+ notes: Array<{ id: string; content: string; updatedAt: number }>
+ activeFiles: Array<{ path: string; lastAccessed: number; status: 'reading' | 'editing' | 'referenced' }>
+ nextSteps: Array<{ id: string; description: string; completed: boolean; order: number }>
+ blockers: Array<{ id: string; description: string; resolved: boolean }>
+ errors: Array<{ id: string; message: string; resolved: boolean; resolvedAt?: number }>
+}
+```
+
+Projectors are pure functions: `(state, event) => newState`. They're deterministic and idempotent — the state can always be rebuilt from the event log.
+
+Some events are **derived** rather than agent-authored:
+- `file.open`, `file.edit`, `file.close`: Intercepted from opencode's `tool.execute.before/after` hook by watching for Read, Write, Edit tools
+- `context.snapshot`: Auto-generated from `SessionProcessor` events tracking token usage
+
+### HUD Tools (Agent-Facing)
+
+The agent interacts with the HUD through two tools (following the router pattern from open-memory):
+
+**`hud`** (router tool — reduces context bloat from tool definitions):
+
+```typescript
+hud(input: {
+ tool: string, // operation name
+ args?: object // operation arguments
+})
+```
+
+Operations:
+- `task.get` / `task.set` / `task.update` — Manage current task
+- `decisions.list` / `decisions.record` / `decisions.remove` — Key decisions log
+- `notes.list` / `notes.add` / `notes.update` / `notes.remove` — Scratchpad
+- `steps.list` / `steps.add` / `steps.complete` / `steps.reorder` — Next steps / plan
+- `blockers.list` / `blockers.add` / `blockers.remove` — Blockers
+- `snapshot` — Full HUD state
+- `history` — Recent event log (for understanding what changed)
+
+**`hud_compact`** (mutation tool — separate to prevent accidental use):
+
+```typescript
+hud_compact() // Triggers both HUD compaction AND opencode compaction
+```
+
+This is distinct from `memory_compact` because:
+1. It snapshots HUD state to the event log before compaction
+2. After compaction, the stable HUD layer carries forward — the agent doesn't lose its task, decisions, or notes
+3. It can trigger compaction at a natural breakpoint (when the agent says "next steps updated, good time to compact")
+
+### Plugin Integration (opencode)
+
+The HUD is implemented as an opencode plugin, using these hooks:
+
+```typescript
+const HUDPlugin: Plugin = async (ctx) => {
+ const stateManager = new HudStateManager(ctx) // Manages event log + projectors
+ const renderer = new HudRenderer() // JSX component → markdown
+
+ return {
+ tool: { hud: createHudTool(ctx, stateManager), hud_compact: createHudCompactTool(ctx, stateManager) },
+
+ "experimental.chat.system.transform": async (input, output) => {
+ // Render HUD and inject as system prompt
+ const state = stateManager.getState(input.sessionID)
+ const contextInfo = getContextInfo(input.sessionID)
+ const markdown = renderer.render(HUD, { state, contextInfo })
+ output.system.push(markdown)
+ },
+
+ "experimental.session.compacting": async (input, output) => {
+ // Before compaction: snapshot HUD state to event log
+ stateManager.recordEvent(input.sessionID, { type: "compact.before", payload: stateManager.getState(input.sessionID) })
+ // Replace compaction prompt with self-continuity + HUD-aware prompt
+ output.prompt = getCompactionPrompt(stateManager.getState(input.sessionID))
+ },
+
+ "event": async ({ event }) => {
+ // Derive file events from tool calls
+ if (event.type === "tool.execute.after") {
+ stateManager.maybeRecordFileEvent(event)
+ }
+ // Track context snapshots
+ if (event.type === "message.updated") {
+ stateManager.maybeRecordContextSnapshot(event)
+ }
+ },
+
+ "tool.execute.before": async (input, output) => {
+ // Track file access from tool calls
+ stateManager.trackToolCall(input)
+ },
+ }
+}
+```
+
+### Rendering Pipeline Implementation
+
+```typescript
+// core/renderer.ts
+
+import type { FC } from "hono/jsx"
+
+interface RenderContext {
+ density: Density
+ state: HudState
+ contextInfo: ContextInfo
+}
+
+class HudRenderer {
+ // Custom walker over Hono JSXNode tree
+ render(component: FC, props: Record): string {
+ const node = component(props)
+ return this.walkNode(node)
+ }
+
+ private walkNode(node: any): string {
+ if (typeof node === "string" || typeof node === "number") {
+ return String(node)
+ }
+ if (node === null || node === undefined || node === false) {
+ return ""
+ }
+ if (node instanceof Promise) {
+ throw new Error("Async components not supported in HUD rendering")
+ }
+
+ // JSXFragmentNode — just concatenate children
+ if (node.tag === null || node.tag === Symbol.for("hono.fragment")) {
+ return (node.children as any[]).map(c => this.walkNode(c)).join("\n")
+ }
+
+ // Function component — call it and walk the result
+ if (typeof node.tag === "function") {
+ const result = node.tag({ ...node.props, children: node.children })
+ return this.walkNode(result)
+ }
+
+ // Intrinsic element — map HTML tag to markdown
+ return this.renderElement(node.tag, node.props, node.children)
+ }
+
+ private renderElement(tag: string, props: any, children: any[]): string {
+ const childContent = (children || []).map(c => this.walkNode(c)).join("\n")
+
+ switch (tag) {
+ case "h1": return `# ${childContent}`
+ case "h2": return `## ${childContent}`
+ case "h3": return `### ${childContent}`
+ case "strong": case "b": return `**${childContent}**`
+ case "em": case "i": return `*${childContent}*`
+ case "code": return props.lang
+ ? `\`\`\`${props.lang}\n${childContent}\n\`\`\``
+ : `\`${childContent}\``
+ case "ul": return childContent
+ case "li": return `- ${childContent}`
+ case "ol": return childContent // handled by parent
+ case "p": return childContent
+ case "div": case "section": case "article": case "main": case "header":
+ case "footer": case "nav": case "aside": case "span":
+ return childContent // container — just pass through content
+ case "a": return `[${childContent}](${props.href})`
+ case "blockquote": return childContent.split("\n").map(l => `> ${l}`).join("\n")
+ case "hr": return "---"
+ case "br": return "\n"
+ case "pre": return childContent // content already formatted by
+ case "table": return this.renderTable(props, children)
+ default:
+ // Unknown/custom tags: use data-md attribute or just render content
+ if (props?.["data-md"]) {
+ // Custom markdown rendering hint
+ return this.renderCustomMd(props["data-md"], props, childContent)
+ }
+ return childContent
+ }
+ }
+}
+```
+
+### Adaptive Density in Practice
+
+The key insight from open-memory's context status thresholding: **information density should be proportional to context pressure.**
+
+```
+Context < 70% (GREEN / "full"):
+ ┌────────────────────────────────────┐
+ │ # Task │
+ │ Implement user authentication │
+ │ │
+ │ ## Context: 45% (90k/200k) stable │
+ │ │
+ │ ## Decisions (3) │
+ │ • Using JWT over sessions │
+ │ • bcrypt for password hashing │
+ │ • Rate limiting: 100/min default │
+ │ │
+ │ ## Active Files │
+ │ • src/auth/mod.ts (editing) │
+ │ • src/auth/jwt.ts (referenced) │
+ │ • src/db/schema.ts (referenced) │
+ │ │
+ │ ## Next Steps │
+ │ 1. ~~Add refresh token rotation~~ │
+ │ 2. Write auth middleware │
+ │ 3. Add tests │
+ │ │
+ │ ## Notes │
+ │ • DB schema: users, sessions │
+ │ • Env vars: JWT_SECRET, DB_URL │
+ └────────────────────────────────────┘
+ ~300-500 tokens
+
+Context 70-85% (YELLOW / "compact"):
+ ┌────────────────────────────────────┐
+ │ Task: Implement auth │ 72% (144k) ↑ │
+ │ Decisions: JWT, bcrypt, 100/min │
+ │ Steps: ~~rotation~~, middleware, │
+ │ tests │
+ │ Files: auth/mod.ts, auth/jwt.ts │
+ │ Notes: DB schema users/sessions │
+ └────────────────────────────────────┘
+ ~100-150 tokens
+
+Context 85-92% (RED / "minimal"):
+ ┌────────────────────────────────────┐
+ │ Auth impl │ 89% │ ⚠ compact soon │
+ │ JWT+bcrypt, step: middleware │
+ └────────────────────────────────────┘
+ ~30-50 tokens
+```
+
+This adaptive compression means the agent always has situational awareness, but the cost scales inversely with available context.
+
+### Compaction That Preserves State
+
+The critical difference from current compaction: **the HUD state survives compaction.**
+
+Current flow:
+```
+[conversation] → COMPACT → [summary replaces everything] → agent loses context
+```
+
+HUD-aware flow:
+```
+[event log] → project to HUD state → render HUD → [inject into system prompt]
+[conversation] → COMPACT → [summary replaces conversation, but HUD persisted state carries forward]
+```
+
+Before compaction:
+1. Agent records `compact.before` event with full HUD state
+2. HUD state is persisted to the event log (already append-only)
+3. Compaction prompt includes: "Your HUD state: {rendered HUD}. This will survive compaction."
+
+After compaction:
+1. `filterCompacted` drops pre-compaction messages
+2. But the system prompt still contains the fully rendered HUD
+3. The agent sees its task, decisions, notes, and next steps — not just a narrative summary
+
+The compaction summary becomes a **complement** to the HUD, not a **replacement** for lost context. The summary handles conversational continuity ("we were discussing..."), while the HUD provides structured persistent state.
+
+### Comparison: Current vs HUD Architecture
+
+| Aspect | Current (Compaction) | HUD Architecture |
+|--------|---------------------|------------------|
+| State management | Monolithic conversation log | Structured event log + HUD projection |
+| Context loss | All-or-nothing compaction cliff | Adaptive density that preserves key state |
+| Agent awareness | Must call memory tool | Ambient via system prompt injection |
+| Cache optimization | 2-part system prompt only | Multi-part with stable HUD layer |
+| Recovery from compaction | LLM-generated summary (lossy) | Structured HUD state (deterministic) |
+| Cognitive load | Full conversation always visible | Relevant state always visible, details on demand |
+| Token cost at 50% | Full conversation (~100k tokens of history) | Conversation + HUD (~100k + ~300 tokens) |
+| Token cost at 90% | Conversation (truncated by compaction, then grows again) | Conversation + compact HUD (truncated + ~50 tokens) |
+
+---
+
+## Implementation Plan
+
+### Phase 1: Minimal Viable HUD (Plugin)
+
+1. **Event log table**: Add `hud_event` table to opencode's SQLite database (via plugin)
+2. **Basic event types**: `task.set`, `task.update`, `decision.record`, `note.add`, `step.add`, `step.complete`
+3. **State projector**: Pure functions that fold events into `HudState`
+4. **Simple renderer**: Template-based markdown rendering (no JSX yet)
+5. **Plugin hooks**: `system.transform` for injection, `event` for derivation, `session.compacting` for pre-compaction snapshot
+6. **Two tools**: `hud` (router) and `hud_compact`
+
+### Phase 2: JSX Rendering Pipeline
+
+1. **Hono JSXNode walking**: Custom ` HudRenderer` that walks JSXNode trees directly to markdown
+2. **HUD components**: ``, ``, ``, ``, ``, ``
+3. **Adaptive density**: Components that render differently based on `density` prop
+4. **Test rendering**: Snapshot tests comparing component output to expected markdown
+
+### Phase 3: Cache Optimization
+
+1. **HUD layer splitting**: Separate HUD into static layer (task, decisions, next steps) and dynamic layer (context bar, notes, active files)
+2. **Static layer diffing**: Only push to `output.system[]` when static content changes, reducing cache misses
+3. **Dynamic layer minimal updates**: Track what changed since last render, include only deltas
+4. **Measure cache hit rates**: Instrument provider token usage to verify caching improvements
+
+### Phase 4: Advanced Features
+
+1. **Derived events**: File tracking from tool calls, context snapshots from message events
+2. **Search integration**: `hud.search` operation using FTS5 instead of LIKE
+3. **Cross-session HUD**: Persist HUD state across sessions, enable resuming tasks
+4. **QuickJS scripting**: Use toolEnv's envProxy pattern to let agents customize their HUD components
+5. **Multi-agent HUD**: When `coord.spawn` creates sub-agents, share HUD state via parent session events
+
+---
+
+## Key Design Decisions
+
+### Why event log over direct state mutation?
+
+1. **Auditability**: Every state change has a trace. You can reconstruct the HUD at any point in time.
+2. **Compaction resilience**: Events survive compaction because they're in a separate table, not the conversation message stream.
+3. **No conflict resolution needed**: Unlike CRDTs, we're single-author (one agent per session). The event log is append-only with no merge conflicts.
+4. **Projection flexibility**: Different projectors can derive different views from the same events. The HUD is one projection; a task progress tracker could be another.
+
+### Why JSX over Handlebars/templates?
+
+1. **Component composition**: JSX supports arbitrary nesting and composition. `` can wrap `` with different rendering logic.
+2. **Conditional rendering**: `{density === 'full' && }` is cleaner than `{{#if density.full}}...{{/if}}`.
+3. **Type safety**: Components are typed functions. Props, state, density — all compile-time checked.
+4. **Developer familiarity**: React-like patterns are widely understood.
+5. **Direct JSXNode walking avoids HTML roundtrip**: No `renderToStaticMarkup → parse → hast → mdast → markdown` needed.
+
+### Why system prompt injection instead of a dedicated message role?
+
+1. **Cache alignment**: OpenCode already manages the system prompt as a cache-aware structure. Injecting into `output.system[]` gives us immediate cache optimization.
+2. **No protocol change**: We don't need to change opencode's core messaging protocol. The plugin hook is sufficient.
+3. **Survives compaction**: System prompt is always included (it's never compacted). The HUD is always visible.
+4. **Provider compatibility**: System prompts work with every LLM provider. A custom message role might not.
+
+### Why router pattern (1 tool) over separate tools?
+
+From open-memory's research: each tool definition adds ~1-2k tokens to the system prompt. With 10+ HUD operations, that's 10-20k tokens of overhead. A single `hud` router tool costs ~2k tokens regardless of how many operations it supports. The `help` operation provides inline documentation.
+
+---
+
+## File Structure (Proposed)
+
+```
+packages/hud-plugin/
+ src/
+ index.ts # Plugin entry point
+ state/
+ types.ts # HudState, HudEvent types
+ projector.ts # Event → State projectors
+ store.ts # SQLite read/write for hud_event
+ renderer/
+ components/
+ HUD.tsx # Root HUD component
+ TaskSection.tsx # Task display
+ ContextBar.tsx # Context percentage bar
+ DecisionsList.tsx # Key decisions
+ NotesSection.tsx # Scratchpad
+ NextSteps.tsx # Plan/next steps
+ ActiveFiles.tsx # Currently active files
+ WarningBanner.tsx # Context pressure warning
+ renderer.ts # JSXNode → markdown walker
+ density.ts # Adaptive density logic
+ tools/
+ hud.ts # hud router tool definition
+ hud_compact.ts # hud_compact tool definition
+ operations/ # Individual operations
+ task.ts
+ decisions.ts
+ notes.ts
+ steps.ts
+ files.ts
+ snapshot.ts
+ history.ts
+ hooks/
+ system-transform.ts # experimental.chat.system.transform
+ compacting.ts # experimental.session.compacting
+ event.ts # event derivation (file tracking, context snapshots)
+ context/
+ tracker.ts # Context window tracking (from open-memory)
+ thresholds.ts # Density thresholds
+```
+
+---
+
+## Risks and Open Questions
+
+1. **Token overhead at low context usage**: Even "minimal" HUD adds ~30-50 tokens. Is 0% context worth the overhead? Probably yes — the ROI is in the 70%+ range where the HUD prevents catastrophic compaction. At 0%, the full HUD costs ~300-500 tokens, which is ~0.25% of a 200k context. The payoff is avoiding a compaction event that loses the entire conversation.
+
+2. **Agent compliance**: Will agents consistently use `hud` tools to update their state? The current approach relies on the agent choosing to call `hud` tools. Alternatives:
+ - **Auto-derivation**: More events derived automatically from tool calls (file tracking is automatic, but decisions/notes require agent action)
+ - **AGENTS.md prompt**: Include HUD tool usage in instructions
+ - **Conventional prompting**: "Always update your HUD after completing a step or making a decision" in the compaction/system prompt
+
+3. **Stale state**: If the agent doesn't update the HUD before compaction, the HUD might be stale. Mitigation: auto-snapshot HUD state before compaction in the `session.compacting` hook.
+
+4. **JSX dependency weight**: Hono's JSX runtime adds a dependency. Alternative: use a lightweight custom JSX transform that doesn't need Hono. The renderer only needs `JSXNode` types and the walker — not the full Hono framework.
+
+5. **Multi-agent sessions**: When sub-agents are spawned, should they share HUD state? The event log is per-session, but parent-child relationships in opencode could enable HUD state inheritance.
+
+6. **Search vs. structured state**: Should agents search conversation history (like `memory({tool: "search"})`) or maintain structured state (like `hud({tool: "decisions.record"})`)? Both. The HUD is for state the agent actively maintains. Search is for recovering information the agent didn't think to record. They complement each other.
+
+7. **Event log growth**: The `hud_event` table will grow. Needs a cleanup strategy — perhaps tied to compaction events (archive events older than the last compaction point).
\ No newline at end of file
diff --git a/docs/research/hono-jsx-ssr-llm-hud.md b/docs/research/hono-jsx-ssr-llm-hud.md
new file mode 100644
index 0000000..e010818
--- /dev/null
+++ b/docs/research/hono-jsx-ssr-llm-hud.md
@@ -0,0 +1,1077 @@
+# Hono JSX Rendering & SSR: Deep Research for LLM HUD
+
+## Executive Summary
+
+Hono's JSX system is a lightweight, server-first JSX implementation that renders directly to HTML strings via a custom virtual node tree (`JSXNode`). Critically, the **virtual tree is accessible before serialization** — the `JSXNode` class holds the tag, props, and children, and only serializes to HTML when `.toString()` is called. This creates a key interception point for repurposing JSX → markdown pipelines.
+
+---
+
+## 1. JSX Renderer Middleware (`src/middleware/jsx-renderer/`)
+
+### Source Location
+`/workspace/hono/src/middleware/jsx-renderer/index.ts`
+
+### How It Works
+
+The `jsxRenderer` middleware sets up a rendering pipeline on the Hono `Context` object:
+
+```typescript
+export const jsxRenderer = (
+ component?: ComponentWithChildren,
+ options?: RendererOptions | ((c: Context) => RendererOptions)
+): MiddlewareHandler
+```
+
+**Key behavior:**
+
+1. **Sets a renderer** on the context via `c.setRenderer(createRenderer(c, Layout, component, options))`
+2. **Sets a layout** on the context via `c.setLayout((props) => component({ ...props, Layout }, c))`
+3. **After `next()`**, routes can call `c.render(, { title: 'foo' })` which invokes the stored renderer
+4. The renderer wraps content in a `RequestContext.Provider` so components can access the Hono request/context via `useRequestContext()`
+
+### API Options
+
+```typescript
+type RendererOptions = {
+ docType?: boolean | string // default: '', false omits it
+ stream?: boolean | Record // streaming response with chunked transfer
+}
+```
+
+### Layout Nesting
+
+The `Layout` prop allows nested layouts. Each route-level middleware can define a layout that wraps the parent layout:
+
+```tsx
+// Outer layout
+app.use('*', jsxRenderer(({ children, Layout, title }) => (
+
+ {title}{children}
+
+)))
+
+// Inner layout
+app2.use('*', jsxRenderer(({ children, Layout, title }) => (
+
+ {children}
+
+)))
+```
+
+The `Layout` component resolves to the parent's renderer function, enabling composition.
+
+### Renderer Data Flow
+
+```
+c.render(, { title: 'X' })
+ → createRenderer(c, Layout, component, options)(children, props)
+ → if component exists: jsx(component, { Layout, ...props }, children)
+ → wraps in RequestContext.Provider: jsx(RequestContext.Provider, { value: c }, ...)
+ → prepends docType string
+ → if stream: c.body(renderToReadableStream(body)) with chunked headers
+ → else: c.html(body) // standard HTML response
+```
+
+---
+
+## 2. JSX Components in Hono (`src/jsx/`)
+
+### Core Data Structures
+
+**`JSXNode` (base.ts:130-244)** — The fundamental virtual node:
+
+```typescript
+export class JSXNode implements HtmlEscaped {
+ tag: string | Function // HTML tag name OR component function
+ props: Props // Properties object
+ key?: string // React-style key
+ children: Child[] // Child nodes
+ isEscaped: true // Marks as HTML-escaped string
+ localContexts?: LocalContexts // Context values for SSR
+}
+```
+
+**`JSXFunctionNode` (base.ts:247-289)** — Extends `JSXNode` for function components. Overrides `toStringToBuffer` to call `this.tag(props)` and recursively render the result.
+
+**`JSXFragmentNode` (base.ts:291-294)** — Extends `JSXNode` for fragments. Simply concatenates children without wrapping tags.
+
+**`Child` type (base.ts:121-129)**:
+```typescript
+export type Child =
+ | string | Promise | number | JSXNode
+ | null | undefined | boolean | Child[]
+```
+
+### How JSX Gets Transformed
+
+The `jsx()` function (base.ts:297-313) is the entry point:
+
+```typescript
+export const jsx = (
+ tag: string | Function,
+ props: Props | null,
+ ...children: (string | number | HtmlEscapedString)[]
+): JSXNode => {
+ // ... props normalization
+ return jsxFn(tag, props, children)
+}
+```
+
+`jsxFn()` (base.ts:316-351) determines node type:
+1. If `tag` is a function → `new JSXFunctionNode(tag, props, children)`
+2. If `tag` is an intrinsic element with special behavior (e.g., ``, `<script>`, `<meta>`, `<link>`, `<style>`, `<form>`, `<input>`, `<button>`) → `new JSXFunctionNode(intrinsicElementComponent, props, children)`
+3. If `tag` is `'svg'` or `'head'` → creates a namespace context wrapper
+4. Otherwise → `new JSXNode(tag, props, children)` (plain HTML element)
+
+### Key Insight: JSXNodes are Accessible Before Serialization
+
+When you write:
+
+```tsx
+const node = <div class="container"><h1>Hello</h1></div>
+```
+
+The result is a `JSXNode` instance with:
+- `node.tag === 'div'`
+- `node.props === { class: 'container' }`
+- `node.children === [<JSXNode tag='h1' props={} children=['Hello']>]`
+
+**The tree is Materialized Before toString()** — this is the critical interception point.
+
+### Component Model
+
+Function components are plain functions that receive props and return `JSXNode | string | Promise<JSXNode> | HtmlEscapedString`:
+
+```typescript
+export type FC<P = Props> = {
+ (props: P): HtmlEscapedString | Promise<HtmlEscapedString> | null
+ defaultProps?: Partial<P>
+ displayName?: string
+}
+```
+
+When rendered, `JSXFunctionNode.toStringToBuffer()` calls `this.tag(props)` and recursively renders the result.
+
+### Hooks (SSR Support)
+
+Hooks (`useState`, `useEffect`, etc.) have split implementations:
+- **Server-side**: The hooks in `src/jsx/hooks/` — only `useState`, `useReducer`, `useCallback`, `useMemo`, `useId`, `useRef`, and `useSyncExternalStore` have meaningful SSR behavior
+- **Client-side (DOM)**: The hooks in `src/jsx/dom/hooks/` — full React-like behavior for browser rehydration
+
+For SSR, `useState` returns the initial value, `useMemo` caches computation, and `useId` generates deterministic IDs.
+
+### Context System
+
+```typescript
+// src/jsx/context.ts
+export const createContext = <T>(defaultValue: T): Context<T> => {
+ const values = [defaultValue]
+ const context = ((props): HtmlEscapedString | Promise<HtmlEscapedString> => {
+ values.push(props.value)
+ // ... renders children with value on stack, then pops
+ }) as Context<T>
+ context.values = values
+ context.Provider = context
+ globalContexts.push(context as Context<unknown>)
+ return context
+}
+
+export const useContext = <T>(context: Context<T>): T => {
+ return context.values.at(-1) as T
+}
+```
+
+Context works by maintaining a stack of values. The Provider pushes a new value, renders children, then pops. This is critical for passing request-scoped data through the component tree.
+
+---
+
+## 3. SSR Pattern: From JSX to Output
+
+### The Rendering Pipeline
+
+```
+JSX Syntax
+ │
+ ▼ (JSX transform / runtime)
+JSXNode tree (tag, props, children)
+ │
+ ▼ (.toString() or .toStringToBuffer())
+StringBufferWithCallbacks ['chunk1', Promise<string>, 'chunk2', ...]
+ │
+ ▼ (stringBufferToString / resolveCallback)
+HtmlEscapedString (string with {isEscaped: true, callbacks?: [...]})
+
+
+For streaming:
+ │
+ ▼ (renderToReadableStream)
+ReadableStream<Uint8Array>
+```
+
+### `JSXNode.toString()` (base.ts:153-170)
+
+```typescript
+toString(): string | Promise<string> {
+ const buffer: StringBufferWithCallbacks = [''] as StringBufferWithCallbacks
+ this.localContexts?.forEach(([context, value]) => {
+ context.values.push(value)
+ })
+ try {
+ this.toStringToBuffer(buffer)
+ } finally {
+ this.localContexts?.forEach(([context]) => {
+ context.values.pop()
+ })
+ }
+ return buffer.length === 1
+ ? 'callbacks' in buffer
+ ? resolveCallbackSync(raw(buffer[0], buffer.callbacks)).toString()
+ : buffer[0]
+ : stringBufferToString(buffer, buffer.callbacks)
+}
+```
+
+### `JSXNode.toStringToBuffer()` for intrinsic elements (base.ts:172-244)
+
+This is the HTML serialization method. It:
+1. Opens the tag: `buffer[0] += '<${tag}'`
+2. Serializes attributes (with escaping via `escapeToBuffer`)
+3. Handles special props: `style` (object→string), `dangerouslySetInnerHTML`, boolean attributes
+4. Handles void elements (`<br/>`, `<img/>`, etc.)
+5. Renders children recursively via `childrenToStringToBuffer(children, buffer)`
+6. Closes the tag: `buffer[0] += '</${tag}>'`
+
+### `JSXFunctionNode.toStringToBuffer()` for function components (base.ts:248-289)
+
+```typescript
+toStringToBuffer(buffer: StringBufferWithCallbacks): void {
+ const { children } = this
+ const props = { ...this.props }
+ if (children.length) {
+ props.children = children.length === 1 ? children[0] : children
+ }
+ const res = (this.tag as Function).call(null, props)
+ // ... dispatches based on res type:
+ // - null/undefined: skip
+ // - Promise: buffer.unshift('', promise)
+ // - JSXNode: res.toStringToBuffer(buffer) // recurse
+ // - HtmlEscapedString: buffer += res
+ // - string: escapeToBuffer(res, buffer)
+}
+```
+
+### `renderToString` (dom/server.ts:21-30)
+
+```typescript
+const renderToString = (element: Child, options: RenderToStringOptions = {}): string => {
+ const res = element?.toString() ?? ''
+ if (typeof res !== 'string') {
+ throw new Error('Async component is not supported in renderToString')
+ }
+ return res
+}
+```
+
+It simply calls `.toString()` on the element. If there are async components, it throws.
+
+### HtmlEscapedString Protocol (src/utils/html.ts)
+
+```typescript
+export type HtmlEscaped = {
+ isEscaped: true
+ callbacks?: HtmlEscapedCallback[]
+}
+export type HtmlEscapedString = string & HtmlEscaped
+```
+
+Strings are wrapped with `{ isEscaped: true }` to mark them as already-HTML-escaped (no need to re-escape). The `callbacks` array enables lazy resolution for streaming/Suspense — each callback can return a `Promise<string>` that resolves when async content is ready.
+
+### `raw()` helper
+
+```typescript
+export const raw = (value: unknown, callbacks?: HtmlEscapedCallback[]): HtmlEscapedString => {
+ const escapedString = new String(value) as HtmlEscapedString
+ escapedString.isEscaped = true
+ escapedString.callbacks = callbacks
+ return escapedString
+}
+```
+
+Creates an `HtmlEscapedString` that bypasses escaping (for pre-escaped content).
+
+---
+
+## 4. The `html` Tagged Template Literal
+
+### Source: `src/helper/html/index.ts`
+
+```typescript
+export const html = (
+ strings: TemplateStringsArray,
+ ...values: unknown[]
+): HtmlEscapedString | Promise<HtmlEscapedString> => {
+ const buffer: StringBufferWithCallbacks = [''] as StringBufferWithCallbacks
+ for (let i = 0, len = strings.length - 1; i < len; i++) {
+ buffer[0] += strings[i]
+ const children = Array.isArray(values[i])
+ ? (values[i] as Array<unknown>).flat(Infinity)
+ : [values[i]]
+ for (let i = 0, len = children.length; i < len; i++) {
+ const child = children[i] as any
+ if (typeof child === 'string') {
+ escapeToBuffer(child, buffer)
+ } else if (typeof child === 'number') {
+ buffer[0] += child
+ } else if (typeof child === 'object' && (child as HtmlEscaped).isEscaped) {
+ // JSXNodes or HtmlEscapedStrings (already escaped)
+ if ((child as HtmlEscapedString).callbacks) {
+ buffer.unshift('', child)
+ } else {
+ const tmp = child.toString()
+ if (tmp instanceof Promise) {
+ buffer.unshift('', tmp)
+ } else {
+ buffer[0] += tmp
+ }
+ }
+ } else if (child instanceof Promise) {
+ buffer.unshift('', child)
+ } else {
+ escapeToBuffer(child.toString(), buffer)
+ }
+ }
+ }
+ buffer[0] += strings.at(-1)
+ // ...
+}
+```
+
+**Key insight**: The `html` tagged template can interoperate with JSXNodes. When you write:
+
+```tsx
+html`<div>${someJsxNode}</div>`
+```
+
+It detects the `isEscaped` property on JSXNodes and calls `.toString()` on them, producing the same HTML output. This means `html` templates and JSX are composable.
+
+**Could this be an alternative for markdown?** Potentially — you could write:
+
+```typescript
+html`## ${title}\n\n${content}\n`
+```
+
+But this doesn't give you the component composition model. JSX is the way to get composable, reusable UI primitives.
+
+---
+
+## 5. Relevant Middleware Ecosystem
+
+| Middleware | Path | Relevance |
+|---|---|---|
+| **jsx-renderer** | `src/middleware/jsx-renderer/` | Core SSR rendering pipeline |
+| **compress** | `src/middleware/compress/` | Response compression (gzip/deflate) |
+| **cache** | `src/middleware/cache/` | HTTP caching headers |
+| **etag** | `src/middleware/etag/` | ETag generation for caching |
+| **pretty-json** | `src/middleware/pretty-json/` | JSON formatting (pattern for custom formatting) |
+| **context-storage** | `src/middleware/context-storage/` | Async context storage (could carry renderer config) |
+| **streaming** | N/A (built into jsx-renderer) | Streaming via `renderToReadableStream` |
+| **content-type** | N/A (auto via c.html, c.text, etc.) | Content-Type headers |
+
+The most relevant pattern is how `jsxRenderer` hooks into the context via `c.setRenderer()` / `c.setLayout()` / `c.render()`. This is the pattern we'd emulate for a markdown renderer.
+
+---
+
+## 6. Feasibility: JSX → hast → mdast → Markdown Pipeline
+
+### The Core Idea
+
+Instead of the standard pipeline:
+```
+JSX → JSXNode tree → .toString() → HTML string
+```
+
+We want:
+```
+JSX → JSXNode tree → Custom walker → hast/mdast → markdown string
+```
+
+### Approach A: Intercept at `JSXNode.toStringToBuffer()` (MOST PROMISING)
+
+**The `JSXNode` tree is fully materialized before serialization.** When you write `<div class="x"><p>Hello</p></div>`, the result is:
+
+```javascript
+JSXNode {
+ tag: 'div',
+ props: { class: 'x' },
+ children: [
+ JSXNode {
+ tag: 'p',
+ props: {},
+ children: ['Hello']
+ }
+ ]
+}
+```
+
+You can walk this tree without calling `.toString()` at all:
+
+```typescript
+function jsxNodeToMarkdown(node: Child): string {
+ if (node == null || typeof node === 'boolean') return ''
+ if (typeof node === 'string') return node
+ if (typeof node === 'number') return String(node)
+ if (Array.isArray(node)) return node.map(jsxNodeToMarkdown).join('')
+
+ // node is JSXNode
+ const jsxNode = node as JSXNode
+
+ // Function component — evaluate it first
+ if (typeof jsxNode.tag === 'function') {
+ // Call the component to get the rendered result
+ // NOTE: For async components, this gets more complex
+ const props = { ...jsxNode.props }
+ if (jsxNode.children.length) {
+ props.children = jsxNode.children.length === 1
+ ? jsxNode.children[0]
+ : jsxNode.children
+ }
+ const result = (jsxNode.tag as Function)(props)
+ return jsxNodeToMarkdown(result)
+ }
+
+ // Intrinsic element — map to markdown
+ const tag = jsxNode.tag as string
+ const children = jsxNode.children.map(jsxNodeToMarkdown).join('')
+
+ switch (tag) {
+ case 'h1': return `# ${children}\n\n`
+ case 'h2': return `## ${children}\n\n`
+ case 'h3': return `### ${children}\n\n`
+ case 'p': return `${children}\n\n`
+ case 'strong': case 'b': return `**${children}**`
+ case 'em': case 'i': return `*${children}*`
+ case 'code': return `\`${children}\``
+ case 'pre': return `\`\`\`\n${children}\n\`\`\`\n`
+ case 'ul': return `${children}\n`
+ case 'ol': return `${children}\n`
+ case 'li': return `- ${children}\n`
+ case 'a': return `[${children}](${jsxNode.props.href || ''})`
+ case 'img': return ``
+ case 'br': return '\n'
+ case 'hr': return '---\n\n'
+ case 'div': case 'section': case 'article': case 'main': case 'span':
+ return children // non-semantic containers pass through
+ default:
+ return children // fallback: strip unknown tags
+ }
+}
+```
+
+**Advantages:**
+- Direct access to the structured tree (tag, props, children)
+- No need to parse HTML back into an AST
+- Component composition still works perfectly
+- Hooks that don't depend on DOM (useState initial, useMemo, useContext) still work
+- Can handle async components with `Promise.all`
+
+**Challenges:**
+- Async components return Promises — need async walker
+- `JSXFunctionNode` vs `JSXNode` vs `JSXFragmentNode` need different handling
+- Special intrinsic elements (title, script, etc.) are wrapped in `JSXFunctionNode`
+- Context system works via side-effects (push/pop on the `context.values` array) during `toString()`/`toStringToBuffer()` — for our walker, we'd need to handle context providers differently
+
+### Approach B: Intercept at `toStringToBuffer()` Level
+
+Override or wrap `toStringToBuffer` to build an AST instead of an HTML string buffer:
+
+```typescript
+// Create a custom buffer type that builds a hast tree instead of strings
+interface HastBuffer {
+ type: 'element'
+ tagName: string
+ properties: Record<string, unknown>
+ children: HastNode[]
+ // ...
+}
+```
+
+This is more invasive but gives cleaner AST output. However, it requires restructuring the entire rendering pipeline since `toStringToBuffer` is deeply coupled to the string buffer protocol.
+
+### Approach C: Render to HTML, then parse back via rehype/remark
+
+```
+JSX → JSXNode.toString() → HTML string → rehype-parse → hast → rehype-remark → mdast → remark-stringify → markdown
+```
+
+This is the simplest approach but involves:
+1. Full HTML serialization (wasteful if we're going to convert away from HTML)
+2. Dependency on the unified/rehype/remark ecosystem
+3. Parsing overhead
+4. Loss of semantic information that was in the JSXNode tree but not in the HTML (e.g., component boundaries, custom props)
+
+### Recommended: Approach A (Direct JSXNode Walking)
+
+The JSXNode tree IS an AST. It's not a full hast/html AST (no position info, slightly different structure), but it has tag names, attributes, and children — everything needed to produce markdown. The mapping is:
+
+| JSXNode field | hast equivalent |
+|---|---|
+| `tag` | `tagName` |
+| `props` | `properties` |
+| `children` (string items) | `value` (text nodes) |
+| `children` (JSXNode items) | `children` (element nodes) |
+
+---
+
+## 7. Custom Renderer Architecture: "LLM HUD Renderer"
+
+### Proposed Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│ Hono Application │
+│ │
+│ app.get('/chat/:id', mdRenderer(), (c) => { │
+│ return c.render(<ChatHUD messages={...} />) │
+│ }) │
+│ │
+│ mdRenderer = jsxRenderer analog that sets up │
+│ a markdown renderer instead of HTML renderer │
+└──────────┬──────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────┐
+│ mdRenderer Middleware │
+│ │
+│ 1. Sets c.setRenderer((jsxNode, props) => { │
+│ const md = renderJSXToMarkdown(jsxNode) │
+│ return c.text(md, 200, { │
+│ 'Content-Type': 'text/markdown' │
+│ }) │
+│ }) │
+│ 2. Provides a markdown layout wrapper │
+│ 3. Sets content-type to text/markdown │
+└──────────┬──────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────┐
+│ renderJSXToMarkdown(jsxNode) │
+│ │
+│ 1. Walk the JSXNode tree recursively │
+│ 2. For function components: call tag(props) │
+│ to get rendered JSXNode, then recurse │
+│ 3. For intrinsic elements: map tag→markdown │
+│ 4. For text nodes: pass through (with escaping) │
+│ 5. For async components: await and recurse │
+│ │
+│ Returns: markdown string │
+└─────────────────────────────────────────────────┘
+```
+
+### Implementation Sketch
+
+```typescript
+// md-renderer.ts
+
+import { jsxRenderer, useRequestContext } from 'hono/jsx-renderer'
+import { createContext, useContext } from 'hono/jsx'
+import type { Child, JSXNode, FC, PropsWithChildren } from 'hono/jsx'
+import type { Context } from 'hono'
+
+// ─── Markdown Rendering Engine ───────────────────────────────
+
+interface MdRenderOptions {
+ /** Whether to include frontmatter in output */
+ frontmatter?: Record<string, string>
+ /** Custom tag-to-markdown mappings */
+ tagMap?: Record<string, (children: string, props: Record<string, unknown>) => string>
+}
+
+async function renderChildToMd(child: Child, options: MdRenderOptions): Promise<string> {
+ if (child == null || typeof child === 'boolean') return ''
+ if (typeof child === 'string') return child
+ if (typeof child === 'number') return String(child)
+ if (child instanceof Promise) {
+ const resolved = await child
+ return renderChildToMd(resolved, options)
+ }
+ if (Array.isArray(child)) {
+ const parts = await Promise.all(child.map(c => renderChildToMd(c, options)))
+ return parts.join('')
+ }
+ // It's a JSXNode-like object
+ return renderJSXNodeToMd(child as JSXNode, options)
+}
+
+async function renderJSXNodeToMd(node: JSXNode, options: MdRenderOptions): Promise<string> {
+ const tag = node.tag
+
+ // Handle function components
+ if (typeof tag === 'function') {
+ const props = { ...node.props }
+ if (node.children.length) {
+ props.children = node.children.length === 1
+ ? node.children[0]
+ : node.children
+ }
+ const result = await tag(props)
+ return renderChildToMd(result, options)
+ }
+
+ // Handle fragment-like nodes (tag === '')
+ if (tag === '') {
+ const parts = await Promise.all(
+ node.children.map(c => renderChildToMd(c, options))
+ )
+ return parts.join('')
+ }
+
+ // Intrinsic element — recurse into children first
+ const childStrings = await Promise.all(
+ node.children.map(c => renderChildToMd(c, options))
+ )
+ const children = childStrings.join('')
+
+ // Check custom mappings first
+ if (options.tagMap?.[tag as string]) {
+ return options.tagMap[tag as string](children, node.props)
+ }
+
+ // Default HTML→Markdown mapping
+ switch (tag as string) {
+ // Headings
+ case 'h1': return `# ${children.trim()}\n\n`
+ case 'h2': return `## ${children.trim()}\n\n`
+ case 'h3': return `### ${children.trim()}\n\n`
+ case 'h4': return `#### ${children.trim()}\n\n`
+ case 'h5': return `##### ${children.trim()}\n\n`
+ case 'h6': return `###### ${children.trim()}\n\n`
+
+ // Block elements
+ case 'p': return `${children.trim()}\n\n`
+ case 'blockquote': return children.split('\n').map(l => `> ${l}`).join('\n') + '\n\n'
+ case 'pre': {
+ const lang = node.props['data-language'] || node.props.className?.toString().replace('language-', '') || ''
+ return `\`\`\`${lang}\n${children}\n\`\`\`\n\n`
+ }
+ case 'code': return `\`${children}\``
+
+ // Inline elements
+ case 'strong': case 'b': return `**${children}**`
+ case 'em': case 'i': return `*${children}*`
+ case 'del': case 's': return `~~${children}~~`
+ case 'a': return `[${children}](${node.props.href || ''})`
+ case 'img': return ``
+
+ // Lists
+ case 'ul': return `${children}\n`
+ case 'ol': return `${children}\n`
+ case 'li': return `- ${children.trim()}\n`
+
+ // Table elements
+ case 'table': return `${children}\n`
+ case 'thead': return children
+ case 'tbody': return children
+ case 'tr': return `| ${children} |\n`
+ case 'th': return children
+ case 'td': return children
+
+ // Utility
+ case 'br': return '\n'
+ case 'hr': return '---\n\n'
+
+ // Non-semantic containers (pass through)
+ case 'div': case 'section': case 'article':
+ case 'main': case 'span': case 'header':
+ case 'footer': case 'nav': case 'aside':
+ return children
+
+ // HTML boilerplate (pass through children)
+ case 'html': case 'body': case 'head':
+ return children
+
+ default:
+ return children // Unknown tags: strip and pass through
+ }
+}
+
+// ─── Middleware ─────────────────────────────────────────────
+
+export const mdRenderer = <E extends Env>(
+ component?: FC<PropsWithChildren<{ Layout: FC }>>,
+ options?: MdRenderOptions | ((c: Context<E>) => MdRenderOptions)
+) => {
+ return async (c: Context, next: Next) => {
+ const opts = typeof options === 'function' ? options(c) : options
+
+ c.setRenderer((jsxNode: JSXNode, props: Record<string, unknown>) => {
+ // Wrap in component if provided (layout support)
+ const tree = component
+ ? jsx(component, { Layout: Fragment, ...props }, jsxNode as any)
+ : jsxNode
+
+ return renderJSXNodeToMd(tree as JSXNode, opts || {}).then(md => {
+ // Optionally wrap in frontmatter
+ if (opts?.frontmatter) {
+ const fm = '---\n' +
+ Object.entries(opts.frontmatter).map(([k, v]) => `${k}: ${v}`).join('\n') +
+ '\n---\n\n'
+ md = fm + md
+ }
+ return c.text(md, 200, { 'Content-Type': 'text/markdown; charset=UTF-8' })
+ })
+ })
+ await next()
+ }
+}
+
+// ─── LLM Output Components ────────────────────────────────
+
+// These are reusable JSX components for building LLM-facing markdown HUDs
+
+export const CodeBlock: FC<{ language?: string; title?: string }> = ({
+ children, language, title
+}) => (
+ <pre data-language={language} data-title={title}>{children}</pre>
+)
+
+export const Thinking: FC<{ effort?: string }> = ({ children, effort }) => (
+ <blockquote data-type="thinking" data-effort={effort}>{children}</blockquote>
+)
+
+export const ToolResult: FC<{ name: string; success: boolean }> = ({
+ children, name, success
+}) => (
+ <section data-type="tool-result" data-tool={name} data-success={String(success)}>
+ {children}
+ </section>
+)
+
+export const StatusBadge: FC<{ status: string; label?: string }> = ({
+ status, label
+}) => (
+ <span data-status={status}>{label || status}</span>
+)
+```
+
+### Context Handling for Custom Renderers
+
+The context system in Hono JSX works by pushing/popping values during toString(). For a markdown renderer, we need context support too. Two options:
+
+**Option 1 — Manually handle context providers:**
+
+```typescript
+// When walking the JSXNode tree and encountering a Context.Provider,
+// push the value onto the context stack before recursing into children,
+// then pop it afterward.
+async function renderChildToMd(child: Child, options: MdRenderOptions, contextStack: Map<Context<unknown>, unknown>): Promise<string> {
+ // ...
+ if (typeof tag === 'function' && tag === SomeContext.Provider) {
+ const prevValue = SomeContext.values.at(-1)
+ SomeContext.values.push(node.props.value)
+ try {
+ const result = await renderChildToMd(node.children, options, contextStack)
+ return result
+ } finally {
+ SomeContext.values.pop()
+ }
+ }
+}
+```
+
+**Option 2 — Leverage the existing `RequestContext` pattern:**
+
+The `jsx-renderer` middleware already provides `useRequestContext()` via `RequestContext.Provider`. We can reuse this to make the Hono `Context` available in our markdown components:
+
+```tsx
+app.use('/api/*', mdRenderer())
+
+app.get('/api/status', (c) => {
+ return c.render(<StatusDashboard />)
+})
+
+const StatusDashboard: FC = () => {
+ const c = useRequestContext()
+ const status = c.get('currentStatus')
+ return (
+ <div>
+ <h2>System Status</h2>
+ <p>Current status: {status}</p>
+ </div>
+ )
+})
+```
+
+### Key Integration Points
+
+1. **`c.setRenderer()`** — The primary hook. Set a custom renderer that walks JSXNodes instead of converting to HTML
+2. **`c.setLayout()`** / **`c.getLayout()`** — For nested layout composition in markdown output
+3. **`jsxRenderer` middleware** — Reference implementation showing how to set up the rendering pipeline
+4. **`JSXNode` class** — The tree structure accessible before `.toString()` serialization
+5. **`JSXFunctionNode` class** — The subclass for function components; calling `this.tag(props)` evaluates components
+6. **`JSXFragmentNode` class** — The subclass for fragments; just concatenates children
+7. **Hono `Context`** — Available via `RequestContext.Provider` for injecting request data into components
+
+### Async Component Handling
+
+Since Hono supports async components natively:
+
+```tsx
+const AsyncData: FC = async () => {
+ const data = await fetchData()
+ return <div>{data}</div>
+}
+```
+
+Our markdown renderer must handle `Promise<JSXNode>` returns:
+
+```typescript
+async function renderJSXNodeToMd(node: JSXNode, options: MdRenderOptions): Promise<string> {
+ if (typeof tag === 'function') {
+ const result = await tag(props) // May return Promise
+ if (result instanceof Promise) {
+ const resolved = await result
+ return renderChildToMd(resolved, options)
+ }
+ return renderChildToMd(result, options)
+ }
+ // ...
+}
+```
+
+The JSXNode tree may contain `Promise<string>` in children (from `HtmlEscapedString` with async callbacks). These need `await` resolution.
+
+### What About Special Intrinsic Elements?
+
+Hono wraps certain tags in function component wrappers:
+
+- `<title>` → Calls `intrinsicElementTags.title` which handles document metadata
+- `<script>` → Handles hoisting to `<head>`
+- `<style>` → Handles precedence-based insertion
+- `<link>` → Handles stylesheet deduplication
+- `<meta>` → Handles metadata deduplication
+- `<form>`, `<input>`, `<button>` → Handle action/PERMALINK
+
+For markdown rendering, these should all pass through or be stripped. The markdown renderer would need to detect these function-tag wrappers and handle them appropriately:
+
+```typescript
+// For markdown, we don't need document metadata handling
+// Just render the children of title/script/etc.
+if (typeof tag === 'function' && tag === intrinsicElementTags.title) {
+ // Extract just the text content
+ const children = await Promise.all(node.children.map(c => renderChildToMd(c, options)))
+ return children.join('')
+}
+```
+
+Actually, since `intrinsicElementTags.title` etc. return JSXNodes when called (they're component functions), our walker already handles this automatically — it calls the function component and recurses.
+
+---
+
+## 8. Data Flow Summary: JSX to Markdown
+
+```
+ User Code Hono Internals Custom Renderer
+ ───────── ────────────── ────────────────
+
+ <ChatHUD>
+ │
+ ▼ jsx()
+ JSXNode {
+ tag: ChatHUD,
+ props: {...},
+ children: []
+ }
+ │
+ ▼ ChatHUD(props)
+ evaluates to
+ JSXNode {
+ tag: 'div',
+ props: {class:'hud'},
+ children:
+ [JSXNode {tag:'h2',...},
+ JSXNode {tag:'p',...}]
+ }
+ │
+ │ ┌──────────────────────┼─────────────────────┐
+ │ │ Standard Path │ LLM HUD Path │
+ │ │ │ │
+ │ ▼ .toString() │ ▼ renderJSXNodeToMd()│
+ │ StringBuffer │ Recursive walk │
+ │ │ │ │ │
+ │ ▼ escapeToBuffer() │ ▼ tag→md mapping │
+ │ '<div class="hud">' │ '# ...\n\n...' │
+ │ <h2>Title</h2> │ │
+ │ <p>Content</p> │ │
+ │ </div> │ │
+ │ │ │ │ │
+ │ ▼ c.html(result) │ ▼ c.text(md, { │
+ │ │ │ 'Content-Type': │
+ │ ▼ Response │ 'text/markdown' │
+ │ Content-Type: │ }) │
+ │ text/html │ │
+ │ │ ▼ Response │
+ │ │ Content-Type: │
+ │ │ text/markdown │
+ └─────────────────────────────────────────────────┘
+```
+
+---
+
+## 9. Alternative: hast/mdast Pipeline (Full AST)
+
+If we want proper hast→mdast conversion (rather than direct JSXNode→markdown), we could:
+
+1. **Walk JSXNode tree → produce hast tree**
+2. **Use `hast-util-to-mdast` to convert hast→mdast**
+3. **Use `mdast-util-to-markdown` to produce markdown string**
+
+This gives us all the remark/rehype ecosystem benefits (GFM tables, footnotes, etc.) but adds significant dependency weight.
+
+**JSXNode → hast conversion:**
+
+```typescript
+import type { Element, Text, Root, ElementContent } from 'hast'
+
+function jsxNodeToHast(node: Child): ElementContent[] | undefined {
+ if (node == null || typeof node === 'boolean') return undefined
+ if (typeof node === 'string') return [{ type: 'text', value: node }]
+ if (typeof node === 'number') return [{ type: 'text', value: String(node) }]
+ if (Array.isArray(node)) return node.flatMap(jsxNodeToHast).filter(Boolean) as ElementContent[]
+
+ const jsxNode = node as JSXNode
+
+ if (typeof jsxNode.tag === 'function') {
+ // Evaluate function component
+ const props = { ...jsxNode.props }
+ if (jsxNode.children.length) {
+ props.children = jsxNode.children.length === 1 ? jsxNode.children[0] : jsxNode.children
+ }
+ const result = jsxNode.tag(props)
+ return jsxNodeToHast(result) ?? undefined
+ }
+
+ if (jsxNode.tag === '') {
+ // Fragment
+ return jsxNode.children.flatMap(jsxNodeToHast).filter(Boolean) as ElementContent[]
+ }
+
+ // Intrinsic element → hast Element
+ const properties: Record<string, unknown> = {}
+ for (const [key, value] of Object.entries(jsxNode.props)) {
+ if (key === 'children') continue
+ if (key === 'className') properties.className = value
+ else if (key === 'htmlFor') properties.htmlFor = value
+ else properties[key] = value
+ }
+
+ const children = jsxNode.children.flatMap(jsxNodeToHast).filter(Boolean) as ElementContent[]
+
+ return [{
+ type: 'element',
+ tagName: jsxNode.tag as string,
+ properties,
+ children
+ }]
+}
+```
+
+**Then:**
+
+```typescript
+import { toMdast } from 'hast-util-to-mdast'
+import { toMarkdown } from 'mdast-util-to-markdown'
+
+function renderToMarkdown(jsxNode: JSXNode): string {
+ const hast = jsxNodeToHast(jsxNode)
+ const mdast = toMdast({ type: 'root', children: hast })
+ return toMarkdown(mdast)
+}
+```
+
+**Trade-offs:**
+
+| Approach | Pros | Cons |
+|---|---|---|
+| Direct JSXNode→MD | Zero dependencies, fast, simple | Must implement all tag mappings manually |
+| JSXNode→hast→mdast→MD | Full GFM support, extensible, standards-based | Heavy dependency tree (~50 packages from unified ecosystem) |
+| JSXNode→HTML→rehype→MD | Simplest to implement, no JSX walking | Wasteful roundtrip, loses semantic info |
+
+**Recommendation**: Start with direct JSXNode→MD for simplicity and zero dependencies. Add hast/mdast pipeline later if GFM tables, footnotes, or other advanced markdown features are needed.
+
+---
+
+## 10. Key Files Reference
+
+| File | Purpose |
+|---|---|
+| `/workspace/hono/src/jsx/base.ts` | Core `JSXNode`, `JSXFunctionNode`, `JSXFragmentNode`, `jsx()`, `jsxFn()`, `Fragment` |
+| `/workspace/hono/src/jsx/jsx-dev-runtime.ts` | `jsxDEV()` — JSX transform entry point |
+| `/workspace/hono/src/jsx/streaming.ts` | `Suspense`, `renderToReadableStream()` |
+| `/workspace/hono/src/jsx/context.ts` | `createContext()`, `useContext()` |
+| `/workspace/hono/src/jsx/components.ts` | `ErrorBoundary`, `childrenToString()` |
+| `/workspace/hono/src/jsx/children.ts` | `Children` utility (map, forEach, count, only, toArray) |
+| `/workspace/hono/src/jsx/intrinsic-element/components.ts` | Special element handlers (title, script, style, link, meta, form) |
+| `/workspace/hono/src/jsx/intrinsic-element/common.ts` | `domRenderers` map, deduplication helpers |
+| `/workspace/hono/src/jsx/types.ts` | Type exports (`Child`, `JSXNode`, `FC`, etc.) |
+| `/workspace/hono/src/utils/html.ts` | `HtmlEscapedString`, `raw()`, `escapeToBuffer()`, `stringBufferToString()`, `resolveCallback()` |
+| `/workspace/hono/src/helper/html/index.ts` | `html` tagged template literal |
+| `/workspace/hono/src/jsx/dom/server.ts` | `renderToString()`, `renderToReadableStream()` (React-compatible API) |
+| `/workspace/hono/src/jsx/dom/render.ts` | DOM renderer (client-side hydration) |
+| `/workspace/hono/src/jsx/hooks/index.ts` | All hooks (useState, useEffect, etc.) — DOM-oriented |
+| `/workspace/hono/src/middleware/jsx-renderer/index.ts` | `jsxRenderer` middleware, `useRequestContext()`, `RequestContext` |
+| `/workspace/hono/src/context.ts` | `Context` class with `setRenderer()`, `setLayout()`, `getLayout()`, `render()` |
+
+---
+
+## 11. Conclusion & Architecture Recommendation
+
+### The Core Insight
+
+**Hono's JSXNode tree is an accessible AST that exists before HTML serialization.** The `.toString()` / `.toStringToBuffer()` methods are the serialization layer. By walking the tree before calling these methods, we can produce any output format — including markdown.
+
+### Recommended Architecture
+
+1. **Create `mdRenderer` middleware** analogous to `jsxRenderer` that:
+ - Calls `c.setRenderer()` with a custom renderer function
+ - The custom renderer walks the JSXNode tree using `renderJSXNodeToMd()`
+ - Returns `c.text(markdown, 200, {'Content-Type': 'text/markdown; charset=UTF-8'})`
+ - Supports layout composition via `c.setLayout()` / `c.getLayout()`
+
+2. **Create `renderJSXNodeToMd()` walker** that:
+ - Recursively walks `JSXNode` trees
+ - Calls function components to evaluate them (with async support)
+ - Maps HTML tags to markdown syntax
+ - Handles fragments by concatenating children
+ - Preserves semantic meaning from component structure
+
+3. **Build an LLM HUD component library** using standard Hono JSX:
+ - `Thinking` → renders to `<blockquote>` → converted to `> ...` in markdown
+ - `CodeBlock` → renders to `<pre data-language="...">` → converted to fenced code blocks
+ - `ToolResult` → renders to `<section>` → converted to structured markdown sections
+ - `StatusBadge` → renders to `<span data-status="...">` → converted to emoji/status text
+
+4. **Content negotiation** middleware that detects `Accept: text/markdown` and routes to the markdown renderer:
+
+ ```typescript
+ app.get('/api/status', async (c) => {
+ const acceptsMarkdown = c.req.header('Accept')?.includes('text/markdown')
+ if (acceptsMarkdown) {
+ return mdRender(<StatusDashboard data={...} />)
+ }
+ return c.json({ status: 'ok' })
+ })
+ ```
+
+5. **Future: hast/mdast pipeline** for full GFM support, if the direct-walker approach proves insufficient for complex table/footnote rendering.
+
+### Risk Assessment
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| Async component handling | Medium | Must `await` component results; walker must be async throughout |
+| Context providers need push/pop | Low | Can handle manually in walker or skip RequestContext for markdown |
+| Special intrinsic elements (title, form) | Low | They evaluate to JSXNodes; walker recurses naturally |
+| Loss of semantic info in tag→md mapping | Medium | Use `data-*` attributes for custom markdown semantics |
+| `HtmlEscapedString` protocol | Medium | Must detect `isEscaped` flag and handle `Promise` children |
+
+The approach is highly feasible. Hono's architecture — with `JSXNode` as a first-class tree structure and `c.setRenderer()` as the output hook — makes this a natural extension rather than a hack.
diff --git a/docs/research/prior-poc-source-reference.md b/docs/research/prior-poc-source-reference.md
new file mode 100644
index 0000000..0377afa
--- /dev/null
+++ b/docs/research/prior-poc-source-reference.md
@@ -0,0 +1,119 @@
+# Prior UJSX POC: Source Code Reference
+
+Source: `/workspace/aui/ujsx/` (Deno/JSR package `@ade/ujsx`)
+Summary: `/workspace/aui/SUMMARY.md`
+
+## What to Preserve
+
+### Transform Registry (`transform/registry.ts`)
+
+Priority-based transformation with continuation-passing style:
+
+```typescript
+interface TransformRule<T, U, A> {
+ name: string;
+ match: (node: T) => boolean;
+ transform: (node: T, ctx: TransformContext<A>, next: TransformFn<T, U, A>) => U;
+ priority?: number;
+}
+```
+
+Key pattern: `next` continuation allows recursive child transforms. Rules sorted by priority (higher = first). V2 extends this with `direction` and `schema` fields.
+
+### HostConfig + Reconciler (`host/config.ts`)
+
+React-reconciler-inspired host adapter:
+
+```typescript
+interface HostConfig<TTag, Instance, RootCtx> {
+ name: string;
+ createRootContext(container, options?): RootCtx;
+ createInstance(tag, props, ctx, parent?): Instance;
+ createTextInstance(text, ctx, parent?): Instance;
+ appendChild(parent, child, ctx): void;
+ insertBefore?(parent, child, before, ctx): void;
+ removeChild?(parent, child, ctx): void;
+ prepareUpdate?(instance, tag, prevProps, nextProps, ctx): unknown | null;
+ commitUpdate?(instance, payload, tag, prevProps, nextProps, ctx): void;
+}
+```
+
+The `createRoot()` reconciler is mount-only (MVP). V2 needs full reconciliation with key-based diffing.
+
+### Graphology Host (`host/graphology.ts`)
+
+Dirty bitmask pattern on graph nodes:
+
+```typescript
+const DIRTY = { Props: 1<<0, Content: 1<<1, Structure: 1<<2 } as const;
+```
+
+Edges use `parent->child#order` keys. Version tracking on nodes. Issue: `createInstance` has commented-out append logic, `prepareUpdate` uses `JSON.stringify` diffing.
+
+### Streaming Transformer (`streaming/transformer.ts`)
+
+Chunk-based async iterable processor. V2 preserves this but flush should pass real ancestor context instead of empty arrays.
+
+## What to Remove/Rewrite
+
+### `UniversalProps` (`core/types.ts`)
+
+HTML-specific props that don't belong in a universal IR:
+- `onClick`, `onSubmit`, `onInput`, `onChange` (event handlers)
+- `className`, `class` (HTML-specific)
+- `data-*`, `aria-*` template keys
+- `__html` (dangerouslySetInnerHTML)
+
+V2 replaces with plain `Record<string, unknown>`.
+
+### `genId()` (`core/jsx.ts`)
+
+```typescript
+function genId(): string {
+ return `e_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+```
+
+Non-deterministic. V2 uses counter-based or injectable IDs.
+
+### Metadata Injection (`core/jsx.ts`)
+
+Every element gets `{ timestamp: new Date(), id: genId() }`. This is overhead without clear use in a universal IR. Move to host-specific concerns if needed.
+
+## TypeBox Research Examples
+
+Source: `/workspace/research/typebox_research/ujsx/`
+
+### `unist.ts` - Unist schema as TypeBox Module
+
+```typescript
+export const Unist = Type.Module({
+ Data: Type.Object({},{additionalProperties: Type.Unknown()}),
+ Point: Type.Object({ line: Type.Number(), column: Type.Number(), ... }),
+ Position: Type.Object({ start: Type.Ref('Point'), end: Type.Ref("Point") }),
+ Node: Type.Object({ type: Type.String(), data: Type.Optional(...), position: Type.Optional(...) }),
+ Literal: Type.Composite([Type.Ref("Node"), Type.Object({ value: Type.Unknown() })]),
+ Parent: Type.Composite([Type.Ref("Node"), Type.Object({ children: Type.Array(Type.Ref("Node")) })]),
+})
+```
+
+### `ujsx.ts` - UJSX schema as TypeBox Module
+
+```typescript
+export const UJSX = Type.Module({
+ ElementMetadata: Type.Object({ id: Type.Optional(Type.String()), timestamp: Type.Optional(Type.Date()) }, { additionalProperties: Type.Unknown() }),
+ Children: Type.Union([Type.Ref("UniversalNode"), Type.Array(Type.Ref("UniversalNode"))]),
+ PropValue: Type.Union([Type.String(), Type.Number(), ..., Type.Function([...Type.Rest(Type.Array(Type.Unknown()))], Type.Void())]),
+ UniversalProps: Type.Object({ id: Type.Optional(Type.String()), children: Type.Optional(Type.Ref("Children")) }, { additionalProperties: Type.Union([Type.Ref("PropValue"), Type.Undefined()]) }),
+ RootElement: Type.Object({ type: Type.Literal("root"), props: Type.Intersect([...]), children: Type.Array(Type.Ref("UniversalNode")), ... }),
+ UniversalElement: Type.Object({ type: Type.Union([Type.String(), Type.Function([Type.Ref("UniversalProps")], Type.Ref("UniversalNode"))]), props: Type.Ref("UniversalProps"), children: Type.Array(Type.Ref("UniversalNode")), ... }),
+})
+```
+
+Key insight: `Type.Module` creates a `TModule` whose `$defs` is a live `string → TSchema` map. Access via `ValuePointer.Get(UJSX, "$defs/Children")`. Add at runtime via `ValuePointer.Set()`. Import resolved schemas via `UJSX.Import("Element")`.
+
+Note: `ElementMetadata` is defined twice in the research file (duplicate). V2 should clean this up and likely drop metadata from the core schema entirely.
+
+### ts2typebox
+
+CLI tool `ts2typebox` can convert TypeScript types to TypeBox defs but has issues with complex types (JSDoc comments, linked references). Useful for basic types, unreliable for complex ones like unist/mdast type definitions.
\ No newline at end of file
diff --git a/docs/research/signals-ujsx-reactive-pipeline.md b/docs/research/signals-ujsx-reactive-pipeline.md
new file mode 100644
index 0000000..75ce875
--- /dev/null
+++ b/docs/research/signals-ujsx-reactive-pipeline.md
@@ -0,0 +1,372 @@
+# Signals + UJSX: Reactive Transform Pipeline
+
+## The Core Idea
+
+Preact Signals' `computed` provides exactly what UJSX needs for efficient rendering: a component whose output is automatically cached and only recomputed when its input signals change.
+
+In the context of an agent HUD:
+- HUD **state** lives in `signal()` values (task description, decisions, notes, context %)
+- HUD **components** are `computed()` signals that read their input signals and produce UElements
+- The **root render** is a `computed()` that traverses the component tree and produces markdown
+- Changing one signal (e.g., context percentage from 70% to 85%) automatically marks only the downstream components as outdated — not the entire tree
+
+This is fundamentally different from the current approach where the entire HUD is re-rendered from scratch every turn.
+
+## How Signals Work (from source)
+
+Key behaviors from `/workspace/signals/packages/core/src/index.ts`:
+
+### `signal(value)` — The Reactive Primitive
+```typescript
+const count = signal(0)
+count.value // read (tracks deps if in computed/effect)
+count.value = 1 // write (notifies dependents, batches updates)
+count.peek() // read WITHOUT tracking (untracked)
+```
+
+### `computed(fn)` — Derived, cached computation
+```typescript
+const doubled = computed(() => count.value * 2)
+```
+- Lazily evaluated: fn only runs when `.value` is read AND deps have changed
+- Cached: if deps haven't changed, returns cached value without running fn
+- Version tracking: uses `_version` numbers on signals instead of storing values
+- Dependency graph: automatically tracks which signals were read during evaluation
+
+### `effect(fn)` — Side effects
+```typescript
+effect(() => {
+ console.log(doubled.value) // re-runs when count changes
+})
+```
+- Returns a dispose function
+- fn can return a cleanup function
+- Batches: multiple signal writes within `batch()` only trigger one effect run
+
+### `batch(fn)` — Batching
+```typescript
+batch(() => {
+ a.value = 1 // doesn't trigger effects yet
+ b.value = 2 // still batched
+}) // effects run once after batch completes
+```
+
+### `createModel(factory)` — Model pattern
+```typescript
+const Counter = createModel((initial: number) => ({
+ count: signal(initial),
+ increment: action(() => { Counter.count.value++ }),
+ doubled: computed(() => Counter.count.value * 2),
+}))
+const c = new Counter(0)
+c.count.value // 0
+c.increment() // batched, untracked write
+c.doubled.value // 2
+c[Symbol.dispose]() // cleans up all effects
+```
+
+### Key Implementation Details
+
+1. **Version numbers, not value storage**: Computed signals store `_version` per dependency node, not values. When checking if recomputation is needed, it compares version numbers. This is memory-efficient.
+
+2. **Global version counter**: `globalVersion` increments when ANY signal changes. Computed signals track `_globalVersion` — if global hasn't changed since last evaluation, skip entirely (fast path).
+
+3. **Lazy evaluation**: Computed values are NOT computed until someone reads `.value`. No eager re-computation.
+
+4. **Batch snapshots**: When writing multiple signals in a batch, `_batchSnapshotVersion` tracks which signals were written. On batch end, `reconcileBatchSnapshots()` restores version numbers for signals that were written but ended up with the same value (avoiding spurious notifications).
+
+5. **Auto-dispose**: Effects created within `createModel` are captured and disposed when the model's `[Symbol.dispose]()` is called.
+
+6. **Untracked reads**: `signal.peek()` reads without tracking. `untracked(fn)` runs fn without tracking. `action(fn)` wraps fn in batch+untracked.
+
+## Application to UJSX Transform Pipeline
+
+### The Problem
+
+In the HUD, every agent turn re-renders the entire HUD from the root. If the task description hasn't changed, the task section still re-renders. If context went from 67% to 68%, the entire tree is walked even though only `ContextBar` changed.
+
+With signals:
+- Each component whose input hasn't changed **skips re-evaluation entirely**
+- Only the `computed` signals that depend on changed `signal` values re-compute
+- The render pipeline walks the tree, but `computed.value` returns cached results for unchanged components
+
+### Proposed Architecture
+
+```typescript
+import { signal, computed, batch, effect } from "@preact/signals-core"
+
+// --- State Layer (signals) ---
+
+const hudState = createModel(() => ({
+ task: signal<{ description: string; updatedAt: number } | null>(null),
+ contextPercent: signal(0),
+ contextStatus: computed(() => {
+ const p = hudState.contextPercent.value
+ if (p < 70) return 'green' as const
+ if (p < 85) return 'yellow' as const
+ return 'red' as const
+ }),
+ decisions: signal<Array<{ id: string; summary: string }>>([]),
+ notes: signal<Array<{ id: string; content: string }>>([]),
+ nextSteps: signal<Array<{ id: string; description: string; completed: boolean }>>([]),
+ activeFiles: signal<Array<{ path: string; status: string }>>([]),
+ density: computed(() => {
+ const p = hudState.contextPercent.value
+ if (p < 70) return 'full' as const
+ if (p < 85) return 'compact' as const
+ return 'minimal' as const
+ }),
+}))
+
+// --- Component Layer (computed signals producing UElements) ---
+
+function TaskSection() {
+ return computed(() => {
+ const task = hudState.task.value
+ const density = hudState.density.value
+ if (!task) return null
+ if (density === 'minimal') {
+ return h('p', null, task.description)
+ }
+ return h('div', null,
+ h('h2', null, 'Task'),
+ h('p', null, task.description),
+ )
+ })
+}
+
+function ContextBar() {
+ return computed(() => {
+ const percent = hudState.contextPercent.value
+ const status = hudState.contextStatus.value
+ const density = hudState.density.value
+ if (density === 'minimal') {
+ return h('p', null, `${Math.round(percent)}% ${status === 'red' ? '⚠' : ''}`)
+ }
+ return h('div', null,
+ h('h2', null, 'Context'),
+ h('p', null, `${Math.round(percent)}% used (${status})`),
+ )
+ })
+}
+
+function DecisionsList() {
+ return computed(() => {
+ const density = hudState.density.value
+ const decisions = hudState.decisions.value
+ if (density === 'minimal') return null
+ if (density === 'compact') {
+ return h('p', null, `Decisions (${decisions.length})`)
+ }
+ return h('div', null,
+ h('h2', null, 'Decisions'),
+ h('ul', null, ...decisions.map(d => h('li', null, d.summary))),
+ )
+ })
+}
+
+// --- Root Render (computed signal) ---
+
+const hudRender = computed(() => {
+ const task = TaskSection()
+ const ctx = ContextBar()
+ const decisions = DecisionsList()
+
+ const children = [task, ctx, decisions].filter(Boolean)
+ return createRoot('hud', ...children)
+})
+
+// --- Markdown Output (effect, or manual) ---
+
+// Option A: Reactive — auto-renders when any signal changes
+const dispose = effect(() => {
+ const tree = hudRender.value // only recomputes what changed
+ const markdown = renderMarkdown(tree)
+ sendToSystemPrompt(markdown)
+})
+
+// Option B: Manual — called when we know we need a new render
+function renderHUD() {
+ return hudRender.value // triggers only necessary computed() evaluations
+}
+
+// --- Updates are batched ---
+
+function updateHUD(event: HudEvent) {
+ batch(() => {
+ switch (event.type) {
+ case 'task.set':
+ hudState.task.value = { description: event.description, updatedAt: Date.now() }
+ break
+ case 'context.snapshot':
+ hudState.contextPercent.value = event.percent
+ break
+ case 'decision.record':
+ hudState.decisions.value = [...hudState.decisions.value, event.decision]
+ break
+ }
+ })
+ // Only one effect run after the batch, even if multiple signals changed
+}
+```
+
+### What This Buys Us
+
+1. **Skip unchanged components**: If `task` signal hasn't changed, `TaskSection()` returns the cached UElement without calling the component function.
+
+2. **Density changes propagate efficiently**: Changing `contextPercent` from 67% to 68% (green→green) doesn't trigger `ContextBar` re-render because the computed `contextStatus` still returns 'green'. From 69%→71% (green→yellow) DOES trigger `ContextBar` and anything that reads `density`.
+
+3. **Batched updates**: A multi-field update (task + decisions + context) in one `batch()` only triggers one render pass.
+
+4. **No global dirty tracking needed**: The existing POC's `dirty` bitmask on graphology nodes is a manual approximation. Signals do this automatically and correctly.
+
+5. **Separation of state and rendering**: State is in `signal()` values. Rendering is `computed()` derivations. Effects wire rendering to side effects (injecting into system prompt).
+
+6. **`peek()` for untracked reads**: During transformation (walking the tree to produce markdown), we can `peek()` at values without subscribing — useful when the transform doesn't need to be reactive.
+
+7. **Disposal**: `hudState[Symbol.dispose]()` cleans up all effects created within the model. Clean teardown when a session ends.
+
+### What This Does NOT Buy Us (Yet)
+
+1. **Structural changes still need full walk**: Adding/removing a list item still requires re-walking that part of the tree. Signals help with value changes, not structural changes. For structural changes, we'd need a keyed list diff (like React's reconciliation).
+
+2. **The transform (UJSX → mdast → markdown) is always full**: Even if only one component re-computes, the entire tree still gets walked to produce markdown. To skip unchanged subtrees in the transform, we'd need to memoize transform results per node (using `computed` at the transform level too).
+
+3. **No framework dependency yet**: We're using signals-core standalone, not via Preact/React integration. The Preact adapter (`@preact/signals`) adds `useSignal()` hook, React adapter (`@preact/signals-react`) adds `useSignalValue()`. We don't need either — we use `signal`/`computed` directly.
+
+### Computed Transforms (Memoization at Every Level)
+
+The real power: make the transform pipeline itself reactive:
+
+```typescript
+// State signal
+const taskText = signal("Implement auth module")
+
+// Component produces a UElement (computed — cached)
+const taskElement = computed(() =>
+ h('h2', null, taskText.value)
+)
+
+// Transform produces mdast (computed — cached)
+const taskMdast = computed(() =>
+ transformToMdast(taskElement.value, { direction: 'ujsx->mdast' })
+)
+
+// Serialize to markdown (computed — cached)
+const taskMarkdown = computed(() =>
+ toMarkdown(taskMdast.value)
+)
+
+// Only runs when taskText changes: taskElement → taskMdast → taskMarkdown
+// If taskText hasn't changed, reading taskMarkdown.value returns cached string
+```
+
+This means the ENTIRE pipeline is memoized. If you change `contextPercent` from 67% to 68% (green→green, no density change), `taskMarkdown.value` returns the cached string instantly. Only `contextBarMarkdown.value` recomputes.
+
+### The Final Composition
+
+```typescript
+// Each section is its own computed pipeline
+const taskMd = computed(() => renderSection(TaskSection(), 'ujsx->mdast'))
+const ctxMd = computed(() => renderSection(ContextBar(), 'ujsx->mdast'))
+const decisionsMd = computed(() => renderSection(DecisionsList(), 'ujsx->mdast'))
+
+// Root markdown is computed from sections
+const fullMarkdown = computed(() =>
+ [taskMd.value, ctxMd.value, decisionsMd.value]
+ .filter(Boolean)
+ .join('\n\n')
+)
+
+// Only the sections whose signals changed recompute their markdown
+// fullMarkdown recomputes its string join (cheap) but doesn't re-walk unchanged sections
+```
+
+### Integration with opencode Plugin
+
+The `effect()` that injects into the system prompt would be:
+
+```typescript
+const dispose = effect(() => {
+ const markdown = fullMarkdown.value
+ // This runs whenever any upstream signal changes
+ // But only the changed computed() evaluations actually ran
+ systemPromptInjector.push(markdown)
+})
+```
+
+Or more pragmatically, since opencode calls the plugin hook on every LLM turn:
+
+```typescript
+// In the plugin's system.transform hook:
+"experimental.chat.system.transform": async (input, output) => {
+ // Just read .value — it's cached, no work if unchanged
+ const markdown = fullMarkdown.value
+ output.system.push(markdown)
+}
+```
+
+This is the simplest integration: no effect, no subscription. Just read `.value` when asked. If nothing changed, it's O(1). If something changed, only the minimal recomputation happens.
+
+### Signals + TypeBox Module Interaction
+
+The signals hold runtime state. The TypeBox Module defines the schema for that state.
+
+```typescript
+import { Type, Static } from "@alkdev/typebox"
+
+const HudStateModule = Type.Module({
+ Task: Type.Object({
+ description: Type.String(),
+ updatedAt: Type.Number(),
+ }),
+ Decision: Type.Object({
+ id: Type.String(),
+ summary: Type.String(),
+ details: Type.Optional(Type.String()),
+ }),
+ ContextInfo: Type.Object({
+ percent: Type.Number(),
+ status: Type.Union([Type.Literal('green'), Type.Literal('yellow'), Type.Literal('red')]),
+ model: Type.String(),
+ }),
+})
+
+// Import for validation
+const Task = HudStateModule.Import("Task")
+const Decision = HudStateModule.Import("Decision")
+
+// Validate before setting signal values
+function updateHUD(event: HudEvent) {
+ batch(() => {
+ if (event.type === 'task.set') {
+ if (Value.Check(Task, event.task)) {
+ hudState.task.value = event.task
+ }
+ }
+ // ...
+ })
+}
+```
+
+The TypeBox Module validates incoming events. The signals hold the validated state. The `computed` components derive UElements from the state. The transform pipeline serializes to markdown.
+
+### File Structure Addition
+
+```
+@alkdev/ujsx/
+ core/
+ schema.ts # TypeBox Module for UNode/UElement/URoot
+ h.ts # h(), createRoot(), Fragment factory
+ context.ts # Signal-based context (density, target)
+ signals.ts # createHudModel() — signals for HUD state
+ host/
+ config.ts # HostConfig interface (preserved)
+ markdown.ts # Markdown host (new)
+ transform/
+ registry.ts # Enhanced TransformRegistry with direction + schema
+ rule.ts # Rule type with TypeBox schema
+ ...
+```
+
+The signals integration is an **addition** to the TypeBox-driven rewrite, not a replacement. The TypeBox Module defines the shape. The signals hold the runtime values. The computed signals produce the rendered output.
\ No newline at end of file
diff --git a/docs/research/typebox-module-type-registry.md b/docs/research/typebox-module-type-registry.md
new file mode 100644
index 0000000..bdca816
--- /dev/null
+++ b/docs/research/typebox-module-type-registry.md
@@ -0,0 +1,113 @@
+# TypeBox Module Research: UJSX Schema Implications
+
+## Key Finding: `Type.Module` IS the Type Registry
+
+`Type.Module` creates a `TModule` object whose `$defs` property is a live `string → TSchema` map. This is exactly the "type registry" pattern needed for UJSX.
+
+### Core Operations
+
+```typescript
+const UJSX = Type.Module({
+ Props: Type.Object({ id: Type.Optional(Type.String()) }, { additionalProperties: Type.Unknown() }),
+ Element: Type.Object({
+ type: Type.String(),
+ props: Type.Ref("Props"),
+ children: Type.Array(Type.Ref("Node")),
+ }),
+ Node: Type.Union([Type.String(), Type.Number(), Type.Null(), Type.Ref("Element")]),
+})
+```
+
+#### Reading schemas by name
+```typescript
+ValuePointer.Get(UJSX, "$defs/Props") // → TSchema with $id: "Props"
+ValuePointer.Get(UJSX, "$defs/Element") // → TSchema with $id: "Element"
+```
+
+#### Adding schemas at runtime
+```typescript
+ValuePointer.Set(UJSX, "$defs/Heading", Type.Object({
+ type: Type.Literal("heading"),
+ depth: Type.Number(),
+ children: Type.Array(Type.Ref("Node")),
+}))
+// Now UJSX.$defs.Heading exists and can be referenced by Type.Ref("Heading")
+```
+
+#### Importing (resolves $ref, creates self-contained schema for validation)
+```typescript
+const Element = UJSX.Import("Element")
+// Element = { [Kind]: 'Import', $defs: { Props: {...}, Element: {...}, Node: {...} }, $ref: "Element" }
+Value.Check(Element, someData) // Works! All $refs resolved via inlined $defs
+```
+
+#### Static type inference
+```typescript
+type UE = Static<typeof Element>
+// UE = { type: string; props: { id?: string; [k: string]: unknown }; children: UE[] }
+```
+
+### How `Import` Works (from source)
+
+The `Import` method on `TModule` (module.ts:70-72):
+
+```typescript
+public Import<Key extends keyof ComputedModuleProperties>(key: Key, options?: SchemaOptions): TImport<ComputedModuleProperties, Key> {
+ const $defs = { ...this.$defs, [key]: CreateType(this.$defs[key], options) }
+ return CreateType({ [Kind]: 'Import', $defs, $ref: key }) as never
+}
+```
+
+It creates a `TImport` schema with:
+- `[Kind]: 'Import'` — uniquely identifies this as a module import
+- `$defs` — ALL module definitions copied in (so $refs resolve)
+- `$ref: key` — which definition to use as the root
+
+### How `ComputeModuleProperties` Works (from compute.ts)
+
+The constructor calls `ComputeModuleProperties` which walks every property and:
+
+1. Resolves `Type.Ref("X")` → dereferences to the actual type at `moduleProperties[X]`
+2. Recursively processes: `Type.Array(Type.Ref("Node"))` → `Type.Array(ResolvedNode)`
+3. Handles all TypeBox combinators: Object, Union, Intersect, Function, Record, etc.
+4. Adds `$id` to each definition via `WithIdentifiers`
+
+This means you can use `Type.Ref()` inside `Type.Module()` and they get resolved to direct references. The $ref JSON pointer stays in the output for JSON Schema compatibility, but TypeBox's internal resolution handles them.
+
+### `TInferFromModuleKey` — Type-Level Inference
+
+The `infer.ts` file provides `TInferFromModuleKey<ModuleProperties, Key>` which is the type-level path of resolving refs. This is what makes `Static<typeof ImportedElement>` produce a proper recursive type:
+
+```typescript
+type UE = Static<typeof Element>
+// Resolves to:
+// { type: string; props: { id?: string; [k: string]: unknown }; children: (string | number | null | UE)[] }
+```
+
+This is a **recursive type** inferred from the module. No `Type.Recursive` needed because the Module's type-level inference handles cycles through `TRef`.
+
+### Function Types in Modules
+
+`Type.Function([...params], returnType)` creates a JavaScript-extended schema type:
+
+```typescript
+ComponentFn: Type.Function([Type.Ref("Props")], Type.Ref("Node"))
+```
+
+This produces a JSON Schema with `{ type: "Function", parameters: [...], returns: {...} }` which is NOT standard JSON Schema but IS valid TypeBox. `Value.Check` validates that the value is a function at runtime. This means we can represent component functions in the schema.
+
+### Implications for UJSX v2
+
+1. **No separate type registry needed.** `TModule` IS the registry. It's a map of `string → TSchema` with computed resolution and `$id` assignment built in.
+
+2. **Schemas ARE types AND ARE tool parameter schemas.** One definition creates the TypeScript type, the runtime validator, and the JSON Schema for tool definitions.
+
+3. **Bi-directional transforms can be schema-driven.** Transform rules can match on `Value.Check(ruleSchema, node)` instead of string tag matching.
+
+4. **Node definitions can be added at runtime.** `ValuePointer.Set(module, "$defs/CustomNode", ...)` or simply defining new entries in the Module. This means plugins can extend the IR.
+
+5. **Function components are first-class in the schema.** `Type.Function([Type.Ref("Props")], Type.Ref("Node"))` validates that `type` is a function at runtime. For serialization, we'd resolve function components to string tags before going to mdast/other targets.
+
+6. **`Import` creates self-contained schemas.** Perfect for sending to tool definitions or validation contexts where the full module isn't available.
+
+7. **The `ComponentFn` pattern means we can separate runtime and serializable representations.** At runtime, `type` can be a function. Before serialization (JSON, mdast), we resolve function components to string identifiers and emit `{ type: "Component", componentId: "TaskSection", ... }`.
\ No newline at end of file
diff --git a/docs/research/typebox-module-valuepointer.md b/docs/research/typebox-module-valuepointer.md
new file mode 100644
index 0000000..9e4d65b
--- /dev/null
+++ b/docs/research/typebox-module-valuepointer.md
@@ -0,0 +1,101 @@
+# TypeBox Module & ValuePointer: Core Patterns for UJSX
+
+Source: `/workspace/@alkdev/typebox` (npm: `@alkdev/typebox`)
+
+## TModule: The Schema Registry
+
+`Type.Module()` creates a `TModule` whose `$defs` property is a live `string → TSchema` map. This IS the type registry UJSX needs — no separate registry required.
+
+### Core Operations
+
+```typescript
+const UJSX = Type.Module({
+ Props: Type.Object({ id: Type.Optional(Type.String()) }, { additionalProperties: Type.Unknown() }),
+ Element: Type.Object({
+ type: Type.String(),
+ props: Type.Ref("Props"),
+ children: Type.Array(Type.Ref("Node")),
+ }),
+ Node: Type.Union([Type.String(), Type.Number(), Type.Null(), Type.Ref("Element")]),
+})
+```
+
+### Read schemas by name
+
+```typescript
+import { ValuePointer } from "@alkdev/typebox/value";
+ValuePointer.Get(UJSX, "$defs/Props") // TSchema with $id: "Props"
+ValuePointer.Get(UJSX, "$defs/Element") // TSchema with $id: "Element"
+```
+
+### Add schemas at runtime
+
+```typescript
+ValuePointer.Set(UJSX, "$defs/Heading", Type.Object({
+ type: Type.Literal("heading"),
+ depth: Type.Number(),
+ children: Type.Array(Type.Ref("Node")),
+}))
+// Now UJSX.$defs.Heading exists and Type.Ref("Heading") resolves
+```
+
+### Import: Resolved schemas for validation
+
+```typescript
+const Element = UJSX.Import("Element")
+// Creates TImport with: { [Kind]: 'Import', $defs: { all module defs inlined }, $ref: "Element" }
+Value.Check(Element, someData) // Works! All $refs resolved via inlined $defs
+```
+
+### Static type inference
+
+```typescript
+type UE = Static<typeof Element>
+// UE = { type: string; props: { id?: string; [k: string]: unknown }; children: UE[] }
+```
+
+The Module's type-level inference handles cycles through `TRef` — no `Type.Recursive` needed.
+
+## How Import Works (from source)
+
+Module source: `/workspace/@alkdev/typebox/src/type/module/index.ts`
+
+```typescript
+public Import<Key>(key: Key, options?: SchemaOptions): TImport {
+ const $defs = { ...this.$defs, [key]: CreateType(this.$defs[key], options) }
+ return CreateType({ [Kind]: 'Import', $defs, $ref: key })
+}
+```
+
+Creates a `TImport` schema with:
+- `[Kind]: 'Import'` — uniquely identifies as module import
+- `$defs` — ALL module definitions copied in (so $refs resolve)
+- `$ref: key` — which definition to use as root
+
+## ComputeModuleProperties
+
+Called during Module construction. Walks every property and:
+1. Resolves `Type.Ref("X")` → dereferences to actual type at `moduleProperties[X]`
+2. Recursively processes: `Type.Array(Type.Ref("Node"))` → `Type.Array(ResolvedNode)`
+3. Handles all TypeBox combinators: Object, Union, Intersect, Function, Record, etc.
+4. Adds `$id` to each definition via `WithIdentifiers`
+
+## Function Types in Modules
+
+```typescript
+Type.Function([Type.Ref("Props")], Type.Ref("Node"))
+```
+
+Creates a JavaScript-extended schema type `{ type: "Function", parameters: [...], returns: {...} }`. Not standard JSON Schema but valid TypeBox. `Value.Check` validates that the value is a function at runtime.
+
+This means component functions CAN be represented in the schema. For serialization, resolve function components to string identifiers before going to mdast/other targets.
+
+## Implications for UJSX v2
+
+1. **No separate type registry needed** — `TModule` IS the registry
+2. **Schemas ARE types AND tool parameter schemas** — one definition, triple duty
+3. **Bi-directional transforms can be schema-driven** — `Value.Check(ruleSchema, node)` instead of string matching
+4. **Node definitions can be added at runtime** — plugins can extend the IR via `ValuePointer.Set()`
+5. **`Import` creates self-contained schemas** — perfect for tool definitions or validation contexts
+6. **Function components are first-class in schema** — separate runtime vs serializable representations
+7. **No `Type.Recursive` needed in Module** — cycles handle through `TRef` + type-level inference
\ No newline at end of file
diff --git a/docs/research/ujsx-v2-typebox-rewrite.md b/docs/research/ujsx-v2-typebox-rewrite.md
new file mode 100644
index 0000000..9b59796
--- /dev/null
+++ b/docs/research/ujsx-v2-typebox-rewrite.md
@@ -0,0 +1,554 @@
+# UJSX v2: TypeBox-Schema-Driven Universal JSX IR
+
+## What Exists: The Current POC
+
+The `/workspace/aui` codebase has two packages:
+
+- **`@ade/ujsx`** — Core universal JSX IR: `h()` factory, `UniversalElement`/`RootElement` types, `HostConfig` reconciler, `TransformRegistry`, `StreamingTransformer`
+- **`@ade/aui`** — Markdown consumer: `jsxToMdast` transform rules, `renderMarkdown()` via mdast-util-to-markdown + GFM
+
+The architecture is already right at a high level:
+```
+JSX (h calls) → UniversalNode tree → Host/Transform → Output
+```
+
+## What's Wrong
+
+1. **No actual JSX syntax** — Uses `h()` calls instead of `<Component />` syntax. Needs a JSX transform config (like Hono's `tsconfig.json` jsxFactory) so you can write real JSX.
+
+2. **HTML baggage** — `UniversalProps` has `onClick`, `onSubmit`, `onInput`, `onChange`, `className`, `aria-*`, `data-*` — all HTML-specific. For a universal IR targeting markdown (and eventually other formats), these are noise.
+
+3. **No schema-driven types** — Types are hand-written interfaces. The whole point of using TypeBox is that the IR *is* a schema — nodes can be validated at runtime, composed generically, and converted to JSON Schema for tool definitions.
+
+4. **Non-deterministic IDs** — `genId()` uses `Math.random()`. Needs to be injectable/deterministic.
+
+5. **Separate props + children** — `UniversalElement` has both `props` and `children`. This is the React/HTML model where `children` is a special prop. For a universal IR, children is just a prop like any other. Simplify.
+
+6. **No Context system** — React's Context/Provider pattern is essential for passing density/target/host config down the tree without prop drilling.
+
+7. **Fragment not integrated** — Exists but reconciler and transforms don't handle it specially.
+
+8. **Missing markdown nodes** — No blockquote, link, image, hr, table support.
+
+## The Rewrite: TypeBox-Schema-Driven UJSX
+
+### Core Principle
+
+**The UniversalElement IS a TypeBox schema at runtime.** Every node in the tree is both a valid TypeScript value AND a valid JSON Schema value. This means:
+
+- Runtime validation: `Value.Check(UElementSchema, node)`
+- Tool schema generation: Convert any component's props schema to JSON Schema for agent tool definitions
+- Generic composition: `Type.Intersect()`, `Type.Partial()`, `Type.Omit()` work on node schemas
+- Bi-directional transforms: Rules match on schema shape, not string tags
+
+### TypeBox AST Schema
+
+```typescript
+import { Type, Static, TSchema } from "@alkdev/typebox"
+
+// The recursive node schema — the heart of the system
+const UNodeSchema = Type.Recursive((This) =>
+ Type.Union([
+ Type.Null(),
+ Type.String(),
+ Type.Number(),
+ Type.Boolean(),
+ Type.Object({
+ type: Type.Union([Type.String(), Type.Function([Type.Object({}), This], This)]),
+ props: Type.Record(Type.String(), Type.Any()),
+ children: Type.Array(This),
+ }),
+ ]),
+ { $id: "UNode" }
+)
+
+type UNode = Static<typeof UNodeSchema>
+
+// Refined: element is the object branch
+const UElementSchema = Type.Object({
+ type: Type.Union([Type.String(), Type.Function([Type.Object({}), UNodeSchema], UNodeSchema)]),
+ props: Type.Record(Type.String(), Type.Any()),
+ children: Type.Array(UNodeSchema),
+})
+
+type UElement = Static<typeof UElementSchema>
+```
+
+Wait — `Type.Function` in TypeBox creates a JavaScript extended schema type, not a JSON Schema one. For the IR's purposes, we want function components to be part of the *runtime* TypeScript type but NOT part of the serializable schema. The schema (what gets validated and what tools see) should only have string types.
+
+Better approach: separate the runtime type from the serializable schema:
+
+```typescript
+// Serializable schema — what validation and tool definitions see
+const USerializableElementSchema = Type.Recursive((This) =>
+ Type.Object({
+ type: Type.String(), // Always a string after component resolution
+ props: Type.Record(Type.String(), Type.Any()),
+ children: Type.Array(Type.Union([
+ Type.String(),
+ Type.Number(),
+ Type.Null(),
+ This,
+ ])),
+ }),
+ { $id: "UElement" }
+)
+
+// Runtime TypeScript type — includes function components
+type UType = string | ComponentFn
+type UNode = UElement | string | number | null
+type UElement = {
+ type: UType
+ props: Record<string, unknown>
+ children: UNode[]
+}
+```
+
+Actually, let me think about this differently. The key insight from the user's message is **bi-directional transforms**. The current `TransformRegistry` goes one direction (UJSX → mdast). The universal IR concept means rules should go both ways:
+
+- UJSX → mdast (for markdown rendering)
+- mdast → UJSX (for parsing markdown back into the IR)
+- UJSX → hast (for HTML rendering)
+- hast → UJSX (for parsing HTML)
+- Eventually: UJSX → Graphology, UJSX → terminal ANSI, etc.
+
+This is where TypeBox schemas really shine: **each node type's schema IS the match criterion**. Instead of string-based matching (`n.type === 'h1'`), rules match on schema shape:
+
+```typescript
+// Current: string-based matching
+jsxToMdast.register({
+ name: 'heading',
+ match: (n) => isUniversalElement(n) && typeof n.type === 'string' && /^h[1-6]$/.test(n.type),
+ transform: ...
+})
+
+// TypeBox-driven: schema-based matching
+const HeadingSchema = Type.Object({
+ type: Type.String({ pattern: '^h[1-6]$' }),
+ props: Type.Object({ level: Type.Number().optional() }),
+ children: Type.Array(UNodeSchema),
+})
+
+rule({
+ name: 'heading',
+ schema: HeadingSchema,
+ direction: 'ujsx->mdast',
+ transform: (node, ctx, next) => ({
+ type: 'heading',
+ depth: Number(node.type.slice(1)),
+ children: transformChildren(node, ctx, next),
+ }),
+})
+```
+
+This is more verbose but gives us:
+1. `Value.Check(HeadingSchema, node)` — validate before transforming
+2. The schema can be registered as a tool parameter schema
+3. Bi-directional: a `mdast->ujsx` rule for heading uses the same schema
+4. `Type.Intersect()` to compose schemas for compound elements
+
+### Simplified Element Model
+
+Remove HTML-specific stuff. The `props` becomes a plain `Record<string, unknown>` with no HTML-centric defaults. Event handlers (`onClick`, etc.) and HTML attributes (`className`, `aria-*`) are gone from the core — they belong in an HTML host extension, not the universal IR.
+
+```typescript
+// core/schema.ts
+import { Type, Static } from "@alkdev/typebox"
+
+// Primitives
+const UPrimitive = Type.Union([Type.String(), Type.Number(), Type.Null()])
+
+// Element — the universal IR node
+const UElement = Type.Recursive((This) =>
+ Type.Object({
+ type: Type.String(),
+ props: Type.Record(Type.String(), Type.Any()),
+ children: Type.Array(Type.Union([UPrimitive, This])),
+ }, { $id: "UElement" }),
+)
+
+// Root — session/frame container
+const URoot = Type.Object({
+ type: Type.Literal("root"),
+ props: Type.Object({
+ id: Type.Optional(Type.String()),
+ target: Type.Optional(Type.String()),
+ }),
+ children: Type.Array(Type.Union([UPrimitive, UElement])),
+}, { $id: "URoot" })
+
+// Node = everything a position in the tree can hold
+const UNode = Type.Union([UPrimitive, UElement, URoot], { $id: "UNode" })
+
+type UElement = Static<typeof UElement>
+type URoot = Static<typeof URoot>
+type UNode = Static<typeof UNode>
+```
+
+### The `h()` Factory (Cleaned Up)
+
+```typescript
+// core/h.ts
+import type { UNode, UElement, URoot } from './schema.ts'
+
+let _idCounter = 0
+
+export function h(
+ type: string,
+ props?: Record<string, unknown> | null,
+ ...children: UNode[]
+): UElement {
+ return {
+ type,
+ props: props ?? {},
+ children: children.flat(Infinity).filter(c => c != null && c !== false) as UNode[],
+ }
+}
+
+export function createRoot(id?: string, ...children: UNode[]): URoot {
+ return {
+ type: 'root',
+ props: { id },
+ children: children.flat(Infinity).filter(c => c != null && c !== false) as UNode[],
+ }
+}
+
+// Alias for JSX transform compatibility
+export const jsx = h
+export const jsxs = h
+export const jsxDEV = h
+
+// Fragment: children pass-through
+export function Fragment(props: { children?: UNode[] }): UNode[] {
+ return (props.children ?? []).flat(Infinity).filter(c => c != null && c !== false) as UNode[]
+}
+```
+
+Key changes from current:
+- **No metadata injection** — `timestamp` and `id` on every element was overhead without clear use. If needed, it belongs in the host, not the IR.
+- **No `className`/event handlers** — Universal props, not HTML props.
+- **Deterministic by default** — No `Math.random()`.
+
+### JSX Transform Config
+
+To support actual JSX syntax (`<TaskSection task={state.task} />`), you need a `tsconfig.json` or `deno.json` with:
+
+```json
+{
+ "compilerOptions": {
+ "jsx": "react-jsx",
+ "jsxImportSource": "@ade/ujsx"
+ }
+}
+```
+
+And an `jsx-runtime` module that exports `jsx`, `jsxs`, `jsxDEV`, `Fragment`. This is what Hono does (`hono/jsx/jsx-runtime`).
+
+### Host System (Preserved, Simplified)
+
+The `HostConfig` interface is good. Keep it but remove the HTML-specific assumptions:
+
+```typescript
+// host/config.ts
+export interface HostConfig<TTag extends string, Instance, RootCtx> {
+ name: string
+ createRootContext(container: unknown, options?: Record<string, unknown>): RootCtx
+ finalizeRoot?(ctx: RootCtx): void
+ createInstance(tag: TTag, props: Record<string, unknown>, ctx: RootCtx, parent?: Instance): Instance
+ createTextInstance(text: string, ctx: RootCtx, parent?: Instance): Instance
+ appendChild(parent: Instance, child: Instance, ctx: RootCtx): void
+ insertBefore?(parent: Instance, child: Instance, before: Instance, ctx: RootCtx): void
+ removeChild?(parent: Instance, child: Instance, ctx: RootCtx): void
+ prepareUpdate?(instance: Instance, tag: TTag, prevProps: Record<string, unknown>, nextProps: Record<string, unknown>, ctx: RootCtx): unknown | null
+ commitUpdate?(instance: Instance, payload: unknown, tag: TTag, prevProps: Record<string, unknown>, nextProps: Record<string, unknown>, ctx: RootCtx): void
+}
+```
+
+No changes needed. The host is host-agnostic already. The graphology host stays. A markdown host can be added:
+
+```typescript
+// host/markdown.ts
+export function createMarkdownHost(): HostConfig<string, MdastNode, MdastRoot> {
+ // Maps universal tags to mdast node creation
+ // Uses the same rules as the TransformRegistry but via HostConfig
+}
+```
+
+### TypeBox-Driven Transform Rules
+
+The key evolution of the `TransformRegistry`. Rules are now schema-aware and bi-directional:
+
+```typescript
+// transform/rule.ts
+import { Type, TSchema, Value } from "@alkdev/typebox"
+
+export type Direction = 'ujsx->mdast' | 'mdast->ujsx' | 'ujsx->hast' | 'hast->ujsx'
+
+export interface TransformRule<TInput, TOutput, TAncestor> {
+ name: string
+ direction: Direction
+ schema: TSchema // The TypeBox schema this rule matches against
+ match: (node: TInput) => boolean // Runtime match (can use schema or custom logic)
+ transform: (node: TInput, ctx: TransformContext<TAncestor>, next: TransformFn<TInput, TOutput, TAncestor>) => TOutput
+ priority?: number
+}
+
+export class TransformRegistry<TInput, TOutput, TAncestor> {
+ private rules: TransformRule<TInput, TOutput, TAncestor>[] = []
+
+ register(rule: TransformRule<TInput, TOutput, TAncestor>) {
+ this.rules.push(rule)
+ this.rules.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+ }
+
+ transform(node: TInput, ctx: TransformContext<TAncestor>, direction?: Direction): TOutput {
+ const rule = direction
+ ? this.rules.find(r => r.direction === direction && r.match(node))
+ : this.rules.find(r => r.match(node))
+ if (!rule) throw new Error(`No rule for node`)
+ return rule.transform(node, ctx, (n, c) => this.transform(n, c, direction))
+ }
+}
+```
+
+With schema-based matching, we can also do:
+
+```typescript
+// Validate a node against a rule's schema before transforming
+function matchesSchema(schema: TSchema, node: unknown): boolean {
+ return Value.Check(schema, node)
+}
+```
+
+### Bi-Directional Markdown Rules
+
+```typescript
+// markdown/rules.ts
+import { Type } from "@alkdev/typebox"
+
+const HeadingUSchema = Type.Object({
+ type: Type.String({ pattern: '^h[1-6]$' }),
+ props: Type.Record(Type.String(), Type.Any()),
+ children: Type.Array(Type.Any()),
+})
+
+const HeadingMdastSchema = Type.Object({
+ type: Type.Literal('heading'),
+ depth: Type.Number(),
+ children: Type.Array(Type.Any()),
+})
+
+// UJSX → mdast
+registry.register({
+ name: 'heading-ujsx-to-mdast',
+ direction: 'ujsx->mdast',
+ schema: HeadingUSchema,
+ match: (n) => isUElement(n) && /^h[1-6]$/.test(String(n.type)),
+ transform: (n, ctx, next) => ({
+ type: 'heading',
+ depth: Number(String(n.type).slice(1)),
+ children: transformChildren(n, ctx, next),
+ }),
+})
+
+// mdast → UJSX
+registry.register({
+ name: 'heading-mdast-to-ujsx',
+ direction: 'mdast->ujsx',
+ schema: HeadingMdastSchema,
+ match: (n) => n.type === 'heading',
+ transform: (n, ctx, next) => ({
+ type: `h${n.depth}`,
+ props: {},
+ children: (n.children || []).map((c, i) => next(c, childCtx(n, ctx, i))),
+ }),
+})
+```
+
+This is the bi-directional concept. Same registry, same `transform()` call, different `direction` parameter. The schemas provide the contract for each direction.
+
+### Component Schema = Tool Schema
+
+The real payoff of TypeBox-driven schemas: any component's props schema is automatically a tool parameter schema.
+
+```typescript
+// A HUD component defined with TypeBox
+const TaskSectionProps = Type.Object({
+ task: Type.Object({
+ description: Type.String(),
+ updatedAt: Type.Number(),
+ }),
+ density: Type.Union([Type.Literal('full'), Type.Literal('compact'), Type.Literal('minimal')]),
+})
+
+// The component
+function TaskSection(props: Static<typeof TaskSectionProps>): UElement {
+ if (props.density === 'minimal') {
+ return h('p', null, props.task.description)
+ }
+ return h('div', null,
+ h('h2', null, 'Task'),
+ h('p', null, props.task.description),
+ )
+}
+
+// TaskSectionProps IS the schema for an agent tool that sets the task:
+// hud({ tool: "task.set", args: { description: "...", updatedAt: Date.now() } })
+// The tool's inputSchema = TaskSectionProps
+```
+
+No duplication. The component's type IS the tool's schema. `Value.Check(TaskSectionProps, input)` validates both.
+
+### Context System
+
+Needed for passing density/target config down the tree without prop drilling:
+
+```typescript
+// core/context.ts
+
+export interface ContextValue {
+ density: 'full' | 'compact' | 'minimal'
+ target: string // 'markdown' | 'graph' | 'html' | etc.
+ metadata: Record<string, unknown>
+}
+
+// Simple context implementation (no React dependency)
+type ContextListener = (value: ContextValue) => void
+
+export class Context {
+ private value: ContextValue
+ private listeners: Set<ContextListener> = new Set()
+
+ constructor(initial: ContextValue) {
+ this.value = initial
+ }
+
+ get(): ContextValue { return this.value }
+
+ set(partial: Partial<ContextValue>) {
+ this.value = { ...this.value, ...partial }
+ for (const fn of this.listeners) fn(this.value)
+ }
+
+ subscribe(fn: ContextListener): () => void {
+ this.listeners.add(fn)
+ return () => this.listeners.delete(fn)
+ }
+}
+```
+
+This is lightweight and doesn't need React. Components receive context via the `host` or `transform` path.
+
+### File Structure (Proposed Rewrite)
+
+```
+ujsx/
+ mod.ts # Re-exports
+ deno.json # JSX transform config
+ core/
+ schema.ts # TypeBox schemas for UNode, UElement, URoot
+ h.ts # h() factory, createRoot(), Fragment
+ context.ts # Context system for density/target
+ jsx-runtime.ts # JSX transform runtime exports
+ host/
+ config.ts # HostConfig interface + createRoot reconciler (preserved)
+ graphology.ts # Graphology host (preserved, fix commented-out append)
+ markdown.ts # NEW: Markdown host using HostConfig pattern
+ transform/
+ registry.ts # Enhanced TransformRegistry with direction + schema
+ rule.ts # TransformRule type with TSchema
+ streaming/
+ transformer.ts # Chunk-based async transformer (preserved)
+
+aui/
+ mod.ts
+ deno.json
+ markdown/
+ render.ts # renderMarkdown() (preserved, uses new registry)
+ rules.ts # Bi-directional rules with TypeBox schemas
+ types.ts # mdast type re-exports
+ components/ # NEW: Pre-built markdown-targeted components
+ container.ts # <Container>
+ context-bar.ts # <ContextBar> with density awareness
+ heading.ts # <Heading level={1-6}>
+ list.ts # <List>, <ListItem>, <TaskList>
+ code.ts # <Code>, <CodeBlock>
+ blockquote.ts # NEW: <Blockquote>
+ link.ts # NEW: <Link>
+ table.ts # NEW: <Table>
+ hr.ts # NEW: <Divider>
+ hud/ # NEW: HUD-specific components
+ HUD.tsx # Root HUD component
+ TaskSection.tsx # Task display
+ DecisionsList.tsx # Key decisions
+ NotesSection.tsx # Scratchpad
+ NextSteps.tsx # Plan/next steps
+ ActiveFiles.tsx # Currently active files
+ WarningBanner.tsx # Context pressure warning
+```
+
+### tsconfig for JSX Syntax
+
+```json
+{
+ "compilerOptions": {
+ "jsx": "react-jsx",
+ "jsxImportSource": "@ade/ujsx"
+ }
+}
+```
+
+With this, you write:
+
+```tsx
+import { h } from "@ade/ujsx"
+
+function TaskSection({ task, density }: TaskSectionProps) {
+ if (density === 'minimal') {
+ return <p>{task.description}</p>
+ }
+ return (
+ <div>
+ <h2>Task</h2>
+ <p>{task.description}</p>
+ </div>
+ )
+}
+```
+
+Instead of:
+
+```typescript
+function TaskSection({ task, density }: TaskSectionProps) {
+ if (density === 'minimal') {
+ return h('p', null, task.description)
+ }
+ return h('div', null,
+ h('h2', null, 'Task'),
+ h('p', null, task.description),
+ )
+}
+```
+
+### Migration Steps
+
+1. **Replace types.ts with schema.ts** — TypeBox schemas for UNode/UElement/URoot. Export both schemas and `Static<>` types.
+2. **Clean up h.ts** — Remove metadata injection, HTML-specific props, `Math.random()`. Add `jsx-runtime.ts` export.
+3. **Add deno.json jsxImportSource** — Enable JSX syntax.
+4. **Strip UniversalProps** — Replace with plain `Record<string, unknown>`. No `onClick`, `className`, etc.
+5. **Upgrade TransformRegistry** — Add `direction` and `schema` fields to rules.
+6. **Add missing markdown rules** — blockquote, link, image, hr, table.
+7. **Add Context** — Simple context system for density/target.
+8. **Fix graphology host** — Uncomment append logic, replace `JSON.stringify` diffing.
+9. **Add Markdown host** — `createMarkdownHost()` using HostConfig.
+10. **Add bi-directional rules** — mdast → ujsx direction for each element.
+11. **Build HUD components** — The `aui/hud/` directory with density-aware components.
+
+### What This Enables for the Agent HUD
+
+With the cleaned-up UJSX:
+- Components ARE schemas — any HUD component's props schema is automatically a tool parameter schema
+- Bi-directional transforms mean we can parse markdown INTO the IR (parse existing agent notes, markdown files, AGENTS.md)
+- The host system means the same HUD component tree could render to markdown for LLM consumption OR to a graph for visualization OR to HTML for a web dashboard
+- TypeBox validation means we can validate HUD events against component schemas before accepting them
+- The Context system carries density/target through the component tree — clean and no prop drilling
\ No newline at end of file
diff --git a/docs/research/unist-ecosystem-jsx-to-markdown.md b/docs/research/unist-ecosystem-jsx-to-markdown.md
new file mode 100644
index 0000000..c4946f7
--- /dev/null
+++ b/docs/research/unist-ecosystem-jsx-to-markdown.md
@@ -0,0 +1,1211 @@
+# Unist Ecosystem Research: JSX → Markdown Pipeline for LLM Consumption
+
+**Date**: 2026-04-28
+**Topic**: Feasibility of JSX components → hast → mdast → markdown pipeline using the Unist/syntax-tree ecosystem
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#1-executive-summary)
+2. [unist: The Universal Foundation](#2-unist-the-universal-foundation)
+3. [hast: Hypertext Abstract Syntax Tree](#3-hast-hypertext-abstract-syntax-tree)
+4. [mdast: Markdown Abstract Syntax Tree](#4-mdast-markdown-abstract-syntax-tree)
+5. [hast-util-to-mdast: The Key Transform](#5-hast-util-to-mdast-the-key-transform)
+6. [mdast-util-to-markdown: Serialization to Markdown](#6-mdast-util-to-markdown-serialization-to-markdown)
+7. [remark/rehype Ecosystem](#7-remarkrehype-ecosystem)
+8. [unist-util-visit and Related Utilities](#8-unist-util-visit-and-related-utilities)
+9. [TypeScript Type Definitions](#9-typescript-type-definitions)
+10. [Pipeline Feasibility Assessment](#10-pipeline-feasibility-assessment)
+11. [Alternative Approaches](#11-alternative-approaches)
+12. [Recommended Architecture](#12-recommended-architecture)
+13. [Appendix: Element-to-Markdown Mapping Table](#13-appendix-element-to-markdown-mapping-table)
+
+---
+
+## 1. Executive Summary
+
+The JSX → hast → mdast → markdown pipeline is **feasible and well-supported** by mature, well-typed libraries in the unist/syntax-tree ecosystem. The core transformation chain is:
+
+```
+JSX Component Tree → hast (HTML AST) → mdast (Markdown AST) → markdown string
+ │ │ │ │
+ React rendering hast-util-from-html hast-util-to-mdast mdast-util-to-markdown
+ or react-dom/ or manual hast (v10.1.2) (v2.1.2)
+ server rendering construction
+```
+
+**Key finding**: The hardest step is not hast→mdast→markdown (which is solved by existing, mature libraries), but rather **JSX → hast** and handling **custom components** that have no direct HTML/markdown equivalent. The ecosystem provides excellent tooling for standard HTML elements but requires a custom strategy for framework-specific components.
+
+**Verdict**: Use the existing unist ecosystem libraries for the hast→mdast→markdown steps. Build a custom JSX→hast adapter layer that handles React component rendering and custom element mapping.
+
+---
+
+## 2. unist: The Universal Foundation
+
+**Repository**: https://github.com/syntax-tree/unist
+**Current version**: 3.0.0
+**License**: CC-BY-4.0
+
+unist is the abstract base specification that hast, mdast, xast, and nlcst all implement. It defines the minimal node interface that all syntax tree nodes share.
+
+### Core Node Interface
+
+```typescript
+interface Node {
+ type: string // Non-empty string identifying the node variant
+ data?: Data // Ecosystem-specific metadata
+ position?: Position // Source location info
+}
+
+interface Parent <: Node {
+ children: [Node] // Child nodes
+}
+
+interface Literal <: Node {
+ value: any // Node's value
+}
+
+interface Position {
+ start: Point
+ end: Point
+}
+
+interface Point {
+ line: number // 1-indexed
+ column: number // 1-indexed
+ offset?: number // 0-indexed
+}
+```
+
+### Design Principles
+
+- All values must be JSON-serializable (no functions, undefined, symbols)
+- Trees can survive `JSON.parse(JSON.stringify(tree))` roundtrips
+- `data` field is reserved for ecosystem use; specifications never define fields on it
+- `position` must be absent on generated nodes
+
+### Why This Matters for Our Pipeline
+
+The JSON-serializability constraint means the AST is inherently portable and can be passed between contexts (server/client, different frameworks). The `data` field provides an escape hatch for custom metadata that custom component handlers can use.
+
+---
+
+## 3. hast: Hypertext Abstract Syntax Tree
+
+**Repository**: https://github.com/syntax-tree/hast
+**Spec version**: 2.4.0
+**Type definitions**: `@types/hast`
+**Stars**: 892
+
+hast represents HTML (and embedded SVG/MathML) as an abstract syntax tree. It extends unist.
+
+### Node Types
+
+| Node Type | Extends | Description | Key Fields |
+|-----------|---------|-------------|------------|
+| **`Root`** | Parent | Document root | `children` |
+| **`Element`** | Parent | HTML element | `tagName`, `properties`, `children`, `content?` |
+| **`Text`** | Literal | Text content | `value` |
+| **`Comment`** | Literal | HTML comment | `value` |
+| **`Doctype`** | Node | Document type declaration | (none beyond unist Node) |
+
+### Element Interface (the workhorse)
+
+```typescript
+interface Element <: Parent {
+ type: 'element'
+ tagName: string // e.g., 'div', 'span', 'custom-card'
+ properties: Properties // HTML attributes mapped to DOM properties
+ content?: Root // Only for <template> elements
+ children: [Comment | Element | Text]
+}
+```
+
+### Properties System
+
+hast uses DOM-style property names, not HTML attribute names:
+
+| HTML Attribute | hast Property |
+|----------------|---------------|
+| `class` | `className` (array: `['foo', 'bar']`) |
+| `for` | `htmlFor` |
+| `data-*` | `data*` (camelCase) |
+| `aria-*` | `aria*` (camelCase) |
+| `tabindex` | `tabIndex` |
+| `colspan` | `colSpan` |
+
+Property values:
+- Boolean attributes: `true`/`false`
+- Numeric attributes: `number`
+- Space-separated: `string[]` (e.g., `className: ['foo', 'bar']`)
+- All other: `string`
+
+### Example: hast tree for HTML
+
+HTML:
+```html
+<a href="https://alpha.com" class="bravo" download>Link</a>
+```
+
+hast:
+```json
+{
+ "type": "element",
+ "tagName": "a",
+ "properties": {
+ "href": "https://alpha.com",
+ "className": ["bravo"],
+ "download": true
+ },
+ "children": [{"type": "text", "value": "Link"}]
+}
+```
+
+### Key Utilities for hast Construction
+
+- **`hastscript`** (v9.0.1) — `h()` function to create hast trees, like React's `createElement`. Supports JSX via automatic runtime (`@jsxImportSource hastscript`).
+- **`hast-util-from-html`** — Parse HTML string to hast
+- **`hast-util-from-dom`** — Convert browser DOM nodes to hast
+- **`hast-util-to-html`** — Serialize hast to HTML string
+- **`hast-util-to-jsx-runtime`** (v2.3.6) — Convert hast to React/Preact/Solid/Svelte/Vue (the *reverse* direction of what we need)
+- **`hast-util-select`** — CSS selector queries on hast trees (`querySelector`, etc.)
+
+### hastscript JSX Support
+
+This is significant: hastscript supports using JSX syntax to directly create hast trees:
+
+```jsx
+/** @jsxImportSource hastscript */
+const tree = (
+ <div class="foo" id="some-id">
+ <span>some text</span>
+ <input type="text" value="foo" />
+ </div>
+)
+```
+
+This produces a **hast tree**, not a React element. This is a potential alternative entry point for our pipeline.
+
+---
+
+## 4. mdast: Markdown Abstract Syntax Tree
+
+**Repository**: https://github.com/syntax-tree/mdast
+**Spec version**: 5.0.0
+**Type definitions**: `@types/mdast`
+**Stars**: 1.4k
+
+mdast represents markdown as an abstract syntax tree. It extends unist.
+
+### Core Node Types (CommonMark)
+
+| Node Type | Category | Description | Key Fields |
+|-----------|----------|-------------|------------|
+| **`Root`** | — | Document root | `children` |
+| **`Paragraph`** | Content | Text paragraph | `children: [PhrasingContent]` |
+| **`Heading`** | Flow | Section heading | `depth: 1-6`, `children: [PhrasingContent]` |
+| **`Blockquote`** | Flow | Quoted section | `children: [FlowContent]` |
+| **`List`** | Flow | Ordered/unordered list | `ordered`, `start`, `spread`, `children: [ListItem]` |
+| **`ListItem`** | ListContent | List item | `spread`, `checked?`, `children: [FlowContent]` |
+| **`Code`** | Flow | Fenced/indented code block | `value`, `lang?`, `meta?` |
+| **`ThematicBreak`** | Flow | Horizontal rule `---` | (none) |
+| **`Html`** | Flow/Phrasing | Raw HTML in markdown | `value` |
+| **`Definition`** | Content | Link/image reference def | `identifier`, `label`, `url`, `title` |
+| **`Text`** | Phrasing | Plain text | `value` |
+| **`Emphasis`** | Phrasing | Italic `*text*` | `children: [PhrasingContent]` |
+| **`Strong`** | Phrasing | Bold `**text**` | `children: [PhrasingContent]` |
+| **`InlineCode`** | Phrasing | Inline code `` `code` `` | `value` |
+| **`Break`** | Phrasing | Hard line break | (none) |
+| **`Link`** | Phrasing | Hyperlink | `url`, `title?`, `children: [PhrasingContent]` |
+| **`LinkReference`** | Phrasing | Link by reference | `identifier`, `label`, `referenceType` |
+| **`Image`** | Phrasing | Image | `url`, `title?`, `alt?` |
+| **`ImageReference`** | Phrasing | Image by reference | `identifier`, `label`, `referenceType`, `alt?` |
+
+### GFM Extension Nodes
+
+| Node Type | Description | Key Fields |
+|-----------|-------------|------------|
+| **`Delete`** | Strikethrough `~~text~~` | `children: [PhrasingContent]` |
+| **`Table`** | Table | `align?: [alignType]`, `children: [TableRow]` |
+| **`TableRow`** | Table row | `children: [TableCell]` |
+| **`TableCell`** | Table cell | `children: [PhrasingContent]` |
+| **`FootnoteDefinition`** | Footnote def | `identifier`, `label`, `children: [FlowContent]` |
+| **`FootnoteReference`** | Footnote ref | `identifier`, `label` |
+
+### Content Model Hierarchy
+
+```
+MdastContent = FlowContent | ListContent | PhrasingContent
+
+FlowContent = Blockquote | Code | Heading | Html | List | ThematicBreak | Paragraph
+ListContent = ListItem
+PhrasingContent = Break | Emphasis | Html | Image | ImageReference | InlineCode
+ | Link | LinkReference | Strong | Text
+ + GFM: Delete | FootnoteReference
+```
+
+This hierarchy is critical: hast-util-to-mdast must map HTML's content model (which doesn't have this distinction) into mdast's strict flow/phrasing content model.
+
+### Mixin Types
+
+```typescript
+interface Resource {
+ url: string
+ title?: string
+}
+
+interface Alternative {
+ alt?: string
+}
+
+interface Association {
+ identifier: string
+ label?: string
+}
+
+interface Reference {
+ referenceType: 'shortcut' | 'collapsed' | 'full'
+}
+```
+
+---
+
+## 5. hast-util-to-mdast: The Key Transform
+
+**Repository**: https://github.com/syntax-tree/hast-util-to-mdast
+**Current version**: 10.1.2
+**License**: MIT
+**Stars**: 43
+
+This is the critical library in the pipeline — it converts hast (HTML AST) into mdast (Markdown AST).
+
+### API
+
+```typescript
+import { toMdast } from 'hast-util-to-mdast'
+
+const mdastTree = toMdast(hastTree, options?)
+```
+
+### Options
+
+```typescript
+interface Options {
+ newlines?: boolean // Keep line endings when collapsing whitespace (default: false)
+ checked?: string // Value for checked checkbox (default: '[x]')
+ unchecked?: string // Value for unchecked checkbox (default: '[ ]')
+ quotes?: string[] // Quote characters for <q> nesting (default: ['"'])
+ document?: boolean // Whether tree is a complete document (default: auto-detect)
+ handlers?: Record<string, Handle> // Custom element handlers
+ nodeHandlers?: Record<string, NodeHandle> // Custom node type handlers
+}
+```
+
+### Custom Handlers
+
+This is the **extensibility mechanism** most relevant to our use case:
+
+```typescript
+type Handle = (
+ state: State,
+ element: Element,
+ parent: HastParent
+) => Array<MdastNode> | MdastNode | undefined
+
+type NodeHandle = (
+ state: State,
+ node: any,
+ parent: HastParent
+) => Array<MdastNode> | MdastNode | undefined
+```
+
+The `handlers` option maps HTML tag names to custom conversion functions. Custom handlers are **merged** into the defaults, so you can override specific tags without reimplementing everything.
+
+The `nodeHandlers` option maps hast node types (like `'text'`, `'comment'`) to custom handlers.
+
+### State Object
+
+Passed to all handlers:
+
+```typescript
+interface State {
+ patch: (from: HastNode, to: MdastNode) => undefined // Copy positional info
+ one: (node: HastNode, parent?: HastParent) => MdastNode // Transform single node
+ all: (parent: HastParent) => Array<MdastContent> // Transform children
+ toFlow: (nodes: Array<MdastContent>) => Array<MdastFlowContent> // Promote to flow content
+ resolve: (url: string | null | undefined) => string // Resolve URLs
+ options: Options
+ elementById: Map<string, Element>
+ handlers: Record<string, Handle>
+ nodeHandlers: Record<string, NodeHandle>
+ inTable: boolean // Whether we're inside a table
+ qNesting: number // <q> nesting depth
+}
+```
+
+### How It Handles Different Element Categories
+
+#### Inline Elements (Phrasing Content)
+
+| HTML Element | mdast Node | Notes |
+|-------------|------------|-------|
+| `<strong>`, `<b>` | `strong` | Children processed recursively |
+| `<em>`, `<i>` | `emphasis` | Children processed recursively |
+| `<code>` | `inlineCode` | Value extracted from text child |
+| `<a href="...">` | `link` | `url` from `href`, `title` from `title` attr |
+| `<br>` | `break` | Hard line break |
+| `<del>`, `<s>`, `<strike>` | `delete` (GFM) | Strikethrough |
+| `<q>` | `text` with quotes | Uses `quotes` option for nesting |
+| `<img>` | `image` | `url` from `src`, `alt` from `alt` attr |
+| `<sub>`, `<sup>`, `<mark>`, etc. | Text content only | Non-semantic in markdown; children extracted |
+| `<input type="checkbox">` | `text` | Uses `checked`/`unchecked` options |
+
+#### Block Elements (Flow Content)
+
+| HTML Element | mdast Node | Notes |
+|-------------|------------|-------|
+| `<h1>`–`<h6>` | `heading` (depth 1-6) | |
+| `<p>` | `paragraph` | |
+| `<blockquote>` | `blockquote` | |
+| `<ul>` | `list` (ordered: false) | |
+| `<ol>` | `list` (ordered: true, start) | |
+| `<li>` | `listItem` | GFM: `checked` for task lists |
+| `<pre><code>` | `code` | `lang` from class (`language-js`), `meta` from data attributes |
+| `<table>` | `table` (GFM) | With `align` from `align` attribute |
+| `<tr>` | `tableRow` | |
+| `<td>`/`<th>` | `tableCell` | |
+| `<hr>` | `thematicBreak` | |
+| `<dl>`, `<dt>`, `<dd>` | Paragraphs | No markdown equivalent; downgraded |
+
+#### Special Behaviors
+
+- **`<template>`**: Content is processed from the `content` field
+- **`<noscript>`**: Children processed as if scripting is disabled
+- **`<svg>`**, **`<math>`**: **Ignored** by default (no markdown equivalent)
+- **`<video>`**, **`<audio>`**, **`<iframe>`**: Converted to **links** to the source
+- **`<form>`** elements: Processed for their text content
+- **Implicit paragraphs**: The algorithm correctly handles HTML's implicit paragraph model (e.g., text + heading inside a container gets proper paragraph wrapping)
+
+#### `data-mdast` Attribute
+
+Elements with `data-mdast="ignore"` are excluded from output:
+
+```html
+<p><strong>Important</strong> and <em data-mdast="ignore">ignored</em>.</p>
+```
+→ `**Important** and .`
+
+### Algorithm
+
+The algorithm is described as "very powerful" and handles all HTML elements including ancient and obscure ones. It is particularly good at:
+
+1. **Implicit/explicit paragraph handling**: Correctly wraps loose text in paragraphs when adjacent to block elements
+2. **Whitespace collapsing**: Collapses inter-element whitespace to single spaces (configurable with `newlines`)
+3. **Content model enforcement**: Ensures phrasing content doesn't end up in flow contexts (auto-wraps in paragraphs)
+4. **GFM output**: Tables produce GFM `table` nodes; `<del>`/`<s>`/`<strike>` produce `delete` nodes
+
+### Custom Handler Example: Preserving SVG as Raw HTML
+
+```typescript
+import { toHtml } from 'hast-util-to-html'
+
+const mdast = toMdast(hast, {
+ handlers: {
+ svg(state, node) {
+ const result = { type: 'html', value: toHtml(node, { space: 'svg' }) }
+ state.patch(node, result)
+ return result
+ }
+ }
+})
+```
+
+This pattern — converting an unhandled element to an mdast `html` node — is the standard escape hatch for elements that don't map cleanly to markdown.
+
+---
+
+## 6. mdast-util-to-markdown: Serialization to Markdown
+
+**Repository**: https://github.com/syntax-tree/mdast-util-to-markdown
+**Current version**: 2.1.2
+**License**: MIT
+**Stars**: 139
+
+This library serializes an mdast tree back to a markdown string.
+
+### API
+
+```typescript
+import { toMarkdown } from 'mdast-util-to-markdown'
+
+const markdown = toMarkdown(mdastTree, options?)
+```
+
+### Key Options
+
+```typescript
+interface Options {
+ // List formatting
+ bullet?: '*' | '+' | '-' // Unordered list marker (default: '*')
+ bulletOther?: '*' | '+' | '-' // Fallback list marker (default: '-')
+ bulletOrdered?: '.' | ')' // Ordered list marker (default: '.')
+ listItemIndent?: 'mixed' | 'one' | 'tab' // List item indentation (default: 'one')
+ incrementListMarker?: boolean // Increment ordered list numbers (default: true)
+
+ // Heading formatting
+ closeAtx?: boolean // Close ATX headings with trailing #s (default: false)
+ setext?: boolean // Use setext headings when possible (default: false)
+
+ // Emphasis/strong markers
+ emphasis?: '*' | '_' // Emphasis marker (default: '*')
+ strong?: '*' | '_' // Strong marker (default: '*')
+
+ // Code blocks
+ fence?: '`' | '~' // Fenced code marker (default: '`')
+ fences?: boolean // Always use fenced code (default: true)
+
+ // Links
+ resourceLink?: boolean // Always use resource links (default: false)
+ quote?: '"' | "'" // Title quote character (default: '"')
+
+ // Thematic breaks
+ rule?: '*' | '-' | '_' // Thematic break marker (default: '*')
+ ruleRepetition?: number // Number of markers (default: 3, min: 3)
+ ruleSpaces?: boolean // Spaces between markers (default: false)
+
+ // Definitions
+ tightDefinitions?: boolean // No blank lines between definitions (default: false)
+
+ // Extensibility
+ handlers?: Handlers // Custom node type handlers
+ join?: Array<Join> // Custom block-joining behavior
+ unsafe?: Array<Unsafe> // Characters that need escaping in contexts
+ extensions?: Array<Options> // Extension options (e.g., GFM)
+}
+```
+
+### GFM Support
+
+GFM output is achieved by using the `mdast-util-gfm` extension:
+
+```typescript
+import { toMarkdown } from 'mdast-util-to-markdown'
+import { gfmToMarkdown } from 'mdast-util-gfm'
+
+const markdown = toMarkdown(tree, {
+ extensions: [gfmToMarkdown()]
+})
+```
+
+This adds support for:
+- Tables (`| col1 | col2 |`)
+- Strikethrough (`~~text~~`)
+- Task lists (`- [x] item`)
+- Autolink literals
+- Footnotes
+
+### Safety / Escaping
+
+The library carefully escapes characters that would be interpreted as markdown syntax:
+
+```typescript
+// Character that would break markdown is properly escaped:
+Input mdast: { type: 'text', value: '- a\nb !' }
+Output: \- a\nb \!
+```
+
+This is handled via the `Unsafe` type system, which specifies which characters are dangerous in which constructs.
+
+### Custom Handlers
+
+```typescript
+type Handle = (node, parent, state, info) => string
+
+type Handlers = Record<Node['type'], Handle>
+```
+
+Custom handlers can be provided for any node type, including custom/extension node types.
+
+---
+
+## 7. remark/rehype Ecosystem
+
+### Architecture
+
+```
+unified (core processor)
+ ├── remark (markdown) ─── mdast ─── remarkParse / remarkStringify
+ ├── rehype (HTML) ────── hast ───── rehypeParse / rehypeStringify
+ └── retext (NLP) ────── nlcst ───── retextEnglish / retextContent
+```
+
+### Cross-Ecosystem Plugins
+
+| Plugin | Direction | Description |
+|--------|-----------|-------------|
+| `remark-rehype` | mdast → hast | Markdown to HTML (the common direction) |
+| `rehype-remark` | hast → mdast | HTML to Markdown (our direction!) |
+| `remark-retext` | mdast → nlcst | Markdown to NLP |
+| `rehype-retext` | hast → nlcst | HTML to NLP |
+
+### rehype-remark (v10.0.1)
+
+**Repository**: https://github.com/rehypejs/rehype-remark
+**Stars**: 99
+
+This is the higher-level wrapper around `hast-util-to-mdast`. It operates as a unified plugin:
+
+```typescript
+import { unified } from 'unified'
+import rehypeParse from 'rehype-parse'
+import rehypeRemark from 'rehype-remark'
+import remarkStringify from 'remark-stringify'
+
+const file = await unified()
+ .use(rehypeParse) // HTML → hast
+ .use(rehypeRemark) // hast → mdast (uses hast-util-to-mdast internally)
+ .use(remarkStringify) // mdast → markdown (uses mdast-util-to-markdown internally)
+ .process(htmlString)
+
+console.log(String(file))
+```
+
+**Recommendation**: For our JSX→markdown pipeline, we should use the lower-level utilities (`hast-util-to-mdast` + `mdast-util-to-markdown`) directly rather than the unified processor chain. This avoids the overhead of the unified pipeline and gives us more control.
+
+However, `rehype-remark` plus remark plugins could be useful if we want to add post-processing transformations (e.g., `remark-gfm` for explicit GFM support).
+
+### Available remark Plugins (for post-processing)
+
+- `remark-gfm` — GFM syntax support
+- `remark-frontmatter` — YAML/TOML frontmatter
+- `remark-mdx` — MDX syntax support
+- `remark-lint` — Markdown linting
+- `remark-toc` — Table of contents generation
+- `remark-comment-config` — Configure remark from HTML comments
+- 150+ total plugins
+
+---
+
+## 8. unist-util-visit and Related Utilities
+
+**Repository**: https://github.com/syntax-tree/unist-util-visit
+**Current version**: 5.1.0
+**License**: MIT
+
+### Core Traversal: unist-util-visit
+
+```typescript
+import { visit, CONTINUE, EXIT, SKIP } from 'unist-util-visit'
+
+visit(tree, 'heading', (node, index, parent) => {
+ // Return CONTINUE (default), EXIT, SKIP, or a new index
+ if (node.depth === 1) return EXIT
+ if (node.depth === 2) return SKIP // Don't visit children
+ return [SKIP, 5] // Skip children, continue from index 5
+})
+```
+
+### Complete Utility Landscape
+
+| Utility | Purpose | Stars |
+|---------|---------|-------|
+| `unist-util-visit` | Walk tree depth-first | 346 |
+| `unist-util-visit-parents` | Walk with parent stack | — |
+| `unist-util-is` | Check if node matches test | — |
+| `unist-util-filter` | Create filtered tree | — |
+| `unist-util-map` | Create mapped tree | — |
+| `unist-util-remove` | Remove nodes from tree | — |
+| `unist-util-select` | CSS-like selectors on trees | — |
+| `unist-util-find-after` | Find node after another | — |
+| `unist-util-find-and-replace` | Find/replace text in tree | — |
+| `unist-builder` | Create trees programmatically | — |
+
+### hast-specific Utilities
+
+| Utility | Purpose |
+|---------|---------|
+| `hast-util-is-element` | Check if node is (a specific) element |
+| `hast-util-select` | querySelector/querySelectorAll on hast |
+| `hast-util-find-and-replace` | Text find/replace in hast |
+| `hast-util-classnames` | Merge class names |
+| `hast-util-to-string` | Get textContent |
+| `hast-util-to-text` | Get innerText |
+| `hast-util-phrasing` | Check if node is phrasing content |
+| `hast-util-heading` | Check if node is heading content |
+| `hast-util-embedded` | Check if node is embedded content |
+| `hast-util-sanitize` | Sanitize tree (XSS prevention) |
+
+### mdast-specific Utilities
+
+| Utility | Purpose |
+|---------|---------|
+| `mdast-util-to-string` | Get plain text content |
+| `mdast-util-definitions` | Find definition nodes |
+| `mdast-util-heading-range` | Use headings as ranges |
+| `mdast-util-toc` | Generate TOC |
+| `mdast-util-phrasing` | Check if node is phrasing content |
+| `mdast-util-gfm` | GFM parse/serialize |
+| `mdast-util-gfm-table` | GFM tables specifically |
+| `mdast-util-directive` | Generic directives |
+
+---
+
+## 9. TypeScript Type Definitions
+
+### Availability
+
+| Package | Types | Source |
+|---------|-------|--------|
+| `@types/unist` | Built-in | DefinitelyTyped |
+| `@types/hast` | Built-in | DefinitelyTyped |
+| `@types/mdast` | Built-in | DefinitelyTyped |
+| `hast-util-to-mdast` | **Shipped with package** | Included TypeScript types + `index.d.ts` |
+| `mdast-util-to-markdown` | **Shipped with package** | Included TypeScript types + `index.d.ts` |
+| `unist-util-visit` | **Shipped with package** | Included TypeScript types + `index.d.ts` |
+| `hastscript` | **Shipped with package** | Included TypeScript types |
+| `hast-util-to-jsx-runtime` | **Shipped with package** | Included TypeScript types |
+| `rehype-remark` | **Shipped with package** | Included TypeScript types |
+| `unified` | **Shipped with package** | Included TypeScript types |
+
+### Type Quality
+
+**Excellent**. All packages in the syntax-tree and unified ecosystems are written in TypeScript or ship hand-written `.d.ts` files. The type definitions are comprehensive and well-maintained. Key observations:
+
+1. **Hast types are well-defined**: `Element`, `Text`, `Comment`, `Root`, `Properties`, `PropertyValue` are all properly typed
+2. **Mdast types are well-defined**: All node types with their specific fields, plus content model types like `FlowContent`, `PhrasingContent`
+3. **Handler types are exported**: `Handle`, `NodeHandle`, `Options`, `State` from hast-util-to-mdast
+4. **Serializer types are exported**: `Handle`, `Handlers`, `Options`, `Unsafe`, `Join` from mdast-util-to-markdown
+5. **Generic node types**: The TypeScript types support discriminated unions on `node.type`
+
+### Type Usage Example
+
+```typescript
+import type { Element, Root, Text } from 'hast'
+import type { Root as MdastRoot, Heading, Code } from 'mdast'
+import type { Handle, Options as ToMdastOptions } from 'hast-util-to-mdast'
+import type { Options as ToMarkdownOptions } from 'mdast-util-to-markdown'
+```
+
+---
+
+## 10. Pipeline Feasibility Assessment
+
+### The Full Pipeline
+
+```
+┌─────────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
+│ JSX Components │ ──▶ │ hast │ ──▶ │ mdast │ ──▶ │ markdown │
+│ (React tree) │ │ (HTML AST)│ │ (MD AST) │ │ (string) │
+└─────────────────┘ └──────────┘ └──────────┘ └──────────┘
+ │ │ │ │
+ STEP 1: STEP 2: STEP 3: STEP 4:
+ JSX → hast hast → mdast mdast → md md string
+ (the solved (well-solved)
+ problem)
+```
+
+### Step-by-Step Assessment
+
+#### Step 1: JSX → hast (THE HARDEST STEP)
+
+**Challenge**: React components are not HTML. They have:
+- Custom component elements (`<Card>`, `<UserAvatar>`) that don't map to HTML tags
+- Props that aren't HTML attributes
+- Rendering logic (conditionals, loops, state)
+- Event handlers that are meaningless in markdown
+
+**Approaches**:
+
+**Approach A: Render to HTML string, then parse to hast**
+```typescript
+import { renderToStaticMarkup } from 'react-dom/server'
+import { fromHtml } from 'hast-util-from-html'
+
+const html = renderToStaticMarkup(<MyComponent />)
+const hast = fromHtml(html, { fragment: true })
+```
+- Pros: Complete rendering support, handles all React features
+- Cons: Loss of custom element information, all components flatten to HTML
+
+**Approach B: Use React's internal fiber tree to build hast directly**
+- Pros: More control, can preserve custom element boundaries
+- Cons: Relies on React internals, fragile
+
+**Approach C: Use hastscript JSX runtime**
+```jsx
+/** @jsxImportSource hastscript */
+const tree = <div class="card"><h2>Title</h2><p>Body</p></div>
+```
+- Pros: Direct hast construction, type-safe
+- Cons: Can't use React components (no rendering), only raw elements
+
+**Recommendation**: **Approach A** for the base pipeline, with **custom component registry** for handling non-HTML elements (see below).
+
+#### Step 2: hast → mdast (SOLVED by hast-util-to-mdast)
+
+- This step is fully solved by `hast-util-to-mdast` v10.1.2
+- Handles all standard HTML elements
+- Custom handlers for non-standard elements
+- Proper paragraph wrapping, whitespace handling, content model enforcement
+- GFM support (tables, strikethrough, task lists)
+
+**Edge cases to watch**:
+- Nested inline elements: `<strong><em>bold italic</em></strong>` → `***bold italic***`
+- Mixed content: `<div>Text <h2>Heading</h2> More text</div>` → Proper paragraph wrapping
+- Deeply nested lists
+- Tables with merged cells (not supported in GFM)
+- `<br>` inside `<p>`: Produces `break` nodes in phrasing content
+
+#### Step 3: mdast → markdown (SOLVED by mdast-util-to-markdown)
+
+- Fully solved by `mdast-util-to-markdown` v2.1.2
+- Proper character escaping
+- GFM output with `mdast-util-gfm` extension
+- Configurable markers, indentation, heading styles
+
+### Edge Cases and Failure Modes
+
+#### Custom Components (The #1 Challenge)
+
+A React component like `<DataField label="Name" value="Alice" />` renders to HTML like `<div class="data-field"><span class="label">Name</span><span class="value">Alice</span></div>`. But the markdown output would just be "Name Alice" without the structure.
+
+**Solution**: Register custom handlers that use the component's semantic intent:
+
+```typescript
+// Option 1: Use CSS class-based detection
+handlers: {
+ // Custom class→markdown mapping
+ 'data-field': (state, node) => {
+ if (node.properties.className?.includes('data-field')) {
+ const label = findTextByClass(node, 'label')
+ const value = findTextByClass(node, 'value')
+ return { type: 'paragraph', children: [
+ { type: 'strong', children: [{ type: 'text', value: label }] },
+ { type: 'text', value: `: ${value}` }
+ ]}
+ }
+ }
+}
+```
+
+```typescript
+// Option 2: Use data attributes for semantic hints
+// Render with: <div data-md-type="field" data-md-label="Name">Alice</div>
+handlers: {
+ div: (state, node) => {
+ const mdType = node.properties.dataMdType
+ if (mdType === 'field') {
+ // Custom conversion
+ }
+ return defaultHandlers.div(state, node, parent)
+ }
+}
+```
+
+```typescript
+// Option 3: Pre-transform the hast tree before passing to toMdast
+// Walk the hast tree, replace custom structures with semantic mdast nodes
+visit(hast, 'element', (node) => {
+ if (node.properties.className?.includes('callout')) {
+ // Transform the element's structure to something that maps cleanly
+ }
+})
+```
+
+#### SVG/Math Content
+
+- **Default behavior**: Ignored (content lost)
+- **Workaround 1**: Convert to mdast `html` node (preserves as raw HTML in markdown)
+- **Workaround 2**: Render to an image and use mdast `image` node
+- **For LLM consumption**: Image alt text is likely more useful than raw SVG markup
+
+#### Forms and Interactive Elements
+
+- `<input>`, `<select>`, `<textarea>`: Processed for their text content
+- Checkboxes become `[x]`/`[ ]` in GFM task lists
+- Other form elements: Downgraded to text content
+
+#### CSS-Dependent Layout
+
+- Tables rendered via CSS grid/flexbox (not `<table>` elements) won't produce GFM tables
+- Tab components rendered as `<div>` stacks won't produce meaningful markdown
+- **Workaround**: Use semantic HTML (`<table>`, `<details>`, etc.) in the component's render output when markdown output is needed
+
+#### Content That Has No Markdown Equivalent
+
+| HTML Construct | Default Behavior | Better Alternative |
+|---------------|-----------------|-------------------|
+| `<details>/<summary>` | Text content only | Use mdast `html` node or custom directive |
+| `<dialog>` | Ignored | Pre-process to extract content |
+| `<meter>`, `<progress>` | Text content | Convert to descriptive text |
+| `<ruby>`, `<rt>` | Text content | Custom handler for pronunciation annotation |
+| `<iframe>` | Link to src | Custom handler for embed description |
+| `<video>`, `<audio>` | Link to src | Custom handler for media description |
+
+#### Whitespace and Formatting
+
+- Multiple spaces in HTML collapse to single spaces by default
+- `<pre>` whitespace is preserved in `code` nodes
+- `newlines: true` option preserves line breaks during whitespace collapsing
+- Indentation in `<pre>` blocks may need careful handling
+
+#### Roundtrip Fidelity
+
+Not all markdown constructs survive HTML roundtripping:
+- Reference-style links (`[text][id]`) become direct links `[text](url)`
+- Setext headings become ATX headings (configurable)
+- Tight vs. loose lists may change
+- Multiple markdown syntaxes collapse to one (e.g., both `*` and `_` for emphasis become `*`)
+
+**For LLM consumption, this is acceptable** — the goal is readable markdown, not perfect roundtripping.
+
+---
+
+## 11. Alternative Approaches
+
+### Existing Libraries: React/JSX → Markdown
+
+There is **no mature, well-maintained library** that directly converts React component trees to markdown. The approaches that exist are simpler or serve different purposes:
+
+#### 1. react-markdown + remark (the reverse direction)
+**React Markdown** renders markdown as React components. This is the **opposite** of what we need. Not relevant.
+
+#### 2. html-to-markdown (turndown)
+**Repository**: https://github.com/mixmark-io/turndown
+A widely-used HTML-to-markdown converter (not based on unist). It works on HTML strings, not ASTs.
+
+- **Pros**: Simple API, well-tested, many plugins, configurable rules
+- **Cons**: Not AST-based, no TypeScript AST types, no GFM table support out-of-box, less extensible than unist ecosystem
+- **Comparison**: `hast-util-to-mdast` is more principled (proper AST, content model enforcement, better extensibility)
+
+#### 3. react-to-markdown (hypothetical)
+No prominent library exists under this name or concept on npm. Search terms "react to markdown", "jsx to mdast", "component to markdown" yield no direct results.
+
+#### 4. mdast-util-from-adf
+Converts Atlassian Document Format to mdast. Demonstrates the pattern of converting external formats to mdast, but for a different source format.
+
+#### 5. hast-util-to-portable-text
+Converts hast to Sanity's Portable Text format. Another example of hast → alternative format, but not markdown.
+
+#### 6. Custom JSX → mdast builders
+One could build React components that directly produce mdast nodes using `mdast-builder` or manual construction:
+
+```typescript
+function MarkdownHeading({ depth, children }) {
+ return { type: 'heading', depth, children }
+}
+```
+
+- **Pros**: Direct control, no intermediate HTML
+- **Cons**: Can't reuse existing React component ecosystem, dual rendering needed
+
+#### 7. React Server Components + hast
+If using RSC, the output could be intercepted and converted to hast before HTML serialization. This is speculative and would require custom infrastructure.
+
+### Comparison Table
+
+| Approach | Maturity | Type Safety | Extensibility | Custom Components | GFM Support |
+|----------|----------|-------------|---------------|-------------------|-------------|
+| hast-util-to-mdast | **High** (v10) | Excellent | Excellent (handlers) | Needs custom layer | Built-in |
+| turndown | High | Poor | Good (rules) | Needs custom rules | Plugin |
+| Custom JSX→mdast | Low | Manual | Full control | Full control | Manual |
+| unified/rehype-remark | High | Excellent | Excellent (plugins) | Needs custom layer | Via remark-gfm |
+
+**Recommended**: Use `hast-util-to-mdast` + `mdast-util-to-markdown` with custom JSX→hast adapter.
+
+---
+
+## 12. Recommended Architecture
+
+### Overview
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│ JSX → Markdown Pipeline │
+│ │
+│ ┌──────────────┐ ┌───────────────┐ ┌─────────┐ ┌───────────┐ │
+│ │ JSX Renderer │──▶│ hast Builder │──▶│ hast → │──▶│ mdast → │ │
+│ │ (React SSR) │ │ (fromHtml + │ │ mdast │ │ markdown │ │
+│ │ │ │ pre-process) │ │ │ │ (GFM) │ │
+│ └──────────────┘ └───────────────┘ └─────────┘ └───────────┘ │
+│ │ │ │ │ │
+│ ┌──────────────┐ ┌───────────────┐ │ │ │
+│ │ Component │ │ Custom │ │ │ │
+│ │ Registry │ │ Handlers │ │ │ │
+│ │ (markdown │ │ (data-md- │ │ │ │
+│ │ hints) │ │ attributes) │ │ │ │
+│ └──────────────┘ └───────────────┘ │ │ │
+│ │ │ │
+│ ┌────────┘ │ │
+│ │ │ │
+│ ┌──────────────┐ ┌──────────┘ │
+│ │ Post-process │ │ Output │
+│ │ (unist-util) │ │ (markdown string) │
+│ └──────────────┘ │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+### Implementation Design
+
+#### Phase 1: Core Pipeline
+
+```typescript
+// renderToMarkdown.ts
+
+import { renderToStaticMarkup } from 'react-dom/server'
+import { fromHtml } from 'hast-util-from-html'
+import { toMdast } from 'hast-util-to-mdast'
+import { toMarkdown } from 'mdast-util-to-markdown'
+import { gfmToMarkdown } from 'mdast-util-gfm'
+import type { Element, Root as HastRoot } from 'hast'
+import type { Handle } from 'hast-util-to-mdast'
+
+interface RenderOptions {
+ /** Custom hast → mdast handlers */
+ handlers?: Record<string, Handle>
+ /** Markdown serialization options */
+ markdownOptions?: MarkdownOptions
+ /** Whether to produce GFM output (default: true) */
+ gfm?: boolean
+ /** Pre-processing hook for the hast tree */
+ preProcess?: (hast: HastRoot) => HastRoot
+ /** Post-processing hook for the mdast tree */
+ postProcess?: (mdast: MdastRoot) => MdastRoot
+}
+
+function renderToMarkdown(element: React.ReactElement, options?: RenderOptions): string {
+ // Step 1: Render JSX to HTML
+ const html = renderToStaticMarkup(element)
+
+ // Step 2: Parse HTML to hast
+ let hast = fromHtml(html, { fragment: true })
+
+ // Step 3: Pre-process hast (optional: semantic annotation, cleanup)
+ if (options?.preProcess) {
+ hast = options.preProcess(hast)
+ }
+
+ // Step 4: Convert hast to mdast
+ const mdast = toMdast(hast, {
+ handlers: {
+ ...defaultCustomHandlers,
+ ...options?.handlers,
+ },
+ document: false,
+ })
+
+ // Step 5: Post-process mdast (optional: custom transforms)
+ if (options?.postProcess) {
+ mdast = options.postProcess(mdast)
+ }
+
+ // Step 6: Serialize mdast to markdown
+ const extensions = options?.gfm !== false ? [gfmToMarkdown()] : []
+ const markdown = toMarkdown(mdast, {
+ ...options?.markdownOptions,
+ extensions,
+ })
+
+ return markdown
+}
+```
+
+#### Phase 2: Component Registry / Semantic Annotations
+
+The key innovation is a **data attribute convention** that components use to hint markdown semantics:
+
+```tsx
+// Component renders with markdown hints
+function InfoCallout({ title, children }) {
+ return (
+ <div data-md="callout" data-md-callout-type="info">
+ <strong data-md="callout-title">{title}</strong>
+ <div data-md="callout-content">{children}</div>
+ </div>
+ )
+}
+```
+
+Handler:
+```typescript
+const calloutHandler: Handle = (state, node) => {
+ const calloutType = node.properties.dataMdCalloutType || 'note'
+ const title = findChildByDataMd(node, 'callout-title')
+ const content = findChildByDataMd(node, 'callout-content')
+
+ return {
+ type: 'blockquote',
+ children: [
+ {
+ type: 'paragraph',
+ children: [
+ { type: 'strong', children: [{ type: 'text', value: calloutType.toUpperCase() }] },
+ { type: 'text', value: ': ' },
+ ...state.all(content),
+ ]
+ }
+ ]
+ }
+}
+```
+
+Registry:
+```typescript
+const defaultCustomHandlers: Record<string, Handle> = {
+ // Map data-md attributes to handlers
+ div: (state, node, parent) => {
+ const mdType = node.properties.dataMd
+ switch (mdType) {
+ case 'callout': return calloutHandler(state, node)
+ case 'admonition': return admonitionHandler(state, node)
+ // ... extensible
+ default: return undefined // Fall through to default handler
+ }
+ }
+}
+```
+
+#### Phase 3: Advanced - Dual-Mode Components
+
+For components that need to render differently in "markdown mode" vs "visual mode":
+
+```tsx
+interface MarkdownAwareProps {
+ /** When defined, used for markdown output instead of the visual render */
+ markdownContent?: string | React.ReactNode
+}
+
+function DataTable({ data, markdownContent }: MarkdownAwareProps & DataTableProps) {
+ // Visual mode: rich table with sorting, pagination
+ // Markdown mode: simple GFM table
+ return (
+ <div className="data-table" data-md="table" data-md-raw={markdownContent}>
+ {/* ... rich visual table ... */}
+ </div>
+ )
+}
+```
+
+#### Phase 4: Pre-Render Hooks
+
+For components that need full control over their markdown output:
+
+```typescript
+interface MarkdownRenderer {
+ /** If returned, used directly as markdown instead of converting the hast */
+ toMarkdown?(): string | MdastNode
+}
+
+// In the pre-process step:
+function preProcess(hast: HastRoot): HastRoot {
+ visit(hast, 'element', (node) => {
+ // Check if this element's component provided a markdown hint
+ const markdownDirect = node.properties.dataMdRaw
+ if (markdownDirect) {
+ // Replace the element with a text node containing the markdown
+ // (this will be parsed separately or stored as raw markdown)
+ }
+ })
+ return hast
+}
+```
+
+### Package Dependencies
+
+```json
+{
+ "dependencies": {
+ "hast-util-from-html": "^2.0.0",
+ "hast-util-to-mdast": "^10.0.0",
+ "mdast-util-to-markdown": "^2.0.0",
+ "mdast-util-gfm": "^3.0.0",
+ "unist-util-visit": "^5.0.0",
+ "hast-util-select": "^6.0.0",
+ "hast-util-to-string": "^3.0.0"
+ },
+ "devDependencies": {
+ "@types/hast": "^3.0.0",
+ "@types/mdast": "^4.0.0",
+ "@types/unist": "^3.0.0",
+ "react": "^18.0.0",
+ "react-dom": "^18.0.0"
+ }
+}
+```
+
+Estimated total bundle size: ~50-80KB (tree-shaken, minified)
+
+---
+
+## 13. Appendix: Element-to-Markdown Mapping Table
+
+### Complete Mapping for Standard HTML Elements
+
+| HTML Element | mdast Output | Markdown | Notes |
+|-------------|-------------|----------|-------|
+| `<h1>` | `heading` (depth: 1) | `# ` | |
+| `<h2>` | `heading` (depth: 2) | `## ` | |
+| `<h3>` | `heading` (depth: 3) | `### ` | |
+| `<h4>` | `heading` (depth: 4) | `#### ` | |
+| `<h5>` | `heading` (depth: 5) | `##### ` | |
+| `<h6>` | `heading` (depth: 6) | `###### ` | |
+| `<p>` | `paragraph` | (blank line delimited) | |
+| `<strong>`, `<b>` | `strong` | `**text**` | |
+| `<em>`, `<i>` | `emphasis` | `*text*` | |
+| `<del>`, `<s>`, `<strike>` | `delete` (GFM) | `~~text~~` | |
+| `<code>` | `inlineCode` | `` `code` `` | |
+| `<pre><code>` | `code` | ````\ncode\n```` | `lang` from `class="language-xxx"` |
+| `<a href>` | `link` | `[text](url "title")` | |
+| `<img>` | `image` | `` | |
+| `<ul>` | `list` (ordered: false) | `- item` | |
+| `<ol>` | `list` (ordered: true) | `1. item` | `start` attribute respected |
+| `<li>` | `listItem` | (list item) | GFM: `checked` for task lists |
+| `<blockquote>` | `blockquote` | `> text` | |
+| `<hr>` | `thematicBreak` | `---` | |
+| `<table>` | `table` (GFM) | `\| col \| col \|` | |
+| `<tr>` | `tableRow` | | |
+| `<th>`, `<td>` | `tableCell` | | `align` from `align` attr |
+| `<br>` | `break` | (hard break) | Two spaces + newline or `\` |
+| `<q>` | `text` with quotes | ("quoted") | Uses `quotes` option for nesting |
+| `<input type="checkbox">` | `text` | `[x]` or `[ ]` | GFM task list item support |
+| `<abbr>` | `text` | (just text) | Title lost |
+| `<sup>` | `text` | (just text) | Superscript lost |
+| `<sub>` | `text` | (just text) | Subscript lost |
+| `<mark>` | `text` | (just text) | Highlight lost |
+| `<small>` | `text` | (just text) | Small text lost |
+| `<details>` | Children only | (content extracted) | No markdown equivalent |
+| `<summary>` | `text` | (just text) | Collapsed with details |
+| `<dl>`, `<dt>`, `<dd>` | paragraphs | (text only) | No definition list in markdown |
+| `<figure>` | Children only | (content extracted) | |
+| `<figcaption>` | paragraph/text | (text) | |
+| `<video>`, `<audio>` | `link` | `[src](url)` | Downgraded to link |
+| `<iframe>` | `link` | `[src](url)` | Downgraded to link |
+| `<svg>` | (ignored) | (nothing) | Use custom handler to preserve |
+| `<math>` | (ignored) | (nothing) | Use custom handler for LaTeX output |
+| `<script>` | (ignored) | (nothing) | |
+| `<style>` | (ignored) | (nothing) | |
+| `<div>`, `<section>`, `<article>` | Children extracted | (children only) | Container elements unwrapped |
+| `<span>`, `<time>` | Children extracted | (children only) | Inline containers unwrapped |
+
+---
+
+## Summary of Key Findings
+
+1. **The hast→mdast→markdown chain is production-ready**: `hast-util-to-mdast` (v10.1.2) and `mdast-util-to-markdown` (v2.1.2) are mature, well-tested, well-typed libraries that handle the full HTML spec and produce clean GFM markdown.
+
+2. **The gap is JSX→hast**: There is no off-the-shelf solution for converting React component trees directly to hast. The recommended approach is React server-side rendering (to HTML) followed by `hast-util-from-html` parsing.
+
+3. **Custom components need a strategy**: Standard HTML elements map well, but custom React components lose their semantics through HTML rendering. A `data-md` attribute convention + custom handler registry is the recommended solution.
+
+4. **TypeScript support is excellent**: All packages in the ecosystem ship with proper TypeScript types. The discriminated union on `node.type` makes pattern matching clean and type-safe.
+
+5. **GFM is fully supported**: Tables, strikethrough, task lists, and autolink literals are all handled.
+
+6. **The unist utility ecosystem is rich**: `unist-util-visit`, `hast-util-select`, and dozens of other utilities provide all the building blocks needed for pre/post-processing.
+
+7. **For LLM consumption specifically**: The markdown output quality from this pipeline is already excellent for standard HTML. The main investment should go into the component annotation system and custom handlers for domain-specific components.
+
+---
+
+*Research completed 2026-04-28. All version numbers and repository states reflect the latest available at time of research.*