ujsx/docs/research/README.md

UJSX Research Index

All research documents for the @alkdev/ujsx rewrite. This project is a universal JSX IR that treats JSX as an intermediate representation for multi-target rendering (markdown primary, graph/HTML/etc. future).

Architecture & Design

Doc	Description
agent-hud-architecture.md	Full HUD architecture: event log, adaptive density, cache-aware system prompt, plugin integration
ujsx-v2-typebox-rewrite.md	The rewrite plan: TypeBox-schema-driven UJSX, bi-directional transforms, JSX syntax, HTML-agnostic core
signals-ujsx-reactive-pipeline.md	Preact Signals integration: computed() components, reactive transform pipeline, signals+TypeBox interaction

Ecosystem & Feasibility

Doc	Description
unist-ecosystem-jsx-to-markdown.md	hast/mdast/syntax-tree ecosystem, pipeline feasibility, element mappings, alternative approaches
hono-jsx-ssr-llm-hud.md	Hono JSXNode internals, SSR pipeline, custom walker feasibility for markdown rendering

TypeBox Patterns

Doc	Description
typebox-module-type-registry.md	Type.Module as type registry, Import mechanics, runtime schema access, implications for UJSX
typebox-module-valuepointer.md	TModule + ValuePointer API, ComputeModuleProperties, Function types, practical patterns

Prior Art & Source Reference

Doc	Description
prior-poc-source-reference.md	Code from /workspace/aui/ujsx POC: what to preserve, what to remove/rewrite, TypeBox research examples

External Resources

Location	Description
/workspace/aui/ujsx/	Prior POC: core types, h() factory, HostConfig, Graphology host, TransformRegistry, StreamingTransformer
/workspace/aui/SUMMARY.md	POC summary with architecture, strengths, gaps, recommendations
/workspace/research/typebox_research/ujsx/	TypeBox Module examples: unist.ts (unist schema), ujsx.ts (UJSX schema draft)
/workspace/@alkdev/typebox/	TypeBox fork source: Module, ValuePointer, Value system
/workspace/signals/packages/core/	Preact Signals core: signal, computed, effect, batch, createModel
/workspace/conversations/research/	Original research docs from conversation session

Reconciler Implementation Plan

Doc	Description
reconciler/README.md	Index — Phase overview, dependency graph, parallelism opportunities, key design decisions
reconciler/00-KEY-FIELD-DESIGN.md	Phase 0: Add key?: string as first-class field on UElement
reconciler/01-reactive-host-bridge.md	Phase 1: Connect reactive layer to HostConfig reconciler via fiber tree
reconciler/02-key-based-children-reconciliation.md	Phase 2: Key-based children matching with LIS algorithm for move detection
reconciler/03-unmount-dispose-support.md	Phase 3: Proper disposal — unmount, signal cleanup, instance teardown
reconciler/04-typebox-optimization-layer.md	Phase 4: TypeBox Value primitives as incremental performance optimizations
reconciler/05-flowgraph-host-configs.md	Phase 5: Flowgraph HostConfig implementations (graphology DAG, reactive executor)

Key Decisions from Prior Discussion

1. TypeBox Module IS the type registry — no separate registry needed. ValuePointer.Get/Set for runtime access, Module.Import for resolved schemas.
2. Signals for reactivity — computed() wrapping component functions so unchanged inputs skip re-evaluation. NOT in the registry, but in the transformation process.
3. Bi-directional transforms — same registry, direction parameter. UJSX↔mdast, UJSX↔hast. Rules match on TypeBox schemas, not string tags.
4. HTML-agnostic core — no onClick, className, aria-* in UniversalProps. Hosts handle platform specifics.
5. Actual JSX syntax — jsxImportSource: "@alkdev/ujsx" with jsx-runtime exports.
6. HostConfig preserved — same reconciler pattern from POC, but mount-only → full reconciliation.
7. Platform agnostic — no Deno/Node-specific APIs in core. Published as @alkdev/ujsx.