@pyreon/runtime-dom 0.21.0 → 0.23.0

package/README.md

@@ -1,155 +1,179 @@
 # @pyreon/runtime-dom
 
-DOM renderer for Pyreon. Performs surgical signal-to-DOM updates with no virtual DOM diffing.
+Surgical signal-to-DOM renderer — no virtual DOM, no diff.
+
+Mounts VNode trees and compiler-emitted `_tpl()` cloneNode templates directly into the DOM; per-node `_bind()` calls produce surgical signal-to-DOM updates without VDOM diffing. Reactive text uses `TextNode.data` (not `.textContent`) for minimal mutation; SVG / MathML namespaces are auto-detected (67 tags); custom elements receive props as properties. Ships CSS-transition support (`<Transition>` / `<TransitionGroup>`) and component caching (`<KeepAlive>`) — each also available as a subpath export so apps that don't use animations or caching can tree-shake them out.
 
 ## Install
 
 ```bash
-bun add @pyreon/runtime-dom
+bun add @pyreon/runtime-dom @pyreon/core @pyreon/reactivity
 ```
 
-## Quick Start
+## Quick start
 
 ```tsx
-import { mount } from '@pyreon/runtime-dom'
+import { mount, hydrateRoot, Transition, KeepAlive } from '@pyreon/runtime-dom'
 import { signal } from '@pyreon/reactivity'
+import { Show } from '@pyreon/core'
 
 const count = signal(0)
 
-const App = () => (
-  <button onClick={() => count.update((n) => n + 1)}>Clicks: {() => count()}</button>
-)
+function App() {
+  return (
+    <button onClick={() => count.update(n => n + 1)}>
+      Clicks: {() => count()}
+    </button>
+  )
+}
 
 const unmount = mount(<App />, document.getElementById('app')!)
+// Or hydrate SSR-rendered markup:
+hydrateRoot(<App />, document.getElementById('app')!)
 ```
 
-## Transition Examples
+## mount / render / unmount
 
-Animate elements on enter and leave:
+```ts
+const unmount = mount(<App />, container)
+unmount()                                // teardown effects, unmount subtree
+```
 
-```tsx
-import { Transition } from '@pyreon/runtime-dom'
-import { signal } from '@pyreon/reactivity'
+`render` is an alias for `mount` (Solid-parity). `mountChild(child, parent, anchor)` is the low-level form for advanced integrations.
+
+## Hydration
+
+```ts
+import {
+  hydrateRoot, enableHydrationWarnings, disableHydrationWarnings, onHydrationMismatch,
+} from '@pyreon/runtime-dom'
 
-const show = signal(true)
+hydrateRoot(<App />, container)
 
-const App = () => (
-  <div>
-    <button onClick={() => show.set(!show())}>Toggle</button>
-    <Transition name="fade">{() => show() && <p>Hello!</p>}</Transition>
-  </div>
-)
+enableHydrationWarnings()                  // dev console warnings on mismatch
+onHydrationMismatch((ctx) => {
+  // ctx: { type, node, expected, received, path }
+  reportToTelemetry(ctx)
+})
 ```
 
-Animate keyed lists with move support:
+The `_tpl` hydration path uses a framework-wide correctness-first SWAP: when the SSR DOM doesn't match the freshly-built template, the SSR subtree is replaced with the rebuilt one (same final DOM byte-for-byte for matched cases; correct DOM for mismatches without a crash). Reactivity survives across the swap.
 
-```tsx
-import { TransitionGroup } from '@pyreon/runtime-dom'
-import { For } from '@pyreon/core'
-import { signal } from '@pyreon/reactivity'
+## applyProp / applyProps
 
-const items = signal([1, 2, 3])
+```ts
+applyProp(el, 'class', { active: isActive() })   // cx-normalized
+applyProp(el, 'style', { color: 'red' })
+applyProp(el, 'onClick', handler)
+applyProps(el, { class: 'btn', 'data-id': id })
+```
+
+The `class` prop accepts strings, arrays, objects, or any nested mix — normalized via `cx()` from `@pyreon/core`. Event handlers may go through the delegation path (`DELEGATED_EVENTS` allowlist + `setupDelegation`) instead of `addEventListener` for common bubbling events.
+
+## HTML sanitization
+
+```ts
+import { sanitizeHtml, setSanitizer } from '@pyreon/runtime-dom'
 
-const List = () => (
-  <TransitionGroup name="list">
-    <For each={items} by={(n) => n}>
-      {(item) => <div>{() => item()}</div>}
-    </For>
-  </TransitionGroup>
-)
+setSanitizer((html) => DOMPurify.sanitize(html))
+sanitizeHtml('<script>…</script>') // routes through the active sanitizer
 ```
 
-## KeepAlive Example
+Used by `innerHTML` / `dangerouslySetInnerHTML` paths. Default sanitizer is a conservative pass-through — install `DOMPurify` or equivalent for production.
 
-Cache inactive component subtrees instead of destroying them:
+## SVG / MathML / custom elements
 
