@zakkster/lite-observe 1.0.0

package/src/Mutation.js

@@ -0,0 +1,153 @@
+/**
+ * @zakkster/lite-observe -- MutationObserver bridge.
+ *
+ * MutationObserver is event-shaped, not state-shaped: records arrive in
+ * batches, are inherently transient (the browser doesn't retain them), and
+ * different consumers may want to inspect different aspects (added nodes,
+ * removed nodes, attribute changes). Modelling "the current mutation" as a
+ * signal is a category error.
+ *
+ * Instead we surface a monotonic `tick` signal that increments on every
+ * delivered batch and a peek-only accessor for the latest batch. Consumers
+ * reacting only need to subscribe to `tick`; consumers needing the records
+ * call `peekRecords()` inside their effect body. The records array is the
+ * browser-allocated MutationRecord[] -- no copy.
+ *
+ * Sharing model: MutationObserver instances accept distinct `.observe(el,
+ * opts)` calls, but the option set is keyed to the (observer, target) pair
+ * by the browser, and once observed you cannot change the options without
+ * disconnecting. Pragmatically we key sharing by (element, optionsKey) and
+ * use one observer per slot. Two consumers asking for the same element with
+ * the same options share; differing options get a distinct observer.
+ */
+
+import { signal } from '@zakkster/lite-signal';
+import { attachFinalizer } from './_finalize.js';
+
+function optionsKey(options) {
+    // Stable serialisation of the option flags we accept. The set is small
+    // and finite, so direct concatenation beats JSON.stringify.
+    let k = '';
+    k += options.childList ? '1' : '0';
+    k += options.attributes ? '1' : '0';
+    k += options.characterData ? '1' : '0';
+    k += options.subtree ? '1' : '0';
+    k += options.attributeOldValue ? '1' : '0';
+    k += options.characterDataOldValue ? '1' : '0';
+    const filter = options.attributeFilter;
+    if (filter !== undefined) {
+        // Order matters semantically in the API; preserve consumer's order.
+        k += '|' + filter.join(',');
+    }
+    return k;
+}
+
+// element -> Map<optionsKey, slot>. WeakMap so detached elements can be GC'd
+// when consumers properly dispose -- and, critically, when they DON'T, the
+// engine's spec-defined observer-retains-target semantics are the only thing
+// keeping the element alive, rather than our own ad-hoc bookkeeping.
+const slotsByElement = new WeakMap();
+
+// The previous design held a parallel `Set<Element>` to support deterministic
+// enumeration in `_resetMutation` (WeakMap is not enumerable). That Set's
+// strong references completely defeated the WeakMap's GC behaviour: every
+// element ever observed lived until manual cleanup, even if the consumer had
+// dropped the element from the DOM and forgotten to dispose.
+//
+// The current design tracks the lightweight library objects (the
+// MutationObserver instances) instead. This isn't a full fix for the
+// forgot-to-dispose case -- both WebKit (HashSet<Ref<Node>>) and Chromium
+// (HeapVector<Member<Node>>) implementations of MutationObserver retain
+// strong references to their observed nodes internally, so a leaked
+// observer keeps its target alive regardless. But it removes the explicit
+// strong-ref Set from our code, makes the disposal path symmetric, and lets
+// engines apply their own optimisation/finalization machinery to the
+// observer chain. A v0.2.0 FinalizationRegistry-based auto-disconnect for
+// orphaned observers is the real fix.
+const activeObservers = new Set();
+
+function dispatchMutation(records, slot) {
+    slot.lastRecords = records;
+    slot.tick.set(slot.tick.peek() + 1);
+}
+
+/**
+ * @typedef {object} MutationHandle
+ * @property {import('@zakkster/lite-signal').Signal<number>} tick Monotonic counter; increments per delivered batch.
+ * @property {() => MutationRecord[]} peekRecords Returns the latest batch without tracking. Empty array before the first batch.
+ * @property {() => void} dispose
+ */
+
+const EMPTY = Object.freeze([]);
+
+/**
+ * Observe DOM mutations on `element` with the given options. Returns a
+ * handle whose `tick` signal increments each time a batch is delivered.
+ *
+ * @param {Node} element
+ * @param {MutationObserverInit} options
+ * @returns {MutationHandle}
+ */
+export function observeMutation(element, options) {
+    let inner = slotsByElement.get(element);
+    if (inner === undefined) {
+        inner = new Map();
+        slotsByElement.set(element, inner);
+    }
+    const key = optionsKey(options);
+    let slot = inner.get(key);
+    if (slot === undefined) {
+        slot = {
+            tick: signal(0),
+            lastRecords: EMPTY,
+            observer: null,
+            refCount: 0
+        };
+        if (typeof MutationObserver !== 'undefined') {
+            slot.observer = new MutationObserver(function (records) {
+                dispatchMutation(records, slot);
+            });
+            slot.observer.observe(element, options);
+            activeObservers.add(slot.observer);
+        }
+        inner.set(key, slot);
+    }
+    slot.refCount++;
+
+    function peekRecords() { return slot.lastRecords; }
+
+    let disposed = false;
+    function dispose() {
+        if (disposed) return;
+        disposed = true;
+        slot.refCount--;
+        if (slot.refCount === 0) {
+            if (slot.observer !== null) {
+                slot.observer.disconnect();
+                activeObservers.delete(slot.observer);
+            }
+            inner.delete(key);
+            if (inner.size === 0) {
+                slotsByElement.delete(element);
+            }
+        }
+    }
+
+    return attachFinalizer(
+        { tick: slot.tick, peekRecords: peekRecords, dispose: dispose },
+        dispose
+    );
+}
+
+/** @internal */
+export function _resetMutation() {
+    // Disconnect every active observer. The slotsByElement WeakMap drops
+    // its entries automatically once nothing else holds the elements.
+    for (const obs of activeObservers) obs.disconnect();
+    activeObservers.clear();
+}
+
+/** @internal */
+export function _mutationObserverCount() {
+    return activeObservers.size;
+}

