@zakkster/lite-observe 1.0.0

package/index.d.ts

@@ -0,0 +1,219 @@
+/**
+ * @zakkster/lite-observe -- type declarations.
+ *
+ * Zero-GC reactive bridge for the DOM observer APIs.
+ */
+
+import type { Signal } from '@zakkster/lite-signal';
+
+// --- Resize ------------------------------------------------------------------
+
+/** Handle returned by {@link observeResize}. */
+export interface ResizeHandle {
+    /** Width in CSS pixels. Content-box by default; border-box when the
+     *  handle was created with `{ box: 'border' }`. Zero until the first
+     *  ResizeObserver callback fires after layout. */
+    readonly width: Signal<number>;
+    /** Height in CSS pixels. Content-box by default; border-box when the
+     *  handle was created with `{ box: 'border' }`. Zero until the first
+     *  ResizeObserver callback fires after layout. */
+    readonly height: Signal<number>;
+    /** Drop this consumer's reference. Idempotent. When the last handle for
+     *  an element is disposed, the element is unobserved. */
+    dispose(): void;
+}
+
+/** Options for {@link observeResize}. */
+export interface ResizeOptions {
+    /** Which box dimensions to surface on `width` / `height`.
+     *  - `'content'` (default): mirrors `entry.contentRect`. Excludes
+     *    padding and border, matching the historical default.
+     *  - `'border'`: mirrors `entry.borderBoxSize`. Includes padding
+     *    and border, matching `getBoundingClientRect()`. On legacy
+     *    browsers without `borderBoxSize` we fall back to contentRect
+     *    until the runtime catches up. */
+    box?: 'content' | 'border';
+}
+
+/**
+ * Observe an element's size as fine-grained signals. N consumers of the same
+ * element share one underlying observation; the element is unobserved when
+ * the last handle is disposed.
+ *
+ * @param element Element to observe.
+ * @param options Optional. `box` selects content-box (default) or border-box
+ *   dimensions for the `width` / `height` signals.
+ */
+export function observeResize(element: Element, options?: ResizeOptions): ResizeHandle;
+
+// --- Intersection ------------------------------------------------------------
+
+/** Handle returned by {@link observeIntersection}. */
+export interface IntersectionHandle {
+    /** True iff the element currently intersects the root by at least the
+     *  configured threshold. False until the first callback fires. */
+    readonly isIntersecting: Signal<boolean>;
+    /** Raw `IntersectionObserverEntry.intersectionRatio` -- 0..1. */
+    readonly ratio: Signal<number>;
+    /** Idempotent dispose. */
+    dispose(): void;
+}
+
+/**
+ * Observe an element's intersection with a root (default: viewport).
+ * Equivalent options (same root identity, same rootMargin string, same
+ * threshold) share one underlying observer.
+ *
+ * @param element Element to observe.
+ * @param options Standard `IntersectionObserverInit`. Optional.
+ */
+export function observeIntersection(
+    element: Element,
+    options?: IntersectionObserverInit
+): IntersectionHandle;
+
+// --- Mutation ----------------------------------------------------------------
+
+/** Handle returned by {@link observeMutation}. */
+export interface MutationHandle {
+    /** Monotonic counter; increments by 1 each time a batch of mutation
+     *  records is delivered. Mutations are events, not state -- consumers
+     *  react to this counter changing. */
+    readonly tick: Signal<number>;
+    /** Returns the latest delivered batch of records without tracking. Empty
+     *  array before the first batch. The returned array is the
+     *  browser-allocated MutationRecord[]; do not retain across batches. */
+    peekRecords(): ReadonlyArray<MutationRecord>;
+    /** Idempotent dispose. */
+    dispose(): void;
+}
+
+/**
+ * Observe DOM mutations on `element`. Consumers asking for the same element
+ * with the same options share one underlying observer; differing options
+ * spawn distinct observers (the option set is part of an observer's
+ * identity in the spec).
+ *
+ * @param element Node to observe (Element or document).
+ * @param options Standard `MutationObserverInit`. Required.
+ */
+export function observeMutation(
+    element: Node,
+    options: MutationObserverInit
+): MutationHandle;
+
+/** Handle returned by {@link observeMutationSelector}. */
+export interface MutationSelectorHandle {
+    /** Elements matching the selector that were added in the most recent
+     *  batch. The frozen empty array is returned (with stable identity)
+     *  when a batch contains no matching adds. */
+    readonly added: Signal<readonly Element[]>;
+    /** Elements matching the selector that were removed in the most recent
+     *  batch. Same allocation behaviour as `added`. */
+    readonly removed: Signal<readonly Element[]>;
+    /** Monotonic batch counter mirroring the underlying `observeMutation`
+     *  handle's tick. */
+    readonly tick: Signal<number>;
+    /** Pass-through to the underlying handle. */
+    peekRecords(): readonly MutationRecord[];
+    /** Tears down the underlying observer + the internal filtering effect. */
+    dispose(): void;
+}
+
+/**
+ * Observe mutations under `root`, surfacing only matching elements.
+ *
+ * When `options.subtree` is true, also walks descendants of added /
+ * removed subtrees with `querySelectorAll(selector)` -- catches the case
+ * where a matching element arrives as a deep descendant of an added
+ * container rather than as its own addedNodes entry.
+ *
+ * Allocation: `added` / `removed` arrays are allocated fresh per batch
+ * with at least one matching mutation, so consumers may retain references
+ * safely. Batches with zero matches return the same frozen empty array
+ * (no allocation).
+ *
+ * @param root      The mutation root.
+ * @param selector  A CSS selector string. `element.matches(selector)` must
+ *                  be available on the host runtime.
+ * @param options   Forwarded to MutationObserver. Defaults to
+ *                  `{ childList: true, subtree: true }`.
+ */
+export function observeMutationSelector(
+    root: Element,
+    selector: string,
+    options?: MutationObserverInit
+): MutationSelectorHandle;
+
+// --- Media -------------------------------------------------------------------
+
+/**
+ * Boolean signal that reflects whether `query` currently matches. The same
+ * query string returns the same signal across calls. The underlying
+ * `change` listener is attached lazily on first read and detached when no
+ * consumer is reading; an imported-but-unread query costs only its signal
+ * node and one Map entry.
+ *
+ * @param query A media-query string, e.g. `(min-width: 768px)`.
+ */
+export function observeMedia(query: string): Signal<boolean>;
+
+// --- Visibility --------------------------------------------------------------
+
+/**
+ * Page-visibility signal. True iff `document.visibilityState === 'visible'`.
+ * The `visibilitychange` listener is attached lazily on first read and
+ * detached when no consumer is reading.
+ */
+export const documentVisible: Signal<boolean>;
+
+// --- Internal / test isolation ----------------------------------------------
+
+/** @internal Reset all resize observation state. Outstanding handles' dispose
+ *  calls become no-ops. */
+export function _resetResize(): void;
+/** @internal */
+export function _resizeSlotCount(): number;
+
+/** @internal */
+export function _resetIntersection(): void;
+/** @internal */
+export function _intersectionBucketCount(): number;
+
+/** @internal */
+export function _resetMutation(): void;
+/** @internal */
+export function _mutationObserverCount(): number;
+
+/** @internal */
+export function _resetMedia(): void;
+/** @internal */
+export function _mediaCacheSize(): number;
+
+/** @internal */
+export function _forceVisibilitySync(): void;
+
+// --- Orphan-cleanup safety net ----------------------------------------------
+
+/**
+ * Register a consumer handle for FinalizationRegistry-backed orphan cleanup.
+ * When the consumer drops the handle without calling its `dispose()`, the
+ * runtime eventually GCs the handle and `innerCleanup` runs as a safety net.
+ *
+ * Public so downstream code can build observer-shaped primitives with the
+ * same orphan safety the built-in observers have. See JSDoc in source for
+ * the contract: `innerCleanup` must not capture `handle`, must be
+ * idempotent, may throw safely.
+ *
+ * Timing is non-deterministic; explicit dispose is still the primary path
+ * when a lifecycle hook is available.
+ */
+export function attachFinalizer<T extends { dispose: () => void }>(
+    handle: T,
+    innerCleanup: () => void
+): T;
+
+/** Returns true on runtimes with FinalizationRegistry support (all evergreen
+ *  browsers + Node 14+). Returns false on environments without it; in that
+ *  case `attachFinalizer` becomes a no-op pass-through. */
+export function _hasFinalizationRegistry(): boolean;

