@pyreon/runtime-dom 0.13.1 → 0.15.0

package/src/index.ts

@@ -3,12 +3,27 @@
 export { DELEGATED_EVENTS, delegatedPropName, setupDelegation } from './delegate'
 export type { DevtoolsComponentEntry, PyreonDevtools } from './devtools'
 export { hydrateRoot } from './hydrate'
-export { disableHydrationWarnings, enableHydrationWarnings } from './hydration-debug'
+export type {
+  HydrationMismatchContext,
+  HydrationMismatchHandler,
+  HydrationMismatchType,
+} from './hydration-debug'
+export {
+  disableHydrationWarnings,
+  enableHydrationWarnings,
+  onHydrationMismatch,
+} from './hydration-debug'
 export type { KeepAliveProps } from './keep-alive'
 export { KeepAlive } from './keep-alive'
 export { mountChild } from './mount'
 export type { SanitizeFn } from './props'
-export { applyProp, applyProps, applyProps as _applyProps, sanitizeHtml, setSanitizer } from './props'
+export {
+  applyProp,
+  applyProps,
+  applyProps as _applyProps,
+  sanitizeHtml,
+  setSanitizer,
+} from './props'
 export { _bindDirect, _bindText, _mountSlot, _tpl, createTemplate } from './template'
 export type { TransitionProps } from './transition'
 export { Transition } from './transition'
@@ -22,8 +37,10 @@ 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 }
 
 /**
  * Mount a VNode tree into a container element.
@@ -39,10 +56,17 @@ export function mount(root: VNodeChild, container: Element): () => void {
       '[pyreon] mount() called with a null/undefined container. Make sure the element exists in the DOM, e.g. document.getElementById("app")',
     )
   }
-  installDevTools()
+  if (__DEV__) {
+    _countSink.__pyreon_count__?.('runtime.mount')
+    installDevTools()
+  }
   setupDelegation(container)
   container.innerHTML = ''
-  return mountChild(root, container, null)
+  const unmount = mountChild(root, container, null)
+  return () => {
+    if (__DEV__) _countSink.__pyreon_count__?.('runtime.unmount')
+    unmount()
+  }
 }
 
 /** Alias for `mount` */

package/src/keep-alive-entry.ts

@@ -0,0 +1,3 @@
+// Subpath entry for @pyreon/runtime-dom/keep-alive
+export type { KeepAliveProps } from './keep-alive'
+export { KeepAlive } from './keep-alive'

package/src/keep-alive.ts

@@ -1,5 +1,5 @@
 import type { Props, VNodeChild } from '@pyreon/core'
-import { createRef, h, onMount } from '@pyreon/core'
+import { createRef, h, nativeCompat, onMount } from '@pyreon/core'
 import { effect } from '@pyreon/reactivity'
 import { mountChild } from './mount'
 
@@ -70,3 +70,7 @@ export function KeepAlive(props: KeepAliveProps): VNodeChild {
   // (children appear as if directly in the parent flow)
   return h('div', { ref: containerRef, style: 'display: contents' })
 }
+
+// Mark as native so compat-mode jsx() runtimes skip wrapCompatComponent —
+// KeepAlive uses onMount + effect + mountChild that need Pyreon's setup frame.
+nativeCompat(KeepAlive)

package/src/mount.ts

