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

Signals handle 90% of updates — No tree diffing for property changes. Signal subscriptions drive prepareUpdate/commitUpdate directly.
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).
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).
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.
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

5.1 KiB Raw Blame History