import research docs from prior conversation and scattered sources

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`.