package/src/MutationSelector.js

@@ -0,0 +1,136 @@
+/**
+ * @zakkster/lite-observe -- selector-filtered MutationObserver bridge.
+ *
+ * Wraps observeMutation with selector-based filtering. The common
+ * consumer pattern is "tell me when elements matching X are added or
+ * removed under this root" -- combobox option lists, infinite-scroll
+ * containers, autocomplete result panels. Without library-side
+ * support, every consumer reimplements the record walk + selector
+ * match, and most get the subtree-descendant case subtly wrong (a
+ * matching element added as a deep descendant of an added subtree
+ * arrives as a child of an addedNodes entry, not as its own entry).
+ *
+ * Signals:
+ *   added: Signal<Element[]>    -- matching elements added since last tick
+ *   removed: Signal<Element[]>  -- matching elements removed since last tick
+ *   tick: Signal<number>        -- monotonic batch counter (mirrors observeMutation)
+ *
+ * Allocation profile:
+ *   The added / removed arrays are allocated fresh per batch that has
+ *   at least one matching mutation. Consumer ergonomics win out over
+ *   strict zero-alloc here -- a returned array consumers might retain
+ *   for later inspection must be theirs, not the library's. Batches
+ *   with zero matches reuse the frozen empty array (no allocation).
+ *
+ * Cleanup:
+ *   Composes the inner observeMutation handle's dispose. The
+ *   FinalizationRegistry orphan safety net inherited from the inner
+ *   handle catches forgot-to-dispose; this wrapper does not need its
+ *   own registry registration since dropping the outer handle drops
+ *   the inner handle too.
+ */
+
+import { signal, effect, dispose as disposeEffect } from '@zakkster/lite-signal';
+import { observeMutation } from './Mutation.js';
+
+const EMPTY_ARR = Object.freeze([]);
+
+/**
+ * @typedef {object} MutationSelectorHandle
+ * @property {import('@zakkster/lite-signal').Signal<Element[]>} added
+ * @property {import('@zakkster/lite-signal').Signal<Element[]>} removed
+ * @property {import('@zakkster/lite-signal').Signal<number>} tick
+ * @property {() => MutationRecord[]} peekRecords
+ * @property {() => void} dispose
+ */
+
+/**
+ * Observe mutations under `root`, surfacing only nodes (or descendants
+ * of mutated subtrees, when `options.subtree` is true) matching `selector`.
+ *
+ * @param {Element} root         The mutation root.
+ * @param {string} selector      A CSS selector string. `.matches(selector)`
+ *                               must succeed on the host runtime.
+ * @param {MutationObserverInit} [options]  Forwarded to the underlying
+ *   MutationObserver. Defaults to `{ childList: true, subtree: true }`.
+ * @returns {MutationSelectorHandle}
+ */
+export function observeMutationSelector(root, selector, options) {
+    const opts = options || { childList: true, subtree: true };
+    const walkSubtree = opts.subtree === true;
+
+    const addedSig = signal(EMPTY_ARR);
+    const removedSig = signal(EMPTY_ARR);
+
+    const inner = observeMutation(root, opts);
+
+    // Effect: every tick of the inner handle, walk the latest batch and
+    // surface matching adds/removes. The effect is captured so we can
+    // dispose it in our own dispose path.
+    const fxHandle = effect(function () {
+        const t = inner.tick();
+        if (t === 0) return;            // initial seed: no batch yet
+        const records = inner.peekRecords();
+
+        let added = null;               // lazy alloc: only if a match shows up
+        let removed = null;
+
+        for (let i = 0; i < records.length; i++) {
+            const rec = records[i];
+            if (rec.type !== 'childList') continue;
+
+            const addedNodes = rec.addedNodes;
+            for (let j = 0; j < addedNodes.length; j++) {
+                const node = addedNodes[j];
+                if (node.nodeType !== 1) continue;     // not an Element
+                if (typeof node.matches === 'function' && node.matches(selector)) {
+                    if (added === null) added = [];
+                    added.push(node);
+                }
+                if (walkSubtree && typeof node.querySelectorAll === 'function') {
+                    const desc = node.querySelectorAll(selector);
+                    for (let k = 0; k < desc.length; k++) {
+                        if (added === null) added = [];
+                        added.push(desc[k]);
+                    }
+                }
+            }
+
+            const removedNodes = rec.removedNodes;
+            for (let j = 0; j < removedNodes.length; j++) {
+                const node = removedNodes[j];
+                if (node.nodeType !== 1) continue;
+                if (typeof node.matches === 'function' && node.matches(selector)) {
+                    if (removed === null) removed = [];
+                    removed.push(node);
+                }
+                if (walkSubtree && typeof node.querySelectorAll === 'function') {
+                    const desc = node.querySelectorAll(selector);
+                    for (let k = 0; k < desc.length; k++) {
+                        if (removed === null) removed = [];
+                        removed.push(desc[k]);
+                    }
+                }
+            }
+        }
+
+        addedSig.set(added !== null ? added : EMPTY_ARR);
+        removedSig.set(removed !== null ? removed : EMPTY_ARR);
+    });
+
+    let disposed = false;
+    function dispose() {
+        if (disposed) return;
+        disposed = true;
+        disposeEffect(fxHandle);
+        inner.dispose();
+    }
+
+    return {
+        added: addedSig,
+        removed: removedSig,
+        tick: inner.tick,
+        peekRecords: inner.peekRecords,
+        dispose: dispose
+    };
+}