package/index.js

@@ -0,0 +1,25 @@
+/**
+ * @zakkster/lite-observe
+ *
+ * Zero-GC reactive bridge for the DOM observer APIs.
+ *
+ * ResizeObserver, IntersectionObserver, MutationObserver, matchMedia, and
+ * Page Visibility, each surfaced as fine-grained lite-signal signals. A
+ * shared internal registry means N components observing the same element
+ * (or matching the same media query) share one underlying observer.
+ */
+
+export { observeResize } from './src/Resize.js';
+export { observeIntersection } from './src/Intersection.js';
+export { observeMutation } from './src/Mutation.js';
+export { observeMutationSelector } from './src/MutationSelector.js';
+export { observeMedia } from './src/Media.js';
+export { documentVisible } from './src/Visibility.js';
+
+// Test-isolation utilities. Not part of the stable public surface.
+export { _resetResize, _resizeSlotCount } from './src/Resize.js';
+export { _resetIntersection, _intersectionBucketCount } from './src/Intersection.js';
+export { _resetMutation, _mutationObserverCount } from './src/Mutation.js';
+export { _resetMedia, _mediaCacheSize } from './src/Media.js';
+export { _forceVisibilitySync } from './src/Visibility.js';
+export { _hasFinalizationRegistry, attachFinalizer } from './src/_finalize.js';

