ujsx/docs/reviews/architecture-review-2026-05-18.md

Architecture Review: @alkdev/ujsx

Date: 2026-05-18
Reviewer: Architecture Reviewer (subagent)
Scope: All docs/architecture/ documents + source verification

Summary

The @alkdev/ujsx architecture documentation is thorough, well-structured, and internally consistent across 15 documents. The docs accurately reflect the current source code implementation in almost all respects. The core architectural story — an HTML-agnostic, signal-driven, host-configurable reactive tree system — is clearly articulated with well-documented design decisions (ADRs). The documentation honestly catalogs known gaps and open questions alongside constraints. Key issues include: an inconsistency in how selectNode handles prop navigation vs. how the docs describe it, missing documentation for childCtx/ctx helper functions in the transform system, an undocumented RenderContext type visible in public exports, and several cross-reference paths that use different conventions (relative vs. bare). No document exceeds 265 lines.

Metrics

• Critical issues: 4
• Warnings: 10
• Suggestions: 8
• Overall: needs revision before stabilization

---

Critical Issues

1. selectNode prop navigation behavior differs from docs

Location: docs/architecture/pointers.md, lines 66-68
Issue: The docs state that a non-numeric segment resolves a prop by checking typeof propVal === "object", implying that only object-typed prop values can be navigation targets. However, the source code (src/core/pointer.ts, line 41) performs the check:

if (propVal !== undefined && typeof propVal === "object" && propVal !== null)

This means Array values (which are typeof === "object") also qualify as navigation targets, but the docs only mention "object nodes" and UElement-like structures. More critically, the docs state that navigating into props.title (where title is a string) returns undefined, but the example path ["props", "title"] is misleading — the path ["props"] would try to resolve "props" as a children index or prop key, not traverse into the props object. The path resolution algorithm in the docs doesn't match how the source actually works for prop access.

Recommendation: Rewrite the path segment resolution table to accurately describe the source behavior:

• Numeric string → children[index]
• Non-numeric string → props[segment], and if the value is a non-null object (including arrays), navigate into it; otherwise return undefined
• Remove the confusing ["props", "title"] example, or clarify that "props" is a prop key lookup, not a special accessor.

2. setNode prop-key path behavior undocumented for non-array segments

Location: docs/architecture/pointers.md, lines 79-109
Issue: The docs describe setNode in terms of children array index updates, but the source code (src/core/pointer.ts, lines 51-69) also handles a branch for non-numeric path segments that sets values into the props object:

const props = { ...rootEl.props, [head as string]: value };
return { ...rootEl, props } as UElement;

This means setNode(root, ["title"], someNode) would set root.props.title = someNode, which is a significant behavior not documented at all. The docs' "Edge cases" section mentions empty paths and paths into primitives, but not prop-key navigation for writes.

Recommendation: Add a section documenting non-numeric path segment behavior in setNode, explaining that it shallow-merges a key into props, and note the constraint that value must be a valid PropValue (or UNode) for the result to remain type-safe.

3. RenderContext and Density types are exported but undocumented

Location: src/mod.ts line 12; src/core/context.ts lines 50-54
Issue: The barrel export in mod.ts re-exports Density, Direction, and RenderContext from context.ts. However, render-context.md does not exist, and neither Density nor RenderContext is documented anywhere in the architecture docs. The context.ts source file defines a RenderContext interface that extends ContextValue with a direction field, and a Density type with three string literals. The host-config doc mentions the Context class briefly (line 79), but does not document Density or RenderContext.

Recommendation: Either add documentation for RenderContext and Density in a new or existing architecture doc, or add a constraint note explaining that these are exported for downstream consumer use and are not core to UJSX's internal architecture. At minimum, document how Density is intended to be consumed by hosts.

4. ADR frontmatter status: draft contradicts ADR body Status: Proposed

Location: All ADRs (decisions/001 through decisions/005)
Issue: Each ADR file has YAML frontmatter with status: draft, which follows the document lifecycle convention defined in README.md (lines 104-118). However, each ADR also has an internal **Status**: Proposed field in its body. The README states: "ADR documents use a separate Status field in their body" and lists statuses as Proposed, Accepted, Deprecated, or Superseded. This creates two status fields that could diverge — the frontmatter says draft (a document lifecycle status) while the body says Proposed (an ADR decision status). If an implementer reads status: draft and thinks "this decision isn't finalized," they may ignore the ADR, even though ADRs document decisions that have already been made.

