@zakkster/lite-observe 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## 1.1.0 -- Lazy resize box-pair allocation + pooled-node census docs
+
+### Changed
+
+- **`observeResize` allocates only the box pair the first caller asks for
+  (B-2).** Previously every `observeResize` slot minted four signal nodes
+  (content width/height + border width/height) regardless of the `box`
+  requested. It now mints only the requested pair -- 2 nodes in the common
+  case -- and lazily adds the other pair only when a mixed-box consumer asks
+  for it on the same element (then 4). Shared-slot refcounting and mixed-box
+  cooperation are unchanged: a content consumer and a border consumer on one
+  element still share a single underlying `ResizeObserver` observation and
+  each reads its own pair. `drainResize` null-guards each pair write and stays
+  zero-allocation; `dispose` frees only the pairs that were minted. The slot
+  literal keeps all four fields present at birth (initialized `null`) so the
+  hot-path hidden class stays stable. Backward-compatible: the handle surface
+  and the shared-observation contract are unchanged; only the pooled-node
+  footprint of a single-box consumer drops from 4 to 2.
+
+### Documentation
+
+- **Pooled-node cost documented per entry point (B-2).** README and `llms.txt`
+  now state the steady-state (while-observed) pooled signal-node cost next to
+  every entry point: `observeResize` 2 (4 mixed-box), `observeIntersection` 2
+  per (element, options-key), `observeMutation` 1, `observeMutationSelector` 4
+  (added + removed + inner tick + effect), `observeMedia` 1 per query string,
+  `documentVisible` 1 module-scope. All are freed on final dispose. A new
+  "Pooled-registry census" note in Design notes explains that a consumer
+  sizing a capped registry via `createRegistry({ maxNodes, prealloc,
+  onCapacityExceeded })` must sum these counts over concurrently observed
+  elements/keys/queries; guessing low throws `CapacityError` from inside the
+  library.
+- **`observeMedia` documented as the reactive replacement for one-shot
+  `matchMedia` reads.** A README line notes that
+  `observeMedia('(prefers-reduced-motion: reduce)')` (and similar) is the
+  reactive answer to hand-rolled `matchMedia` reads that never update when the
+  OS setting changes mid-session.
+
+## 1.0.3 -- Batched paired writes + peer range bump
+
+### Changed
+
+- **Peer range bumped to `^1.5.0` (B-3).** The source is written against the
+  modern callable surface and the synchronous flush semantics the batch fix
+  depends on; the old `^1.2.2` advertised a line that predates both the pooled
+  registry and that flush behaviour. README and `llms.txt` now state that
+  effects observing a lite-observe handle flush synchronously on the observer
+  callback.
+
+### Fixed
+
+- **Paired signal writes are now batched (B-1).** Each observer delivery
+  writes a logically-atomic pair -- `width` + `height` (Resize),
+  `isIntersecting` + `ratio` (Intersection), `added` + `removed`
+  (MutationSelector) -- as two independent `set()` calls. Because lite-signal
+  (>= 1.4) flushes effects synchronously in the writing call stack (unlike the
+  microtask-deferred libraries that coalesced these invisibly), a consumer
+  effect reading both halves ran twice per observation, the first run seeing
+  the new value paired with a stale one. Every pair is now wrapped in
+  lite-signal `batch()` so the effect wakes once per delivery on a consistent
+  state. Resize and Intersection batch the whole delivery, so N observed
+  elements in one callback flush once, not 2N times.
+- **Zero-alloc preserved.** The batching uses the hoisted stable-function +
+  module/handle-scope slot pattern (`pendingEntries` / `pendingBucket` /
+  `pendA` / `pendR` parked for a stable `drainResize` / `drainIntersection` /
+  `commitPair`); no per-fire closure is minted. Slots are captured and nulled
+  before the drain loop so a throwing consumer effect cannot retain the
+  browser-owned entries array. Allocation gate unchanged: 0 B/call, 0
+  scavenges on all dispatch paths.
+- **observe\* handles now dispose their lite-signal nodes on final teardown.**
+  On the last dispose of a refcounted slot (Resize width/height + border pair,
+  Intersection `isIntersecting` + `ratio`, Mutation `tick`) -- and
+  unconditionally for MutationSelector's per-handle `added` / `removed` -- the
+  slot's `signal()` nodes are now released via lite-signal `dispose()`. Prior
+  to this, each observe/dispose cycle tore down the observer and Map slot but
+  leaked the pooled signal nodes, permanently retaining them (+4 Resize, +2
+  Intersection, +1 Mutation, +2 MutationSelector per cycle) and throwing
+  `CapacityError` under a capped registry. Disposal happens only when the last
+  consumer leaves, so shared consumers are unaffected; a retained handle's read
+  returns undefined and `set()` is inert (gen guard), keeping it
+  fail-closed-safe. Mutation also nulls its retained browser records
+  (`lastRecords = EMPTY`) so the final batch is not pinned by the dead slot.
+
 ## 1.0.1 -- Internal: delegate to @zakkster/lite-cleanup
 
 ### Changed

