pulse-js-framework 1.7.38 → 1.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.7.38",
+  "version": "1.8.1",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "sideEffects": false,
@@ -179,11 +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/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,248 @@
+/**
+ * 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();
+
+  // Track active keys per render cycle to clean stale itemMap entries
+  let activeKeys = new Set();
+
+  // Wrap template to add data-pulse-key attribute
+  const wrappedTemplate = (item, index) => {
+    const rawKey = keyFn(item, index);
+    // Security: ensure key is a string or number to prevent collisions
+    // Objects would all stringify to "[object Object]"
+    const key = (typeof rawKey === 'string' || typeof rawKey === 'number')
+      ? String(rawKey)
+      : String(index);
+    const node = template(item, index);
+    const root = Array.isArray(node) ? node[0] : node;
+
+    if (root && dom.isElement(root)) {
+      dom.setAttribute(root, KEY_ATTR, key);
+    }
+
+    itemMap.set(key, { item, index });
+    activeKeys.add(key);
+    return node;
+  };
+
+  // Wrap getItems to track render cycles and prune stale entries
+  const wrappedGetItems = typeof getItems === 'function'
+    ? () => {
+        activeKeys = new Set();
+        const result = getItems();
+        // Schedule cleanup after current effect cycle completes
+        if (typeof queueMicrotask === 'function') {
+          queueMicrotask(() => {
+            for (const key of itemMap.keys()) {
+              if (!activeKeys.has(key)) {
+                itemMap.delete(key);
+              }
+            }
+          });
+        }
+        return result;
+      }
+    : getItems; // Pulse source — template calls track keys directly
+
+  // Create list with wrapped template
+  const fragment = list(wrappedGetItems, 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');
@@ -138,10 +142,60 @@ export function list(getItems, template, keyFn = (item, i) => i) {
     });
 
     // Phase 2: Batch create new nodes using DocumentFragment
+    // When recycling is enabled, try to acquire root elements from the pool
+    // before falling back to createElement
     if (newItems.length > 0) {
       for (const { key, item, index } of newItems) {
         const result = template(item, index);
         const nodes = Array.isArray(result) ? result : [result];
+
+        // Pool acquire: if the root node is an element and pool has a matching
+        // tag, transfer children/attributes from template result to recycled element
+        if (pool && nodes.length === 1 && dom.isElement(nodes[0])) {
+          const original = nodes[0];
+          const tagName = (original.tagName || original.nodeName || '').toLowerCase();
+          if (tagName) {
+            const recycled = pool.acquire(tagName);
+            // Only use recycled element if it came from the pool (not freshly created)
+            // Pool.acquire creates new if empty, so always returns a valid element
+            if (recycled !== original) {
+              // Transfer attributes (skip event handler attributes for security)
+              if (original.attributes) {
+                const attrs = original.attributes;
+                for (let a = 0; a < attrs.length; a++) {
+                  const attrName = attrs[a].name;
+                  // Security: skip inline event handlers (onclick, onerror, etc.)
+                  if (attrName.length > 2 && attrName.charCodeAt(0) === 111 &&
+                      attrName.charCodeAt(1) === 110 && attrName.charCodeAt(2) > 96) {
+                    continue;
+                  }
+                  dom.setAttribute(recycled, attrName, attrs[a].value);
+                }
+              }
+              // Transfer children
+              let child = dom.getFirstChild(original);
+              while (child) {
+                const next = dom.getNextSibling(child);
+                dom.appendChild(recycled, child);
+                child = next;
+              }
+              // Transfer event listeners if tracked
+              if (original._eventListeners) {
+                recycled._eventListeners = original._eventListeners;
+              }
+              // Transfer inline styles
+              if (original.style && original.style.cssText) {
+                recycled.style.cssText = original.style.cssText;
+              }
+              // Transfer className
+              if (original.className) {
+                recycled.className = original.className;
+              }
+              nodes[0] = recycled;
+            }
+          }
+        }
+
         newItemNodes.set(key, { nodes, cleanup: null, item });
       }
     }
@@ -150,6 +204,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,276 @@
+/**
+ * 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';
+import { delegate } from './dom-event-delegate.js';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_OPTIONS = {
+  overscan: 5,
+  containerHeight: 400,
+  recycle: false,
+  on: null
+};
+
+// ============================================================================
+// 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
+ * @param {Object} [options.on] - Delegated event handlers: { eventType: (event, item, index) => void }
+ * @returns {Element} Scroll container element with scrollToIndex(index) and _dispose() methods
+ *
+ * @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, on: eventHandlers } = 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');
+  container.scrollTop = 0; // Initialize for mock/SSR compatibility
+  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([]);
+  const currentStartIndex = pulse(0);
+  let allItems = [];
+
+  effect(() => {
+    const items = typeof getItems === 'function' ? getItems() : getItems.get();
+    allItems = Array.isArray(items) ? items : [];
+    const totalItems = allItems.length;
+    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 startIdx = Math.floor(top / itemHeight) - overscan;
+    let endIdx = Math.ceil((top + height) / itemHeight) + overscan;
+    startIdx = Math.max(0, startIdx);
+    endIdx = Math.min(totalItems, endIdx);
+
+    // Position viewport at start offset
+    dom.setStyle(viewport, 'top', `${startIdx * itemHeight}px`);
+
+    // ARIA: announce total count
+    dom.setAttribute(container, 'aria-rowcount', String(totalItems));
+
+    batch(() => {
+      currentStartIndex.set(startIdx);
+      visibleSlice.set(allItems.slice(startIdx, endIdx));
+    });
+  });
+
+  // ---- Render visible items using list() ----
+  const listOptions = {};
+  if (recycle) {
+    listOptions.recycle = true;
+  }
+
+  // Item map for event delegation
+  const itemMap = new Map();
+  const KEY_ATTR = 'data-pulse-key';
+
+  const rendered = list(
+    () => visibleSlice.get(),
+    (item, relativeIndex) => {
+      const absIndex = currentStartIndex.peek() + relativeIndex;
+      const node = template(item, absIndex);
+      const root = Array.isArray(node) ? node[0] : node;
+      if (root && dom.isElement(root)) {
+        dom.setAttribute(root, 'role', 'listitem');
+        // ARIA: set 1-based row index for screen readers
+        dom.setAttribute(root, 'aria-rowindex', String(absIndex + 1));
+        // Mark for event delegation
+        if (eventHandlers) {
+          const rawKey = keyFn(item, absIndex);
+          // Security: ensure key is a primitive to prevent collisions
+          const key = (typeof rawKey === 'string' || typeof rawKey === 'number')
+            ? String(rawKey)
+            : String(absIndex);
+          dom.setAttribute(root, KEY_ATTR, key);
+          itemMap.set(key, { item, index: absIndex });
+        }
+      }
+      return node;
+    },
+    keyFn,
+    listOptions
+  );
+
+  dom.appendChild(viewport, rendered);
+
+  // ---- Event delegation on viewport ----
+  const delegateCleanups = [];
+
+  if (eventHandlers && typeof eventHandlers === 'object') {
+    // Set up delegation after microtask (viewport needs to be in DOM)
+    const setupDelegation = () => {
+      for (const [eventType, handler] of Object.entries(eventHandlers)) {
+        const cleanup = delegate(viewport, 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);
+          }
+        });
+        delegateCleanups.push(cleanup);
+      }
+    };
+
+    if (typeof queueMicrotask === 'function') {
+      queueMicrotask(setupDelegation);
+    } else {
+      setupDelegation();
+    }
+  }
+
+  // ---- Programmatic scroll API ----
+
+  /**
+   * Scroll to bring a specific item index into view.
+   * @param {number} index - Zero-based item index
+   * @param {Object} [scrollOptions] - Options
+   * @param {'start'|'center'|'end'} [scrollOptions.align='start'] - Alignment in viewport
+   */
+  container.scrollToIndex = (index, scrollOptions = {}) => {
+    const { align = 'start' } = scrollOptions;
+    const totalItems = allItems.length;
+    const clampedIndex = Math.max(0, Math.min(index, totalItems - 1));
+
+    const height = typeof containerHeight === 'number'
+      ? containerHeight
+      : (container.clientHeight || 400);
+
+    let targetTop;
+    if (align === 'center') {
+      targetTop = clampedIndex * itemHeight - (height / 2) + (itemHeight / 2);
+    } else if (align === 'end') {
+      targetTop = (clampedIndex + 1) * itemHeight - height;
+    } else {
+      targetTop = clampedIndex * itemHeight;
+    }
+
+    targetTop = Math.max(0, targetTop);
+
+    if (container.scrollTop !== undefined) {
+      container.scrollTop = targetTop;
+    }
+    scrollTop.set(targetTop);
+  };
+
+  // ---- Cleanup method ----
+  container._dispose = () => {
+    dom.removeEventListener(container, 'scroll', onScroll);
+    if (rafId !== null) {
+      (typeof cancelAnimationFrame === 'function' ? cancelAnimationFrame : clearTimeout)(rafId);
+      rafId = null;
+    }
+    for (const cleanup of delegateCleanups) cleanup();
+    delegateCleanups.length = 0;
+    itemMap.clear();
+  };
+
+  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/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;
   }
