@pyreon/runtime-dom 0.14.0 → 0.16.0

package/src/nodes.ts

@@ -7,8 +7,7 @@ import { effect, runUntracked } from '@pyreon/reactivity'
 
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
 
 // Dev-time counter sink — see packages/internals/perf-harness for contract.
 const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
@@ -38,6 +37,11 @@ function clearBetween(start: Node, end: Node): void {
   // frag goes out of scope → nodes are GC-eligible
 }
 
+/** Emit `runtime.cleanup` once per registered mount cleanup that actually runs. */
+function _emitCleanup(): void {
+  if (__DEV__) _countSink.__pyreon_count__?.('runtime.cleanup')
+}
+
 /**
  * Mount a reactive node whose content changes over time.
  *
@@ -50,6 +54,7 @@ export function mountReactive(
   anchor: Node | null,
   mount: (child: VNodeChild, p: Node, a: Node | null) => Cleanup,
 ): Cleanup {
+  if (__DEV__) _countSink.__pyreon_count__?.('runtime.mountReactive')
   const marker = document.createComment('pyreon')
   parent.insertBefore(marker, anchor)
 
@@ -62,6 +67,9 @@ export function mountReactive(
   let currentCleanup: Cleanup = () => {
     /* noop */
   }
+  // hasCleanup gates `runtime.cleanup` so we don't count the placeholder
+  // noop on the first effect run as a "cleanup invocation".
+  let hasCleanup = false
   let generation = 0
 
   const e = effect(() => {
@@ -69,10 +77,12 @@ export function mountReactive(
     // Run cleanup outside tracking context — cleanup may write to signals
     // (e.g. onUnmount hooks), and those writes must not accidentally register
     // as dependencies of this effect, which would cause infinite recursion.
+    if (hasCleanup) _emitCleanup()
     runUntracked(() => currentCleanup())
     currentCleanup = () => {
       /* noop */
     }
+    hasCleanup = false
     const value = accessor()
     // Note: typeof value === 'function' is a VALID return from a reactive
     // accessor — it represents a nested `() => VNodeChild` accessor (the
@@ -99,7 +109,9 @@ export function mountReactive(
       // set by the re-entrant run.
       if (myGen === generation) {
         currentCleanup = cleanup
+        hasCleanup = true
       } else {
+        _emitCleanup()
         cleanup()
       }
     }
@@ -107,6 +119,7 @@ export function mountReactive(
 
   return () => {
     e.dispose()
+    if (hasCleanup) _emitCleanup()
     currentCleanup()
     marker.parentNode?.removeChild(marker)
   }
@@ -271,6 +284,7 @@ export function mountKeyedList(
   const removeStaleEntries = (newKeySet: Set<string | number>) => {
     for (const [key, entry] of cache) {
       if (newKeySet.has(key)) continue
+      _emitCleanup()
       entry.cleanup()
       entry.anchor.parentNode?.removeChild(entry.anchor)
       cache.delete(key)
@@ -294,35 +308,42 @@ export function mountKeyedList(
   const e = effect(() => {
     const newList = accessor()
     const n = newList.length
+    // Same untracking rationale as mountFor — see comment there. Child
+    // mounts via mountVNode must not re-track on this effect's run.
+    runUntracked(() => {
+      if (n === 0 && cache.size > 0) {
+        for (const entry of cache.values()) {
+          _emitCleanup()
+          entry.cleanup()
+        }
+        cache.clear()
+        curPos.clear()
+        currentKeyOrder = []
+        clearBetween(startMarker, tailMarker)
+        return
+      }
 
-    if (n === 0 && cache.size > 0) {
-      for (const entry of cache.values()) entry.cleanup()
-      cache.clear()
-      curPos.clear()
-      currentKeyOrder = []
-      clearBetween(startMarker, tailMarker)
-      return
-    }
-
-    const { newKeyOrder, newKeySet } = collectKeyOrder(newList)
-    removeStaleEntries(newKeySet)
-    mountNewEntries(newList)
+      const { newKeyOrder, newKeySet } = collectKeyOrder(newList)
+      removeStaleEntries(newKeySet)
+      mountNewEntries(newList)
 
-    if (currentKeyOrder.length > 0 && n > 0) {
-      lis = keyedListReorder(lis, n, newKeyOrder, curPos, cache, parent, tailMarker)
-    }
+      if (currentKeyOrder.length > 0 && n > 0) {
+        lis = keyedListReorder(lis, n, newKeyOrder, curPos, cache, parent, tailMarker)
+      }
 
-    curPos.clear()
-    for (let i = 0; i < newKeyOrder.length; i++) {
-      const k = newKeyOrder[i]
-      if (k !== undefined) curPos.set(k, i)
-    }
-    currentKeyOrder = newKeyOrder
+      curPos.clear()
+      for (let i = 0; i < newKeyOrder.length; i++) {
+        const k = newKeyOrder[i]
+        if (k !== undefined) curPos.set(k, i)
+      }
+      currentKeyOrder = newKeyOrder
+    })
   })
 
   return () => {
     e.dispose()
     for (const entry of cache.values()) {
+      _emitCleanup()
       entry.cleanup()
       entry.anchor.parentNode?.removeChild(entry.anchor)
     }
@@ -603,7 +624,12 @@ export function mountFor<T>(
     liveParent: Node,
   ) => {
     if (cleanupCount > 0) {
-      for (const entry of cache.values()) if (entry.cleanup) entry.cleanup()
+      for (const entry of cache.values()) {
+        if (entry.cleanup) {
+          _emitCleanup()
+          entry.cleanup()
+        }
+      }
     }
     cache = new Map()
     cleanupCount = 0
@@ -635,6 +661,7 @@ export function mountFor<T>(
     for (const [key, entry] of cache) {
       if (newKeySet.has(key)) continue
       if (entry.cleanup) {
+        _emitCleanup()
         entry.cleanup()
         cleanupCount--
       }
@@ -661,7 +688,12 @@ export function mountFor<T>(
   const handleFastClear = (liveParent: Node) => {
     if (cache.size === 0) return
     if (cleanupCount > 0) {
-      for (const entry of cache.values()) if (entry.cleanup) entry.cleanup()
+      for (const entry of cache.values()) {
+        if (entry.cleanup) {
+          _emitCleanup()
+          entry.cleanup()
+        }
+      }
     }
     const pp = liveParent.parentNode
     if (pp && liveParent.firstChild === startMarker && liveParent.lastChild === tailMarker) {
@@ -716,31 +748,45 @@ export function mountFor<T>(
     if (!liveParent) return
     const items = source()
     const n = items.length
+    // Child mounts (renderInto → mountChild) must NOT re-track on this
+    // effect's run, mirroring mountReactive's pattern at line ~92. Without
+    // this, any signal read during a child component's setup (e.g. useQuery
+    // calling `new QueryObserver(client, options())` at construction time,
+    // which reads any signals inside the options builder) leaks its
+    // subscription up to the For effect. A flip of the unrelated signal
+    // re-runs For, runCleanup() disposes ALL inner effects, and
+    // handleIncrementalUpdate skips re-mount on key match — leaving the
+    // subtree's inner effects gone forever. Reproduced by the
+    // `<For>`-shaped test in fanout-repro.test.tsx; deferred from PR #490.
+    runUntracked(() => {
+      if (n === 0) {
+        handleFastClear(liveParent)
+        return
+      }
 
-    if (n === 0) {
-      handleFastClear(liveParent)
-      return
-    }
-
-    if (currentKeys.length === 0) {
-      handleFreshRender(items, n, liveParent)
-      return
-    }
+      if (currentKeys.length === 0) {
+        handleFreshRender(items, n, liveParent)
+        return
+      }
 
-    const newKeys = collectNewKeys(items, n)
+      const newKeys = collectNewKeys(items, n)
 
-    if (!hasAnyKeptKey(n, newKeys)) {
-      handleReplaceAll(items, n, newKeys, liveParent)
-      return
-    }
+      if (!hasAnyKeptKey(n, newKeys)) {
+        handleReplaceAll(items, n, newKeys, liveParent)
+        return
+      }
 
-    handleIncrementalUpdate(items, n, newKeys, liveParent)
+      handleIncrementalUpdate(items, n, newKeys, liveParent)
+    })
   })
 
   return () => {
     e.dispose()
     for (const entry of cache.values()) {
-      if (cleanupCount > 0 && entry.cleanup) entry.cleanup()
+      if (cleanupCount > 0 && entry.cleanup) {
+        _emitCleanup()
+        entry.cleanup()
+      }
       entry.anchor.parentNode?.removeChild(entry.anchor)
     }
     cache = new Map()

package/src/props.ts

@@ -8,8 +8,10 @@ type Cleanup = () => void
 
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
+
+// Dev-time counter sink — see packages/internals/perf-harness for contract.
+const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
 
 // ─── Configurable sanitizer ──────────────────────────────────────────────────
 
@@ -206,6 +208,7 @@ export function applyProps(el: Element, props: Props): Cleanup | null {
  * Bind an event handler (onClick → "click") with batching + delegation support.
  */
 function applyEventProp(el: Element, key: string, value: unknown): Cleanup | null {
+  if (__DEV__) _countSink.__pyreon_count__?.('runtime.applyEvent')
   if (typeof value !== 'function') {
     // `undefined` and `null` are legitimate — conditional handler pattern:
     //   <button onClick={condition ? handler : undefined}>
@@ -296,7 +299,13 @@ function applyStaticProp(el: Element, key: string, value: unknown): void {
   setStaticProp(el, key, value)
 }
 
+// `runtime.applyProp` fires for EVERY prop key, including events. `runtime.applyEvent`
+// fires only for `on*` props — strict subset. Useful diagnostic ratios:
+//   applyEvent / applyProp = event-handler density per element
+//   applyProp - applyEvent = static / reactive attr density
+// Don't subtract them and treat as disjoint.
 export function applyProp(el: Element, key: string, value: unknown): Cleanup | null {
+  if (__DEV__) _countSink.__pyreon_count__?.('runtime.applyProp')
   // Event listener: onClick → "click"
   if (EVENT_RE.test(key)) return applyEventProp(el, key, value)
 

package/src/template.ts

@@ -4,8 +4,7 @@ import { mountChild } from './mount'
 
 // Dev-mode gate: see `pyreon/no-process-dev-gate` lint rule for why this
 // uses `import.meta.env.DEV` instead of `typeof process !== 'undefined'`.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
 
 // Dev-time counter sink — see packages/internals/perf-harness for contract.
 const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
@@ -72,6 +71,7 @@ export function _bindText(
   source: { _v?: unknown; direct?: (fn: () => void) => () => void },
   node: Text,
 ): () => void {
+  if (__DEV__) _countSink.__pyreon_count__?.('runtime.bindText')
   // Fast path: source has .direct() (signal or computed)
   if (source.direct) {
     const textUpdate = () => {
@@ -113,6 +113,7 @@ export function _bindDirect(
   source: { _v?: unknown; direct?: (fn: () => void) => () => void },
   updater: (value: unknown) => void,
 ): () => void {
+  if (__DEV__) _countSink.__pyreon_count__?.('runtime.bindDirect')
   // Fast path: source has .direct() (signal or computed)
   if (source.direct) {
     updater(source._v)
@@ -126,6 +127,22 @@ export function _bindDirect(
 // ─── Compiler-facing template API ─────────────────────────────────────────────
 
 // Cache parsed <template> elements by HTML string — parse once, clone many.
+//
+// LRU bound (audit bug #5): typical apps emit a small bounded set of unique
+// HTML strings (one per JSX element tree the compiler hoists), so the cache
+// stays in the dozens-to-hundreds in practice. But an app that constructs
+// JSX from user input (or compiles many large dynamic templates) could grow
+// this unbounded — every unique string holds a parsed <template> alive.
+//
+// Map preserves insertion order; on overflow we evict the OLDEST entry (the
+// least-recently-inserted). Common HTML strings hit the cache before
+// eviction; pathological inputs cycle through the cap without leaking.
+//
+// 1024 chosen as a balance: ~1024 unique templates × ~1KB parsed = ~1MB
+// worst case — well within memory budget for any realistic app, and
+// generous enough that no real codebase will hit the cap. Apps that
+// genuinely need a different cap can swap their own _tpl wrapper.
+const TPL_CACHE_MAX = 1024
 const _tplCache = new Map<string, HTMLTemplateElement>()
 
 /**
@@ -157,6 +174,18 @@ export function _tpl(html: string, bind: (el: HTMLElement) => (() => void) | nul
   if (!tpl) {
     tpl = document.createElement('template')
     tpl.innerHTML = html
+    // LRU eviction — drop the oldest entry once we hit the cap. Map
+    // iteration is insertion-order so the first key is always the
+    // oldest. delete() is O(1).
+    if (_tplCache.size >= TPL_CACHE_MAX) {
+      const oldest = _tplCache.keys().next().value
+      if (oldest !== undefined) _tplCache.delete(oldest)
+    }
+    _tplCache.set(html, tpl)
+  } else {
+    // LRU touch — re-insert moves to most-recent position so frequently
+    // used templates survive eviction.
+    _tplCache.delete(html)
     _tplCache.set(html, tpl)
   }
   const el = tpl.content.firstElementChild?.cloneNode(true) as HTMLElement
@@ -164,6 +193,23 @@ export function _tpl(html: string, bind: (el: HTMLElement) => (() => void) | nul
   return { __isNative: true, el, cleanup }
 }
 
+/**
+ * Test-only: clear the template cache. Used by tests that assert on
+ * cache size; never called by runtime code. Not exported from the
+ * package's public index.
+ */
+export function _clearTplCache(): void {
+  _tplCache.clear()
+}
+
+/**
+ * Test-only: read current cache size. Used by tests that assert
+ * eviction. Not exported from the package's public index.
+ */
+export function _tplCacheSize(): number {
+  return _tplCache.size
+}
+
 /**
  * Mount a children slot inside a template.
  *

package/src/tests/dev-gate-pattern.test.ts

@@ -8,22 +8,27 @@ const SRC = path.resolve(here, '..')
 
 // Source-pattern regression test for the dev-mode warning gate. Pairs with
 // the browser test in `runtime-dom.browser.test.ts` (which proves the gate
-// fires in dev) — this asserts the gate is written using the pattern that
-// Vite/Rolldown can literal-replace at build time, NOT the broken
-// `typeof process` pattern that PR #200 cleaned up.
+// fires in dev) — this asserts the gate is written using the bundler-agnostic
+// pattern (`process.env.NODE_ENV !== 'production'`) that every modern bundler
+// (Vite, Webpack/Next.js, esbuild, Rollup, Parcel, Bun) literal-replaces at
+// consumer build time. The two previously-shipped broken patterns must not
+// appear:
+//   1. `typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'`
+//      — dead in Vite browser bundles.
+//   2. `import.meta.env.DEV` — Vite/Rolldown-only; undefined and silent in
+//      Webpack/Next.js, esbuild, Rollup, Parcel, Bun.
 //
 // Same shape as `flow/src/tests/integration.test.ts:warnIgnoredOptions`.
 //
-// The lint rule `pyreon/no-process-dev-gate` (introduced in PR #220) is the
-// CI-wide enforcement for this. This test is the narrow, package-local
-// safety net so a regression in runtime-dom is caught even if the lint
-// configuration drifts.
+// The lint rule `pyreon/no-process-dev-gate` is the CI-wide enforcement for
+// this. This test is the narrow, package-local safety net so a regression in
+// runtime-dom is caught even if the lint configuration drifts.
 
 const FILES_WITH_DEV_GATE = ['nodes.ts', 'hydration-debug.ts']
 
 describe('runtime-dom dev-warning gate (source pattern)', () => {
   for (const file of FILES_WITH_DEV_GATE) {
-    it(`${file} uses import.meta.env.DEV, not typeof process`, async () => {
+    it(`${file} uses bundler-agnostic process.env.NODE_ENV`, async () => {
       const source = await readFile(path.join(SRC, file), 'utf8')
       // Strip line + block comments so referencing the broken pattern in
       // documentation doesn't false-positive.
@@ -31,10 +36,11 @@ describe('runtime-dom dev-warning gate (source pattern)', () => {
         .replace(/\/\*[\s\S]*?\*\//g, '')
         .replace(/(^|[^:])\/\/.*$/gm, '$1')
 
-      // The gate constant must exist, defined via Vite's literal-replaced env.
-      expect(code).toMatch(/const\s+__DEV__\s*=\s*import\.meta\.env\??\.DEV/)
-      // The broken pattern must not appear anywhere in executable code.
+      // The bundler-agnostic gate must appear (bare `process.env.NODE_ENV`).
+      expect(code).toMatch(/process\.env\.NODE_ENV/)
+      // Neither broken pattern may appear in executable code.
       expect(code).not.toMatch(/typeof\s+process\s*!==?\s*['"]undefined['"]/)
+      expect(code).not.toMatch(/import\.meta\.env\??\.DEV/)
     })
   }
 })

package/src/tests/dev-gate-treeshake.test.ts

@@ -8,28 +8,24 @@ import { build } from 'vite'
 const here = path.dirname(fileURLToPath(import.meta.url))
 const SRC = path.resolve(here, '..')
 
-// Bundle-level regression test for the T1.1 C-2 finding.
+// Bundle-level regression test for the dev-warning gate.
 //
-// Background — the shape of the problem from PR #227 bring-up:
-//   Raw `esbuild --minify` preserves chained `__DEV__ && cond &&
-//   console.warn(...)` patterns even when `import.meta.env.DEV` is
-//   defined to `false`. That tempted a pattern-rewrite across all
-//   Pyreon sources.
+// runtime-dom uses bundler-agnostic `process.env.NODE_ENV !== 'production'`
+// for dev gates — the cross-bundler library convention used by React, Vue,
+// Preact, Solid, MobX, Redux. Every modern bundler (Vite, Webpack/Next.js,
+// esbuild, Rollup, Parcel, Bun) auto-replaces `process.env.NODE_ENV` at
+// consumer build time. This test bundles each representative runtime-dom
+// file through Vite's production build and asserts dev-warning strings
+// are GONE from the output — proving literal-replacement + dead-code
+// elimination work end-to-end.
 //
-// What the C-2 investigation actually found:
-//   Pyreon's real consumer path is Vite (which uses Rolldown under the
-//   hood plus its own import.meta.env replacement + tree-shake passes).
-//   Vite's production build DOES eliminate the chained patterns
-//   correctly — the raw esbuild baseline was misleading. Raw Rolldown
-//   alone also doesn't replicate Vite's behavior because Rolldown's
-//   `define` doesn't rewrite optional-chain access paths.
+// The test uses Vite because that's Pyreon's reference consumer pipeline
+// today; the same files under Webpack / esbuild / Rollup etc. tree-shake
+// equivalently because they all replace `process.env.NODE_ENV`. Vite is
+// just the most-tested path.
 //
-// This test bundles a runtime-dom entry through Vite's production
-// build and asserts dev-warning strings are GONE. If Vite's handling
-// ever regresses, this catches it.
-//
-// Scope note: the existing `dev-gate-pattern.test.ts` is the cheap
-// source-level guard (grep for `typeof process`, require `import.meta.env.DEV`).
+// Scope note: `dev-gate-pattern.test.ts` is the cheap source-level guard
+// (grep for the broken patterns, require bare `process.env.NODE_ENV`).
 // This test is the expensive end-to-end guard for the bundle path.
 
 interface FileContract {
@@ -84,19 +80,17 @@ const FILES_UNDER_TEST: FileContract[] = [
 async function bundleWithVite(entry: string, dev: boolean): Promise<string> {
   const outDir = mkdtempSync(path.join(tmpdir(), 'pyreon-vite-treeshake-'))
   try {
-    // Vite library-mode build with explicit minify. `define` on
-    // `import.meta.env` isn't usually needed (Vite sets it automatically
-    // based on mode), but `mode: 'production'` flips DEV to false.
+    // Vite library-mode build with explicit minify. The bundler-agnostic
+    // gate uses `process.env.NODE_ENV` — Vite's library mode doesn't apply
+    // the default replacement automatically, so we set it ourselves to
+    // match what every modern bundler does at consumer build time.
     await build({
       mode: dev ? 'development' : 'production',
       logLevel: 'error',
       configFile: false,
       resolve: { conditions: ['bun'] },
-      // Explicit define — Vite in lib mode doesn't always apply the
-      // default production env replacement, so we set it ourselves.
       define: {
-        'import.meta.env.DEV': JSON.stringify(dev),
-        'import.meta.env': JSON.stringify({ DEV: dev, PROD: !dev, MODE: dev ? 'development' : 'production' }),
+        'process.env.NODE_ENV': JSON.stringify(dev ? 'development' : 'production'),
       },
       build: {
         // PINNED minifier: 'esbuild' is what Pyreon's reference consumers