stabilize architecture docs: address review findings and advance to stable

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)
This commit is contained in:
2026-05-18 16:10:24 +00:00
parent 23659233ca
commit 0d5b9d5ea8
16 changed files with 167 additions and 61 deletions

View File

@@ -1,5 +1,5 @@
---
status: draft
status: stable
last_updated: 2026-05-18
---
@@ -73,6 +73,19 @@ type UjsxEventMap = {
The event map defines the known event types and their payload shapes. Each key is an event type string; each value is the expected payload structure.
## UjsxEnvelope
```typescript
type UjsxEnvelope<TType extends keyof UjsxEventMap = keyof UjsxEventMap> = EventEnvelope<
TType,
UjsxEventMap[TType]
>;
```
A convenience type alias that parameterizes `EventEnvelope` with `UjsxEventMap`. Instead of writing `EventEnvelope<"root.render", { childCount: number }>`, consumers write `UjsxEnvelope<"root.render">`. The type parameter defaults to the full key union, so `UjsxEnvelope` alone means "an envelope for any UJSX event."
This type is exported from `src/core/events.ts` and re-exported from the barrel.
| Event | When emitted | Payload |
|-------|-------------|---------|
| `root.render` | HostConfig calls `render()` on a root | `childCount` of the rendered tree |
@@ -136,7 +149,7 @@ The event map does not include error events (e.g., `instance.error`, `render.err
### No cleanup on unmount
The current `unmount()` implementation in `HostConfig` does not tear down event subscriptions. If a pubsub emitter was wired to the host's `emit()` during render, unmount does not unsubscribe. This gap is shared with the broader reconciler disposal gap — see [lifecycle.md](lifecycle.md) and the unmount & dispose research (`docs/research/reconciler/03-unmount-dispose-support.md`).
The current `unmount()` implementation in `HostConfig` does not tear down event subscriptions. If a pubsub emitter was wired to the host's `emit()` during render, unmount does not unsubscribe. This gap is shared with the broader reconciler disposal gap — see [lifecycle.md](lifecycle.md) and the unmount & dispose research (`../research/reconciler/03-unmount-dispose-support.md`).
## Constraints