Recommendation: Clarify the relationship between the two status fields. Either: (a) rename one to avoid confusion (e.g., use doc_status in frontmatter), (b) add a note in the README explaining that frontmatter status is the document's editorial status while the body Status is the decision's status, or (c) unify them. This is critical because the frontmatter convention is supposed to govern whether implementation should begin, and the mismatch could cause confusion about whether these decisions are stable enough to implement against.

---

Warnings

1. Fragment JSX runtime export missing from build-distribution docs

Location: docs/architecture/build-distribution.md, lines 58-59 (sub-path exports list)
Issue: The sub-path exports table lists jsx-runtime but documents it as mapping to src/core/jsx-runtime.ts. The actual jsx-runtime.ts file re-exports Fragment in addition to jsx, jsxs, and jsxDEV. The element-factory.md documents Fragment as a factory function, but build-distribution.md doesn't mention that Fragment is available from the jsx-runtime sub-path. This could confuse consumers who expect Fragment to be importable from the JSX runtime but can't find it documented there.

Recommendation: Add a note to build-distribution.md that jsx-runtime also exports Fragment.

2. childCtx and ctx (as transformCtx) are public exports but undocumented as architecture concepts

Location: src/mod.ts line 22; src/transform/registry.ts lines 44-63
Issue: The barrel export re-exports childCtx, matchesSchema, and ctx as transformCtx from the transform module. matchesSchema is documented in transforms.md, but childCtx and ctx (exported as transformCtx) are not documented anywhere in the architecture docs. These are convenience functions for creating transform contexts and pushing ancestors. Consumers importing from @alkdev/ujsx/transform would encounter them with no architectural guidance.

Recommendation: Add documentation for childCtx and ctx/transformCtx in transforms.md, explaining their purpose as factory functions for creating TransformContext instances.

3. The render() method processes URoot children, but docs and source differ in detail

Location: docs/architecture/host-config.md, lines 96-103; src/host/config.ts, lines 97-101
Issue: The docs describe render() as calling mountNode recursively, but the actual source code does:

const payloadChildren = isURoot(node) ? (node as URoot).children : [node];
for (const child of payloadChildren) { mountNode(child, undefined); }

This means if a non-root node is passed to render(), it wraps it in an array and mounts it as a single top-level node without a URoot container. The documentation in host-config.md's "Mount Pipeline" section describes URoot nodes as transparent containers, but doesn't describe this render() behavior of accepting non-root nodes. The docs describe render(node) as "Mount the tree" without noting that non-root nodes are wrapped.

Recommendation: Document that render() accepts any UNode, and if the node is not a URoot, it mounts the node directly as a single top-level element without a root container.

4. URoot type casting in h() source differs from docs

Location: src/core/h.ts, lines 9-15; docs/architecture/element-factory.md, lines 20-28
Issue: The docs describe h() as returning UElement | URoot depending on the type argument. The source code matches this. However, the source uses as URoot cast for the root case and as UElement for the default case. The docs don't mention this casting, which is fine, but the docs also don't mention that when type === "root", the type argument of h() is widened from UType (which includes string | ComponentFn) to the "root" literal. This means h("root", ...) has special runtime behavior that bypasses the normal string-type element creation path.

Recommendation: Add a constraint or note that h("root", ...) is a special case that produces a URoot rather than a UElement, and that the string "root" is effectively a reserved type string.

5. Research cross-references use inconsistent formats

Location: Multiple docs
Issue: Cross-references to research documents use different path formats across documents:

• README.md uses ../research/reconciler/01-reactive-host-bridge.md (relative from architecture/)
• schema.md uses docs/research/reconciler/00-KEY-FIELD-DESIGN.md (project-relative)
• reactive-layer.md uses docs/research/reconciler/01-reactive-host-bridge.md (project-relative)
• build-distribution.md uses forward references without paths (just names)

Since all architecture docs live in docs/architecture/, project-relative paths like docs/research/... will not resolve correctly from the architecture directory. Only the ../research/... style works for relative links from architecture docs.

Recommendation: Standardize all research cross-references to use consistent relative paths from the architecture docs directory (e.g., ../research/reconciler/01-reactive-host-bridge.md).

6. Open questions about Value.Hash non-reentrancy are not addressed in constraints

