@zakkster/lite-observe 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 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)
 
@@ -232,6 +233,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

@@ -73,6 +73,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 +88,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.0.3",
     "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();
@@ -41,7 +46,11 @@ const slots = new Map();
  *
  * @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);
@@ -71,6 +80,14 @@ function dispatch(entries) {
     }
 }
 
+// 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;
@@ -144,6 +161,13 @@ 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).
+            disposeNode(slot.contentWidth);
+            disposeNode(slot.contentHeight);
+            disposeNode(slot.borderWidth);
+            disposeNode(slot.borderHeight);
         }
     }