package/llms.txt

@@ -0,0 +1,86 @@
+# @zakkster/lite-observe
+
+Zero-GC reactive bridge for the DOM observer APIs. ResizeObserver,
+IntersectionObserver, MutationObserver, matchMedia, and Page Visibility
+collapsed to fine-grained lite-signal signals with a shared internal
+registry: N consumers of the same element share one underlying observer.
+
+## Exports
+
+- `observeResize(el, options?)` -> `{ width: Signal<number>, height: Signal<number>, dispose }`
+  Singleton ResizeObserver, refcounted per element. Width and height are
+  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.
+
+- `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).
+
+- `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).
+
+- `observeMutationSelector(root, selector, options?)` -> `{ added: Signal<Element[]>, removed: Signal<Element[]>, tick: Signal<number>, peekRecords(), dispose }`
+  Selector-filtered wrapper over observeMutation. Surfaces matching elements
+  added/removed per batch. With `subtree: true` (the default option set is
+  `{ childList: true, subtree: true }`), walks descendants of added/removed
+  subtrees via querySelectorAll so deep matches arriving inside an added
+  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.
+
+- `observeMedia(query)` -> `Signal<boolean>`
+  One signal per query string, cached. Listener attached lazily via
+  lite-signal observeObservers; detached when no consumer is reading.
+
+- `documentVisible: Signal<boolean>`
+  Module-level. True iff document.visibilityState === 'visible'.
+  Lazy listener.
+
+## Orphan-safety utility (public)
+
+- `attachFinalizer(handle, innerCleanup)` -> `handle`
+  Registers `handle` with a shared FinalizationRegistry so dropping it
+  without calling dispose() triggers `innerCleanup` on a later GC pass.
+  `innerCleanup` MUST NOT capture `handle` (would pin it and the finalizer
+  would never fire) and MUST be idempotent. Rewraps `handle.dispose` to
+  unregister before running, preventing double-fire. Exported so downstream
+  code can build observer-shaped primitives (scroll, pointer-capture, etc.)
+  with the same orphan safety the built-ins have.
+- `_hasFinalizationRegistry()` -> boolean. False on runtimes without
+  FinalizationRegistry; there `attachFinalizer` is a no-op pass-through.
+
+## Internal / test-only
+
+- `_resetResize`, `_resizeSlotCount`
+- `_resetIntersection`, `_intersectionBucketCount`
+- `_resetMutation`, `_mutationObserverCount`
+- `_resetMedia`, `_mediaCacheSize`
+- `_forceVisibilitySync`
+
+## Design
+
+- Fine-grained signals, not one rect-shaped object. Consumers tracking
+  one field do not wake on others.
+- Tick + peek for mutations, not a records-shaped signal. Mutation records
+  are transient; a records signal would force allocations or break
+  identity semantics.
+- Lazy listeners on the media + visibility paths via observeObservers
+  0->1 / 1->0 transitions. Idle signals cost only their node.
+- Indexed for-loops in callbacks, no iterator allocation. Closures
+  pre-allocated at registration, not per callback. Library-side allocations
+  occur only at registration time.
+- Orphan-handle cleanup via shared FinalizationRegistry. Handles from
+  observeResize / observeIntersection / observeMutation are registered;
+  dropping the handle without dispose() triggers cleanup on the next GC
+  pass. Explicit dispose unregisters first to avoid double-fire. Non-
+  deterministic in timing; explicit dispose is still preferred when you
+  have a lifecycle hook.
+- SSR safe via typeof guards. Importing never throws under Node.
+
+## Peer dependency
+
+@zakkster/lite-signal ^1.2.2