package/src/Resize.js

@@ -0,0 +1,183 @@
+/**
+ * @zakkster/lite-observe -- ResizeObserver bridge.
+ *
+ * One singleton ResizeObserver instance for the whole page. N consumers
+ * observing the same element pay the cost of one underlying observation;
+ * the slot is reference-counted and the element is unobserved when the last
+ * consumer disposes.
+ *
+ * Two fine-grained numeric signals per element: width and height. Reading
+ * `width` does not wake a consumer that only reads `height`, because
+ * lite-signal's Object.is equality gate halts propagation at the unchanged
+ * source. ResizeObserver fires with sub-pixel precision; we forward the raw
+ * `contentRect.width` / `contentRect.height` values.
+ *
+ * SSR-safe. In a Node environment without `ResizeObserver`, signals are
+ * created and stay at zero; observe is a no-op.
+ */
+
+import { signal } 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;
+
+// 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();
+
+/**
+ * The observer callback. Hot path: must not allocate.
+ *
+ * `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.
+ *
+ * @param {ResizeObserverEntry[]} entries
+ */
+function dispatch(entries) {
+    for (let i = 0; i < entries.length; i++) {
+        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.
+        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.
+        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);
+        }
+    }
+}
+
+function ensureObserver() {
+    if (observerInstance !== null) return observerInstance;
+    if (typeof ResizeObserver === 'undefined') return null;
+    observerInstance = new ResizeObserver(dispatch);
+    return observerInstance;
+}
+
+/**
+ * @typedef {object} ResizeHandle
+ * @property {import('@zakkster/lite-signal').Signal<number>} width
+ * @property {import('@zakkster/lite-signal').Signal<number>} height
+ * @property {() => void} dispose
+ */
+
+/**
+ * @typedef {object} ResizeOptions
+ * @property {'content' | 'border'} [box] Which box dimensions to surface
+ *   on the `width` / `height` signals. Default `'content'` (matches
+ *   `contentRect`). Border box includes padding and border, matching
+ *   what `getBoundingClientRect()` reports.
+ */
+
+/**
+ * Observe an element's size as a pair of fine-grained signals.
+ *
+ * The first emission arrives asynchronously after the next layout. Until
+ * then both signals read zero. Multiple `observeResize(sameEl)` calls
+ * share one underlying observation and return distinct handles; each has
+ * 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.
+ *
+ * @param {Element} element
+ * @param {ResizeOptions} [options]
+ * @returns {ResizeHandle}
+ */
+export function observeResize(element, options) {
+    const box = (options && options.box === 'border') ? 'border' : 'content';
+    let slot = slots.get(element);
+    if (slot === undefined) {
+        slot = {
+            contentWidth: signal(0),
+            contentHeight: signal(0),
+            borderWidth: signal(0),
+            borderHeight: signal(0),
+            refCount: 0
+        };
+        slots.set(element, slot);
+        const obs = ensureObserver();
+        if (obs !== null) obs.observe(element);
+    }
+    slot.refCount++;
+
+    let disposed = false;
+    function dispose() {
+        if (disposed) return;
+        disposed = true;
+        slot.refCount--;
+        if (slot.refCount === 0) {
+            if (observerInstance !== null) observerInstance.unobserve(element);
+            slots.delete(element);
+            // Symmetric with Intersection's empty-bucket tear-down: when no
+            // slots remain, disconnect and null the singleton. Next call to
+            // observeResize cheaply rebuilds it. Cost is one allocation on
+            // the first observe after a fully-idle period; gain is no
+            // long-lived observer holding references on otherwise-empty
+            // pages (single-page-app navigation that mounts and unmounts
+            // popovers benefits).
+            if (slots.size === 0 && observerInstance !== null) {
+                observerInstance.disconnect();
+                observerInstance = null;
+            }
+        }
+    }
+
+    const width = box === 'border' ? slot.borderWidth : slot.contentWidth;
+    const height = box === 'border' ? slot.borderHeight : slot.contentHeight;
+
+    return attachFinalizer(
+        { width: width, height: height, dispose: dispose },
+        // Inner cleanup for the orphan path. Closes over `dispose` (which
+        // closes over slot/element/observerInstance/slots) -- but NOT over
+        // the handle, so the FinalizationRegistry can do its job.
+        dispose
+    );
+}
+
+/**
+ * Test-isolation utility. Tears down all observations and the singleton
+ * observer. Outstanding handles' dispose calls become safe no-ops.
+ *
+ * @internal
+ */
+export function _resetResize() {
+    if (observerInstance !== null) {
+        observerInstance.disconnect();
+        observerInstance = null;
+    }
+    slots.clear();
+}
+
+/**
+ * Diagnostic: number of distinct elements currently under observation.
+ *
+ * @returns {number}
+ */
+export function _resizeSlotCount() {
+    return slots.size;
+}

