add architecture docs synced to current source and sdd process
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.
This commit is contained in:
31
docs/architecture/decisions/001-html-agnostic-core.md
Normal file
31
docs/architecture/decisions/001-html-agnostic-core.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-05-18
|
||||
---
|
||||
|
||||
# ADR-001: HTML-agnostic core
|
||||
|
||||
**Status**: Proposed
|
||||
|
||||
## Context
|
||||
|
||||
UJSX is a universal JSX IR that treats JSX as an intermediate representation. The core types (UNode, UElement, UniversalProps) are deliberately free of any platform-specific concepts.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- **HTML-compatible props (className, onClick, etc.)**: Include DOM/HTML-specific prop names in core types. Rejected because it biases toward DOM rendering and forces non-DOM hosts to filter/translate irrelevant props.
|
||||
- **Separate "web" prop types**: Create a parallel type hierarchy for web/DOM props alongside the universal core. Rejected because it creates two type hierarchies and increases complexity for hosts that don't need HTML.
|
||||
|
||||
## Decision
|
||||
|
||||
UJSX core does NOT include HTML/DOM-specific concepts. No `onClick`, no `className`, no `style`, no `aria-*`. UniversalProps accepts any key-value pairs because different hosts need different prop shapes. The host decides what props mean.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Clean separation. Each host defines its own prop semantics. Flowgraph hosts use `{ name, type, url }` not `{ className, id }`.
|
||||
- TypeBox schemas for host-specific props can validate independently. No "stripping" step needed.
|
||||
|
||||
### Negative
|
||||
- Consumers targeting HTML must map their own props (e.g., `class` → `className`). This is the host's responsibility.
|
||||
- No built-in event handling system — events are host-specific. The event system (`PubSubLike`, `EventEnvelope`) is generic.
|
||||
Reference in New Issue
Block a user