@zakkster/lite-observe 1.0.3 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 1.1.1 -- Late mixed-box joiner reads the last delivered size, not a stale zero
+
+### Fixed
+
+- **A late `observeResize` mixed-box joiner no longer reads 0 until the next
+  resize (B-4).** 1.1.0's lazy box-pair mint was correct for cost but wrong for
+  value: when a second consumer asked for the other box on an element already
+  under observation, its pair was minted fresh at `signal(0)` and nothing wrote
+  it until the element next resized -- on a settled layout, potentially never, so
+  a border-box reader mounted into a stable layout saw a zero-size element with
+  no error and no warning. `drainResize` now parks the last delivered box
+  dimensions on the slot as four primitives (`lastCW`/`lastCH`/`lastBW`/`lastBH`)
+  -- numbers only, no browser object retained, no allocation added to the hot
+  path -- and a lazily minted pair is seeded from them (`=== null ? 0 : x`, so a
+  parked 0 survives and a never-delivered box still reads 0). Before any delivery
+  the parked fields are null and a freshly minted pair reads 0, unchanged. The
+  slot literal births the four fields as `null` for hidden-class stability. No
+  API change; the drain path stays zero-allocation (Phase A `maxMajor=0` holds)
+  and retention stays 0 per cycle.
+
+## 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

@@ -146,7 +146,9 @@ interface ResizeHandle {
 
 Width and height are independent fine-grained signals. N consumers of the same element share one underlying `ResizeObserver.observe()` call; the element is unobserved when the last handle is disposed.
 
-`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.
+`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. A consumer that joins an already-observed element after a delivery has happened is seeded from that element's last delivered size for its box (the slot parks those numbers), so it reads the real size at once rather than a zero that would persist until the next resize; before any delivery has arrived, a freshly minted pair reads 0. 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`
 
@@ -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

@@ -12,16 +12,22 @@ registry: N consumers of the same element share one underlying observer.
   independent signals (Object.is-gated). First emission async. `options.box`
   selects `'content'` (default, contentRect) or `'border'` (borderBoxSize,
   matches getBoundingClientRect). Mixed-box consumers of one element still
-  share a single observation.
+  share a single observation; a late joiner is seeded from the element's
+  last delivered size for its box (0 if nothing has been delivered yet),
+  not a stale zero until the next resize.
+  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 +37,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.1",
     "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

@@ -12,6 +12,13 @@
  * source. ResizeObserver fires with sub-pixel precision; we forward the raw
  * `contentRect.width` / `contentRect.height` values.
  *
+ * Each slot also parks the last delivered box dimensions as four primitives
+ * (no browser object retained, no allocation on the drain path). A late
+ * mixed-box joiner that mints the other pair after delivery has already
+ * happened reads those last numbers immediately, not a stale zero that would
+ * persist until the element next resizes; before any delivery the parked
+ * fields are null and a freshly minted pair reads 0.
+ *
  * SSR-safe. In a Node environment without `ResizeObserver`, signals are
  * created and stay at zero; observe is a no-op.
  */
@@ -37,12 +44,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,27 +63,38 @@ function drainResize() {
         const entry = entries[i];
         const slot = slots.get(entry.target);
         if (slot === undefined) continue;
-        // Content box: the historical default. Matches the rect a consumer
-        // would derive from `getBoundingClientRect` after subtracting
-        // padding + border.
+        // 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;
-        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
-        // plus the differential measured via getBoundingClientRect at the
-        // 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.
+        // Older browsers without borderBoxSize fall back to contentRect; for
+        // zero-alloc cleanliness we just mirror content here when it is absent,
+        // so a legacy-runtime border consumer sees content-box values until the
+        // next layout pass. Resolve both dimensions into locals once (numbers,
+        // not references) so the parking and the guarded write below reuse them.
         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);
+        const bw = (bbs && bbs.length > 0) ? bbs[0].inlineSize : rect.width;
+        const bh = (bbs && bbs.length > 0) ? bbs[0].blockSize : rect.height;
+        // Park the last delivered numbers on the slot unconditionally so a late
+        // mixed-box joiner can seed its lazily-minted pair from the element's
+        // real size instead of a stale zero (B-4). Four primitives: zero
+        // allocation, no browser object retained.
+        slot.lastCW = rect.width;
+        slot.lastCH = rect.height;
+        slot.lastBW = bw;
+        slot.lastBH = bh;
+        // Content box: the historical default. Matches the rect a consumer
+        // would derive from `getBoundingClientRect` after subtracting
+        // 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: written only if a border-box consumer minted the pair.
+        if (slot.borderWidth !== null) {
+            slot.borderWidth.set(bw);
+            slot.borderHeight.set(bh);
         }
     }
 }
@@ -119,7 +138,9 @@ function ensureObserver() {
  * its own dispose. The element stays observed until every handle has been
  * disposed. Consumers requesting different boxes for the same element
  * cooperate transparently: a single ResizeObserver fires both, and each
- * handle surfaces the pair it asked for.
+ * handle surfaces the pair it asked for. A handle that joins an already-
+ * observed element after a delivery is seeded from that element's last
+ * delivered size for its box; before any delivery it reads 0.
  *
  * @param {Element} element
  * @param {ResizeOptions} [options]
@@ -129,17 +150,45 @@ 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,
+            // Last delivered box dimensions, parked as primitives by
+            // drainResize so a late mixed-box joiner seeds its pair from the
+            // element's real size, not a stale zero (B-4). null until the first
+            // delivery; a null-check (not `??`) reads that as 0 at mint time.
+            lastCW: null,
+            lastCH: null,
+            lastBW: null,
+            lastBH: 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. Seed from the last delivered numbers so a late
+    // joiner reads the element's real size at once, not a stale zero until the
+    // next resize (B-4). Explicit `=== null ? 0 : x` rather than `?? 0`: only
+    // null (never delivered) means "no size yet" and reads 0; any delivered
+    // number, 0 included, passes through untouched. Law: null is not zero.
+    if (box === 'border') {
+        if (slot.borderWidth === null) {
+            slot.borderWidth = signal(slot.lastBW === null ? 0 : slot.lastBW);
+            slot.borderHeight = signal(slot.lastBH === null ? 0 : slot.lastBH);
+        }
+    } else {
+        if (slot.contentWidth === null) {
+            slot.contentWidth = signal(slot.lastCW === null ? 0 : slot.lastCW);
+            slot.contentHeight = signal(slot.lastCH === null ? 0 : slot.lastCH);
+        }
+    }
     slot.refCount++;
 
     let disposed = false;
@@ -163,11 +212,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); }
         }
     }