package/package.json

@@ -0,0 +1,71 @@
+{
+    "name": "@zakkster/lite-observe",
+    "version": "1.0.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",
+    "sideEffects": false,
+    "main": "index.js",
+    "module": "index.js",
+    "types": "./index.d.ts",
+    "exports": {
+        ".": {
+            "node": "./index.js",
+            "import": "./index.js",
+            "types": "./index.d.ts",
+            "default": "./index.js"
+        }
+    },
+    "files": [
+        "src/",
+        "index.js",
+        "index.d.ts",
+        "README.md",
+        "llms.txt",
+        "LICENSE.txt",
+        "CHANGELOG.md"
+    ],
+    "scripts": {
+        "test": "node --test test/*.test.js",
+        "test:gc": "node --expose-gc --test test/*.test.js",
+        "test:browser": "node test/browser/serve.js",
+        "demo": "node test/browser/serve.js 8767 demo/index.html",
+        "bench": "node --expose-gc bench/lite-observe.bench.js",
+        "verify": "npm test && npm run bench"
+    },
+    "keywords": [
+        "resize-observer",
+        "intersection-observer",
+        "mutation-observer",
+        "match-media",
+        "page-visibility",
+        "reactive",
+        "signals",
+        "lite-signal",
+        "fine-grained",
+        "zero-gc",
+        "zero-dependency",
+        "shared-observer",
+        "tiny",
+        "esm"
+    ],
+    "peerDependencies": {
+        "@zakkster/lite-signal": "^1.2.2"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "license": "MIT",
+    "homepage": "https://github.com/PeshoVurtoleta/lite-observe#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/PeshoVurtoleta/lite-observe.git"
+    },
+    "bugs": {
+        "url": "https://github.com/PeshoVurtoleta/lite-observe/issues",
+        "email": "shinikchiev@yahoo.com"
+    },
+    "engines": {
+        "node": ">=18"
+    }
+}

package/src/Intersection.js