package/src/Visibility.js

@@ -0,0 +1,40 @@
+/**
+ * @zakkster/lite-observe -- Page Visibility bridge.
+ *
+ * A single module-level signal: `documentVisible`. True iff the document is
+ * currently visible (`document.visibilityState === 'visible'`). Lazily
+ * attaches the `visibilitychange` listener on the 0->1 observer transition
+ * and detaches on 1->0.
+ *
+ * Importing this module does not attach a listener; only reading the signal
+ * inside an effect/computed (or subscribing to it) does.
+ */
+
+import { signal, observeObservers } from '@zakkster/lite-signal';
+
+function readState() {
+    if (typeof document === 'undefined') return true;
+    return document.visibilityState === 'visible';
+}
+
+export const documentVisible = signal(readState());
+
+const onChange = function () { documentVisible.set(readState()); };
+
+if (typeof document !== 'undefined') {
+    observeObservers(documentVisible, {
+        onConnect: function () {
+            // Re-seed in case visibility changed while detached.
+            documentVisible.set(readState());
+            document.addEventListener('visibilitychange', onChange);
+        },
+        onDisconnect: function () {
+            document.removeEventListener('visibilitychange', onChange);
+        }
+    });
+}
+
+/** @internal */
+export function _forceVisibilitySync() {
+    documentVisible.set(readState());
+}

package/src/_finalize.js

