alkdev/ujsx
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add reconciler architecture docs and update existing docs with cross-references

Browse Source 
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
This commit is contained in:
glm-5.1
2026-05-18 15:15:13 +00:00
parent 09f32f0c64
commit da82b52b27
10 changed files with 631 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/architecture/element-factory.md
View File

@@ -124,7 +124,7 @@ Consumers who prefer hyperscript-style code can call `h()` directly. The JSX run
### `key` prop not extracted
`h()` currently passes **all** props through to the element, including `key` if provided. The reconciler requires `key` as a first-class field on `UElement` for identity-based children matching (see Phase 2 research in `docs/research/reconciler/02-key-based-children-reconciliation.md`).
`h()` currently passes **all** props through to the element, including `key` if provided. The reconciler requires `key` as a first-class field on `UElement` for identity-based children matching (see [reconciler.md](reconciler.md) and [ADR-004](decisions/004-key-as-first-class-field.md)).
When `key` extraction is implemented, `h()` should:
@@ -132,7 +132,7 @@ When `key` extraction is implemented, `h()` should:
2. Promote `key` to `element.key` as a top-level field.
3. Ensure component functions never receive `key` in their props.
This is documented in the schema architecture (`docs/architecture/schema.md` — Known Gaps: `key` field on `UElement`) and the reconciler key design (`docs/research/reconciler/00-KEY-FIELD-DESIGN.md`).
This is documented in the schema architecture ([schema.md](schema.md) — Known Gaps: `key` field on `UElement`) and the reconciler key field ADR ([decisions/004-key-as-first-class-field.md](decisions/004-key-as-first-class-field.md)).
### No prop validation
@@ -152,5 +152,6 @@ This is documented in the schema architecture (`docs/architecture/schema.md` —
- Source: `src/core/h.ts`
- Schema types: `src/core/schema.ts`
- Schema architecture: `docs/architecture/schema.md`
- Key field design: `docs/research/reconciler/00-KEY-FIELD-DESIGN.md`
- Key-based reconciliation: `docs/research/reconciler/02-key-based-children-reconciliation.md`
- Key field ADR: [decisions/004-key-as-first-class-field.md](decisions/004-key-as-first-class-field.md)
- Reconciler architecture: [reconciler.md](reconciler.md)
- Key-based reconciliation research: `docs/research/reconciler/02-key-based-children-reconciliation.md`