# UJSX Reconciler: Implementation Plan

## Overview

This document indexes the research and spec documents for adding a full reconciler to `@alkdev/ujsx`. The plan is ordered by dependency — each phase builds on the previous one. Phases 0 and 1 are prerequisite; Phases 2-3 can partially overlap; Phase 4 is incremental optimization; Phase 5 is a downstream consumer that validates the design.

## Phase Index

| # | Document | Description | Dependencies | Status |
|---|----------|-------------|-------------|--------|
| 0 | [00-KEY-FIELD-DESIGN.md](./00-KEY-FIELD-DESIGN.md) | Add `key?: string` as a first-class field on `UElement`. Extracted by `h()`, not passed to components. Prerequisite for all reconciliation. | None | Draft |
| 1 | [01-reactive-host-bridge.md](./01-reactive-host-bridge.md) | Connect the reactive layer (ReactiveRoot, signals) to the HostConfig reconciler. Signal-driven property updates flow through `prepareUpdate`/`commitUpdate`. Introduces fiber tree. | Phase 0 | Draft |
| 2 | [02-key-based-children-reconciliation.md](./02-key-based-children-reconciliation.md) | Key-based children matching with LIS algorithm for move detection. Handles add/remove/reorder of children. The custom reconciliation piece (~300 lines). | Phase 0, Phase 1 | Draft |
| 3 | [03-unmount-dispose-support.md](./03-unmount-dispose-support.md) | Proper disposal: `unmount()` tears down the fiber tree, removes instances, cleans up signal subscriptions. Fixes no-op `dispose` functions in reactive layer. | Phase 1, Phase 2 | Draft |
| 4 | [04-typebox-optimization-layer.md](./04-typebox-optimization-layer.md) | Layer TypeBox value primitives (`Value.Equal`, `Value.Hash`, `Value.Clone`, `Value.Mutate`, `Value.Diff`) as performance optimizations on the reconciler. Incremental, not required for correctness. | Phase 1-3 | Draft |
| 5 | [05-flowgraph-host-configs.md](./05-flowgraph-host-configs.md) | Build flowgraph-specific HostConfig implementations (graphology DAG, reactive execution engine). Validates the reconciler design by building a real consumer. | Phase 1-3 (Phase 4 optional) | Draft |

## Dependency Graph

```
Phase 0 (key field)
    │
    ▼
Phase 1 (reactive → host bridge)
    │
    ├──────────────────┐
    ▼                  ▼
Phase 2 (children    Phase 3 (unmount/dispose)
  reconciliation)       │
    │                  │
    └────────┬─────────┘
             ▼
Phase 4 (TypeBox optimizations)  ← incremental, can be layered over time
             │
             ▼
Phase 5 (flowgraph host configs) ← downstream consumer, validates design
```

## Parallelism Opportunities

After Phase 1 is complete:
- **Phase 2 and Phase 3 can run in parallel** — children reconciliation and disposal are largely independent concerns. Phase 3's partial-tree disposal (removing a child) does depend on Phase 2's reconciliation identifying which children to remove, so commit Phase 2 first if strict ordering is needed.
- **Phase 4 can start as soon as Phase 1 is complete** — `Value.Equal` bail-out is useful even without children reconciliation. But maximum benefit comes after Phase 2-3.
- **Phase 5 can start as soon as Phase 1-3 are functionally complete** — the graphology host doesn't need optimizations, but the reactive host benefits from proper disposal.

## Key Design Decisions

1. **Signals handle 90% of updates** — No tree diffing for property changes. Signal subscriptions drive `prepareUpdate`/`commitUpdate` directly.
2. **`key` is a first-class field, not a prop** — Avoids the React "key leaks into props" problem. Cleaner for schema validation (TypeBox schemas don't need to declare `key`).
3. **Fiber tree, not virtual DOM** — The reconciler maintains a parallel tree of fiber nodes that map UElement positions to host instances. Fibers track lifecycle state (props, effects, subscriptions).
4. **TypeBox value primitives are optimizations, not the foundation** — `Value.Diff` cannot serve as the tree-level reconciler (positional array diffing). But `Value.Equal`, `Value.Hash`, `Value.Clone`, `Value.Mutate` are excellent building blocks for the reconciler's internal operations.
5. **Flowgraph is a consumer, not a modification** — The workflow-specific host configs live in `@alkdev/flowgraph`, not in ujsx. Ujsx stays generic.

## Estimated Scope

| Phase | Lines of Code (approx) | New Files | Modified Files |
|-------|----------------------|-----------|----------------|
| 0 | ~30 | 0 | schema.ts, h.ts |
| 1 | ~200 | fiber.ts | config.ts, reactive.ts |
| 2 | ~300 | reconcile.ts | config.ts, h.ts |
| 3 | ~100 | 0 | config.ts, reactive.ts, fiber.ts |
| 4 | ~150 | 0 | reconcile.ts, fiber.ts |
| 5 | ~400 (in flowgraph repo) | graphology.ts, reactive.ts | N/A (separate package) |

## Reference

Prior analysis and research:
- `../signals-ujsx-reactive-pipeline.md` — Signals + UJSX reactive architecture
- `../ujsx-v2-typebox-rewrite.md` — TypeBox-driven rewrite plan, HostConfig design
- `../prior-poc-source-reference.md` — POC codebase reference, known gaps
- `../typebox-module-valuepointer.md` — TypeBox ValuePointer patterns