@pyreon/runtime-dom 0.12.14 → 0.13.0

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/delegate.ts","../../../src/devtools.ts","../../../src/hydrate.ts","../../../src/hydration-debug.ts","../../../src/keep-alive.ts","../../../src/mount.ts","../../../src/props.ts","../../../src/template.ts","../../../src/transition.ts","../../../src/transition-group.ts","../../../src/index.ts"],"mappings":"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"}
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/delegate.ts","../../../src/devtools.ts","../../../src/hydrate.ts","../../../src/hydration-debug.ts","../../../src/keep-alive.ts","../../../src/mount.ts","../../../src/props.ts","../../../src/template.ts","../../../src/transition.ts","../../../src/transition-group.ts","../../../src/index.ts"],"mappings":";;;;;;AAoBA;;;;;AA8BA;;;;;AAWA;;;;cAzCa,gBAAA,EAAgB,GAAA;;;;ACJ7B;iBDkCgB,iBAAA,CAAkB,SAAA;;;;;iBAWlB,eAAA,CAAgB,SAAA,EAAW,OAAA;;;;;;AAzC3C;;;;;AA8BA;;;;;AAWA;;UC7CiB,sBAAA;EACf,EAAA;EACA,IAAA;;EAEA,EAAA,EAAI,OAAA;EACJ,QAAA;EACA,QAAA;AAAA;AAAA,UAGe,cAAA;EAAA,SACN,OAAA;EACT,gBAAA,IAAoB,sBAAA;EACpB,gBAAA,IAAoB,sBAAA;EACpB,SAAA,CAAU,EAAA;EACV,gBAAA,CAAiB,EAAA,GAAK,KAAA,EAAO,sBAAA;EAC7B,kBAAA,CAAmB,EAAA,GAAK,EAAA;EATxB;EAWA,aAAA;EACA,cAAA;AAAA;;;;;;AAlBF;;;;;;;;;;;iBCmagB,WAAA,CAAY,SAAA,EAAW,OAAA,EAAS,KAAA,EAAO,UAAA;;;;;;AF/ZvD;;;;;AA8BA;;iBGhCgB,uBAAA,CAAA;AAAA,iBAIA,wBAAA,CAAA;;;UCjBC,cAAA,SAAuB,KAAA;;AJexC;;;;;EIRE,MAAA;EACA,QAAA,GAAW,UAAA;AAAA;;;AJgDb;;;;;;;;AC7CA;;;;;;;;;;;;AASA;;iBGegB,SAAA,CAAU,KAAA,EAAO,cAAA,GAAiB,UAAA;;;KCV7C,SAAA;;ALVL;;;;;AA8BA;iBKCgB,UAAA,CACd,KAAA,EAAO,UAAA,GAAa,UAAA,YAAsB,UAAA,GAAa,UAAA,KACvD,MAAA,EAAQ,IAAA,EACR,MAAA,GAAQ,IAAA,UACP,SAAA;;;KCjDE,OAAA;AAAA,KASO,UAAA,IAAc,IAAA;ANK1B;;;;;AA8BA;;;;;AAWA;;;;;;AAzCA,iBMegB,YAAA,CAAa,EAAA,EAAI,UAAA;;ALnBjC;;;iBK8IgB,YAAA,CAAa,IAAA;;;;;;iBAgBb,UAAA,CAAW,EAAA,EAAI,OAAA,EAAS,KAAA,EAAO,KAAA,GAAQ,OAAA;AAAA,iBA4HvC,SAAA,CAAU,EAAA,EAAI,OAAA,EAAS,GAAA,UAAa,KAAA,YAAiB,OAAA;;;;;ANtRrE;;;;;AA8BA;;;;;AAWA;;;;;;;;AC7CA;;;;;iBMagB,cAAA,GAAA,CACd,IAAA,UACA,IAAA,GAAO,EAAA,EAAI,WAAA,EAAa,IAAA,EAAM,CAAA,4BAC5B,IAAA,EAAM,CAAA,KAAM,UAAA;;;;;;;ANPhB;;;;;;;;;;iBMqCgB,SAAA,CACd,MAAA;EAAU,EAAA;EAAc,MAAA,IAAU,EAAA;AAAA,GAClC,IAAA,EAAM,IAAA;;;;;;;;;;;;;;;;ALmXR;iBK9UgB,WAAA,CACd,MAAA;EAAU,EAAA;EAAc,MAAA,IAAU,EAAA;AAAA,GAClC,OAAA,GAAU,KAAA;;;;;;;;;AJrFZ;;;;;AAIA;;;;;;;;ACjBA;;iBG0IgB,IAAA,CAAK,IAAA,UAAc,IAAA,GAAO,EAAA,EAAI,WAAA,2BAAsC,UAAA;;;;;;;;AHvGpF;;;;;;iBGgIgB,UAAA,CACd,QAAA,EAAU,UAAA,GAAa,UAAA,IACvB,MAAA,EAAQ,IAAA,EACR,WAAA,EAAa,IAAA;;;UC/JE,eAAA;;ARQjB;;;;EQFE,IAAA;ERgCc;EQ9Bd,IAAA;;;;ARyCF;EQpCE,MAAA;EAEA,SAAA;EACA,WAAA;EACA,OAAA;EACA,SAAA;EACA,WAAA;EACA,OAAA;EAEA,aAAA,IAAiB,EAAA,EAAI,WAAA;EACrB,YAAA,IAAgB,EAAA,EAAI,WAAA;EACpB,aAAA,IAAiB,EAAA,EAAI,WAAA;EACrB,YAAA,IAAgB,EAAA,EAAI,WAAA;EPpBpB;;;;EOyBA,QAAA,GAAW,UAAA;AAAA;;;APjBb;;;;;;;;;;;;;;;;;;;;iBO0CgB,UAAA,CAAW,KAAA,EAAO,eAAA,GAAkB,UAAA;;;UC9DnC,oBAAA;;EAEf,GAAA;ETqCA;ESnCA,IAAA;ETW2B;EST3B,MAAA;EAEA,SAAA;EACA,WAAA;EACA,OAAA;EACA,SAAA;EACA,WAAA;EACA,OAAA;ET2C6B;ESzC7B,SAAA;ETyCyC;ESvCzC,KAAA,QAAa,CAAA;;EAEb,KAAA,GAAQ,IAAA,EAAM,CAAA,EAAG,KAAA;;ARRnB;;;;EQcE,MAAA,GAAS,IAAA,EAAM,CAAA,EAAG,KAAA,aAAkB,KAAA;EAEpC,aAAA,IAAiB,EAAA,EAAI,WAAA;EACrB,YAAA,IAAgB,EAAA,EAAI,WAAA;EACpB,aAAA,IAAiB,EAAA,EAAI,WAAA;EACrB,YAAA,IAAgB,EAAA,EAAI,WAAA;AAAA;;;ARVtB;;;;;;;;;;;;;;;;;;;;;;;iBQsDgB,eAAA,aAAA,CAA6B,KAAA,EAAO,oBAAA,CAAqB,CAAA,IAAK,UAAA;;;;;;;;;AR/D9E;;iBSmBgB,KAAA,CAAM,IAAA,EAAM,UAAA,EAAY,SAAA,EAAW,OAAA;;cAatC,MAAA,SAAM,KAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/runtime-dom",
-  "version": "0.12.14",
+  "version": "0.13.0",
   "description": "DOM renderer for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/runtime-dom#readme",
   "bugs": {
@@ -43,14 +43,15 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.12.14",
-    "@pyreon/reactivity": "^0.12.14"
+    "@pyreon/core": "^0.13.0",
+    "@pyreon/reactivity": "^0.13.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
-    "@pyreon/compiler": "^0.12.14",
-    "@pyreon/runtime-server": "^0.12.14",
-    "@pyreon/test-utils": "^0.12.10",
+    "@pyreon/compiler": "^0.13.0",
+    "@pyreon/manifest": "0.13.0",
+    "@pyreon/runtime-server": "^0.13.0",
+    "@pyreon/test-utils": "^0.13.0",
     "@vitest/browser-playwright": "^4.1.4",
     "esbuild": "^0.28.0",
     "happy-dom": "^20.8.3",

package/src/manifest.ts

@@ -0,0 +1,218 @@
+import { defineManifest } from '@pyreon/manifest'
+
+export default defineManifest({
+  name: '@pyreon/runtime-dom',
+  title: 'DOM Renderer',
+  tagline:
+    'DOM renderer, mount, hydrateRoot, Transition, TransitionGroup, KeepAlive, SVG/MathML namespace, custom elements',
+  description:
+    'Surgical signal-to-DOM renderer with zero virtual DOM overhead. The compiler emits `_tpl()` (cloneNode-based template instantiation) + `_bind()` (per-node reactive bindings) calls that mount directly to the DOM without VNode diffing. Reactive text uses `TextNode.data` assignment (not `.textContent`) for minimal DOM mutation. Supports SVG/MathML namespace auto-detection (67 tags), custom elements (props as properties), CSS transitions via `<Transition>` / `<TransitionGroup>`, and component caching via `<KeepAlive>`. Dev-mode warnings use `import.meta.env.DEV` (not `typeof process`) so they tree-shake to zero bytes in production Vite builds.',
+  category: 'browser',
+  longExample: `import { mount, hydrateRoot, Transition, TransitionGroup, KeepAlive } from "@pyreon/runtime-dom"
+import { signal } from "@pyreon/reactivity"
+import { Show, For } from "@pyreon/core"
+
+// Mount — clears container, returns unmount function
+const unmount = mount(<App />, document.getElementById("app")!)
+
+// Hydrate SSR-rendered HTML (preserves existing DOM)
+hydrateRoot(<App />, document.getElementById("app")!)
+
+// Transition — CSS-based enter/leave animations
+const visible = signal(true)
+const FadeExample = () => (
+  <Transition name="fade" mode="out-in">
+    <Show when={visible()}>
+      <div>Content</div>
+    </Show>
+  </Transition>
+)
+// CSS: .fade-enter-active, .fade-leave-active { transition: opacity 0.3s }
+//      .fade-enter-from, .fade-leave-to { opacity: 0 }
+
+// TransitionGroup — animate list items entering/leaving
+const items = signal([1, 2, 3])
+const ListExample = () => (
+  <TransitionGroup name="list">
+    <For each={items()} by={i => i}>
+      {item => <div>{item}</div>}
+    </For>
+  </TransitionGroup>
+)
+
+// KeepAlive — cache component state across mount/unmount cycles
+const tab = signal<"a" | "b">("a")
+const TabExample = () => (
+  <KeepAlive>
+    <Show when={tab() === "a"}><ExpensiveA /></Show>
+    <Show when={tab() === "b"}><ExpensiveB /></Show>
+  </KeepAlive>
+)`,
+  features: [
+    'mount() — mount VNode tree into container, returns unmount function',
+    'hydrateRoot() — hydrate SSR-rendered HTML, preserving existing DOM',
+    'Transition — CSS-based enter/leave animations with mode support',
+    'TransitionGroup — animate list item additions and removals',
+    'KeepAlive — cache and restore component state across mount/unmount cycles',
+    '_tpl() + _bind() — compiler-driven template instantiation with zero VNode overhead',
+    'SVG/MathML — 67 tags auto-detected, correct namespace URI, setAttribute-only',
+    'Custom elements — props set as properties on hyphenated tag names',
+    'Event delegation — synthetic event system for performance',
+    'Dev-mode warnings — container validation, output validation, duplicate keys',
+  ],
+  api: [
+    {
+      name: 'mount',
+      kind: 'function',
+      signature: 'mount(root: VNodeChild, container: Element): () => void',
+      summary:
+        'Mount a VNode tree into a container element. Clears the container first, sets up event delegation, then mounts the given child. Returns an `unmount` function that removes everything and disposes all effects. In dev mode, throws if `container` is null/undefined with an actionable error message.',
+      example: `import { mount } from "@pyreon/runtime-dom"
+
+const dispose = mount(<App />, document.getElementById("app")!)
+
+// To unmount:
+dispose()`,
+      mistakes: [
+        '`createRoot(container).render(<App />)` — Pyreon uses a single function call: `mount(<App />, container)`',
+        '`mount(<App />, document.getElementById("app"))` without `!` — getElementById returns `Element | null`. The runtime throws in dev if null, but TypeScript needs the assertion',
+        '`mount(<App />, document.body)` — mounting directly to body is discouraged; use a dedicated container element',
+        'Forgetting to call the returned unmount function — leaks event listeners and effects. Store and call it on cleanup',
+      ],
+      seeAlso: ['hydrateRoot', 'render'],
+    },
+    {
+      name: 'render',
+      kind: 'function',
+      signature: 'render(root: VNodeChild, container: Element): () => void',
+      summary:
+        'Alias for `mount`. Provided for API familiarity — both names point to the same function.',
+      example: `import { render } from "@pyreon/runtime-dom"
+render(<App />, document.getElementById("app")!)`,
+      seeAlso: ['mount'],
+    },
+    {
+      name: 'hydrateRoot',
+      kind: 'function',
+      signature: 'hydrateRoot(root: VNodeChild, container: Element): () => void',
+      summary:
+        'Hydrate server-rendered HTML. Walks the existing DOM and attaches reactive bindings without recreating elements. Expects the DOM to match the VNode tree structure — mismatches emit dev-mode warnings. Returns an unmount function.',
+      example: `import { hydrateRoot } from "@pyreon/runtime-dom"
+
+// Hydrate SSR-rendered HTML:
+hydrateRoot(<App />, document.getElementById("app")!)`,
+      seeAlso: ['mount', '@pyreon/runtime-server'],
+    },
+    {
+      name: 'Transition',
+      kind: 'component',
+      signature: '<Transition name={name} mode={mode} onEnter={fn} onLeave={fn}>{children}</Transition>',
+      summary:
+        'CSS-based enter/leave animation wrapper. Applies `{name}-enter-from`, `{name}-enter-active`, `{name}-enter-to` classes on enter and the corresponding `-leave-*` classes on leave. `mode` controls sequencing: `"out-in"` waits for leave to complete before entering, `"in-out"` enters first. Has a 5-second safety timeout — if `transitionend`/`animationend` never fires, the transition completes automatically.',
+      example: `<Transition name="fade" mode="out-in">
+  <Show when={visible()}>
+    <div>Content</div>
+  </Show>
+</Transition>
+
+/* CSS:
+.fade-enter-active, .fade-leave-active { transition: opacity 0.3s }
+.fade-enter-from, .fade-leave-to { opacity: 0 }
+*/`,
+      mistakes: [
+        'Missing CSS classes — `<Transition name="fade">` does nothing without `.fade-enter-active` / `.fade-leave-active` CSS',
+        'Wrapping multiple root elements — Transition expects a single child (or null). Multiple children cause undefined behavior',
+        'Using `mode="in-out"` when you want sequential — `"out-in"` is almost always what you want (old leaves, then new enters)',
+      ],
+      seeAlso: ['TransitionGroup', '@pyreon/kinetic'],
+    },
+    {
+      name: 'TransitionGroup',
+      kind: 'component',
+      signature: '<TransitionGroup name={name} tag={tag}>{children}</TransitionGroup>',
+      summary:
+        'Animate list item additions and removals with CSS transitions. Each item gets enter/leave classes on mount/unmount. The `tag` prop controls the wrapper element (defaults to a fragment). Works with `<For>` for reactive lists. Also applies `-move` classes for FLIP-animated reordering.',
+      example: `<TransitionGroup name="list" tag="ul">
+  <For each={items()} by={i => i.id}>
+    {item => <li>{item.name}</li>}
+  </For>
+</TransitionGroup>
+
+/* CSS:
+.list-enter-active, .list-leave-active { transition: all 0.3s }
+.list-enter-from, .list-leave-to { opacity: 0; transform: translateY(10px) }
+.list-move { transition: transform 0.3s }
+*/`,
+      seeAlso: ['Transition', 'For'],
+    },
+    {
+      name: 'KeepAlive',
+      kind: 'component',
+      signature: '<KeepAlive include={pattern} exclude={pattern} max={number}>{children}</KeepAlive>',
+      summary:
+        'Cache component instances across mount/unmount cycles so their state (signals, scroll position, form inputs) is preserved when they are toggled out and back in. `include`/`exclude` filter by component name. `max` limits cache size (LRU eviction). Useful for tab panels and multi-step forms.',
+      example: `const tab = signal<"a" | "b">("a")
+
+<KeepAlive>
+  <Show when={tab() === "a"}><ExpensiveFormA /></Show>
+  <Show when={tab() === "b"}><ExpensiveFormB /></Show>
+</KeepAlive>`,
+      seeAlso: ['Transition', 'Show'],
+    },
+    {
+      name: '_tpl',
+      kind: 'function',
+      signature: '_tpl(html: string): () => DocumentFragment',
+      summary:
+        'Compiler-internal: create a template factory from an HTML string. First call parses the HTML into a `<template>` element; subsequent calls use `cloneNode(true)` for zero-parse instantiation. Not intended for direct use — the JSX compiler emits `_tpl()` calls automatically.',
+      example: `// Compiler output (not hand-written):
+const _$t0 = _tpl("<div class=\\"container\\"><span></span></div>")`,
+      seeAlso: ['_bindText', '_bindDirect'],
+    },
+    {
+      name: '_bindText',
+      kind: 'function',
+      signature: '_bindText(fn: () => string, node: Text): void',
+      summary:
+        'Compiler-internal: bind a reactive expression to a text node via `TextNode.data` assignment. Creates a `renderEffect` that re-runs when tracked signals change. Each text node gets its own independent binding for fine-grained reactivity.',
+      example: `// Compiler output for <div>{count()}</div>:
+const _$t = _tpl("<div> </div>")
+const _$n = _$t()
+_bindText(() => count(), _$n.firstChild)`,
+      seeAlso: ['_tpl', '_bindDirect'],
+    },
+    {
+      name: 'sanitizeHtml',
+      kind: 'function',
+      signature: 'sanitizeHtml(html: string): string',
+      summary:
+        'Sanitize an HTML string using the registered sanitizer (set via `setSanitizer()`). Falls back to the identity function if no sanitizer is registered. Used by the runtime when setting `innerHTML` on elements.',
+      example: `import { setSanitizer, sanitizeHtml } from "@pyreon/runtime-dom"
+setSanitizer(DOMPurify.sanitize)
+const clean = sanitizeHtml(userInput)`,
+      seeAlso: ['setSanitizer'],
+    },
+  ],
+  gotchas: [
+    {
+      label: 'SVG/MathML uses setAttribute only',
+      note: 'SVG and MathML elements ALWAYS use `setAttribute()` for prop forwarding, never property assignment. Many SVG properties (`markerWidth`, `refX`, etc.) are read-only `SVGAnimatedLength` getters — `el[key] = value` crashes. Detected by `el.namespaceURI !== "http://www.w3.org/1999/xhtml"`.',
+    },
+    {
+      label: 'Custom elements use property assignment',
+      note: 'Elements with a hyphen in their tag name (custom elements) get props set as JS properties, not HTML attributes. This matches the web components spec — attributes are strings, properties can be any type.',
+    },
+    {
+      label: 'Transition 5s safety timeout',
+      note: 'If `transitionend` or `animationend` never fires (missing CSS, display:none, zero-duration), the transition completes automatically after 5 seconds to prevent stuck UI.',
+    },
+    {
+      label: 'Dev warnings use import.meta.env.DEV',
+      note: 'All dev-mode warnings (`mount()` null container, duplicate keys, raw signal children) use `import.meta.env.DEV` — NOT `typeof process`. Vite/Rolldown literal-replaces it at build time; production bundles contain zero warning bytes. Tests run in vitest which sets DEV=true automatically.',
+    },
+    {
+      label: 'Event delegation',
+      note: '`setupDelegation(container)` is called by `mount()` — common events are delegated to the container root for performance. Direct event binding (non-delegated) is used for events that do not bubble (focus, blur, scroll, etc.).',
+    },
+  ],
+})

package/src/props.ts

@@ -245,37 +245,76 @@ function applyEventProp(el: Element, key: string, value: unknown): Cleanup | nul
   return () => el.removeEventListener(eventName, batched)
 }
 
