@zakkster/lite-observe 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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

package/README.md

@@ -148,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
@@ -160,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
@@ -174,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
@@ -192,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.
@@ -212,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.

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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zakkster/lite-observe",
-    "version": "1.0.3",
+    "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",

package/src/Resize.js

@@ -37,12 +37,13 @@ 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
  */
@@ -55,12 +56,16 @@ function drainResize() {
         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
@@ -68,14 +73,17 @@ function drainResize() {
         // 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);
+            }
         }
     }
 }
@@ -129,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;
@@ -163,11 +181,10 @@ export function observeResize(element, options) {
             }
             // 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).
-            disposeNode(slot.contentWidth);
-            disposeNode(slot.contentHeight);
-            disposeNode(slot.borderWidth);
-            disposeNode(slot.borderHeight);
+            // 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); }
         }
     }