@@ -25,8 +25,10 @@ import { applyProps } from './props'
 
 // 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 }
 
 type Cleanup = () => void
 const noop: Cleanup = () => {
@@ -40,7 +42,9 @@ let _elementDepth = 0
 
 // Stack tracking which component is currently being mounted (depth-first order).
 // Used to infer parent/child relationships for DevTools.
-const _mountingStack: string[] = []
+// Only allocated in dev — production mounts skip devtools entirely.
+let _mountingStack: string[] | undefined
+if (__DEV__) _mountingStack = []
 
 /**
  * Mount a single child into `parent`, inserting before `anchor` (null = append).
@@ -54,6 +58,7 @@ export function mountChild(
   parent: Node,
   anchor: Node | null = null,
 ): Cleanup {
+  if (__DEV__) _countSink.__pyreon_count__?.('runtime.mountChild')
   // Reactive accessor — function that reads signals
   if (typeof child === 'function') {
     const sample = runUntracked(() => (child as () => VNodeChild | VNodeChild[])())
@@ -72,7 +77,8 @@ export function mountChild(
       parent.insertBefore(text, anchor)
       const dispose = renderEffect(() => {
         const v = (child as () => unknown)()
-        text.data = v == null || v === false ? '' : String(v as string | number)
+        const next = v == null || v === false ? '' : String(v as string | number)
+        if (next !== text.data) text.data = next
       })
       if (_elementDepth > 0) return dispose
       return () => {
@@ -125,10 +131,30 @@ export function mountChild(
   if (vnode.type === Fragment) return mountChildren(vnode.children ?? [], parent, anchor)
 
   if (vnode.type === (ForSymbol as unknown as string)) {
-    const { each, by, children } = vnode.props as unknown as ForProps<unknown>
+    // Compiler wraps `<For each={signal}>` in `_rp(() => signal())` →
+    // `props.each` is a getter that returns the resolved array, not the
+    // function. Destructuring eagerly captures the array and breaks
+    // reactivity + crashes mountFor (which calls `source()`). Read each
+    // lazily so the _rp getter fires inside mountFor's effect, preserving
+    // signal tracking. User-written `each={() => fn()}` (already a
+    // function, not _rp-wrapped) still works because props.each is the
+    // function itself.
+    const props = vnode.props as unknown as ForProps<unknown>
+    const initialEach = props.each as unknown
+    const source: () => unknown[] =
+      typeof initialEach === 'function'
+        ? (initialEach as () => unknown[])
+        : (() => props.each as unknown as unknown[])
     const prevDepth = _elementDepth
     _elementDepth = 0
-    const cleanup = mountFor(each, by, children, parent, anchor, mountChild)
+    const cleanup = mountFor(
+      source as () => unknown[],
+      props.by,
+      props.children,
+      parent,
+      anchor,
+      mountChild,
+    )
     _elementDepth = prevDepth
     return cleanup
   }
@@ -189,21 +215,81 @@ const MATHML_NS = 'http://www.w3.org/1998/Math/MathML'
 
 // Tags that require namespace-aware creation
 const SVG_TAGS = new Set([
-  'svg', 'circle', 'ellipse', 'line', 'path', 'polygon', 'polyline', 'rect',
-  'g', 'defs', 'symbol', 'use', 'text', 'tspan', 'textPath', 'image',
-  'clipPath', 'mask', 'pattern', 'marker', 'linearGradient', 'radialGradient',
-  'stop', 'filter', 'feBlend', 'feColorMatrix', 'feComponentTransfer',
-  'feComposite', 'feConvolveMatrix', 'feDiffuseLighting', 'feDisplacementMap',
-  'feFlood', 'feGaussianBlur', 'feImage', 'feMerge', 'feMergeNode',
-  'feMorphology', 'feOffset', 'feSpecularLighting', 'feTile', 'feTurbulence',
-  'animate', 'animateMotion', 'animateTransform', 'set', 'desc', 'title',
-  'metadata', 'foreignObject',
+  'svg',
+  'circle',
+  'ellipse',
+  'line',
+  'path',
+  'polygon',
+  'polyline',
+  'rect',
+  'g',
+  'defs',
+  'symbol',
+  'use',
+  'text',
+  'tspan',
+  'textPath',
+  'image',
+  'clipPath',
+  'mask',
+  'pattern',
+  'marker',
+  'linearGradient',
+  'radialGradient',
+  'stop',
+  'filter',
+  'feBlend',
+  'feColorMatrix',
+  'feComponentTransfer',
+  'feComposite',
+  'feConvolveMatrix',
+  'feDiffuseLighting',
+  'feDisplacementMap',
+  'feFlood',
+  'feGaussianBlur',
+  'feImage',
+  'feMerge',
+  'feMergeNode',
+  'feMorphology',
+  'feOffset',
+  'feSpecularLighting',
+  'feTile',
+  'feTurbulence',
+  'animate',
+  'animateMotion',
+  'animateTransform',
+  'set',
+  'desc',
+  'title',
+  'metadata',
+  'foreignObject',
 ])
 
 const MATHML_TAGS = new Set([
-  'math', 'mi', 'mo', 'mn', 'ms', 'mtext', 'mspace', 'mrow', 'mfrac',
-  'msqrt', 'mroot', 'msub', 'msup', 'msubsup', 'munder', 'mover',
-  'munderover', 'mtable', 'mtr', 'mtd', 'mpadded', 'mphantom', 'menclose',
+  'math',
+  'mi',
+  'mo',
+  'mn',
+  'ms',
+  'mtext',
+  'mspace',
+  'mrow',
+  'mfrac',
+  'msqrt',
+  'mroot',
+  'msub',
+  'msup',
+  'msubsup',
+  'munder',
+  'mover',
+  'munderover',
+  'mtable',
+  'mtr',
+  'mtd',
+  'mpadded',
+  'mphantom',
+  'menclose',
 ])
 
 /** Track SVG context depth — children of <svg> inherit the SVG namespace. */
@@ -303,9 +389,17 @@ function mountComponent(
   let output: VNodeChild
 
   const componentName = (vnode.type.name || 'Anonymous') as string
-  const compId = `${componentName}-${Math.random().toString(36).slice(2, 9)}`
-  const parentId = _mountingStack[_mountingStack.length - 1] ?? null
-  _mountingStack.push(compId)
+
+  // Devtools: generate ID + track parent/child hierarchy (dev only).
+  // In production, compId/devParentId are never assigned — Vite tree-shakes
+  // all __DEV__ blocks + the devtools module import to zero bytes.
+  let compId: string | undefined
+  let devParentId: string | null | undefined
+  if (__DEV__) {
+    compId = `${componentName}-${Math.random().toString(36).slice(2, 9)}`
+    devParentId = _mountingStack![_mountingStack!.length - 1] ?? null
+    _mountingStack!.push(compId)
+  }
 
   // Merge vnode.children into props.children if not already set
   const children = vnode.children ?? []
@@ -320,14 +414,15 @@ function mountComponent(
   // Convert compiler-emitted () => expr wrappers into getter properties.
   // This makes component props reactive — reading props.state inside an
   // effect/computed tracks the underlying signals.
-  const mergedProps = rawProps === EMPTY_PROPS ? rawProps : makeReactiveProps(rawProps as Record<string, unknown>)
+  const mergedProps =
+    rawProps === EMPTY_PROPS ? rawProps : makeReactiveProps(rawProps as Record<string, unknown>)
 
   try {
     const result = runWithHooks(vnode.type, mergedProps)
     hooks = result.hooks
     output = result.vnode
   } catch (err) {
-    _mountingStack.pop()
+    if (__DEV__) _mountingStack!.pop()
     setCurrentScope(null)
     scope.stop()
     reportError({
@@ -362,7 +457,7 @@ function mountComponent(
           'Components must be synchronous — use lazy() + Suspense for async loading, ' +
           'or fetch data in onMount and store it in a signal.',
       )
-    } else if (!('type' in output) && !Array.isArray(output) && !((output as any).__isNative)) {
+    } else if (!('type' in output) && !Array.isArray(output) && !(output as any).__isNative) {
       // Objects without `type` that are NOT arrays (valid VNodeChild[])
       // and NOT NativeItems (from _tpl()) are invalid. Arrays come from
       // Fragment returns, NativeItems come from compiled templates.
@@ -372,15 +467,15 @@ function mountComponent(
     }
   }
 
-  for (const fn of hooks.update) {
-    scope.addUpdateHook(fn)
+  if (hooks.update) {
+    for (const fn of hooks.update) scope.addUpdateHook(fn)
   }
 
   let subtreeCleanup: Cleanup = noop
   try {
     subtreeCleanup = output != null ? mountChild(output, parent, anchor) : noop
   } catch (err) {
-    _mountingStack.pop()
+    if (__DEV__) _mountingStack!.pop()
     scope.stop()
     const handled = propagateError(err, hooks) || dispatchToErrorBoundary(err)
     if (!handled) {
@@ -396,44 +491,53 @@ function mountComponent(
     return noop
   }
 
-  _mountingStack.pop()
-
-  const firstEl = parent instanceof Element ? parent.firstElementChild : null
-  registerComponent(compId, componentName, firstEl, parentId)
+  if (__DEV__) {
+    _mountingStack!.pop()
+    const firstEl = parent instanceof Element ? parent.firstElementChild : null
+    registerComponent(compId!, componentName, firstEl, devParentId!)
+  }
 
-  // Fire onMount hooks inline — effects created inside are tracked by the scope
-  const mountCleanups: Cleanup[] = []
-  for (const fn of hooks.mount) {
-    try {
-      let cleanup: (() => void) | undefined
-      scope.runInScope(() => {
-        cleanup = fn() as (() => void) | undefined
-      })
-      if (cleanup) mountCleanups.push(cleanup)
-    } catch (err) {
-      console.error(`[Pyreon] Error in onMount hook of <${componentName}>:`, err)
-      reportError({ component: componentName, phase: 'mount', error: err, timestamp: Date.now() })
+  // Fire onMount hooks inline — effects created inside are tracked by the scope.
+  // Lazy-allocate mountCleanups only when an onMount callback returns a cleanup fn.
+  let mountCleanups: Cleanup[] | null = null
+  if (hooks.mount) {
+    for (const fn of hooks.mount) {
+      try {
+        let cleanup: (() => void) | undefined
+        scope.runInScope(() => {
+          cleanup = fn() as (() => void) | undefined
+        })
+        if (cleanup) {
+          if (mountCleanups === null) mountCleanups = []
+          mountCleanups.push(cleanup)
+        }
+      } catch (err) {
+        console.error(`[Pyreon] Error in onMount hook of <${componentName}>:`, err)
+        reportError({ component: componentName, phase: 'mount', error: err, timestamp: Date.now() })
+      }
     }
   }
 
   return () => {
-    unregisterComponent(compId)
+    if (__DEV__) unregisterComponent(compId!)
     scope.stop()
     subtreeCleanup()
-    for (const fn of hooks.unmount) {
-      try {
-        fn()
-      } catch (err) {
-        console.error(`[Pyreon] Error in onUnmount hook of <${componentName}>:`, err)
-        reportError({
-          component: componentName,
-          phase: 'unmount',
-          error: err,
-          timestamp: Date.now(),
-        })
+    if (hooks.unmount) {
+      for (const fn of hooks.unmount) {
+        try {
+          fn()
+        } catch (err) {
+          console.error(`[Pyreon] Error in onUnmount hook of <${componentName}>:`, err)
+          reportError({
+            component: componentName,
+            phase: 'unmount',
+            error: err,
+            timestamp: Date.now(),
+          })
+        }
       }
     }
-    for (const fn of mountCleanups) fn()
+    if (mountCleanups) for (const fn of mountCleanups) fn()
   }
 }
 

package/src/nodes.ts

@@ -7,8 +7,10 @@ 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 }
 
 type Cleanup = () => void
 
@@ -88,9 +90,7 @@ export function mountReactive(
       // (e.g. DynamicStyled's class swap effect). Those effects track
       // their own dependencies independently.
       const cleanup = runUntracked(() =>
-        restoreContextStack(contextSnapshot, () =>
-          mount(value, parent, marker),
-        ),
+        restoreContextStack(contextSnapshot, () => mount(value, parent, marker)),
       )
       // Guard: a re-entrant signal update (e.g. ErrorBoundary catching a child
       // throw) may have already re-run this effect and updated currentCleanup.
@@ -157,6 +157,7 @@ function computeKeyedLis(
 ): number {
   const { tails, tailIdx, pred } = lis
   let lisLen = 0
+  let ops = 0
   for (let i = 0; i < n; i++) {
     const key = newKeyOrder[i]
     if (key === undefined) continue
@@ -167,6 +168,7 @@ function computeKeyedLis(
     let hi = lisLen
     while (lo < hi) {
       const mid = (lo + hi) >> 1
+      ops++
       if ((tails[mid] as number) < v) lo = mid + 1
       else hi = mid
     }
@@ -175,6 +177,7 @@ function computeKeyedLis(
     if (lo > 0) pred[i] = tailIdx[lo - 1] as number
     if (lo === lisLen) lisLen++
   }
+  if (__DEV__ && ops > 0) _countSink.__pyreon_count__?.('runtime.mountFor.lisOps', ops)
   return lisLen
 }
 
@@ -379,21 +382,62 @@ function computeForLis(
 ): number {
   const { tails, tailIdx, pred } = lis
   let lisLen = 0
+  let ops = 0
+  // Two-tier fast path.
+  //
+  // Tier 1 — "extend LIS": if v > the current tail-of-tails, v becomes the
+  // new tail. O(1). Covers APPEND: positions [0..N-1] are strictly
+  // increasing → the whole sequence is the LIS, 0 probes.
+  //
+  // Tier 2 — "known slot": if v ≤ lastV but tails[v] === v already, the
+  // binary-search answer is provably lo = v (strict-increase invariant
+  // guarantees tails[v-1] < v, so v slots exactly at index v). O(1) too.
+  // Covers PREPEND: [new N rows, old M rows] produces positions [0..N-1,
+  // 0..M-1] — the second monotonic run replaces tails[0..M-1] at indices
+  // N..N+M-1 with zero probes each. Before this tier, 1k prepend was ~10k
+  // probes; with it, 0.
+  //
+  // Tier 3 — binary search fallback. Random shuffles and other mixed
+  // reorders pay the standard log₂(lisLen) per index.
+  //
+  // Safety: the `v < lisLen && tails[v] === v` check is a strict subset of
+  // "binary-search would return v", so it never produces a wrong answer on
+  // shufles — it just opportunistically avoids probing when the answer
+  // happens to be the index itself. No behaviour change, only fewer probes.
+  let lastV = -1
   for (let i = 0; i < n; i++) {
     const key = newKeys[i] as string | number
     const v = cache.get(key)?.pos ?? 0
-    let lo = 0
-    let hi = lisLen
-    while (lo < hi) {
-      const mid = (lo + hi) >> 1
-      if ((tails[mid] as number) < v) lo = mid + 1
-      else hi = mid
+    // Tier 1: extend LIS.
+    if (v > lastV) {
+      tails[lisLen] = v
+      tailIdx[lisLen] = i
+      if (lisLen > 0) pred[i] = tailIdx[lisLen - 1] as number
+      lisLen++
+      lastV = v
+      continue
+    }
+    // Tier 2: known slot for piecewise-monotonic patterns (prepend, etc.).
+    let lo: number
+    if (v < lisLen && (tails[v] as number) === v) {
+      lo = v
+    } else {
+      // Tier 3: binary search.
+      lo = 0
+      let hi = lisLen
+      while (lo < hi) {
+        const mid = (lo + hi) >> 1
+        ops++
+        if ((tails[mid] as number) < v) lo = mid + 1
+        else hi = mid
+      }
     }
     tails[lo] = v
     tailIdx[lo] = i
     if (lo > 0) pred[i] = tailIdx[lo - 1] as number
-    if (lo === lisLen) lisLen++
+    // v ≤ lastV here, so tails can't be extended: lo < lisLen always.
   }
+  if (__DEV__ && ops > 0) _countSink.__pyreon_count__?.('runtime.mountFor.lisOps', ops)
   return lisLen
 }
 
@@ -463,6 +507,7 @@ export function mountFor<T>(
 
   let cache = new Map<string | number, ForEntry>()
   let currentKeys: (string | number)[] = []
+  const _reusableKeySet = new Set<string | number>()
   let cleanupCount = 0
   let anchorsRegistered = false
 
@@ -644,7 +689,11 @@ export function mountFor<T>(
     newKeys: (string | number)[],
     liveParent: Node,
   ) => {
-    removeStaleForEntries(new Set<string | number>(newKeys))
+    // Reuse a persistent Set to avoid allocating a new one per update.
+    // Cleared + repopulated instead of constructing new Set(newKeys).
+    _reusableKeySet.clear()
+    for (let i = 0; i < newKeys.length; i++) _reusableKeySet.add(newKeys[i] as string | number)
+    removeStaleForEntries(_reusableKeySet)
     mountNewForEntries(items, n, newKeys, liveParent)
 
     if (!anchorsRegistered) {

package/src/props.ts

@@ -8,8 +8,7 @@ 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'
 
 // ─── Configurable sanitizer ──────────────────────────────────────────────────
 

package/src/template.ts

@@ -2,6 +2,13 @@ import type { NativeItem, VNodeChild } from '@pyreon/core'
 import { renderEffect } from '@pyreon/reactivity'
 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'`.
+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 }
+
 /**
  * Creates a row/item factory backed by HTML template cloning.
  *
@@ -68,7 +75,8 @@ export function _bindText(
   if (source.direct) {
     const textUpdate = () => {
       const v = source._v
-      node.data = v == null || v === false ? '' : String(v as string | number)
+      const next = v == null || v === false ? '' : String(v as string | number)
+      if (next !== node.data) node.data = next
     }
     textUpdate()
     return source.direct(textUpdate)
@@ -77,7 +85,8 @@ export function _bindText(
   const fn = source as unknown as () => unknown
   return renderEffect(() => {
     const v = fn()
-    node.data = v == null || v === false ? '' : String(v as string | number)
+    const next = v == null || v === false ? '' : String(v as string | number)
+    if (next !== node.data) node.data = next
   })
 }
 
@@ -116,6 +125,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>()
 
 /**
@@ -142,10 +167,23 @@ const _tplCache = new Map<string, HTMLTemplateElement>()
  * })
  */
 export function _tpl(html: string, bind: (el: HTMLElement) => (() => void) | null): NativeItem {
+  if (__DEV__) _countSink.__pyreon_count__?.('runtime.tpl')
   let tpl = _tplCache.get(html)
   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
@@ -153,6 +191,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.
  *