@@ -0,0 +1,111 @@
+/**
+ * @zakkster/lite-observe -- shared orphan-handle finalizer.
+ *
+ * The observer modules (Resize, Intersection, Mutation) return handles with
+ * a `dispose()` method. Consumers are expected to call dispose when they're
+ * done. If they don't, the underlying browser observer keeps its target
+ * alive via spec-defined internal references (HashSet<Ref<Node>> in WebKit,
+ * HeapVector<Member<Node>> in Chromium) -- a leak.
+ *
+ * FinalizationRegistry is the canonical safety net: when the consumer drops
+ * the handle (their last reference to it), the runtime eventually GCs the
+ * handle and fires our cleanup callback, which disconnects the browser
+ * observer.
+ *
+ * Caveats acknowledged:
+ *   1. Finalization is non-deterministic. The runtime may run the cleanup
+ *      "eventually" -- on the next GC cycle, or never if the program exits
+ *      first. Explicit dispose remains the primary path; this is a safety
+ *      net for the forgot-to-dispose case.
+ *   2. The held value (second arg to register) must not reference the
+ *      handle. We pass the bare inner-cleanup closure, which captures only
+ *      slot / element / Map references -- never the handle itself.
+ *   3. Calling explicit dispose unregisters the finalizer so it doesn't
+ *      double-fire. The wrapper that does this DOES capture the handle
+ *      (via `registry.unregister(handle)`), but it's set as a property of
+ *      the handle, so the self-reference is collected with the handle.
+ *
+ * Single registry shared across the three modules so finalisation pressure
+ * is concentrated -- the runtime processes one queue, not three.
+ */
+
+const registry = typeof FinalizationRegistry !== 'undefined'
+    ? new FinalizationRegistry(function (cleanup) {
+        // Swallow errors. A failing finalizer must not poison the queue
+        // for other pending finalizations.
+        try { cleanup(); } catch (_e) { /* intentional */ }
+    })
+    : null;
+
+/**
+ * Register a handle for FinalizationRegistry-backed orphan cleanup.
+ *
+ * Used internally by `observeResize`, `observeIntersection`, and
+ * `observeMutation` so dropped handles trigger disconnect via GC.
+ * Public surface so downstream consumers can build their own observer-
+ * shaped primitives (a `ScrollObserver` over `addEventListener('scroll',
+ * ...)`, a `PointerCaptureObserver`, an `AbortSignal`-driven listener,
+ * etc.) with the same orphan safety.
+ *
+ * Contract for `innerCleanup`:
+ *   - MUST NOT reference `handle` (closure capture would keep the
+ *     handle alive and the finalizer would never fire).
+ *   - MUST be idempotent (an explicit dispose may have already run,
+ *     so internal state should guard against double-teardown).
+ *   - Errors thrown are swallowed by the registry so the finalizer
+ *     queue continues to drain for other pending finalisations.
+ *
+ * Note on timing: FinalizationRegistry is non-deterministic. The
+ * runtime decides when to process its queue. Explicit `dispose()` is
+ * still the primary path when you have a lifecycle hook; this is the
+ * safety net for the forgot-to-dispose case.
+ *
+ * Example -- building a ScrollObserver primitive:
+ *
+ *     function observeScroll(target) {
+ *         const positionSig = signal({ x: 0, y: 0 });
+ *         let disposed = false;
+ *         function onScroll() {
+ *             positionSig.set({ x: target.scrollLeft, y: target.scrollTop });
+ *         }
+ *         target.addEventListener('scroll', onScroll);
+ *         function cleanup() {
+ *             if (disposed) return;
+ *             disposed = true;
+ *             target.removeEventListener('scroll', onScroll);
+ *         }
+ *         return attachFinalizer(
+ *             { position: positionSig, dispose: cleanup },
+ *             cleanup
+ *         );
+ *     }
+ *
+ * @param {object} handle        Handle returned to the consumer; must
+ *                               have a `.dispose` method to wrap.
+ * @param {() => void} innerCleanup  Bare cleanup; MUST NOT reference
+ *                                   `handle`.
+ * @returns {object} The same `handle`, with `dispose` rewrapped to
+ *                   unregister the finalizer before running cleanup.
+ */
+export function attachFinalizer(handle, innerCleanup) {
+    if (registry === null) return handle;
+    registry.register(handle, innerCleanup, handle);
+    const originalDispose = handle.dispose;
+    handle.dispose = function () {
+        registry.unregister(handle);
+        originalDispose();
+    };
+    return handle;
+}
+
+/**
+ * Test hook. The shared FinalizationRegistry has no size; tests cannot
+ * directly observe pending finalisations. The runtime's `--expose-gc` flag
+ * plus a few synchronous gc() calls followed by a microtask flush is the
+ * portable way to encourage processing.
+ *
+ * @internal
+ */
+export function _hasFinalizationRegistry() {
+    return registry !== null;
+}