@@ -516,7 +526,12 @@ export class Pulse {
    * unsub(); // Stop listening
    */
   subscribe(fn) {
-    const subscriber = { run: fn, dependencies: new Set() };
+    const self = this;
+    const subscriber = {
+      run() { fn(self.peek()); },
+      dependencies: new Set(),
+      _isSubscriber: true
+    };
     this.#subscribers.add(subscriber);
     return () => this.#subscribers.delete(subscriber);
   }
@@ -948,6 +963,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 +980,8 @@ export function effect(fn, options = {}) {
       }
     },
     dependencies: new Set(),
-    cleanups: []
+    cleanups: [],
+    _generation: 0
   };
 
   // HMR: Register effect with current module

package/types/dom.d.ts

@@ -349,3 +349,136 @@ export declare function configureA11y(options: {
  * Compute the Longest Increasing Subsequence (used internally by list())
  */
 export declare function computeLIS(arr: number[]): number[];
+
+// =============================================================================
+// Event Delegation
+// =============================================================================
+
+/**
+ * Attach a delegated event listener to a parent element.
+ * Events from descendants matching the selector bubble up to the parent.
+ * @returns Cleanup function to remove the listener
+ */
+export declare function delegate(
+  parent: HTMLElement,
+  eventType: string,
+  selector: string,
+  handler: (event: Event, matchedElement: HTMLElement) => void
+): () => void;
+
+/** Delegated list event handlers */
+export interface DelegatedListHandlers<T> {
+  [eventType: string]: (event: Event, item: T, index: number) => void;
+}
+
+/** Options for delegatedList */
+export interface DelegatedListOptions<T> {
+  on?: DelegatedListHandlers<T>;
+  recycle?: boolean;
+}
+
+/**
+ * Create a reactive list with delegated event handlers.
+ * A single listener is placed on the parent container for each event type.
+ */
+export declare function delegatedList<T>(
+  getItems: Reactive<T[]>,
+  template: ListTemplate<T>,
+  keyFn: KeyFn<T>,
+  options?: DelegatedListOptions<T>
+): DocumentFragment;
+
+// =============================================================================
+// Virtual Scrolling
+// =============================================================================
+
+/** Options for virtualList */
+export interface VirtualListOptions<T> {
+  /** Fixed row height in pixels (required) */
+  itemHeight: number;
+  /** Extra items above/below viewport (default: 5) */
+  overscan?: number;
+  /** Viewport height in px or 'auto' (default: 400) */
+  containerHeight?: number | 'auto';
+  /** Enable element recycling (default: false) */
+  recycle?: boolean;
+  /** Delegated event handlers */
+  on?: DelegatedListHandlers<T>;
+}
+
+/** Scroll alignment options */
+export interface ScrollToIndexOptions {
+  /** Alignment in viewport (default: 'start') */
+  align?: 'start' | 'center' | 'end';
+}
+
+/** Virtual list container element with extra methods */
+export interface VirtualListElement extends HTMLElement {
+  /** Scroll to bring a specific item index into view */
+  scrollToIndex(index: number, options?: ScrollToIndexOptions): void;
+  /** Dispose scroll listeners and cleanup */
+  _dispose(): void;
+}
+
+/**
+ * Create a virtual scrolling list that renders only visible items.
+ */
+export declare function virtualList<T>(
+  getItems: Reactive<T[]>,
+  template: ListTemplate<T>,
+  keyFn: KeyFn<T>,
+  options: VirtualListOptions<T>
+): VirtualListElement;
+
+// =============================================================================
+// Element Recycling Pool
+// =============================================================================
+
+/** Options for createElementPool */
+export interface ElementPoolOptions {
+  /** Max recycled elements per tag name (default: 50) */
+  maxPerTag?: number;
+  /** Max total recycled elements (default: 200) */
+  maxTotal?: number;
+  /** Reset attributes/styles on release (default: true) */
+  resetOnRecycle?: boolean;
+}
+
+/** Pool statistics */
+export interface PoolStats {
+  size: number;
+  hits: number;
+  misses: number;
+  hitRate: number;
+}
+
+/** Element recycling pool */
+export interface ElementPool {
+  /** Acquire an element from the pool or create a new one */
+  acquire(tagName: string): HTMLElement;
+  /** Release an element back to the pool for reuse */
+  release(element: HTMLElement): boolean;
+  /** Get pool statistics */
+  stats(): PoolStats;
+  /** Clear all pooled elements */
+  clear(): void;
+  /** Reset statistics counters */
+  resetStats(): void;
+  /** Current number of pooled elements */
+  readonly size: number;
+}
+
+/**
+ * Create an element recycling pool
+ */
+export declare function createElementPool(options?: ElementPoolOptions): ElementPool;
+
+/**
+ * Get the default global element pool (lazy singleton)
+ */
+export declare function getPool(): ElementPool;
+
+/**
+ * Reset and clear the default pool
+ */
+export declare function resetPool(): void;

package/types/index.d.ts

@@ -68,7 +68,21 @@ export {
   portal,
   errorBoundary,
   transition,
-  whenTransition
+  whenTransition,
+  delegate,
+  DelegatedListHandlers,
+  DelegatedListOptions,
+  delegatedList,
+  VirtualListOptions,
+  ScrollToIndexOptions,
+  VirtualListElement,
+  virtualList,
+  ElementPoolOptions,
+  PoolStats,
+  ElementPool,
+  createElementPool,
+  getPool,
+  resetPool
 } from './dom';
 
 // Router