71 lines
5.1 KiB
Markdown
71 lines
5.1 KiB
Markdown
# 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 |