-```tsx
-import { KeepAlive } from '@pyreon/runtime-dom'
-import { signal } from '@pyreon/reactivity'
+- **SVG / MathML** tags (67 detected) are auto-created via `createElementNS` with the correct namespace URI.
+- **SVG attribute application** ALWAYS uses `setAttribute()` (never property assignment) — many SVG properties (`SVGRectElement.x`, `SVGMarkerElement.refX`, etc.) are read-only `SVGAnimatedLength` getters and would crash on property write.
+- **Custom elements** (tag name with hyphen) receive props as properties, not attributes — matches React/Vue/Solid convention.
 
-const tab = signal<'home' | 'settings'>('home')
+## Templates
 
-const App = () => (
-  <div>
-    <button onClick={() => tab.set('home')}>Home</button>
-    <button onClick={() => tab.set('settings')}>Settings</button>
-    <KeepAlive>{() => (tab() === 'home' ? <Home /> : <Settings />)}</KeepAlive>
-  </div>
-)
+```ts
+const template = createTemplate('<div class="card"><h1></h1><p></p></div>')
+const el = template() // cloneNode under the hood
 ```
 
-## API
+`createTemplate(html)` is the user-facing reusable cloneNode factory. The compiler-emitted `_tpl(html)` is the same primitive — emitted automatically for any JSX element tree with ≥1 DOM tag.
 
-### Mounting
+## Compiler-emitted runtime helpers
 
-- **`mount(root, container): () => void`** -- Clears the container and mounts the VNode tree. Returns an `unmount` function.
-- **`render`** -- Alias for `mount`.
-- **`mountChild(child, parent, anchor)`** -- Low-level mount of a single child node.
+These symbols are emitted by `@pyreon/compiler`. Not for hand-written user code, but documented here as the contract:
 
-### Hydration
+| Symbol | Purpose |
+|---|---|
+| `_tpl(html)` | Parse + clone an HTML template once per literal |
+| `_bindText(source, textNode)` | Reactive text — reads `source._v` directly on the fast path |
+| `_bindDirect(source, el, key)` | Reactive attribute — fast path for primitive props |
+| `_mountSlot(...)` | Mount a reactive child slot under a template anchor |
+| `_applyProps(...)` | Spread props on a template element |
+| `_rsCollapse(...)` / `_rsCollapseH(...)` | Rocketstyle compile-time-collapse mount paths |
 
-- **`hydrateRoot(root, container)`** -- Hydrates server-rendered HTML with client-side reactivity.
-- **`enableHydrationWarnings()` / `disableHydrationWarnings()`** -- Toggle console warnings for hydration mismatches.
+## Event delegation
 
-### Props and Sanitization
+```ts
+import { DELEGATED_EVENTS, delegatedPropName, setupDelegation } from '@pyreon/runtime-dom'
 
-- **`applyProp(el, key, value)`** -- Applies a single prop to a DOM element. The `class` prop accepts strings, arrays, objects, or nested mix (processed via `cx()` from `@pyreon/core`).
-- **`applyProps(el, props)`** -- Applies all props to a DOM element.
-- **`sanitizeHtml(html): string`** -- Sanitizes an HTML string using the active sanitizer.
-- **`setSanitizer(fn: SanitizeFn)`** -- Replaces the default HTML sanitizer.
+setupDelegation(rootElement)
+```
 
-### Templates
+Common bubbling events (`click`, `input`, `submit`, …) are attached once at the root via `setupDelegation` and dispatched per-node via the matching prop name. Tree-shakeable; only used by event names in `DELEGATED_EVENTS`.
 
-- **`createTemplate(html): () => Element`** -- Creates a reusable DOM template factory from an HTML string.
+## Transition
 
-### Transitions
+```tsx
+import { Transition } from '@pyreon/runtime-dom'
+// or, for explicit tree-shake:
+// import { Transition } from '@pyreon/runtime-dom/transition'
 
-- **`Transition`** -- Animates a single child on enter/leave with CSS classes or JS hooks.
-- **`TransitionGroup`** -- Animates a list of keyed children, including move transitions.
+<Transition name="fade" mode="out-in">
+  <Show when={visible()}><div>Content</div></Show>
+</Transition>
+```
 
-Also available as a separate subpath export for apps that don't use animations:
+CSS-class enter/leave animations + JS hooks (`onBeforeEnter`, `onAfterLeave`, etc.). A 5-second timeout fires `transitionend` automatically if no real `transitionend` / `animationend` event arrives — animations never get stuck.
 
-```ts
-import { Transition, TransitionGroup } from '@pyreon/runtime-dom/transition'
+```tsx
+import { TransitionGroup } from '@pyreon/runtime-dom'
+
+<TransitionGroup name="list" tag="ul">
+  <For each={items} by={i => i.id}>{(item) => <li>{item.name}</li>}</For>
+</TransitionGroup>
 ```
 
-### KeepAlive
+`TransitionGroup` adds FLIP-style move animations for keyed lists.
 
-- **`KeepAlive`** -- Caches inactive component subtrees instead of destroying them.
+## KeepAlive
 
