Add TypeBox Value.Equal deep-comparison as first optimization layer
in reconcileProps. When a fiber's cached node is deep-equal to the
next node, skip prepareUpdate, commitUpdate, and children
reconciliation entirely. New cachedNode field on Fiber stores the
last reconciled node for comparison.
Adds commitMutations function to reconcile.ts that processes fiber effects
in correct order: removes (reverse), inserts+moves (left-to-right with
insertBefore), updates (top-down). Integrates key-based reconciliation
pipeline into render() via reconcileNode, resolveUNode, and
createFiberForInsert.
First render still does a full mount and builds fiber tree. Subsequent
renders reconcile the new UNode tree against existing fibers: compare
props via prepareUpdate, apply changes via commitUpdate. Excess old
children remain (structural changes deferred to Phase 2). Function
components remain transparent during reconciliation.
Critical fixes:
- Restructure pointers.md: move setNode prop-key writes section under
its own heading (was incorrectly nested under selectNode)
- Add Context/Density/Direction/RenderContext documentation section
to host-config.md (was only a brief constraint bullet)
- Advance all 5 ADRs from Status: Proposed → Accepted and frontmatter
from status: draft → status: stable (decisions are driving implementation)
- Add error handling philosophy section to README
Warning/suggestion fixes:
- Add isUElement null check (node !== null) to schema.md discriminator table
- Add UjsxEnvelope convenience type documentation to events.md
- Add Direction Unicode arrow naming note to transforms.md
- Standardize all cross-references from absolute docs/research/ paths
to relative ../research/ paths across all architecture docs
- Fix schema.md ADR references to use relative paths
- Reduce redundancy between transforms.md and host-config.md Direction notes
- Update all architecture doc frontmatter from draft → stable
Deferred:
- Performance model section (reconciler not yet built)
- Concepts/glossary document (low ROI at current scale)
- Line counts in source references (would date quickly)
Fixes from architecture review (4 critical, 10 warnings):
Critical:
- Fix selectNode/setNode docs to accurately describe prop-key
navigation behavior including array support and prop-key writes
- Document RenderContext/Density exported types in host-config
- Resolve ADR dual status ambiguity with clarifying note in README
(frontmatter status = editorial, body Status = decision)
- Effect types already addressed in prior commit
Warnings addressed:
- Add Fragment re-export note to jsx-runtime section in
build-distribution
- Document childCtx/transformCtx helper functions in transforms.md
- Document render() accepting non-root UNode in host-config
- Add Value.Hash re-entrancy constraint to reconciler.md
- Add true-passthrough constraint and h('root') special case
to element-factory constraints
- Add _idCounter bundling caveat note
Review document added at docs/reviews/architecture-review-2026-05-18.md
with full findings, source verification table, and recommendations.
Phase 2: transitioning reconciler research into architecture documents.
New docs:
- reconciler.md: fiber tree, reconciliation algorithm (signal-driven
props + key-based children), update scheduling, commit order,
TypeBox optimization layer, file structure, consumer impact
- lifecycle.md: mount/update/dispose phases, fiber tree disposal,
partial tree removal, ReactiveRoot.dispose(), finalizeInstance,
idempotent disposal, computed vs effect cleanup
- ADR-004: key as first-class field on UElement (not a prop)
- ADR-005: signal-driven updates for props, reconciliation for
structure (hybrid approach, not full tree diffing)
Updated docs:
- README.md: add reconciler.md, lifecycle.md, ADRs 004/005 to
index; update reconciler roadmap with architecture doc links
- schema.md: add key?: string to UElement type with TODO comment;
update known gaps to reference ADR-004 and reconciler.md;
rephrase key constraint as temporary
- element-factory.md: update key extraction gap to reference
ADR-004 and reconciler.md
- host-config.md: reference reconciler.md and lifecycle.md
for the reconciler bridge and disposal gaps
- reactive-layer.md: reference reconciler.md and lifecycle.md
for the signal-host bridge and disposal gaps
- events.md: reference lifecycle.md for unmount/dispose gap
Phase 1 of SDD process: syncing docs/architecture/ to reflect the
existing source code. Eight component documents describe WHAT and WHY
(not HOW) for each module: schema, element factory, reactive layer,
host config, transforms, events, pointers, and build distribution.
Three ADRs capture key decisions (HTML-agnostic core, TypeBox Module
as type registry, Preact signals-core for reactivity). Each doc
documents known reconciler gaps and references the research in
docs/research/reconciler/.
Also adds docs/sdd_process.md (process reference shared across
alkdev projects) matching the taskgraph_ts pattern.