@@ -0,0 +1,169 @@
+/**
+ * @zakkster/lite-observe -- IntersectionObserver bridge.
+ *
+ * IntersectionObserver instances are NOT interchangeable: the (root,
+ * rootMargin, threshold) tuple is part of the observer's identity, and an
+ * `observe(el)` call inherits whatever configuration the observer was built
+ * with. Two consumers asking for the same element with different thresholds
+ * must each get their own underlying observer.
+ *
+ * Sharing model: a Map keyed by a stringified options tuple holds one
+ * observer plus a per-element slot map. Within a tuple, N consumers of the
+ * same element share one slot; the element is unobserved when the last slot
+ * consumer disposes, and the observer is destroyed when its slot map empties.
+ *
+ * Per-slot signals: `isIntersecting` (boolean) and `ratio` (number, the raw
+ * IntersectionObserverEntry.intersectionRatio). Consumers tracking only
+ * visibility do not wake on ratio changes when the boolean is unchanged.
+ */
+
+import { signal } from '@zakkster/lite-signal';
+import { attachFinalizer } from './_finalize.js';
+
+/**
+ * Build a deterministic key for an IntersectionObserver options object.
+ * The same key must match across equivalent options to enable sharing.
+ *
+ * @param {IntersectionObserverInit | undefined} options
+ * @returns {string}
+ */
+function optionsKey(options) {
+    if (options === undefined) return '||0';
+    const root = options.root;
+    // Root identity is by reference; we cannot serialise an Element. Use a
+    // WeakMap-backed counter to assign each distinct root a stable id.
+    const rootId = root == null ? '' : rootIdFor(root);
+    const margin = options.rootMargin == null ? '' : options.rootMargin;
+    const threshold = options.threshold;
+    let thrKey;
+    if (threshold === undefined) thrKey = '0';
+    else if (typeof threshold === 'number') thrKey = String(threshold);
+    else {
+        // Array: stable order, no allocation beyond the join.
+        thrKey = threshold.join(',');
+    }
+    return rootId + '|' + margin + '|' + thrKey;
+}
+
+const rootIds = new WeakMap();
+let nextRootId = 1;
+function rootIdFor(root) {
+    let id = rootIds.get(root);
+    if (id === undefined) {
+        id = nextRootId++;
+        rootIds.set(root, id);
+    }
+    return 'r' + id;
+}
+
+// optionsKey -> { observer, slots: Map<Element, slot>, options }
+const observersByKey = new Map();
+
+/**
+ * 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
+ */
+function dispatchIntersection(entries, bucket) {
+    const map = bucket.slots;
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const slot = map.get(entry.target);
+        if (slot === undefined) continue;
+        slot.isIntersecting.set(entry.isIntersecting);
+        slot.ratio.set(entry.intersectionRatio);
+    }
+}
+
+function ensureBucket(options) {
+    const key = optionsKey(options);
+    let bucket = observersByKey.get(key);
+    if (bucket !== undefined) return bucket;
+    if (typeof IntersectionObserver === 'undefined') {
+        // SSR / unsupported: install a sentinel bucket with a null observer.
+        // Slots are still created so consumer code reads sane defaults.
+        bucket = { observer: null, slots: new Map(), key };
+        observersByKey.set(key, bucket);
+        return bucket;
+    }
+    bucket = { observer: null, slots: new Map(), key };
+    bucket.observer = new IntersectionObserver(
+        function (entries) { dispatchIntersection(entries, bucket); },
+        options
+    );
+    observersByKey.set(key, bucket);
+    return bucket;
+}
+
+/**
+ * @typedef {object} IntersectionHandle
+ * @property {import('@zakkster/lite-signal').Signal<boolean>} isIntersecting
+ * @property {import('@zakkster/lite-signal').Signal<number>} ratio
+ * @property {() => void} dispose
+ */
+
+/**
+ * Observe an element's intersection with a root (default: viewport) as
+ * fine-grained signals.
+ *
+ * The first emission arrives asynchronously after the next layout. Until then
+ * `isIntersecting` is false and `ratio` is zero. Equivalent options
+ * (same root, same rootMargin, same threshold) share one underlying observer.
+ *
+ * @param {Element} element
+ * @param {IntersectionObserverInit} [options]
+ * @returns {IntersectionHandle}
+ */
+export function observeIntersection(element, options) {
+    const bucket = ensureBucket(options);
+    let slot = bucket.slots.get(element);
+    if (slot === undefined) {
+        slot = {
+            isIntersecting: signal(false),
+            ratio: signal(0),
+            refCount: 0
+        };
+        bucket.slots.set(element, slot);
+        if (bucket.observer !== null) bucket.observer.observe(element);
+    }
+    slot.refCount++;
+
+    let disposed = false;
+    function dispose() {
+        if (disposed) return;
+        disposed = true;
+        slot.refCount--;
+        if (slot.refCount === 0) {
+            if (bucket.observer !== null) bucket.observer.unobserve(element);
+            bucket.slots.delete(element);
+            if (bucket.slots.size === 0) {
+                if (bucket.observer !== null) bucket.observer.disconnect();
+                observersByKey.delete(bucket.key);
+            }
+        }
+    }
+
+    return attachFinalizer(
+        {
+            isIntersecting: slot.isIntersecting,
+            ratio: slot.ratio,
+            dispose: dispose
+        },
+        dispose
+    );
+}
+
+/** @internal */
+export function _resetIntersection() {
+    for (const bucket of observersByKey.values()) {
+        if (bucket.observer !== null) bucket.observer.disconnect();
+    }
+    observersByKey.clear();
+}
+
+/** @internal */
+export function _intersectionBucketCount() {
+    return observersByKey.size;
+}