-export function applyProp(el: Element, key: string, value: unknown): Cleanup | null {
-  // Event listener: onClick → "click"
-  if (EVENT_RE.test(key)) return applyEventProp(el, key, value)
+/**
+ * Sink for a single prop's CALLED value (always a primitive / object /
+ * `null` — never a function). Called both directly for static values and
+ * from the reactive `renderEffect` for accessor-bound values.
+ *
+ * NOTE on architecture: extracting the special-cased sinks
+ * (`innerHTML` / `dangerouslySetInnerHTML`) into this single dispatch
+ * function ensures every prop kind goes through the same reactive
+ * wrapping at `applyProp`'s entry. Previously each special case had its
+ * own early-return branch that needed to remember to handle function
+ * values; missing the dance once meant the closure was stringified and
+ * set as literal text. The structural fix (one reactive-wrap, then
+ * dispatch) eliminates the entire bug class.
+ */
+function applyStaticProp(el: Element, key: string, value: unknown): void {
+  if (__DEV__ && typeof value === 'function') {
+    // Defensive: function values must be unwrapped via `renderEffect`
+    // before reaching here. If we see one, a NEW special-case branch
+    // somewhere upstream skipped the reactive-wrapping dance — exactly
+    // the bug class the structural refactor was meant to eliminate.
+    console.warn(
+      `[Pyreon] applyStaticProp received a function for "${key}". ` +
+        `This likely means a new special-cased prop sink in applyProp() ` +
+        `bypassed the reactive-wrap path. The closure would be stringified ` +
+        `and set as a literal value. Verify the dispatch in applyProp().`,
+    )
+  }
 
-  // innerHTML — sanitized via Sanitizer API or fallback allowlist sanitizer
+  // innerHTML — sanitized via Sanitizer API or fallback allowlist sanitizer.
   if (key === 'innerHTML') {
+    const html = String(value ?? '')
     if (typeof (el as HTMLElement & { setHTML?: (h: string) => void }).setHTML === 'function') {
-      ;(el as HTMLElement & { setHTML: (h: string) => void }).setHTML(value as string)
+      ;(el as HTMLElement & { setHTML: (h: string) => void }).setHTML(html)
     } else {
-      ;(el as HTMLElement).innerHTML = sanitizeHtml(value as string)
+      ;(el as HTMLElement).innerHTML = sanitizeHtml(html)
     }
-    return null
+    return
   }
-  // dangerouslySetInnerHTML — intentionally raw, developer owns sanitization (same as React).
-  // The name itself is the warning — React doesn't log, neither should we.
-  // Previously this warned on every prop application, flooding the console
-  // on re-renders (one warning per render per instance).
+
+  // dangerouslySetInnerHTML — intentionally raw, developer owns sanitization
+  // (same as React). The name itself is the warning — React doesn't log,
+  // neither should we.
   if (key === 'dangerouslySetInnerHTML') {
-    ;(el as HTMLElement).innerHTML = (value as { __html: string }).__html
-    return null
+    const v = value as { __html: string } | null | undefined
+    ;(el as HTMLElement).innerHTML = v?.__html ?? ''
+    return
   }
 
-  // Reactive prop — function that returns the actual value
-  // Uses renderEffect (lighter than effect — no scope registration, no WeakMap)
-  // since lifecycle is managed by mountElement's cleanup array.
+  setStaticProp(el, key, value)
+}
+
+export function applyProp(el: Element, key: string, value: unknown): Cleanup | null {
+  // Event listener: onClick → "click"
+  if (EVENT_RE.test(key)) return applyEventProp(el, key, value)
+
+  // Reactive prop — function value is an accessor closure. The JSX compiler
+  // emits `prop={someExpr(signal())}` as a `() => someExpr(signal())` thunk
+  // so the prop tracks the signal automatically. We wrap in `renderEffect`
+  // ONCE here, before any prop-kind dispatch, so EVERY sink gets the same
+  // reactive treatment. Previously special-cased sinks (innerHTML etc.) had
+  // early-return branches that bypassed this wrap and stringified the
+  // closure — the bug fixed by this restructure.
+  //
+  // Uses renderEffect (lighter than effect — no scope registration, no
+  // WeakMap) since lifecycle is managed by mountElement's cleanup array.
   if (typeof value === 'function') {
-    const dispose = renderEffect(() => setStaticProp(el, key, (value as () => unknown)()))
-    return dispose
+    return renderEffect(() => applyStaticProp(el, key, (value as () => unknown)()))
   }
 
-  setStaticProp(el, key, value)
+  applyStaticProp(el, key, value)
   return null
 }
 

package/src/tests/manifest-snapshot.test.ts

@@ -0,0 +1,84 @@
+import {
+  renderApiReferenceEntries,
+  renderLlmsFullSection,
+  renderLlmsTxtLine,
+} from '@pyreon/manifest'
+import runtimeDomManifest from '../manifest'
+
+describe('gen-docs — runtime-dom snapshot', () => {
+  it('renders @pyreon/runtime-dom to its expected llms.txt bullet', () => {
+    expect(renderLlmsTxtLine(runtimeDomManifest)).toMatchInlineSnapshot(`"- @pyreon/runtime-dom — DOM renderer, mount, hydrateRoot, Transition, TransitionGroup, KeepAlive, SVG/MathML namespace, custom elements. SVG and MathML elements ALWAYS use \`setAttribute()\` for prop forwarding, never property assignment. Many SVG properties (\`markerWidth\`, \`refX\`, etc.) are read-only \`SVGAnimatedLength\` getters — \`el[key] = value\` crashes. Detected by \`el.namespaceURI !== "http://www.w3.org/1999/xhtml"\`."`)
+  })
+
+  it('renders @pyreon/runtime-dom to its expected llms-full.txt section — full body snapshot', () => {
+    expect(renderLlmsFullSection(runtimeDomManifest)).toMatchInlineSnapshot(`
+      "## @pyreon/runtime-dom — DOM Renderer
+
+      Surgical signal-to-DOM renderer with zero virtual DOM overhead. The compiler emits \`_tpl()\` (cloneNode-based template instantiation) + \`_bind()\` (per-node reactive bindings) calls that mount directly to the DOM without VNode diffing. Reactive text uses \`TextNode.data\` assignment (not \`.textContent\`) for minimal DOM mutation. Supports SVG/MathML namespace auto-detection (67 tags), custom elements (props as properties), CSS transitions via \`<Transition>\` / \`<TransitionGroup>\`, and component caching via \`<KeepAlive>\`. Dev-mode warnings use \`import.meta.env.DEV\` (not \`typeof process\`) so they tree-shake to zero bytes in production Vite builds.
+
+      \`\`\`typescript
+      import { mount, hydrateRoot, Transition, TransitionGroup, KeepAlive } from "@pyreon/runtime-dom"
+      import { signal } from "@pyreon/reactivity"
+      import { Show, For } from "@pyreon/core"
+
+      // Mount — clears container, returns unmount function
+      const unmount = mount(<App />, document.getElementById("app")!)
+
+      // Hydrate SSR-rendered HTML (preserves existing DOM)
+      hydrateRoot(<App />, document.getElementById("app")!)
+
+      // Transition — CSS-based enter/leave animations
+      const visible = signal(true)
+      const FadeExample = () => (
+        <Transition name="fade" mode="out-in">
+          <Show when={visible()}>
+            <div>Content</div>
+          </Show>
+        </Transition>
+      )
+      // CSS: .fade-enter-active, .fade-leave-active { transition: opacity 0.3s }
+      //      .fade-enter-from, .fade-leave-to { opacity: 0 }
+
+      // TransitionGroup — animate list items entering/leaving
+      const items = signal([1, 2, 3])
+      const ListExample = () => (
+        <TransitionGroup name="list">
+          <For each={items()} by={i => i}>
+            {item => <div>{item}</div>}
+          </For>
+        </TransitionGroup>
+      )
+
+      // KeepAlive — cache component state across mount/unmount cycles
+      const tab = signal<"a" | "b">("a")
+      const TabExample = () => (
+        <KeepAlive>
+          <Show when={tab() === "a"}><ExpensiveA /></Show>
+          <Show when={tab() === "b"}><ExpensiveB /></Show>
+        </KeepAlive>
+      )
+      \`\`\`
+
+      > **SVG/MathML uses setAttribute only**: SVG and MathML elements ALWAYS use \`setAttribute()\` for prop forwarding, never property assignment. Many SVG properties (\`markerWidth\`, \`refX\`, etc.) are read-only \`SVGAnimatedLength\` getters — \`el[key] = value\` crashes. Detected by \`el.namespaceURI !== "http://www.w3.org/1999/xhtml"\`.
+      >
+      > **Custom elements use property assignment**: Elements with a hyphen in their tag name (custom elements) get props set as JS properties, not HTML attributes. This matches the web components spec — attributes are strings, properties can be any type.
+      >
+      > **Transition 5s safety timeout**: If \`transitionend\` or \`animationend\` never fires (missing CSS, display:none, zero-duration), the transition completes automatically after 5 seconds to prevent stuck UI.
+      >
+      > **Dev warnings use import.meta.env.DEV**: All dev-mode warnings (\`mount()\` null container, duplicate keys, raw signal children) use \`import.meta.env.DEV\` — NOT \`typeof process\`. Vite/Rolldown literal-replaces it at build time; production bundles contain zero warning bytes. Tests run in vitest which sets DEV=true automatically.
+      >
+      > **Event delegation**: \`setupDelegation(container)\` is called by \`mount()\` — common events are delegated to the container root for performance. Direct event binding (non-delegated) is used for events that do not bubble (focus, blur, scroll, etc.).
+      "
+    `)
+  })
+
+  it('renders @pyreon/runtime-dom to MCP api-reference entries — one per api[] item', () => {
+    const record = renderApiReferenceEntries(runtimeDomManifest)
+    expect(Object.keys(record).length).toBe(9)
+    expect(Object.keys(record)).toContain('runtime-dom/mount')
+    // Spot-check the flagship API — mount is the primary entry point
+    const mount = record['runtime-dom/mount']!
+    expect(mount.notes).toContain('container')
+    expect(mount.mistakes?.split('\n').length).toBeGreaterThan(2)
+  })
+})

package/src/tests/mount.test.ts

@@ -3177,6 +3177,95 @@ describe('TransitionGroup — cleanup', () => {
   })
 })
 