package/README.md

@@ -7,6 +7,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-observe?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-observe)
 [![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-observe?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-observe)
 [![lite-signal peer](https://img.shields.io/badge/peer-lite--signal-blue?style=for-the-badge)](https://github.com/PeshoVurtoleta/lite-signal)
+![Tree-Shakeable](https://img.shields.io/badge/tree--shakeable-yes-brightgreen)
 ![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
 
@@ -147,6 +148,8 @@ Width and height are independent fine-grained signals. N consumers of the same e
 
 `options.box` selects which box the `width` / `height` signals surface: `'content'` (default) mirrors `entry.contentRect`; `'border'` mirrors `entry.borderBoxSize` (includes padding + border, matching `getBoundingClientRect()`). Mixed-box consumers of the *same* element still share a single underlying observation -- one `ResizeObserver` fires both, and each handle reads the pair it asked for. On legacy runtimes without `borderBoxSize`, a border-box reader sees content-box values until the next layout.
 
+Pooled signal nodes: 2 while observed (the requested box pair; 4 if both content- and border-box consumers observe the same element). Freed on last dispose.
+
 ### `observeIntersection(element, options?)` -> `IntersectionHandle`
 
 ```ts
@@ -159,6 +162,8 @@ interface IntersectionHandle {
 
 Equivalent options share one underlying observer. Equivalence is `(root by reference, rootMargin by string, threshold by value/order)`. Different options spawn distinct observers, per spec.
 
+Pooled signal nodes: 2 per (element, options-key) while observed (`isIntersecting` + `ratio`). Freed on last dispose.
+
 ### `observeMutation(element, options)` -> `MutationHandle`
 
 ```ts
@@ -173,6 +178,8 @@ Mutations are events, not state: surfacing the latest `MutationRecord[]` as a si
 
 Consumers asking for the same element with the same option set share one observer; differing options spawn distinct observers.
 
+Pooled signal nodes: 1 while observed (the `tick`). Freed on last dispose.
+
 ### `observeMutationSelector(root, selector, options?)` -> `MutationSelectorHandle`
 
 ```ts
@@ -191,14 +198,22 @@ With `subtree: true`, the walk also runs `querySelectorAll(selector)` against ad
 
 **Allocation note.** `added` / `removed` arrays are allocated fresh per batch that has at least one matching mutation, so consumers may safely retain a reference for later inspection. Batches with zero matches return the same frozen empty array (no allocation). This is the one deliberate departure from strict library-side zero-GC, made for consumer-ergonomics; the underlying `observeMutation` dispatch it builds on stays zero-alloc.
 
+Pooled signal nodes: 4 while observed (`added` + `removed`, plus the inner `observeMutation` tick and one effect). Freed on last dispose.
+
 ### `observeMedia(query)` -> `Signal<boolean>`
 
 Returns a boolean signal that reflects the live match state of the given media query. The same query string returns the same signal node across calls. The underlying `change` listener is attached lazily on first read (via lite-signal's observer-lifecycle hook) and detached when no consumer is reading -- an imported-but-unread query costs only the signal node and a Map entry.
 
+`observeMedia(query)` is the reactive replacement for hand-rolled one-shot `matchMedia('(prefers-reduced-motion: reduce)')` reads, which never update when the OS setting changes mid-session -- likely the single most common reason to reach for this package.
+
+Pooled signal nodes: 1, shared per query string. Freed on last dispose.
+
 ### `documentVisible: Signal<boolean>`
 
 Module-level signal. True iff `document.visibilityState === 'visible'`. Listener attached lazily on first read, detached on last unsubscribe.
 
+Pooled signal nodes: 1, module-scope (lives for the module's lifetime).
+
 ## Design notes
 
 **Fine-grained, not coarse.** A coarse-grained API would return a single `rect` signal carrying `{ width, height }`. That makes any read wake on any change, defeating the point. The fine-grained shape leans on lite-signal's `Object.is` equality gate to halt propagation at unchanged sources.
@@ -211,6 +226,8 @@ Module-level signal. True iff `document.visibilityState === 'visible'`. Listener
 
 **Zero-GC steady state.** Library-side allocations happen at registration; the callback path uses indexed `for` loops, no iterators, no closures created per callback. Browser-allocated entries (the `ResizeObserverEntry[]`, the `MutationRecord[]`) we cannot avoid; we add nothing to them.
 
+**Pooled-registry census.** A consumer running `createRegistry({ maxNodes, prealloc, onCapacityExceeded })` (lite-signal 1.5.0) must size the pool from a census of every signal the app allocates. A library minting signals on the default registry is part of that census -- lite-observe is no exception. The per-entry-point counts above (2 per observed element for resize, up to 4 mixed-box; 2 per intersection key; 1 per mutation; 4 per mutation-selector; 1 per media query; 1 module-scope visibility) are the inputs to that sum: add the steady-state count for each entry point times the number of elements/keys/queries observed concurrently. These are steady-state (while-observed) costs, freed on final dispose, so the census is of peak concurrency, not lifetime turnover. Guessing low throws `CapacityError` at runtime from inside the library.
+
 ## Benchmarks
 
 The bench drives each subsystem's dispatch path synthetically (browsers don't run in Node) with one live subscriber per signal so writes actually propagate, and measures heap growth and minor-GC (scavenge) count under load. The gate **fails the build** if any path shows a single scavenge or more than 1 byte/call. That threshold being zero is the point: one accidental allocation regresses the gate.
@@ -232,6 +249,7 @@ The headline figure is **B/call and scavenges, not nanoseconds.** Zero bytes and
 - **Last-dispose tears down.** When the refcount on an element-slot hits zero, the element is unobserved. When an `IntersectionObserver`'s slot map empties, the observer is disconnected and dropped from the cache. The same applies to the `ResizeObserver` singleton: when the last slot is disposed, the singleton is disconnected and nulled. The next `observeResize()` cheaply rebuilds it -- the one-allocation cost is paid only on the first observe after a fully-idle period, never per-call.
 - **Untracked entries are silently ignored.** If a browser delivers an entry for an element not currently in the slot map (e.g. dispose raced with the callback), the entry is skipped.
 - **The first emission is async.** Both `ResizeObserver` and `IntersectionObserver` deliver their initial observation in a future task. Signals read as `0` / `false` until then.
+- **Effects flush synchronously on the observer callback.** Unlike microtask-deferred signal libraries, an effect reading a lite-observe handle re-runs synchronously within the observer's own callback stack (lite-signal flushes in the writing call stack). The paired writes each delivery makes -- width + height, isIntersecting + ratio, added + removed -- are wrapped in a single `batch()` so a consumer effect reading both halves wakes exactly once per delivery, on a consistent state, never on a torn intermediate.
 - **Test isolation utilities.** `_resetResize`, `_resetIntersection`, `_resetMutation`, `_resetMedia`, `_forceVisibilitySync` are exported with a leading underscore. They are not part of the stable public API and exist for test harnesses.
 - **ResizeObserver loop limits and synchronous downstream writes.** The browser dispatches `ResizeObserver` entries to its callback synchronously; we write width / height signals from inside that callback. If a *consumer* effect on those signals then synchronously writes layout-affecting styles (anything that changes element box size, not just `transform`), the browser will throw "ResizeObserver loop limit exceeded" because the same observer would need to re-fire in the same frame. The standard mitigation is to defer DOM writes one frame via `rafEffect` from `@zakkster/lite-raf`, or to use `transform`-only updates which compose without triggering layout. `@zakkster/lite-floating`'s own update loop defers via `requestAnimationFrame` for this reason; consumers writing their own RO-driven effects should do the same.
 - **`observeMedia` cache lifecycle.** Each unique query string is memoised in a `Map` keyed by the string itself. The memo is evicted when the signal's last observer detaches (via lite-signal's `observeObservers` 0-to-1 transition we already use for lazy listener attachment); the cache size is bounded to "queries currently being observed". A consumer who holds a strong reference to the signal across an unobserved period continues to work correctly -- the closure binds `mql` and the change handler, and re-subscribing re-attaches the listener via the same `observeObservers` lifecycle. New callers asking for the same query during such a held-but-unobserved period get a fresh signal+MQL pair (briefly wasteful, never wrong). The pathological case of dynamic query strings (`(min-width: ${changingWidth}px)`) is fully addressed by the eviction.

package/llms.txt

@@ -13,15 +13,19 @@ registry: N consumers of the same element share one underlying observer.
   selects `'content'` (default, contentRect) or `'border'` (borderBoxSize,
   matches getBoundingClientRect). Mixed-box consumers of one element still
   share a single observation.
+  Pooled nodes: 2 while observed (the requested box pair; 4 if both content-
+  and border-box consumers observe the same element). Freed on last dispose.
 
 - `observeIntersection(el, options?)` -> `{ isIntersecting: Signal<boolean>, ratio: Signal<number>, dispose }`
   Observers keyed by (root, rootMargin, threshold). Equivalent options
   share one observer. Different options spawn distinct ones (per spec).
+  Pooled nodes: 2 per (element, options-key) while observed. Freed on last dispose.
 
 - `observeMutation(el, options)` -> `{ tick: Signal<number>, peekRecords(), dispose }`
   Tick is a monotonic counter; increments per delivered batch.
   peekRecords() returns the latest MutationRecord[] without tracking and
   without copying. One observer per (element, optionsKey).
+  Pooled nodes: 1 while observed (the tick). Freed on last dispose.
 
 - `observeMutationSelector(root, selector, options?)` -> `{ added: Signal<Element[]>, removed: Signal<Element[]>, tick: Signal<number>, peekRecords(), dispose }`
   Selector-filtered wrapper over observeMutation. Surfaces matching elements
@@ -31,14 +35,17 @@ registry: N consumers of the same element share one underlying observer.
   container are caught. added/removed allocate fresh arrays only on batches
   with a match (so consumers may retain them); zero-match batches reuse a
   frozen empty array. Composes the inner handle's FinalizationRegistry safety.
+  Pooled nodes: 4 while observed (added + removed, plus the inner
+  observeMutation tick and one effect). Freed on last dispose.
 
 - `observeMedia(query)` -> `Signal<boolean>`
   One signal per query string, cached. Listener attached lazily via
   lite-signal observeObservers; detached when no consumer is reading.
+  Pooled nodes: 1, shared per query string. Freed on last dispose.
 
 - `documentVisible: Signal<boolean>`
   Module-level. True iff document.visibilityState === 'visible'.
-  Lazy listener.
+  Lazy listener. Pooled nodes: 1, module-scope.
 
 ## Orphan-safety utility (public)
 
@@ -73,6 +80,11 @@ registry: N consumers of the same element share one underlying observer.
 - Indexed for-loops in callbacks, no iterator allocation. Closures
   pre-allocated at registration, not per callback. Library-side allocations
   occur only at registration time.
+- Effects observing a handle flush SYNCHRONOUSLY on the observer callback
+  (unlike microtask-deferred signal libraries). Each delivery's paired writes
+  (width+height, isIntersecting+ratio, added+removed) are wrapped in one
+  batch(), so a consumer effect reading both halves wakes once per delivery on
+  a consistent state, never on a torn intermediate.
 - Orphan-handle cleanup via shared FinalizationRegistry. Handles from
   observeResize / observeIntersection / observeMutation are registered;
   dropping the handle without dispose() triggers cleanup on the next GC
@@ -83,4 +95,4 @@ registry: N consumers of the same element share one underlying observer.
 
 ## Peer dependency
 
-@zakkster/lite-signal ^1.2.2
+@zakkster/lite-signal ^1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zakkster/lite-observe",
-    "version": "1.0.2",
+    "version": "1.1.0",
     "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
     "description": "Zero-GC reactive bridge for the DOM observer APIs. ResizeObserver, IntersectionObserver, MutationObserver, matchMedia, and Page Visibility collapsed to fine-grained lite-signal signals. Shared registry: N components observing the same element pay one observer cost.",
     "type": "module",
@@ -53,7 +53,7 @@
         "@zakkster/lite-cleanup": "^1.0.0"
     },
     "peerDependencies": {
-        "@zakkster/lite-signal": "^1.2.2"
+        "@zakkster/lite-signal": "^1.5.0"
     },
     "publishConfig": {
         "access": "public"

package/src/Intersection.js

@@ -17,7 +17,7 @@
  * visibility do not wake on ratio changes when the boolean is unchanged.
  */
 
-import { signal } from '@zakkster/lite-signal';
+import { signal, batch, dispose as disposeNode } from '@zakkster/lite-signal';
 import { attachFinalizer } from './_finalize.js';
 
 /**
@@ -59,14 +59,26 @@ function rootIdFor(root) {
 // optionsKey -> { observer, slots: Map<Element, slot>, options }
 const observersByKey = new Map();
 
+// Delivery slots for the batched drain. The browser-owned `entries` array and
+// the target bucket are parked here between the per-bucket observer callback
+// and the stable `drainIntersection` reference, so the callback need not mint
+// a per-fire closure to carry them into `batch`.
+let pendingEntries = null;
+let pendingBucket = null;
+
 /**
  * Dispatch path. `entries` and the per-callback `this` binding are
  * browser-allocated; we add nothing. Indexed for-loop, no iterator.
  *
- * @param {IntersectionObserverEntry[]} entries
- * @param {{ slots: Map<Element, any> }} bucket
+ * Batches the whole delivery so N observed elements flush once, not 2N times.
+ * Captures and nulls both slots BEFORE the loop: a consumer effect throwing
+ * mid-drain must not retain the browser-owned entries array or the bucket.
  */
-function dispatchIntersection(entries, bucket) {
+function drainIntersection() {
+    const entries = pendingEntries;
+    const bucket = pendingBucket;
+    pendingEntries = null;
+    pendingBucket = null;
     const map = bucket.slots;
     for (let i = 0; i < entries.length; i++) {
         const entry = entries[i];
@@ -90,7 +102,13 @@ function ensureBucket(options) {
     }
     bucket = { observer: null, slots: new Map(), key };
     bucket.observer = new IntersectionObserver(
-        function (entries) { dispatchIntersection(entries, bucket); },
+        // Cold closure: created once per bucket construction, not per delivery.
+        // It only parks the slots and hands the stable drain to `batch`.
+        function (entries) {
+            pendingEntries = entries;
+            pendingBucket = bucket;
+            batch(drainIntersection);
+        },
         options
     );
     observersByKey.set(key, bucket);
@@ -142,6 +160,10 @@ export function observeIntersection(element, options) {
                 if (bucket.observer !== null) bucket.observer.disconnect();
                 observersByKey.delete(bucket.key);
             }
+            // Last consumer left: free the slot's pooled signal nodes so an
+            // observe/dispose cycle does not permanently retain them.
+            disposeNode(slot.isIntersecting);
+            disposeNode(slot.ratio);
         }
     }
 

package/src/Mutation.js

@@ -21,7 +21,7 @@
  * the same options share; differing options get a distinct observer.
  */
 
-import { signal } from '@zakkster/lite-signal';
+import { signal, dispose as disposeNode } from '@zakkster/lite-signal';
 import { attachFinalizer } from './_finalize.js';
 
 function optionsKey(options) {
@@ -130,6 +130,10 @@ export function observeMutation(element, options) {
             if (inner.size === 0) {
                 slotsByElement.delete(element);
             }
+            // Last consumer left: free the slot's pooled tick node and drop
+            // the retained browser records so the final batch isn't pinned.
+            disposeNode(slot.tick);
+            slot.lastRecords = EMPTY;
         }
     }
 

package/src/MutationSelector.js

@@ -30,7 +30,7 @@
  *   the inner handle too.
  */
 
-import { signal, effect, dispose as disposeEffect } from '@zakkster/lite-signal';
+import { signal, effect, batch, dispose as disposeEffect } from '@zakkster/lite-signal';
 import { observeMutation } from './Mutation.js';
 
 const EMPTY_ARR = Object.freeze([]);
@@ -62,6 +62,16 @@ export function observeMutationSelector(root, selector, options) {
     const addedSig = signal(EMPTY_ARR);
     const removedSig = signal(EMPTY_ARR);
 
+    // Delivery slots for the batched pair-write. Parking the arrays here lets
+    // `commitPair` stay a single stable handle-scope reference (created once,
+    // cold), so no per-tick closure is minted to carry them into `batch`.
+    let pendA = null;
+    let pendR = null;
+    function commitPair() {
+        addedSig.set(pendA !== null ? pendA : EMPTY_ARR);
+        removedSig.set(pendR !== null ? pendR : EMPTY_ARR);
+    }
+
     const inner = observeMutation(root, opts);
 
     // Effect: every tick of the inner handle, walk the latest batch and
@@ -114,8 +124,11 @@ export function observeMutationSelector(root, selector, options) {
             }
         }
 
-        addedSig.set(added !== null ? added : EMPTY_ARR);
-        removedSig.set(removed !== null ? removed : EMPTY_ARR);
+        // Batch the atomic added/removed pair so a consumer effect reading
+        // both wakes once on a consistent state, not twice on a torn one.
+        pendA = added;
+        pendR = removed;
+        batch(commitPair);
     });
 
     let disposed = false;
@@ -124,6 +137,11 @@ export function observeMutationSelector(root, selector, options) {
         disposed = true;
         disposeEffect(fxHandle);
         inner.dispose();
+        // Per-handle signals (created once per call, not refcounted): free
+        // their pooled nodes on teardown. lite-signal `dispose` frees a
+        // signal node the same way it frees an effect handle.
+        disposeEffect(addedSig);
+        disposeEffect(removedSig);
     }
 
     return {

package/src/Resize.js

@@ -16,13 +16,18 @@
  * created and stay at zero; observe is a no-op.
  */
 
-import { signal } from '@zakkster/lite-signal';
+import { signal, batch, dispose as disposeNode } from '@zakkster/lite-signal';
 import { attachFinalizer } from './_finalize.js';
 
 // One singleton observer per page. Lazy: only constructed on first observe(),
 // which keeps the module SSR-safe and lets tests install a mock before use.
 let observerInstance = null;
 
+// Delivery slot for the batched drain. The browser-owned `entries` array is
+// parked here between the observer callback and the stable `drainResize`
+// reference so we never mint a per-fire closure to carry it into `batch`.
+let pendingEntries = null;
+
 // Element -> slot. A slot survives so long as refCount > 0. When it hits 0,
 // the element is unobserved and the slot is dropped from the map.
 const slots = new Map();
@@ -32,26 +37,35 @@ const slots = new Map();
  *
  * `entries` is allocated by the browser; we cannot avoid that. We iterate
  * with an indexed for-loop (no iterator allocation) and look up each entry's
- * target in the slot map. Each slot carries four signals (content width/
- * height and border width/height); we write all four every fire. Setting
- * a signal to its current value is a no-op under lite-signal's Object.is
- * equality, so consumers reading only one pair do not wake when the other
- * pair moved -- and consumers reading only `width` do not wake when only
- * `height` moved.
+ * target in the slot map. A slot carries only the box pair(s) its consumers
+ * asked for (content width/height and/or border width/height); each pair is
+ * written only when present (null-guarded), so an element observed for
+ * content-box alone never mints or writes border-box nodes. Setting a signal
+ * to its current value is a no-op under lite-signal's Object.is equality, so
+ * consumers reading only one pair do not wake when the other pair moved -- and
+ * consumers reading only `width` do not wake when only `height` moved.
  *
  * @param {ResizeObserverEntry[]} entries
  */
-function dispatch(entries) {
+function drainResize() {
+    // Capture and null the slot BEFORE the loop: if a consumer effect throws
+    // mid-drain, we must not retain the browser-owned entries array.
+    const entries = pendingEntries;
+    pendingEntries = null;
     for (let i = 0; i < entries.length; i++) {
         const entry = entries[i];
         const slot = slots.get(entry.target);
         if (slot === undefined) continue;
+        // rect is a field read, not an allocation. Hoisted here because the
+        // border fallback reads it too; content-box writes use it directly.
+        const rect = entry.contentRect;
         // Content box: the historical default. Matches the rect a consumer
         // would derive from `getBoundingClientRect` after subtracting
-        // padding + border.
-        const rect = entry.contentRect;
-        slot.contentWidth.set(rect.width);
-        slot.contentHeight.set(rect.height);
+        // padding + border. Written only if a content-box consumer minted it.
+        if (slot.contentWidth !== null) {
+            slot.contentWidth.set(rect.width);
+            slot.contentHeight.set(rect.height);
+        }
         // Border box: includes padding + border. Per spec the field is an
         // array (to support multi-column layout); we read the first entry.
         // Older browsers without borderBoxSize fall back to contentRect
@@ -59,18 +73,29 @@ function dispatch(entries) {
         // next layout. For zero-alloc cleanliness we just mirror content
         // here when borderBoxSize is absent; consumers who specifically
         // requested border-box on a legacy runtime will see content-box
-        // values until the next layout pass.
-        const bbs = entry.borderBoxSize;
-        if (bbs && bbs.length > 0) {
-            slot.borderWidth.set(bbs[0].inlineSize);
-            slot.borderHeight.set(bbs[0].blockSize);
-        } else {
-            slot.borderWidth.set(rect.width);
-            slot.borderHeight.set(rect.height);
+        // values until the next layout pass. Written only if a border-box
+        // consumer minted the pair.
+        if (slot.borderWidth !== null) {
+            const bbs = entry.borderBoxSize;
+            if (bbs && bbs.length > 0) {
+                slot.borderWidth.set(bbs[0].inlineSize);
+                slot.borderHeight.set(bbs[0].blockSize);
+            } else {
+                slot.borderWidth.set(rect.width);
+                slot.borderHeight.set(rect.height);
+            }
         }
     }
 }
 
+// Batch the whole delivery so N observed elements flush once, not 2N times.
+// `drainResize` is a stable module-level reference; parking `entries` in the
+// module slot keeps this callback closure-free per fire (zero alloc).
+function dispatch(entries) {
+    pendingEntries = entries;
+    batch(drainResize);
+}
+
 function ensureObserver() {
     if (observerInstance !== null) return observerInstance;
     if (typeof ResizeObserver === 'undefined') return null;
@@ -112,17 +137,27 @@ export function observeResize(element, options) {
     const box = (options && options.box === 'border') ? 'border' : 'content';
     let slot = slots.get(element);
     if (slot === undefined) {
+        // Keep all four fields present for hidden-class stability, but leave
+        // the unrequested pair null: we mint only the box a caller asks for.
         slot = {
-            contentWidth: signal(0),
-            contentHeight: signal(0),
-            borderWidth: signal(0),
-            borderHeight: signal(0),
+            contentWidth: null,
+            contentHeight: null,
+            borderWidth: null,
+            borderHeight: null,
             refCount: 0
         };
         slots.set(element, slot);
         const obs = ensureObserver();
         if (obs !== null) obs.observe(element);
     }
+    // Lazily mint the requested box pair if absent. Placed before refCount++
+    // so it also covers a later mixed-box caller joining an existing slot that
+    // only holds the other pair.
+    if (box === 'border') {
+        if (slot.borderWidth === null) { slot.borderWidth = signal(0); slot.borderHeight = signal(0); }
+    } else {
+        if (slot.contentWidth === null) { slot.contentWidth = signal(0); slot.contentHeight = signal(0); }
+    }
     slot.refCount++;
 
     let disposed = false;
@@ -144,6 +179,12 @@ export function observeResize(element, options) {
                 observerInstance.disconnect();
                 observerInstance = null;
             }
+            // Last consumer left: free the slot's pooled signal nodes so an
+            // observe/dispose cycle does not permanently retain them (which
+            // throws CapacityError under a capped registry). Only the pairs
+            // that were actually minted exist to free.
+            if (slot.contentWidth !== null) { disposeNode(slot.contentWidth); disposeNode(slot.contentHeight); }
+            if (slot.borderWidth !== null) { disposeNode(slot.borderWidth); disposeNode(slot.borderHeight); }
         }
     }