-Also available as a separate subpath export:
+```tsx
+import { KeepAlive } from '@pyreon/runtime-dom'
+// or: import { KeepAlive } from '@pyreon/runtime-dom/keep-alive'
 
-```ts
-import { KeepAlive } from '@pyreon/runtime-dom/keep-alive'
+<KeepAlive>
+  {() => tab() === 'home' ? <Home /> : <Settings />}
+</KeepAlive>
 ```
 
-### Types
-
-`TransitionProps`, `TransitionGroupProps`, `KeepAliveProps`, `SanitizeFn`, `DevtoolsComponentEntry`, `PyreonDevtools`
+Caches inactive subtrees instead of destroying them — preserves component state (form inputs, scroll positions, signals) across toggles. Pair with `<Show>` or a route guard for tab-style UIs.
 
-## Production Performance
+## Dev-mode gates
 
-The mount pipeline is optimized for zero unnecessary allocations:
+Dev-only warnings (e.g. duplicate `<For>` keys, mount of `null` container) are gated on `process.env.NODE_ENV !== 'production'` — the **bundler-agnostic library convention**. Every modern bundler (Vite, Webpack/Next.js, esbuild, Rollup, Parcel, Bun) auto-replaces `process.env.NODE_ENV` at consumer build time and tree-shakes the dev block to zero bytes in production. This is enforced repo-wide by the `pyreon/no-process-dev-gate` lint rule. Do NOT use `import.meta.env.DEV` (Vite/Rolldown-only) or `typeof process !== 'undefined' && …` (dead in real Vite browser bundles).
 
-- **Devtools gated on `__DEV__`** -- Component ID generation (`Math.random`), parent/child tracking (`_mountingStack`), and `registerComponent`/`unregisterComponent` are all behind `if (__DEV__)`. Vite tree-shakes the entire devtools module from production bundles.
-- **Lazy LifecycleHooks** -- `mount`/`unmount`/`update`/`error` arrays start as `null`, allocated on first hook registration. Components with no hooks (80%+) skip all hook iteration.
-- **Lazy mountCleanups** -- Only allocated when an `onMount` callback returns a cleanup function.
-- **makeReactiveProps scan-first** -- Scans for `_rp()` brands before allocating the getter-backed object. Static-only components return `raw` immediately.
-- **renderEffect first-run skip** -- Skips cleanup on first run since the deps array is empty.
-- **Text .data no-op writes** -- `_bindText` and `_bindDirect` skip DOM writes when the value hasn't changed.
+A tree-shake regression test (`src/tests/dev-gate-treeshake.test.ts`) bundles `mount.ts` through Vite production and asserts warn strings are gone from the output.
 
-## Dev-mode warnings — bundler tree-shake
+## Mount-pipeline optimizations
 
-Dev warnings are gated on `import.meta.env?.DEV`. Tree-shake behavior depends on both the source pattern and the consumer bundler:
+- **Devtools gated on `__DEV__`** — component-ID generation (`Math.random`), `_mountingStack`, `registerComponent`/`unregisterComponent` all behind `if (__DEV__)`. Zero production cost.
+- **Lazy `LifecycleHooks`** — `mount` / `unmount` / `update` / `error` arrays start as `null`; allocated on first hook. ~80% of components have no hooks → no allocation.
+- **Lazy `mountCleanups`** — only allocated when an `onMount` callback returns a cleanup.
+- **`makeReactiveProps` scan-first** — checks for `_rp` brands before allocating the result object. Static-only components (60%+) skip the object entirely.
+- **`renderEffect` first-run skip** — empty deps on first run means no cleanup to invoke.
+- **`TextNode.data` no-op writes** — `_bindText` / `_bindDirect` skip DOM writes when the value hasn't changed.
 
-| Source pattern | Vite prod | Raw esbuild prod | Test |
-| --- | --- | --- | --- |
-| `if (!import.meta.env?.DEV) return` (inline early-return) | tree-shaken | tree-shaken | `flow/src/tests/integration.test.ts` (esbuild) |
-| `const __DEV__ = ...; if (__DEV__) ...` | tree-shaken | mostly tree-shaken | `runtime-dom/src/tests/dev-gate-treeshake.test.ts` (Vite) |
-| `const __DEV__ = ...; __DEV__ && cond && warn(...)` (chained &&) | tree-shaken | runtime-gated only | `runtime-dom/.../dev-gate-treeshake.test.ts` (Vite + non-Vite runtime smoke) |
-| `typeof process !== 'undefined'` | dead in browser | dead in browser | `pyreon/no-process-dev-gate` lint rule |
+## Documentation
 
-Vite is Pyreon's primary supported bundler. Non-Vite consumers (webpack, bunchee, raw esbuild) using the chained `&&` form may retain warning strings as data, but the runtime gate evaluates to `false` when `import.meta.env.DEV` is undefined — warnings don't fire. Only a small bundle-size cost.
+Full docs: [docs.pyreon.dev/docs/runtime-dom](https://docs.pyreon.dev/docs/runtime-dom) (or `docs/docs/runtime-dom.md` in this repo).
 
 ## License