pulse-js-framework 1.7.37 → 1.8.0

package/cli/utils/file-utils.js

@@ -80,6 +80,9 @@ function globMatch(base, pattern, extensions) {
         match(dir, partIndex + 1);
         try {
           for (const entry of readdirSync(dir)) {
+            // Skip hidden files and node_modules
+            if (entry.startsWith('.') || entry === 'node_modules') continue;
+
             const full = join(dir, entry);
             try {
               if (statSync(full).isDirectory()) {
@@ -153,6 +156,9 @@ function matchFilesInDirRecursive(dir, pattern, extensions, results) {
   function walk(currentDir) {
     try {
       for (const entry of readdirSync(currentDir)) {
+        // Skip hidden files and node_modules
+        if (entry.startsWith('.') || entry === 'node_modules') continue;
+
         const full = join(currentDir, entry);
         try {
           const stat = statSync(full);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.7.37",
+  "version": "1.8.0",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "sideEffects": false,
@@ -179,8 +179,16 @@
     "test:esbuild-plugin": "node test/esbuild-plugin.test.js",
     "test:parcel-plugin": "node test/parcel-plugin.test.js",
     "test:swc-plugin": "node test/swc-plugin.test.js",
+    "test:dom-recycle": "node test/dom-recycle.test.js",
+    "test:dom-virtual-list": "node test/dom-virtual-list.test.js",
+    "test:dom-event-delegate": "node test/dom-event-delegate.test.js",
     "test:dom-binding": "node test/dom-binding.test.js",
     "test:interceptor-manager": "node test/interceptor-manager.test.js",
+    "test:vite-plugin": "node --test test/vite-plugin.test.js",
+    "test:memory-cleanup": "node --test test/memory-cleanup.test.js",
+    "test:dev-server": "node --test test/dev-server.test.js",
+    "bench": "node benchmarks/index.js",
+    "bench:json": "node benchmarks/index.js --json",
     "build:netlify": "node scripts/build-netlify.js",
     "version": "node scripts/sync-version.js",
     "docs": "node cli/index.js dev docs"

package/runtime/a11y.js

@@ -523,44 +523,39 @@ export function createPreferences() {
   const forcedColors = pulse(forcedColorsMode());
   const contrast = pulse(prefersContrast());
 
-  if (typeof window !== 'undefined') {
-    // Listen for preference changes
-    window.matchMedia('(prefers-reduced-motion: reduce)').addEventListener('change', (e) => {
-      reducedMotion.set(e.matches);
-    });
-
-    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
-      colorScheme.set(e.matches ? 'dark' : 'light');
-    });
-
-    window.matchMedia('(prefers-contrast: more)').addEventListener('change', (e) => {
-      highContrast.set(e.matches);
-    });
+  const listeners = [];
 
-    window.matchMedia('(prefers-reduced-transparency: reduce)').addEventListener('change', (e) => {
-      reducedTransparency.set(e.matches);
-    });
-
-    window.matchMedia('(forced-colors: active)').addEventListener('change', (e) => {
-      forcedColors.set(e.matches ? 'active' : 'none');
-    });
-
-    // More granular contrast detection
-    window.matchMedia('(prefers-contrast: more)').addEventListener('change', () => {
-      contrast.set(prefersContrast());
-    });
-    window.matchMedia('(prefers-contrast: less)').addEventListener('change', () => {
-      contrast.set(prefersContrast());
-    });
+  if (typeof window !== 'undefined') {
+    const track = (query, handler) => {
+      const mql = window.matchMedia(query);
+      mql.addEventListener('change', handler);
+      listeners.push({ mql, handler });
+    };
+
+    track('(prefers-reduced-motion: reduce)', (e) => reducedMotion.set(e.matches));
+    track('(prefers-color-scheme: dark)', (e) => colorScheme.set(e.matches ? 'dark' : 'light'));
+    track('(prefers-contrast: more)', (e) => highContrast.set(e.matches));
+    track('(prefers-reduced-transparency: reduce)', (e) => reducedTransparency.set(e.matches));
+    track('(forced-colors: active)', (e) => forcedColors.set(e.matches ? 'active' : 'none'));
+    track('(prefers-contrast: more)', () => contrast.set(prefersContrast()));
+    track('(prefers-contrast: less)', () => contrast.set(prefersContrast()));
   }
 
+  const cleanup = () => {
+    for (const { mql, handler } of listeners) {
+      mql.removeEventListener('change', handler);
+    }
+    listeners.length = 0;
+  };
+
   return {
     reducedMotion,
     colorScheme,
     highContrast,
     reducedTransparency,
     forcedColors,
-    contrast
+    contrast,
+    cleanup
   };
 }
 
@@ -1570,27 +1565,43 @@ export function createAnnouncementQueue(options = {}) {
 
   const queue = [];
   let isProcessing = false;
+  let currentTimerId = null;
+  let aborted = false;
   const queueLength = pulse(0);
 
   const processQueue = async () => {
-    if (isProcessing || queue.length === 0) return;
+    if (isProcessing || queue.length === 0 || aborted) return;
 
     isProcessing = true;
 
-    while (queue.length > 0) {
+    while (queue.length > 0 && !aborted) {
       const { message, priority, clearAfter } = queue.shift();
       queueLength.set(queue.length);
 
       announce(message, { priority, clearAfter });
 
       // Wait for announcement to be read
-      await new Promise(resolve => setTimeout(resolve,
-        Math.max(minDelay, clearAfter || 1000)));
+      await new Promise(resolve => {
+        currentTimerId = setTimeout(resolve,
+          Math.max(minDelay, clearAfter || 1000));
+      });
+      currentTimerId = null;
     }
 
     isProcessing = false;
   };
 
+  const dispose = () => {
+    aborted = true;
+    if (currentTimerId !== null) {
+      clearTimeout(currentTimerId);
+      currentTimerId = null;
+    }
+    queue.length = 0;
+    queueLength.set(0);
+    isProcessing = false;
+  };
+
   return {
     queueLength,
     /**
@@ -1599,6 +1610,7 @@ export function createAnnouncementQueue(options = {}) {
      * @param {object} options - Announcement options (priority, clearAfter)
      */
     add: (message, opts = {}) => {
+      if (aborted) return;
       queue.push({ message, ...opts });
       queueLength.set(queue.length);
       processQueue();
@@ -1614,7 +1626,11 @@ export function createAnnouncementQueue(options = {}) {
      * Check if queue is being processed
      * @returns {boolean}
      */
-    isProcessing: () => isProcessing
+    isProcessing: () => isProcessing,
+    /**
+     * Dispose the queue, cancelling any pending timers
+     */
+    dispose
   };
 }
 

package/runtime/async.js

@@ -462,6 +462,11 @@ export function useAsync(asyncFn, options = {}) {
     }
   }
 
+  const dispose = () => {
+    versionController.cleanup();
+  };
+  onCleanup(dispose);
+
   // Execute immediately if requested
   if (immediate) {
     execute();
@@ -474,7 +479,8 @@ export function useAsync(asyncFn, options = {}) {
     status,
     execute,
     reset,
-    abort
+    abort,
+    dispose
   };
 }
 
@@ -727,6 +733,13 @@ export function useResource(key, fetcher, options = {}) {
     fetch();
   }
 
+  const dispose = () => {
+    if (intervalId) {
+      clearInterval(intervalId);
+      intervalId = null;
+    }
+  };
+
   return {
     data,
     error,
@@ -737,7 +750,8 @@ export function useResource(key, fetcher, options = {}) {
     fetch,
     refresh,
     mutate,
-    invalidate
+    invalidate,
+    dispose
   };
 }
 

package/runtime/dom-adapter.js

@@ -537,6 +537,10 @@ export class MockElement extends MockNode {
   hasAttribute(name) {
     return this._attributes.has(name);
   }
+
+  getAttributeNames() {
+    return Array.from(this._attributes.keys());
+  }
 }
 
 /**

package/runtime/dom-event-delegate.js

@@ -0,0 +1,220 @@
+/**
+ * Pulse DOM Event Delegation
+ *
+ * Provides event delegation for list rendering, placing a single listener
+ * on the parent element instead of individual listeners on each item.
+ *
+ * Related: ADR-0002, list() in dom-list.js
+ *
+ * @module runtime/dom-event-delegate
+ */
+
+import { getAdapter } from './dom-adapter.js';
+import { list } from './dom-list.js';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Events that do not bubble and require capture mode for delegation.
+ * @type {Set<string>}
+ */
+const NON_BUBBLING = new Set([
+  'focus', 'blur', 'scroll',
+  'mouseenter', 'mouseleave',
+  'pointerenter', 'pointerleave',
+  'load', 'unload', 'error'
+]);
+
+/**
+ * Data attribute used to mark list items with their key.
+ * @type {string}
+ */
+const KEY_ATTR = 'data-pulse-key';
+
+// ============================================================================
+// Low-level Delegation
+// ============================================================================
+
+/**
+ * Attach a delegated event listener to a parent element.
+ * Events from descendants matching the selector bubble up to the parent.
+ *
+ * @param {Element} parent - Container element to listen on
+ * @param {string} eventType - Event type (e.g., 'click', 'input')
+ * @param {string} selector - CSS selector to match against (uses closest())
+ * @param {Function} handler - (event, matchedElement) => void
+ * @returns {Function} Cleanup function to remove the listener
+ *
+ * @example
+ * const cleanup = delegate(listContainer, 'click', '[data-key]', (event, el) => {
+ *   console.log('Clicked:', el.dataset.key);
+ * });
+ * // Later: cleanup();
+ */
+export function delegate(parent, eventType, selector, handler) {
+  const dom = getAdapter();
+  const useCapture = NON_BUBBLING.has(eventType);
+
+  const listener = (event) => {
+    let target = event.target;
+
+    // Walk up from target to parent, looking for a match
+    while (target && target !== parent) {
+      if (matchesSelector(target, selector, dom)) {
+        handler(event, target);
+        return;
+      }
+      target = dom.getParentNode(target);
+    }
+  };
+
+  dom.addEventListener(parent, eventType, listener, useCapture);
+
+  return () => {
+    dom.removeEventListener(parent, eventType, listener, useCapture);
+  };
+}
+
+/**
+ * Check if an element matches a CSS selector.
+ * Uses closest() for real elements, falls back to attribute check for mocks.
+ *
+ * @param {Element} element - Element to test
+ * @param {string} selector - CSS selector
+ * @param {DOMAdapter} dom - DOM adapter
+ * @returns {boolean} Whether element matches
+ * @private
+ */
+function matchesSelector(element, selector, dom) {
+  // Use native matches if available
+  if (typeof element.matches === 'function') {
+    return element.matches(selector);
+  }
+
+  // Fallback for MockDOMAdapter: simple attribute selector matching
+  if (selector.startsWith('[') && selector.endsWith(']')) {
+    const inner = selector.slice(1, -1);
+    const eqIdx = inner.indexOf('=');
+    if (eqIdx === -1) {
+      return dom.getAttribute(element, inner) !== null;
+    }
+    const attrName = inner.slice(0, eqIdx);
+    const attrValue = inner.slice(eqIdx + 1).replace(/^["']|["']$/g, '');
+    return dom.getAttribute(element, attrName) === attrValue;
+  }
+
+  return false;
+}
+
+// ============================================================================
+// Delegated List
+// ============================================================================
+
+/**
+ * Create a reactive list with delegated event handlers.
+ * Instead of attaching listeners to each item, a single delegated listener
+ * is placed on the parent container for each event type.
+ *
+ * @param {Function|Pulse} getItems - Items source (reactive)
+ * @param {Function} template - (item, index) => Node | Node[]
+ * @param {Function} keyFn - (item, index) => key
+ * @param {Object} [options] - Configuration
+ * @param {Object} [options.on] - Event handlers: { eventType: (event, item, index) => void }
+ * @param {boolean} [options.recycle] - Enable element recycling
+ * @returns {DocumentFragment} Reactive list fragment
+ *
+ * @example
+ * const fragment = delegatedList(
+ *   () => items.get(),
+ *   (item, index) => el('li', item.name),
+ *   (item) => item.id,
+ *   {
+ *     on: {
+ *       click: (event, item, index) => selectItem(item),
+ *       dblclick: (event, item, index) => editItem(item)
+ *     }
+ *   }
+ * );
+ */
+export function delegatedList(getItems, template, keyFn, options = {}) {
+  const { on: handlers = {}, ...listOptions } = options;
+  const dom = getAdapter();
+
+  // Internal map: key -> { item, index }
+  const itemMap = new Map();
+
+  // Wrap template to add data-pulse-key attribute
+  const wrappedTemplate = (item, index) => {
+    const key = keyFn(item, index);
+    const node = template(item, index);
+    const root = Array.isArray(node) ? node[0] : node;
+
+    if (root && dom.isElement(root)) {
+      dom.setAttribute(root, KEY_ATTR, String(key));
+    }
+
+    itemMap.set(String(key), { item, index });
+    return node;
+  };
+
+  // Create list with wrapped template
+  const fragment = list(getItems, wrappedTemplate, keyFn, listOptions);
+
+  // Set up delegation on the fragment's parent when it's mounted
+  const cleanups = [];
+  let delegationSetUp = false;
+
+  /**
+   * Set up delegation on a parent element.
+   * Called lazily when the fragment is attached to the DOM.
+   * @param {Element} parent - Parent element
+   * @private
+   */
+  function setupDelegation(parent) {
+    if (delegationSetUp) return;
+    delegationSetUp = true;
+
+    for (const [eventType, handler] of Object.entries(handlers)) {
+      const cleanup = delegate(parent, eventType, `[${KEY_ATTR}]`, (event, matchedEl) => {
+        const key = dom.getAttribute(matchedEl, KEY_ATTR);
+        const entry = itemMap.get(key);
+        if (entry) {
+          handler(event, entry.item, entry.index);
+        }
+      });
+      cleanups.push(cleanup);
+    }
+  }
+
+  // Observe when fragment gets a parent by using a MutationObserver-like approach.
+  // Since fragments move to a parent on insertion, we check after microtask.
+  if (typeof queueMicrotask === 'function') {
+    queueMicrotask(() => {
+      // Find the parent by looking at the fragment's first child's parent
+      const firstChild = dom.getFirstChild(fragment);
+      if (firstChild) {
+        const parent = dom.getParentNode(firstChild);
+        if (parent) {
+          setupDelegation(parent);
+        }
+      }
+    });
+  }
+
+  // Attach setup helper for manual use
+  fragment._setupDelegation = setupDelegation;
+  fragment._cleanupDelegation = () => {
+    for (const cleanup of cleanups) cleanup();
+    cleanups.length = 0;
+    delegationSetUp = false;
+  };
+
+  return fragment;
+}
+
+export default {
+  delegate,
+  delegatedList
+};

package/runtime/dom-list.js

@@ -7,6 +7,7 @@
 
 import { effect } from './pulse.js';
 import { getAdapter } from './dom-adapter.js';
+import { getPool } from './dom-recycle.js';
 
 // =============================================================================
 // LIS ALGORITHM
@@ -100,10 +101,13 @@ export function computeLIS(arr) {
  * @param {Function|Pulse} getItems - Items source (reactive)
  * @param {Function} template - (item, index) => Node | Node[]
  * @param {Function} keyFn - (item, index) => key (default: index)
+ * @param {Object} [options] - Optional configuration
+ * @param {boolean} [options.recycle=false] - Enable element recycling via pool
  * @returns {DocumentFragment} Container fragment with reactive list
  */
-export function list(getItems, template, keyFn = (item, i) => i) {
+export function list(getItems, template, keyFn = (item, i) => i, options = {}) {
   const dom = getAdapter();
+  const pool = options.recycle ? getPool() : null;
   const container = dom.createDocumentFragment();
   const startMarker = dom.createComment('list-start');
   const endMarker = dom.createComment('list-end');
@@ -150,6 +154,10 @@ export function list(getItems, template, keyFn = (item, i) => i) {
     for (const [key, entry] of itemNodes) {
       if (!newItemNodes.has(key)) {
         for (const node of entry.nodes) {
+          // Release to recycling pool before removing (if enabled)
+          if (pool && dom.isElement(node)) {
+            pool.release(node);
+          }
           dom.removeNode(node);
         }
         if (entry.cleanup) entry.cleanup();

package/runtime/dom-recycle.js

@@ -0,0 +1,230 @@
+/**
+ * Pulse DOM Element Recycling Pool
+ *
+ * Pools detached DOM elements by tag name for reuse, avoiding expensive
+ * createElement() calls during list reconciliation.
+ *
+ * Used by: list() when `recycle: true` option is set
+ * Related: ADR-0004, virtual scrolling (ADR-0003)
+ *
+ * @module runtime/dom-recycle
+ */
+
+import { getAdapter } from './dom-adapter.js';
+
+// ============================================================================
+// Constants & Configuration
+// ============================================================================
+
+const DEFAULT_OPTIONS = {
+  maxPerTag: 50,
+  maxTotal: 200,
+  resetOnRecycle: true
+};
+
+// ============================================================================
+// Element Reset
+// ============================================================================
+
+/**
+ * Reset an element to a clean state before pooling.
+ * Removes attributes, children, styles, and event listener references.
+ *
+ * @param {Element} element - Element to reset
+ * @param {DOMAdapter} dom - DOM adapter
+ * @private
+ */
+function resetElement(element, dom) {
+  // 1. Clear event listener tracking (if any)
+  if (element._eventListeners) {
+    element._eventListeners.clear();
+  }
+
+  // 2. Remove all attributes
+  if (element.attributes) {
+    const attrs = element.attributes;
+    while (attrs.length > 0) {
+      dom.removeAttribute(element, attrs[0].name);
+    }
+  } else if (typeof element.getAttributeNames === 'function') {
+    for (const name of element.getAttributeNames()) {
+      dom.removeAttribute(element, name);
+    }
+  }
+
+  // 3. Clear content and styles
+  dom.setTextContent(element, '');
+  if (element.className !== undefined) {
+    element.className = '';
+  }
+  if (element.style && typeof element.style === 'object') {
+    element.style.cssText = '';
+  }
+
+  // 4. Remove child nodes
+  let child = dom.getFirstChild(element);
+  while (child) {
+    dom.removeNode(child);
+    child = dom.getFirstChild(element);
+  }
+}
+
+// ============================================================================
+// Element Pool
+// ============================================================================
+
+/**
+ * Create an element recycling pool.
+ *
+ * @param {Object} [options] - Pool configuration
+ * @param {number} [options.maxPerTag=50] - Max recycled elements per tag name
+ * @param {number} [options.maxTotal=200] - Max total recycled elements
+ * @param {boolean} [options.resetOnRecycle=true] - Reset attributes/styles on release
+ * @returns {ElementPool} Pool instance
+ *
+ * @example
+ * const pool = createElementPool({ maxPerTag: 50, maxTotal: 200 });
+ * const li = pool.acquire('li');  // Reuses from pool or creates new
+ * pool.release(li);               // Returns to pool for reuse
+ */
+export function createElementPool(options = {}) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+  const dom = getAdapter();
+
+  /** @type {Map<string, Element[]>} */
+  const pool = new Map();
+  let totalSize = 0;
+  let hits = 0;
+  let misses = 0;
+
+  return {
+    /**
+     * Acquire an element from the pool or create a new one.
+     *
+     * @param {string} tagName - Tag name (e.g., 'li', 'div')
+     * @returns {Element} A clean element ready for use
+     */
+    acquire(tagName) {
+      const tag = tagName.toLowerCase();
+      const bucket = pool.get(tag);
+
+      if (bucket && bucket.length > 0) {
+        hits++;
+        totalSize--;
+        return bucket.pop();
+      }
+
+      misses++;
+      return dom.createElement(tag);
+    },
+
+    /**
+     * Release an element back to the pool for reuse.
+     * The element is reset (attributes, children, styles cleared) before pooling.
+     *
+     * @param {Element} element - Element to release
+     * @returns {boolean} true if element was pooled, false if pool is full
+     */
+    release(element) {
+      if (!dom.isElement(element)) return false;
+
+      const tag = (element.tagName || element.nodeName || '').toLowerCase();
+      if (!tag) return false;
+
+      // Check pool limits
+      if (totalSize >= config.maxTotal) return false;
+
+      let bucket = pool.get(tag);
+      if (!bucket) {
+        bucket = [];
+        pool.set(tag, bucket);
+      }
+
+      if (bucket.length >= config.maxPerTag) return false;
+
+      // Reset element before pooling
+      if (config.resetOnRecycle) {
+        resetElement(element, dom);
+      }
+
+      bucket.push(element);
+      totalSize++;
+      return true;
+    },
+
+    /**
+     * Get pool statistics.
+     *
+     * @returns {Object} Pool stats
+     */
+    stats() {
+      const total = hits + misses;
+      return {
+        size: totalSize,
+        hits,
+        misses,
+        hitRate: total > 0 ? Math.round((hits / total) * 1000) / 1000 : 0
+      };
+    },
+
+    /**
+     * Clear all pooled elements.
+     */
+    clear() {
+      pool.clear();
+      totalSize = 0;
+    },
+
+    /**
+     * Reset statistics counters.
+     */
+    resetStats() {
+      hits = 0;
+      misses = 0;
+    },
+
+    /**
+     * Current number of pooled elements.
+     * @type {number}
+     */
+    get size() {
+      return totalSize;
+    }
+  };
+}
+
+// ============================================================================
+// Default Singleton Pool
+// ============================================================================
+
+/** @type {ReturnType<typeof createElementPool>|null} */
+let defaultPool = null;
+
+/**
+ * Get the default global element pool (lazy singleton).
+ *
+ * @returns {ReturnType<typeof createElementPool>} Default pool
+ */
+export function getPool() {
+  if (!defaultPool) {
+    defaultPool = createElementPool();
+  }
+  return defaultPool;
+}
+
+/**
+ * Reset and clear the default pool.
+ * Useful for testing or SSR cleanup.
+ */
+export function resetPool() {
+  if (defaultPool) {
+    defaultPool.clear();
+  }
+  defaultPool = null;
+}
+
+export default {
+  createElementPool,
+  getPool,
+  resetPool
+};

package/runtime/dom-virtual-list.js

@@ -0,0 +1,190 @@
+/**
+ * Pulse DOM Virtual Scrolling
+ *
+ * Renders only visible items plus an overscan buffer for large lists.
+ * Keeps DOM size constant regardless of data size.
+ *
+ * Related: ADR-0003, element recycling (ADR-0004), event delegation (ADR-0002)
+ *
+ * @module runtime/dom-virtual-list
+ */
+
+import { pulse, effect, computed, batch } from './pulse.js';
+import { getAdapter } from './dom-adapter.js';
+import { list } from './dom-list.js';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_OPTIONS = {
+  overscan: 5,
+  containerHeight: 400,
+  recycle: false
+};
+
+// ============================================================================
+// Virtual List
+// ============================================================================
+
+/**
+ * Create a virtual scrolling list that renders only visible items.
+ *
+ * @param {Function|Pulse} getItems - Reactive data source returning array
+ * @param {Function} template - (item, index) => Node
+ * @param {Function} keyFn - (item) => unique key
+ * @param {Object} options - Configuration
+ * @param {number} options.itemHeight - Fixed row height in pixels (required)
+ * @param {number} [options.overscan=5] - Extra items above/below viewport
+ * @param {number|string} [options.containerHeight=400] - Viewport height in px or 'auto'
+ * @param {boolean} [options.recycle=false] - Enable element recycling for removed items
+ * @returns {Element} Scroll container element
+ *
+ * @example
+ * const vlist = virtualList(
+ *   () => items.get(),
+ *   (item) => el('li', item.name),
+ *   (item) => item.id,
+ *   { itemHeight: 40, overscan: 5, containerHeight: 400 }
+ * );
+ * mount('#app', vlist);
+ */
+export function virtualList(getItems, template, keyFn, options = {}) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+  const { itemHeight, overscan, containerHeight, recycle } = config;
+
+  if (!itemHeight || itemHeight <= 0) {
+    throw new Error('[Pulse] virtualList requires a positive itemHeight');
+  }
+
+  const dom = getAdapter();
+
+  // ---- Reactive state ----
+  const scrollTop = pulse(0);
+
+  // ---- DOM structure ----
+
+  // Outer container: fixed height, scrollable
+  const container = dom.createElement('div');
+  dom.setAttribute(container, 'role', 'list');
+  dom.setAttribute(container, 'aria-label', 'Virtual scrolling list');
+  setStyles(dom, container, {
+    'overflow-y': 'auto',
+    'position': 'relative'
+  });
+  if (typeof containerHeight === 'number') {
+    dom.setStyle(container, 'height', `${containerHeight}px`);
+  }
+
+  // Inner spacer: full height of all items (creates scrollbar)
+  const spacer = dom.createElement('div');
+  dom.setStyle(spacer, 'position', 'relative');
+  dom.appendChild(container, spacer);
+
+  // Viewport: positioned absolutely, holds rendered items
+  const viewport = dom.createElement('div');
+  setStyles(dom, viewport, {
+    'position': 'absolute',
+    'left': '0',
+    'right': '0',
+    'top': '0'
+  });
+  dom.appendChild(spacer, viewport);
+
+  // ---- Scroll handling (rAF-throttled) ----
+  let rafId = null;
+
+  const onScroll = () => {
+    if (rafId !== null) return;
+    rafId = (typeof requestAnimationFrame === 'function' ? requestAnimationFrame : setTimeout)(() => {
+      rafId = null;
+      const top = container.scrollTop !== undefined ? container.scrollTop : 0;
+      scrollTop.set(top);
+    });
+  };
+
+  dom.addEventListener(container, 'scroll', onScroll, { passive: true });
+
+  // ---- Compute visible items slice ----
+  const visibleSlice = pulse([]);
+
+  effect(() => {
+    const items = typeof getItems === 'function' ? getItems() : getItems.get();
+    const totalItems = Array.isArray(items) ? items.length : 0;
+    const top = scrollTop.get();
+
+    // Update spacer height
+    dom.setStyle(spacer, 'height', `${totalItems * itemHeight}px`);
+
+    // Calculate visible range
+    const height = typeof containerHeight === 'number'
+      ? containerHeight
+      : (container.clientHeight || 400);
+
+    let startIndex = Math.floor(top / itemHeight) - overscan;
+    let endIndex = Math.ceil((top + height) / itemHeight) + overscan;
+    startIndex = Math.max(0, startIndex);
+    endIndex = Math.min(totalItems, endIndex);
+
+    // Position viewport at start offset
+    dom.setStyle(viewport, 'top', `${startIndex * itemHeight}px`);
+
+    // ARIA: announce total count
+    dom.setAttribute(container, 'aria-rowcount', String(totalItems));
+
+    // Extract visible slice
+    const slice = Array.isArray(items) ? items.slice(startIndex, endIndex) : [];
+    visibleSlice.set(slice);
+  });
+
+  // ---- Render visible items using list() ----
+  const listOptions = {};
+  if (recycle) {
+    listOptions.recycle = true;
+  }
+
+  const rendered = list(
+    () => visibleSlice.get(),
+    (item, relativeIndex) => {
+      const node = template(item, relativeIndex);
+      // Set ARIA rowindex for accessibility
+      const root = Array.isArray(node) ? node[0] : node;
+      if (root && dom.isElement(root)) {
+        dom.setAttribute(root, 'role', 'listitem');
+      }
+      return node;
+    },
+    keyFn,
+    listOptions
+  );
+
+  dom.appendChild(viewport, rendered);
+
+  // ---- Cleanup method ----
+  container._dispose = () => {
+    dom.removeEventListener(container, 'scroll', onScroll);
+    if (rafId !== null) {
+      (typeof cancelAnimationFrame === 'function' ? cancelAnimationFrame : clearTimeout)(rafId);
+      rafId = null;
+    }
+  };
+
+  return container;
+}
+
+/**
+ * Set multiple styles on an element.
+ * @param {DOMAdapter} dom
+ * @param {Element} element
+ * @param {Object} styles
+ * @private
+ */
+function setStyles(dom, element, styles) {
+  for (const [prop, value] of Object.entries(styles)) {
+    dom.setStyle(element, prop, value);
+  }
+}
+
+export default {
+  virtualList
+};

package/runtime/dom.js

@@ -64,6 +64,15 @@ import {
 // Advanced features
 import { portal, errorBoundary, transition, whenTransition } from './dom-advanced.js';
 
+// Element recycling pool (#60)
+import { createElementPool, getPool, resetPool } from './dom-recycle.js';
+
+// Event delegation (#56)
+import { delegate, delegatedList } from './dom-event-delegate.js';
+
+// Virtual scrolling (#59)
+import { virtualList } from './dom-virtual-list.js';
+
 // =============================================================================
 // INITIALIZE CONTEXT UTILITIES FOR COMPONENT FACTORY
 // =============================================================================
@@ -131,7 +140,19 @@ export {
   portal,
   errorBoundary,
   transition,
-  whenTransition
+  whenTransition,
+
+  // Element recycling (#60)
+  createElementPool,
+  getPool,
+  resetPool,
+
+  // Event delegation (#56)
+  delegate,
+  delegatedList,
+
+  // Virtual scrolling (#59)
+  virtualList
 };
 
 // =============================================================================
@@ -184,5 +205,17 @@ export default {
 
   // Diagnostics
   getCacheMetrics,
-  resetCacheMetrics
+  resetCacheMetrics,
+
+  // Element recycling (#60)
+  createElementPool,
+  getPool,
+  resetPool,
+
+  // Event delegation (#56)
+  delegate,
+  delegatedList,
+
+  // Virtual scrolling (#59)
+  virtualList
 };

package/runtime/form.js

@@ -6,7 +6,7 @@
  * and touched state tracking.
  */
 
-import { pulse, effect, computed, batch } from './pulse.js';
+import { pulse, effect, computed, batch, onCleanup } from './pulse.js';
 
 /**
  * @typedef {Object} FieldState
@@ -698,6 +698,19 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
     });
   }
 
+  const dispose = () => {
+    for (const name of fieldNames) {
+      const timers = debounceTimers[name];
+      if (timers) {
+        for (const timerId of timers.values()) {
+          clearTimeout(timerId);
+        }
+        timers.clear();
+      }
+    }
+  };
+  onCleanup(dispose);
+
   return {
     fields,
     isValid,
@@ -715,7 +728,8 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
     reset,
     handleSubmit,
     setErrors,
-    clearErrors
+    clearErrors,
+    dispose
   };
 }
 
@@ -905,6 +919,14 @@ export function useField(initialValue, rules = [], options = {}) {
     });
   };
 
+  const dispose = () => {
+    for (const timerId of debounceTimers.values()) {
+      clearTimeout(timerId);
+    }
+    debounceTimers.clear();
+  };
+  onCleanup(dispose);
+
   return {
     value,
     error,
@@ -918,7 +940,8 @@ export function useField(initialValue, rules = [], options = {}) {
     onBlur,
     reset,
     setError: (msg) => error.set(msg),
-    clearError: () => error.set(null)
+    clearError: () => error.set(null),
+    dispose
   };
 }
 
@@ -1028,6 +1051,13 @@ export function useFieldArray(initialValues = [], itemRules = []) {
     return asyncResults.every(r => r === true);
   };
 
+  const dispose = () => {
+    for (const field of fieldsArray.get()) {
+      field.dispose?.();
+    }
+  };
+  onCleanup(dispose);
+
   return {
     fields: fieldsArray,
     values,
@@ -1042,7 +1072,8 @@ export function useFieldArray(initialValues = [], itemRules = []) {
     replace,
     reset,
     validateAll,
-    validateAllSync
+    validateAllSync,
+    dispose
   };
 }
 

package/runtime/pulse.js

@@ -142,6 +142,8 @@ export class ReactiveContext {
     this.batchDepth = 0;
     this.pendingEffects = new Set();
     this.isRunningEffects = false;
+    // Generation counter for dependency tracking optimization (#58)
+    this.generation = 0;
     // HMR support
     this.currentModuleId = null;
     this.effectRegistry = new Map();
@@ -155,6 +157,7 @@ export class ReactiveContext {
     this.batchDepth = 0;
     this.pendingEffects.clear();
     this.isRunningEffects = false;
+    this.generation = 0;
     this.currentModuleId = null;
     this.effectRegistry.clear();
   }
@@ -472,9 +475,16 @@ export class Pulse {
    * });
    */
   get() {
-    if (activeContext.currentEffect) {
-      this.#subscribers.add(activeContext.currentEffect);
-      activeContext.currentEffect.dependencies.add(this);
+    const current = activeContext.currentEffect;
+    if (current) {
+      // Optimization (#58): Skip redundant Set.add() if already tracked in this cycle.
+      // When an effect re-runs, generation increments and dependencies are cleared,
+      // so _generation won't match and we'll re-track. Within the same cycle,
+      // dependencies.has() avoids duplicate additions for repeated reads.
+      if (current._generation !== activeContext.generation || !current.dependencies.has(this)) {
+        this.#subscribers.add(current);
+        current.dependencies.add(this);
+      }
     }
     return this.#value;
   }
@@ -948,6 +958,10 @@ export function effect(fn, options = {}) {
       }
       effectFn.dependencies.clear();
 
+      // Stamp generation for dependency tracking optimization (#58)
+      activeContext.generation++;
+      effectFn._generation = activeContext.generation;
+
       // Set as current effect for dependency tracking
       const prevEffect = activeContext.currentEffect;
       activeContext.currentEffect = effectFn;
@@ -961,7 +975,8 @@ export function effect(fn, options = {}) {
       }
     },
     dependencies: new Set(),
-    cleanups: []
+    cleanups: [],
+    _generation: 0
   };
 
   // HMR: Register effect with current module

package/runtime/router.js

@@ -878,16 +878,18 @@ export function createRouter(options = {}) {
     const a = el('a', content);
     a.href = href;
 
-    a.addEventListener('click', (e) => {
+    const handleClick = (e) => {
       // Allow ctrl/cmd+click for new tab
       if (e.ctrlKey || e.metaKey) return;
 
       e.preventDefault();
       navigate(path, options);
-    });
+    };
+
+    a.addEventListener('click', handleClick);
 
     // Add active class when route matches
-    effect(() => {
+    const disposeEffect = effect(() => {
       const current = currentPath.get();
       if (current === path || (options.exact === false && current.startsWith(path))) {
         a.classList.add(options.activeClass || 'active');
@@ -896,6 +898,11 @@ export function createRouter(options = {}) {
       }
     });
 
+    a.cleanup = () => {
+      a.removeEventListener('click', handleClick);
+      disposeEffect();
+    };
+
     return a;
   }