+// ─── TransitionGroup — leak regression tests ─────────────────────────────────
+// Regression for the two fixes:
+// 1. No safety timeout on applyLeave meant an item whose transition never
+//    fired stayed in the `entries` Map forever (`entries.delete(key)` was
+//    gated on the `done` callback firing).
+// 2. Unmount during in-flight transition left the 5s safety timer running,
+//    firing `onAfterEnter` / `onAfterLeave` on detached elements.
+
+describe('TransitionGroup — leak regressions', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  test('onAfterLeave fires via 5s safety timeout when transitionend never fires', async () => {
+    const el = container()
+    const items = signal([{ id: 1 }, { id: 2 }])
+    const onAfterLeave = vi.fn()
+    mount(
+      h(TransitionGroup, {
+        tag: 'div',
+        name: 'fade',
+        items,
+        keyFn: (item: { id: number }) => item.id,
+        render: (item: { id: number }) => h('span', { class: 'item' }, String(item.id)),
+        onAfterLeave,
+      }),
+      el,
+    )
+    await vi.advanceTimersByTimeAsync(20)
+    items.set([{ id: 1 }])
+    await vi.advanceTimersByTimeAsync(20)
+    // transitionend never fires — before the fix this would leak forever.
+    expect(onAfterLeave).not.toHaveBeenCalled()
+    await vi.advanceTimersByTimeAsync(5100)
+    expect(onAfterLeave).toHaveBeenCalledTimes(1)
+  })
+
+  test('onAfterEnter does NOT fire after container unmount during in-flight enter', async () => {
+    const el = container()
+    const items = signal<{ id: number }[]>([])
+    const onAfterEnter = vi.fn()
+    const dispose = mount(
+      h(TransitionGroup, {
+        tag: 'div',
+        name: 'fade',
+        items,
+        keyFn: (item: { id: number }) => item.id,
+        render: (item: { id: number }) => h('span', { class: 'item' }, String(item.id)),
+        onAfterEnter,
+      }),
+      el,
+    )
+    await vi.advanceTimersByTimeAsync(20)
+    items.set([{ id: 1 }])
+    await vi.advanceTimersByTimeAsync(20)
+    // Mid-transition — unmount. The 5s safety timer must NOT fire the
+    // callback on a detached element.
+    dispose()
+    await vi.advanceTimersByTimeAsync(6000)
+    expect(onAfterEnter).not.toHaveBeenCalled()
+  })
+
+  test('onAfterLeave does NOT fire after container unmount during in-flight leave', async () => {
+    const el = container()
+    const items = signal([{ id: 1 }])
+    const onAfterLeave = vi.fn()
+    const dispose = mount(
+      h(TransitionGroup, {
+        tag: 'div',
+        name: 'fade',
+        items,
+        keyFn: (item: { id: number }) => item.id,
+        render: (item: { id: number }) => h('span', { class: 'item' }, String(item.id)),
+        onAfterLeave,
+      }),
+      el,
+    )
+    await vi.advanceTimersByTimeAsync(20)
+    items.set([])
+    await vi.advanceTimersByTimeAsync(20)
+    dispose()
+    await vi.advanceTimersByTimeAsync(6000)
+    expect(onAfterLeave).not.toHaveBeenCalled()
+  })
+})
+
 // ─── Error paths (no ErrorBoundary) ──────────────────────────────────────────
 
 describe('mount — error paths', () => {