Location: docs/architecture/reconciler.md, lines 196-199; section "Constraints"
Issue: The reconciler doc documents that Value.Hash uses a global mutable accumulator and is "not re-entrant" — you cannot call it from within a computed or effect that is itself triggered by a hash comparison. This is listed as a constraint on Value.Hash but not in the main "Constraints" section of the document. It's buried in a subsection. This is a significant constraint that could cause subtle bugs if an implementer skims the constraints section.

Recommendation: Add this to the main "Constraints" section of reconciler.md: "Value.Hash is not re-entrant — it must not be called from within a reactive computation (computed/effect)."

7. true not being filtered from children is a potential footgun not highlighted in element-factory constraints

Location: docs/architecture/element-factory.md, lines 36-37
Issue: The docs note that true is not filtered (unlike false), and state: "This is consistent with how React treats true in JSX (it renders nothing in DOM but is not stripped at the factory level)." However, this means <div>{condition}</div> where condition is true will produce a UElement with true as a UPrimitive child, which most hosts will need to handle explicitly. This is only mentioned in the child normalization section, not in the Constraints section. For a universal library, this behavior could surprise hosts that expect true to be treated like false/null.

Recommendation: Add to the Constraints section: "true passes through h() as a UPrimitive child. Hosts that handle true differently from other primitives should filter it in their createTextInstance."

8. createRoot _idCounter is shared across all callers — no module isolation documented

Location: docs/architecture/element-factory.md, lines 56-61
Issue: The docs state: "The counter is a module-level variable (let _idCounter = 0). It is: Not thread-safe — JavaScript is single-threaded, and root creation is not a concurrent operation." While this is technically correct, the more important concern is that any bundler that deduplicates the module will share the counter across all consumers. If two different packages both depend on @alkdev/ujsx, they may or may not share the counter depending on bundler behavior. This could lead to unexpected root_3 from package A conflicting with root_3 from package B.

Recommendation: Expand the constraint note to mention that bundled consumers may or may not share the counter, and that id values should be treated as unique within a single module instance only, not globally unique. Consider suggesting createRoot(uniquePrefix + counter) for disambiguation.

9. Missing performance/scalability discussion

Location: Overall — no document addresses performance characteristics
Issue: No architecture document discusses performance targets, scalability considerations, or benchmarks. The reconciler doc mentions that "90% of updates bypass tree diffing" and that fiber trees are "cheap to update," but there are no quantified performance targets (latency p50/p99, throughput, memory budget). For a library that positions itself as suitable for workflow DAGs and desktop UI rendering, the absence of performance context means implementers can't validate that the architecture meets their needs.

Recommendation: Consider adding a "Performance Model" section to one of the core docs (or the README) that outlines expected performance characteristics: tree sizes the system is designed for, update propagation latency expectations, and memory usage patterns. This doesn't need hard benchmarks yet, but should establish design targets (e.g., "designed for trees of 10-10,000 nodes" or "signal propagation should complete in <1ms for prop updates").

10. No error handling strategy documented

Location: Overall
Issue: No architecture document discusses what happens when things go wrong at the system level. The host-config doc has an open question about function component error propagation (line 206), and the transform doc notes that transform() throws if no rule matches (line 35). But there's no overarching error handling strategy: When should UJSX throw vs. emit an error event vs. silently no-op? What happens if createInstance throws? What happens if a signal computation throws?

Recommendation: Add an "Error Handling" section to the README or create a separate error-handling.md doc that establishes UJSX's error philosophy: which errors are programmer errors (throw), which are operational (emit event), and which are silently handled (no-op with logging).

---

Suggestions

1. Consider documenting the isUElement null check

Location: docs/architecture/schema.md, line 127
The type guard table documents isUElement as checking typeof === "object" && "type" in node && "props" in node && "children" in node && node.type !== "root". The source code (src/core/schema.ts line 66) adds node !== null to the check. While null would fail the "type" in node check, explicitly documenting the null guard would make the type guard specification complete and help implementers writing host-specific guards.

2. Add a naming convention note for Direction string values

Location: docs/architecture/transforms.md, lines 99-106
The Direction type uses arrow characters (ujsx→mdast) in string literals. These are defined in context.ts and also appear in RenderContext. This is unconventional and could cause issues with IDE autocomplete or linting rules that warn on non-ASCII strings. Consider documenting why Unicode arrows were chosen, or noting that the convention should be maintained consistently.

3. Document the UjsxEnvelope convenience type

