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.
