# 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 |

## Reconciler Implementation Plan

| Doc | Description |
|-----|-------------|
| [reconciler/README.md](./reconciler/README.md) | **Index** — Phase overview, dependency graph, parallelism opportunities, key design decisions |
| [reconciler/00-KEY-FIELD-DESIGN.md](./reconciler/00-KEY-FIELD-DESIGN.md) | Phase 0: Add `key?: string` as first-class field on `UElement` |
| [reconciler/01-reactive-host-bridge.md](./reconciler/01-reactive-host-bridge.md) | Phase 1: Connect reactive layer to HostConfig reconciler via fiber tree |
| [reconciler/02-key-based-children-reconciliation.md](./reconciler/02-key-based-children-reconciliation.md) | Phase 2: Key-based children matching with LIS algorithm for move detection |
| [reconciler/03-unmount-dispose-support.md](./reconciler/03-unmount-dispose-support.md) | Phase 3: Proper disposal — unmount, signal cleanup, instance teardown |
| [reconciler/04-typebox-optimization-layer.md](./reconciler/04-typebox-optimization-layer.md) | Phase 4: TypeBox Value primitives as incremental performance optimizations |
| [reconciler/05-flowgraph-host-configs.md](./reconciler/05-flowgraph-host-configs.md) | Phase 5: Flowgraph HostConfig implementations (graphology DAG, reactive executor) |

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