package/src/Media.js

@@ -0,0 +1,95 @@
+/**
+ * @zakkster/lite-observe -- matchMedia bridge.
+ *
+ * A `MediaQueryList` is one DOM object per query string. We cache the
+ * corresponding signal so that N components asking for `(min-width: 768px)`
+ * all read from the same node, and only one `change` listener is attached
+ * to the underlying MediaQueryList.
+ *
+ * The listener is attached lazily on the first read of the signal (via
+ * lite-signal's `observeObservers` 0->1 transition) and removed on the 1->0
+ * transition. A query that is imported but never read costs nothing beyond
+ * the signal node and one Map entry.
+ */
+
+import { signal, observeObservers } from '@zakkster/lite-signal';
+
+const signalsByQuery = new Map();
+
+/**
+ * Get a boolean signal that reflects whether `query` currently matches.
+ * The same query string returns the same signal across calls.
+ *
+ * In SSR (no `matchMedia`), the signal exists and stays at its initial
+ * value (false).
+ *
+ * @param {string} query e.g. `(min-width: 768px)`, `(prefers-color-scheme: dark)`
+ * @returns {import('@zakkster/lite-signal').Signal<boolean>}
+ */
+export function observeMedia(query) {
+    let s = signalsByQuery.get(query);
+    if (s !== undefined) return s;
+
+    if (typeof matchMedia === 'undefined') {
+        s = signal(false);
+        signalsByQuery.set(query, s);
+        return s;
+    }
+
+    const mql = matchMedia(query);
+    s = signal(mql.matches);
+
+    // Lazy attach/detach. While no consumer is reading this signal we do
+    // not need a change listener; lite-signal's observer-lifecycle hook
+    // fires exactly on the 0<->1 transitions.
+    const onChange = function () { s.set(mql.matches); };
+
+    observeObservers(s, {
+        onConnect: function () {
+            // Re-seed: the MQL may have changed value between detach and
+            // re-attach. Cheaper than maintaining a permanent listener.
+            s.set(mql.matches);
+            if (typeof mql.addEventListener === 'function') {
+                mql.addEventListener('change', onChange);
+            } else if (typeof mql.addListener === 'function') {
+                // Safari < 14 legacy API.
+                mql.addListener(onChange);
+            }
+        },
+        onDisconnect: function () {
+            if (typeof mql.removeEventListener === 'function') {
+                mql.removeEventListener('change', onChange);
+            } else if (typeof mql.removeListener === 'function') {
+                mql.removeListener(onChange);
+            }
+            // Evict from the memo when no consumer is observing. Closure
+            // references (s, mql, onChange) survive in any consumer still
+            // holding the signal -- if they re-subscribe, observeObservers
+            // re-fires onConnect and re-attaches the listener, so the held
+            // reference continues to work correctly. New callers asking
+            // for the same query after eviction get a fresh signal+mql;
+            // wasteful in that transient (two MQL instances for one query),
+            // but correct, and the waste collapses when the held reference
+            // is released.
+            //
+            // This bounds the memo size to "queries currently being
+            // observed" rather than "queries ever requested", which closes
+            // the unbounded-cache leak for consumers generating dynamic
+            // query strings.
+            signalsByQuery.delete(query);
+        }
+    });
+
+    signalsByQuery.set(query, s);
+    return s;
+}
+
+/** @internal */
+export function _resetMedia() {
+    signalsByQuery.clear();
+}
+
+/** @internal */
+export function _mediaCacheSize() {
+    return signalsByQuery.size;
+}