Location: src/core/events.ts, lines 28-31; docs/architecture/events.md
The source exports a UjsxEnvelope type alias that parameterizes EventEnvelope with UjsxEventMap — essentially EventEnvelope<TKeyof, UjsxEventMap[TKeyof]>. This convenience type is not documented in events.md. While not critical, it's a public export that consumers will see.

4. Consider adding a "Quick Start" or "Concepts" doc for new readers

Location: Overall
The architecture docs are detailed and reference-heavy. A new reader would benefit from a single-page "Concepts" overview that introduces UNode, h(), signals, and HostConfig in 50 lines before directing to the detailed docs. The README partially serves this role but focuses on current-state/gaps rather than a conceptual introduction.

5. Consider documenting the Context class more fully

Location: docs/architecture/host-config.md (partial); src/core/context.ts
The Context class has get(), set(), subscribe(), fork(), and a signal getter, but these are only briefly mentioned in host-config.md. The class is exported from the barrel and appears in the context export. A short section explaining its reactive context model would help consumers who import it directly.

6. Standardize ADR status tracking

Location: All ADR documents
All five ADRs have Status: Proposed, but the architectural decisions they describe are already driving implementation (e.g., ADR-003's choice of Preact signals is clearly implemented). Consider advancing ADR statuses to Accepted for decisions that are already in production code. The Proposed status on implemented decisions undermines the ADR's authority.

7. Consider a centralized glossary

Location: Overall
Terms like "fiber," "host," "instance," "primitive," and "reconciler" are defined in individual docs but would benefit from a centralized glossary. For example, "instance" means different things in different contexts (host instance vs. UElement instance), and readers may miss the distinction.

8. Add line counts or complexity indicators to file references

Location: All source references
Each architecture doc references its source file (e.g., "Source: src/core/schema.ts"). Adding approximate line counts (e.g., "Source: src/core/schema.ts (~80 lines)") would help readers calibrate their expectations about implementation complexity.

---

Strengths

1. Honest gap documentation: Every document explicitly catalogs "Known Gaps," "Open Questions," and "Constraints." This is exceptional practice — implementers can immediately see what doesn't work yet and what decisions are still pending. The README's "Known gaps" section with cross-references to relevant docs and ADRs is particularly well done.

2. Decision records (ADRs): All five ADRs follow a consistent format (Context, Alternatives Considered, Decision, Consequences) and document not just what was decided but why. The alternatives sections are substantive — they explain why each rejected option was considered and why it was rejected, not just that it was.

3. Architecture-consistent language: The documents use consistent terminology throughout. A "UNode" always means UPrimitive | UElement | URoot, a "host" always refers to a HostConfig implementation, a "fiber" always means the reconciler's internal node type. This consistency makes cross-document references meaningful.

4. Clear separation of concerns: The docs clearly delineate what each layer owns. The reactive layer owns signals, the host layer owns instances, the transform layer owns conversion, and the pointer layer owns targeted read/write. No layer bleeds into another's responsibilities without explicit bridging (which is documented as a planned reconciler feature).

5. "The tree is the truth" principle: The README's stated core principle ("The tree is the truth. Hosts are interpreters.") is consistently reflected across all docs. Every feature is motivated in terms of what it means for the tree, not for any specific host.

6. Practical consumer context: The README's "Consumer Context" section (Flowgraph, Desktop UI, OpenCode Plugin) grounds the architecture in real use cases, making it easier to evaluate trade-offs with concrete scenarios in mind.

7. Document size discipline: No document exceeds 265 lines (reconciler.md). Each document covers exactly one topic. The README provides navigation. This makes the documentation approachable and scannable.

---

Verification: Source vs. Documentation

Accuracies (docs match source)

Aspect	Doc	Source	Status
UJSX TypeBox Module schema	schema.md	src/core/schema.ts	✅ Match
TypeScript types (UPrimitive, PropValue, etc.)	schema.md	src/core/schema.ts	✅ Match (except key — see below)
key not yet on UElement	schema.md ("Known Gaps")	src/core/schema.ts (no key field)	✅ Consistently documented as not yet implemented
isUElement discriminator logic	schema.md	src/core/schema.ts:66	✅ Match (note: null guard in source not in docs — see suggestion)
h() factory behavior	element-factory.md	src/core/h.ts	✅ Match
createRoot auto-ID counter	element-factory.md	src/core/h.ts:3,24-29	✅ Match
Fragment returns UNode[]	element-factory.md	src/core/h.ts:43-44	✅ Match
jsx/jsxs/jsxDEV aliases	element-factory.md	src/core/h.ts:47-49	✅ Match
ReactiveNode interface	reactive-layer.md	src/core/reactive.ts:4-8	✅ Match
reactiveComponent and reactiveElement behavior	reactive-layer.md	src/core/reactive.ts:10-47	✅ Match
ReactiveRoot class	reactive-layer.md	src/core/reactive.ts:49-89	✅ Match
ReactiveRoot.render() overwriting renderDisposer	reactive-layer.md ("Known Gaps")	src/core/reactive.ts:74	✅ Documented as a known hazard
dispose: () => {} no-op	reactive-layer.md ("Known Gaps")	src/core/reactive.ts:25,46	✅ Consistently documented
HostConfig interface	host-config.md	src/host/config.ts:5-30	✅ Match
Root interface	host-config.md	src/host/config.ts:32-39	✅ Match
createRoot() behavior	host-config.md	src/host/config.ts:41-109	✅ Match
Mount-only rendering	host-config.md ("Known Gaps")	src/host/config.ts (no re-render logic)	✅ Match
unmount() stub behavior	host-config.md, lifecycle.md	src/host/config.ts:105-108	✅ Match
Direction type values	transforms.md	src/core/context.ts:50	✅ Match
TransformRule interface	transforms.md	src/transform/registry.ts:14-21	✅ Match
TransformRegistry methods	transforms.md	src/transform/registry.ts:23-42	✅ Match
EventEnvelope interface	events.md	src/core/events.ts:1-5	✅ Match
PubSubLike interface	events.md	src/core/events.ts:7-17	✅ Match
UjsxEventMap type	events.md	src/core/events.ts:19-26	✅ Match
createPubSubEmitter function	events.md	src/core/events.ts:33-42	✅ Match
proxyEventEmitter function	events.md	src/core/events.ts:45-51	✅ Match
ValuePointer class	pointers.md	src/core/pointer.ts:5-29	✅ Match
selectNode function signature	pointers.md	src/core/pointer.ts:31-49	✅ Match (behavior differs — see critical issue #1)
setNode function signature	pointers.md	src/core/pointer.ts:51-69	✅ Match (behavior differs — see critical issue #2)
Package dependencies	build-distribution.md	package.json	✅ Match
Sub-path exports	build-distribution.md	package.json exports field	✅ Match (except Fragment in jsx-runtime — see warning #1)
Barrel exports in mod.ts	build-distribution.md	src/mod.ts	⚠️ Partial — see critical issue #3
Context class defaults	host-config.md (line 79, line 194)	src/core/context.ts:11-15	✅ Match
Date.now() event IDs	host-config.md, events.md	src/host/config.ts:57,75,103	✅ Consistently documented as placeholder

Discrepancies

Aspect	Doc Says	Source Does	Severity
selectNode prop navigation	Only object-typed props are navigable	Source also navigates arrays (which are typeof === "object")	Critical — doc is incomplete
setNode prop-key writing	Not documented	Source handles non-numeric segments by setting props[segment] = value	Critical — behavior gap
RenderContext and Density	Not documented	Exported from mod.ts and source	Critical — public API undocumented
ADR dual status	Frontmatter draft vs body Proposed	Both present, semantics unclear	Critical — governance confusion
Fragment in jsx-runtime	Not in exports doc	Source re-exports Fragment from jsx-runtime	Warning — minor coverage gap
childCtx, transformCtx	Not in transforms.md	Public exports from registry.ts	Warning — public API gap
isUElement null check	Not in docs	Source includes node !== null	Suggestion — minor

---

Recommendations

1. Address all four critical issues before marking the architecture documents as stable: fix selectNode/setNode docs to match source, document RenderContext/Density, and resolve the ADR status ambiguity.

2. Standardize cross-reference formats across all docs to use consistent relative paths. Pick one format and apply it everywhere.

3. Advance ADR statuses from Proposed to Accepted for decisions that are already driving implementation (particularly ADR-002, ADR-003, and ADR-004 whose decisions are reflected in current source code).

4. Add error handling philosophy as a cross-cutting concern. Even a brief statement like "UJSX throws for programmer errors (invalid arguments) and no-ops for operational errors (invalid paths in selectNode)" would help implementers.

5. Consider performance targets for the reconciler design. The current docs describe algorithms without stating what "good enough" means. This will make it hard to evaluate whether the reconciler implementation meets its design goals.