@zakkster/lite-observe 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,312 @@
+# Changelog
+
+## 1.0.0 -- Production cut
+
+The 0.2.x line proved out FinalizationRegistry-based orphan cleanup; the
+0.3.x demo work proved out the library against real consumer patterns;
+0.5.x-0.7.x added the cross-cutting features that lite-headless needs;
+0.9.x consolidated documentation and conventions. This release declares
+the public surface stable.
+
+- **Pre-publish correctness pass (blocking fixes).**
+  - **Runtime imports in `test/*.test.js`, `bench/lite-observe.bench.js`,
+    and `demo/demo.js` corrected from `../index.d.ts` to `../index.js`.**
+    The declaration file has no runtime exports; under Node >= 22.18
+    (type-stripping on by default) it threw `ERR_INVALID_TYPESCRIPT_SYNTAX`,
+    so the entire `node:test` suite, the bench gate, and the in-browser
+    demo could not load. `test/browser/smoke.html` was already correct.
+    (Shipped `index.js` / `src/*` were never affected; tests/bench/demo
+    are dev-only and not in published `files`.)
+  - **`publishConfig.access: public` added** so the scoped package
+    actually publishes public.
+- **Documentation completeness.** `observeMutationSelector` and the
+  `observeResize` `box` option were shipped and tested but missing from
+  the README API reference and `llms.txt`; both now documented. Added an
+  Architecture (Mermaid) diagram and a Benchmarks section with the
+  measured gate numbers, matching the lite-signal README blueprint.
+  `index.d.ts` JSDoc for `observeResize` was attached to the wrong symbol
+  (`ResizeOptions` instead of the function); corrected. `llms.txt` peer
+  range aligned to `^1.2.2`.
+- **Test coverage added.** SSR / no-DOM-global suite (the documented
+  "SSR-safe" contract, previously untested), the legacy `matchMedia`
+  `addListener`/`removeListener` branch, the removed-subtree selector
+  walk, and `_forceVisibilitySync`. Suite: 59 passing + 6 gc-gated
+  (65 under `npm run test:gc`), bench gate green (0 scavenges, 0 B/call).
+- **Stable public surface.** `observeResize`, `observeIntersection`,
+  `observeMutation`, `observeMutationSelector`, `observeMedia`,
+  `documentVisible`, `attachFinalizer`. Signatures and return shapes
+  are frozen for the 1.x line. The leading-underscore diagnostics
+  (`_resetResize`, `_resizeSlotCount`, etc.) remain unstable by name
+  and are not part of the semver guarantee.
+- **`_hasFinalizationRegistry` diagnostic exported** for test
+  introspection -- consumers writing wrapping libraries can check
+  whether orphan cleanup will be effective on the host runtime.
+- **README "Edge cases & guarantees" rewritten** against the v1.0
+  behaviour. The v0.2-placeholder paragraph that hedged on
+  FinalizationRegistry has been replaced with the actual contract:
+  double-fire safety, non-deterministic timing, what the registry
+  catches and what it doesn't.
+- **`llms.txt` regenerated** with the orphan-cleanup design note so
+  downstream LLM-assisted consumers have the contract in context.
+
+## 0.9.3 -- Demo scene for `observeMutationSelector`
+
+- Sixth scene added to the bundled demo: "Selector Filter". A
+  subtree with mixed children (matching options, non-matching headers,
+  nested wrappers with deep matches) demonstrates the selector filter
+  surfacing only the relevant elements via the `added` / `removed`
+  signals. Buttons drive each mutation kind individually so the
+  selector-vs-record-walk distinction is observable.
+- Cumulative match counters in the corner overlays make the matching/
+  non-matching split obvious during a mutation storm.
+
+## 0.9.2 -- Demo dogfooding audit
+
+- Every per-frame UI write in the demo audited against the
+  "persistent-DOM-node mutation" pattern from the lite-floating README.
+  Every `textContent = X` in a hot path replaced with `textNode.data = X`
+  on a node hoisted at scene setup; every dynamic stream (records,
+  visibility timeline, media tiles) backed by a pre-allocated DOM pool
+  whose children are mutated rather than recreated.
+- Confirmed: the demo allocates zero DOM nodes after mount on the
+  steady-state interaction paths. The browser-allocated `MutationRecord`
+  arrays and `getBoundingClientRect` results are the only unavoidable
+  allocations on the boundary.
+
+## 0.9.1 -- Demo conventions pass
+
+- `oklch()` palette applied across the demo with hex fallback via the
+  redeclare pattern (`:root { --green: #5fe39f; } @supports (color:
+  oklch(0 0 0)) { :root { --green: oklch(82.5% 0.152 157.9); } }`).
+  Each oklch value converted from the canonical hex via the precise
+  sRGB -> linear -> OKLab -> oklch path, not eyeballed.
+- All `:hover` rules collected into a single `@media (hover: hover)`
+  block at the bottom of the stylesheet so touch devices that stick
+  hover after a tap skip the block entirely.
+- `100dvh` on the app root so mobile browser chrome doesn't clip the
+  bottom panel row.
+- `:not([aria-current="true"]):hover` on the tab nav so the hover
+  preview doesn't fight the selected-state styling.
+- ASCII sweep across the full package -- no U+00B7 separators or em-dashes or arrow glyphs slipped into source per project convention.
+
+## 0.9.0 -- Interactive demo, first cut
+
+- Five-scene interactive demo (`demo/index.html`) covering each
+  observer kind: Resize Atlas, Intersection Scanner, Mutation Stream,
+  Media Probe, Visibility Pulse. Full-viewport tabbed layout matching
+  the `@zakkster/lite-floating` demo's oscilloscope visual identity.
+- Resize scene: drag-to-resize via custom pointer handle plus
+  programmatic sliders. Width and height signals stream into corner
+  overlays and panel tiles independently (proves the Object.is gating
+  on each signal).
+- Intersection scene: scrollable area with a target between fillers,
+  threshold every 5% so `ratio` drifts smoothly through transitions.
+- Mutation scene: subtree list with five mutation buttons (single
+  add / remove / toggle / batch-five / clear) and a rolling records
+  stream showing the last six batches with type breakdown.
+- Media scene: ten probe queries (color-scheme, hover, pointer,
+  prefers-reduced-motion, breakpoints, orientation) shown as tiles
+  with active highlight.
+- Visibility scene: pulsing glyph, 32-bar timeline, transition log,
+  hidden-duration accumulator.
+- `npm run demo` script added. Serves at port 8767 to avoid colliding
+  with `npm run test:browser`.
+
+## 0.7.0 -- Public `attachFinalizer`
+
+- The internal orphan-cleanup helper promoted to a public export.
+  Downstream consumers building their own observation primitives (a
+  `ScrollObserver` over `addEventListener('scroll')`, a
+  `PointerCaptureObserver`, an `AbortSignal`-driven listener wrapper)
+  can now use the same FinalizationRegistry safety net the built-in
+  observers have.
+- JSDoc rewritten for public consumption with a worked example
+  building a `ScrollObserver` primitive end-to-end. Contract spelled
+  out: inner cleanup must not capture the handle, must be idempotent,
+  errors are swallowed by the registry.
+- TypeScript declarations updated; the public signature is generic
+  over the handle type, preserving the consumer's handle shape through
+  the registration call.
+
+## 0.6.0 -- Border-box dimensions for `observeResize`
+
+- New `options.box` parameter on `observeResize`: `'content'` (default,
+  matches existing behaviour) or `'border'` (surfaces `borderBoxSize`
+  including padding and border, matching `getBoundingClientRect()`).
+- Each slot now carries both content and border signal pairs. The
+  dispatch callback writes all four every fire; the Object.is gate
+  prevents wakeups for consumers reading only one pair. Mixed-box
+  consumers on the same element transparently share one observation:
+  a single ResizeObserver instance fires both pairs, each handle
+  surfaces the pair it asked for.
+- Legacy-browser fallback: if `entry.borderBoxSize` is absent (older
+  Safari before v15.4), the border signals mirror contentRect. The
+  affected consumer sees content dimensions until the runtime catches
+  up; never undefined, never zero, never wrong-shape.
+- Four new tests covering default-is-content, border surfaces
+  borderBoxSize, mixed-box single-observation, legacy fallback.
+
+## 0.5.0 -- `observeMutationSelector` helper
+
+- New helper module `src/MutationSelector.js` exporting
+  `observeMutationSelector(root, selector, options)`. Wraps the
+  existing `observeMutation` with library-side selector filtering.
+  Returns `{ added: Signal<Element[]>, removed: Signal<Element[]>,
+  tick, peekRecords, dispose }`.
+- When `options.subtree` is true (default), the inner walker uses
+  `querySelectorAll` against each added/removed top-level node to
+  catch matching descendants -- the case where a matching element
+  arrives as a deep descendant of an added container rather than as
+  its own `addedNodes` entry. This is the most common bug class in
+  hand-rolled selector filtering, and the helper makes it unmissable.
+- Allocation profile: fresh arrays per batch with matches; the frozen
+  empty array (stable identity) for batches with no matches. Consumer
+  ergonomics win out over strict zero-alloc here -- arrays the
+  consumer might retain for inspection must be theirs, not the
+  library's.
+- Ten tests covering: matching adds / removes / mixed; subtree-vs-flat
+  walk; top-level + nested in same batch; empty-batch identity reuse;
+  dispose semantics; tick mirroring; non-childList records ignored.
+
+## 0.4.0 -- Bench gate revalidated against FR-enabled dispatch
+
+- All four dispatch paths confirmed 0 B/call, 0 scavenges after the
+  FinalizationRegistry wiring landed.  Registration cost is paid once
+  at observe time, not per dispatched event; the hot paths are
+  untouched.
+- Bench thresholds documented in `bench/lite-observe.bench.js` to make
+  future regressions obvious.
+
+## 0.3.0 -- Finalization test suite
+
+- Nine new tests in `test/finalize.test.js` covering the orphan-cleanup
+  paths:
+  - Resize: orphan handle triggers cleanup via the registry; explicit
+    dispose still works after the `attachFinalizer` wrap; explicit
+    dispose then orphan-settle does not double-fire; refcount-shared
+    slot stays alive while one consumer holds its handle.
+  - Intersection: orphan cleanup, explicit dispose tears down.
+  - Mutation: orphan cleanup, explicit dispose disconnects, explicit
+    dispose plus orphan settle is safe.
+- All FR-requiring tests guard on `typeof gc === 'function'` so they
+  skip gracefully under `npm test` and run under `npm run test:gc`
+  (which adds `--expose-gc`).
+- Settle helper loops six `gc()` + `setImmediate` cycles to encourage
+  V8 to drain the finalisation queue. Documented as the knob to turn
+  if a heavily loaded CI flakes.
+
+## 0.2.1 -- Mutation finalizer wiring
+
+- `observeMutation` returns through `attachFinalizer` so orphaned
+  handles trigger `observer.disconnect()` via GC. The Mutation case is
+  the highest-value because the spec-mandated retention of observed
+  nodes is structural -- a forgotten dispose keeps DOM nodes alive
+  until process exit. The registry catches the common forgot-to-
+  dispose path.
+- Caveat documented in the source header: this doesn't defeat the
+  retention while the handle is held intentionally. The contract is
+  "drop the handle, eventually the observer disconnects" -- nothing
+  more, nothing less.
+
+## 0.2.0 -- FinalizationRegistry helper, Resize + Intersection wired
+
+- New module `src/_finalize.js` exporting `attachFinalizer(handle,
+  innerCleanup)`. Single shared `FinalizationRegistry` across modules so
+  the runtime processes one queue, not three.
+- The held value passed to the registry is the bare inner-cleanup
+  closure -- it captures slot / element / Map references but never the
+  handle itself. This is what makes finalisation possible; the
+  alternative (passing the handle's own `dispose`) would prevent the
+  handle from being collected.
+- `observeResize` and `observeIntersection` return through
+  `attachFinalizer`. Explicit `dispose()` unregisters first so a
+  subsequent finalisation does not double-fire.
+- Defensive: the inner cleanup is wrapped in `try / catch` in the
+  registry callback so one failing finalizer cannot poison the queue
+  for others pending.
+- Bench gate: unchanged. Registration is one-time at observe; the
+  dispatch hot path is identical to 0.1.x.
+
+## 0.1.2 -- Cache eviction + GC honesty
+
+- **Media cache eviction.** `observeMedia`'s memo `Map` now evicts entries
+  when the signal's last observer detaches, via the `observeObservers`
+  lifecycle already in place for lazy listener attachment. Cache size is
+  bounded to "queries currently being observed" rather than "queries ever
+  requested" -- the unbounded-growth hazard for dynamic query strings is
+  closed.
+  - Consumers holding a strong reference to the signal across an unobserved
+    period continue to work: re-subscribing fires `onConnect` and
+    re-attaches the listener through the same closure machinery.
+  - A new caller asking for an evicted query gets a fresh signal+MQL pair.
+    Brief duplicate work in that transient, never incorrect.
+  - Last turn's pushback against this change was wrong: I claimed it would
+    leave consumers with stale signals; tracing through the closure
+    lifecycle, it doesn't. Apologies for the misdirection.
+- **Mutation strong-ref leak removed.** The previous `liveElements`
+  `Set<Element>` defeated the `WeakMap` -- every observed element was
+  retained until manual cleanup. Replaced with a `Set<MutationObserver>`
+  that tracks the lightweight library objects.
+  - Caveat: this is a *code-quality* improvement, not a GC fix. The DOM
+    spec requires `MutationObserver` to retain references to its observed
+    nodes (WebKit's `HashSet<Ref<Node>>`, Chromium's
+    `HeapVector<Member<Node>>`), so the leak in the forgot-to-dispose case
+    persists -- just through spec-defined channels rather than our own
+    Set. Engines can optimise / finalize observer chains; they couldn't
+    optimise our Set.
+  - Diagnostic renamed: `_mutationLiveElementCount` -> `_mutationObserverCount`.
+    The old name implied an element count; what we track now is observers.
+- **README**: documents both the Media eviction behaviour (including the
+  hold-while-unobserved case) and the spec-defined MutationObserver target
+  retention as a known forgot-to-dispose hazard.
+- **Browser smoke suite added.** `npm run test:browser` spawns a zero-
+  dependency Node static server (`test/browser/serve.js`) that serves
+  the package root; opening `http://localhost:8765/test/browser/smoke.html`
+  in any browser runs the suite against real ResizeObserver,
+  IntersectionObserver, MutationObserver, matchMedia, and
+  document.visibilityState APIs. Results render in the page and are also
+  set on `window.__SMOKE_RESULTS__` for programmatic scraping by a future
+  Playwright/Puppeteer wrapper. Smoke files are dev-only (not in published
+  `files`).
+- **Zero-GC bench gate added.** `npm run bench` exercises all four
+  dispatch paths (resize, intersection, mutation, media-change) under
+  100k iterations across 5 runs, with `--expose-gc` and PerformanceObserver
+  scavenge counting. Current measurements on Node 22:
+  - `observeResize.dispatch (64 els)`:        ~13 us/call,  0 B/call,  0 scavenges
+  - `observeIntersection.dispatch (64 els)`:  ~16 us/call,  0 B/call,  0 scavenges
+  - `observeMutation.dispatch (3 records)`:     130 ns/call, 0 B/call,  0 scavenges
+  - `observeMedia.change (1 listener)`:         117 ns/call, 0 B/call,  0 scavenges
+
+  Gate is strict: a single scavenge or > 1 B/call in any run fails the
+  build. `npm run verify` runs tests then bench. Bench files are dev-only
+  (not in published `files`).
+
+## 0.1.1 -- Hardening patches
+
+- **Resize: symmetric singleton tear-down.** When the last refcount on the last
+  observed element hits zero, the singleton `ResizeObserver` is disconnected
+  and nulled. The next `observeResize()` call cheaply rebuilds it. Brings the
+  Resize subsystem in line with Intersection's empty-bucket tear-down; long-
+  lived pages that mount and unmount popovers no longer hold an observer
+  reference indefinitely while idle.
+- **README: ResizeObserver loop-limit warning.** Documented the failure mode
+  where a consumer effect on size signals synchronously writes layout-
+  affecting styles, with the standard mitigation (defer via `rafEffect` from
+  `@zakkster/lite-raf`, or use `transform`-only updates). The library cannot
+  enforce this from the inside; consumers writing custom RO-driven effects
+  are responsible.
+- **README: `observeMedia` cache-growth limitation.** Documented that
+  consumers generating dynamic query strings (`(min-width: ${width}px)` tied
+  to a continuously-changing width) will see the memo Map grow. The fix that
+  preserves API correctness needs `WeakRef` and is planned for v0.2.0; for
+  v0.1.x the recommendation is to avoid dynamic query strings.
+
+## 0.1.0 -- Initial release
+
+- `observeResize(el)` -> `{ width, height, dispose }`. Singleton `ResizeObserver`, refcounted per element.
+- `observeIntersection(el, options?)` -> `{ isIntersecting, ratio, dispose }`. Observers keyed by `(root, rootMargin, threshold)`; refcounted per element within an options bucket.
+- `observeMutation(el, options)` -> `{ tick, peekRecords, dispose }`. Monotonic counter signal plus peek-only record accessor. Observers keyed by `(element, optionsKey)`.
+- `observeMedia(query)` -> `Signal<boolean>`. One signal per query string, cached globally. Listener attached lazily via lite-signal `observeObservers`.
+- `documentVisible: Signal<boolean>`. Module-level page-visibility signal, lazy listener.
+- Test-isolation utilities (underscore-prefixed) for resetting each subsystem.
+- 28 tests passing under `node:test`. Zero runtime dependencies; peer-dep on `@zakkster/lite-signal` ^1.2.0.

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Shinikchiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,305 @@
+# @zakkster/lite-observe
+
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-observe.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-observe)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-observe?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-observe)
+[![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)
+![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)
+
+**The DOM observer APIs as fine-grained signals. N components observing the same element pay one observer cost.**
+
+`ResizeObserver`, `IntersectionObserver`, `MutationObserver`, `matchMedia`, and Page Visibility, each surfaced as a lite-signal signal (or a small handle of signals). A shared internal registry deduplicates the underlying observer per element (or per options key, or per query string) so a list of 200 reactive widgets observing the same scroll container costs one underlying `IntersectionObserver`, not 200.
+
+```js
+import { observeResize, observeIntersection, observeMedia, documentVisible } from '@zakkster/lite-observe';
+import { effect } from '@zakkster/lite-signal';
+
+const { width, height, dispose } = observeResize(panel);
+effect(() => render(width(), height()));      // wakes only when the panel resizes
+
+const isMobile = observeMedia('(max-width: 768px)');
+effect(() => layoutFor(isMobile()));          // wakes only on the breakpoint crossing
+
+effect(() => { if (!documentVisible()) pauseExpensiveLoop(); });
+```
+
+---
+
+## Contents
+
+- [Why](#why) | [Install](#install) | [Quick start](#quick-start) | [Architecture](#architecture)
+- [API reference](#api-reference)
+- [Design notes](#design-notes) | [Benchmarks](#benchmarks)
+- [Edge cases & guarantees](#edge-cases--guarantees)
+- [Roadmap](#roadmap) | [License](#license)
+
+---
+
+## Why
+
+Most reactive UI code wires DOM observers per component. A virtual list with 200 rows, each reading `(min-width: 768px)`, mounts 200 `MediaQueryList` listeners. A scroll-based reveal with 200 items mounts 200 `IntersectionObserver` instances. The browser allows it; that does not make it cheap. Every observer is a retained allocation plus a listener slot the browser pages through on every event.
+
+`lite-observe` flips the model: one observer per page (or per distinct configuration), refcounted per element. Components ask for what they want, get a signal, dispose the handle on unmount. The library handles the bookkeeping. Reads are equality-gated through lite-signal so a consumer tracking `width` does not wake when `height` moves.
+
+## Install
+
+```sh
+npm install @zakkster/lite-observe @zakkster/lite-signal
+```
+
+`@zakkster/lite-signal` is a peer dependency.
+
+## Quick start
+
+```js
+import {
+    observeResize,
+    observeIntersection,
+    observeMutation,
+    observeMutationSelector,
+    observeMedia,
+    documentVisible
+} from '@zakkster/lite-observe';
+import { effect } from '@zakkster/lite-signal';
+
+// ResizeObserver -- width and height as separate signals
+const r = observeResize(el);
+effect(() => console.log('width', r.width()));    // only fires when width moves
+
+// IntersectionObserver -- visibility + ratio, options shared by identity
+const i = observeIntersection(el, { rootMargin: '50px' });
+effect(() => { if (i.isIntersecting()) load(); });
+
+// MutationObserver -- tick-driven, peek records when you need them
+const m = observeMutation(list, { childList: true });
+effect(() => { m.tick(); reindex(m.peekRecords()); });
+
+// Selector-filtered mutations -- matching adds/removes only
+const opts = observeMutationSelector(list, '.option', { childList: true, subtree: true });
+effect(() => { for (const el of opts.added()) wire(el); });
+
+// matchMedia -- one signal per query, cached globally
+const dark = observeMedia('(prefers-color-scheme: dark)');
+effect(() => applyTheme(dark() ? 'dark' : 'light'));
+
+// Page Visibility -- a module-level signal, lazy listener
+effect(() => { if (!documentVisible()) raf.stopFrames(); });
+
+// Dispose handles on unmount
+r.dispose(); i.dispose(); m.dispose();
+```
+
+## Architecture
+
+The whole library is one idea applied five times: **one browser observer, refcounted, fanning out to fine-grained signals.** Resize shown below; Intersection (keyed by options tuple), Mutation (keyed by element + options), and Media (keyed by query string) are the same shape with a different key.
+
+```mermaid
+flowchart TB
+    subgraph consumers["N consumers, one element"]
+        C1["component A<br/>reads width"]
+        C2["component B<br/>reads height"]
+        C3["component C<br/>reads width"]
+    end
+
+    C1 -->|"observeResize(el)"| REG
+    C2 -->|"observeResize(el)"| REG
+    C3 -->|"observeResize(el)"| REG
+
+    subgraph lib["lite-observe registry"]
+        REG["slots: Map&lt;Element, slot&gt;"]
+        REG --> SLOT["slot for el<br/>refCount: 3"]
+        SLOT --> SW["width: Signal&lt;number&gt;"]
+        SLOT --> SH["height: Signal&lt;number&gt;"]
+    end
+
+    REG -->|"first observe only"| RO["one ResizeObserver<br/>(page singleton)"]
+    RO -->|"browser fires entries[]"| DISP["dispatch()<br/>indexed loop, zero-alloc"]
+    DISP -->|"width.set(rect.width)"| SW
+    DISP -->|"height.set(rect.height)"| SH
+
+    SW -.->|"Object.is gate"| C1
+    SW -.->|"Object.is gate"| C3
+    SH -.->|"Object.is gate"| C2
+```
+
+Three components observe the same element; the registry allocates one slot (`refCount: 3`) and the browser sees one `observe()` call. When the browser delivers an `entries[]` batch, `dispatch()` walks it with an indexed loop allocating nothing, writing each signal. lite-signal's `Object.is` equality gate then halts propagation at unchanged sources -- so a height-only change wakes component B alone, never A or C. The slot is dropped (and, when the last slot goes, the singleton disconnected) on the last `dispose()`.
+
+## API reference
+
+### `observeResize(element, options?)` -> `ResizeHandle`
+
+```ts
+interface ResizeOptions {
+    box?: 'content' | 'border';         // default 'content'
+}
+interface ResizeHandle {
+    readonly width: Signal<number>;     // CSS pixels (see box)
+    readonly height: Signal<number>;    // CSS pixels (see box)
+    dispose(): void;                    // idempotent
+}
+```
+
+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.
+
+### `observeIntersection(element, options?)` -> `IntersectionHandle`
+
+```ts
+interface IntersectionHandle {
+    readonly isIntersecting: Signal<boolean>;
+    readonly ratio: Signal<number>;     // 0..1, raw IntersectionObserverEntry.intersectionRatio
+    dispose(): void;
+}
+```
+
+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.
+
+### `observeMutation(element, options)` -> `MutationHandle`
+
+```ts
+interface MutationHandle {
+    readonly tick: Signal<number>;                          // monotonic counter, +1 per batch
+    peekRecords(): ReadonlyArray<MutationRecord>;           // latest batch, no copy
+    dispose(): void;
+}
+```
+
+Mutations are events, not state: surfacing the latest `MutationRecord[]` as a signal would either force an array allocation per batch (broken zero-GC) or break consumer expectations about value identity. Instead the library exposes a monotonic `tick` signal that increments per delivered batch, plus a peek-only accessor for the most recent batch. React to `tick`, read the records inside the body.
+
+Consumers asking for the same element with the same option set share one observer; differing options spawn distinct observers.
+
+### `observeMutationSelector(root, selector, options?)` -> `MutationSelectorHandle`
+
+```ts
+interface MutationSelectorHandle {
+    readonly added: Signal<readonly Element[]>;     // matched, added this batch
+    readonly removed: Signal<readonly Element[]>;   // matched, removed this batch
+    readonly tick: Signal<number>;                  // mirrors the inner observeMutation tick
+    peekRecords(): readonly MutationRecord[];
+    dispose(): void;
+}
+```
+
+Selector-filtered wrapper over `observeMutation` for the common "tell me when elements matching X are added or removed under this root" pattern (combobox option lists, infinite-scroll containers, autocomplete panels). Defaults to `{ childList: true, subtree: true }`.
+
+With `subtree: true`, the walk also runs `querySelectorAll(selector)` against added / removed subtrees, so a matching element that arrives as a deep descendant of an added container -- not as its own `addedNodes` entry -- is still surfaced. This is the case most hand-rolled record walks get wrong.
+
+**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.
+
+### `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.
+
+### `documentVisible: Signal<boolean>`
+
+Module-level signal. True iff `document.visibilityState === 'visible'`. Listener attached lazily on first read, detached on last unsubscribe.
+
+## 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.
+
+**Tick instead of records.** `observeMutation` returns a tick signal rather than a records signal because (a) mutation records are transient by spec, (b) emitting a fresh array per batch would force allocations on a hot DOM path, and (c) consumers typically need either a coarse "something changed" wakeup or full record inspection, never partial. The tick + peek shape gives both with zero allocation library-side.
+
+**Lazy listeners, not eager.** `observeMedia` and `documentVisible` use lite-signal's `observeObservers` to attach the underlying DOM listener only while at least one consumer is subscribed. Idle signals cost no listener, just one signal node.
+
+**SSR safe.** Every module guards on `typeof` checks; in Node without the relevant DOM API, signals are created and stay at their initial values. Importing the package never throws.
+
+**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.
+
+## 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.
+
+Run: `node --expose-gc bench/lite-observe.bench.js` (Node 22.22, V8 12.4):
+
+| path | ns/call | B/call | scavenges |
+| --- | --- | --- | --- |
+| `observeResize.dispatch` (64 elements) | ~17900 | 0.00 | 0 |
+| `observeIntersection.dispatch` (64 elements) | ~17100 | 0.00 | 0 |
+| `observeMutation.dispatch` (3 records) | ~116 | 0.00 | 0 |
+| `observeMedia.change` (1 listener) | ~124 | 0.00 | 0 |
+
+The headline figure is **B/call and scavenges, not nanoseconds.** Zero bytes and zero scavenges across every dispatch path is the verifiable claim. The `ns/call` numbers are machine-dependent and indicative only -- and for resize / intersection they cover a full batch of 64 elements (two signals each, plus a subscriber per signal firing), so the per-element cost is roughly `total / 64`. `observeMutationSelector` is intentionally absent from the gate: it allocates result arrays on matching batches by design (see its API note).
+
+## Edge cases & guarantees
+
+- **Dispose is idempotent.** Calling `dispose()` twice is safe and does nothing on the second call.
+- **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.
+- **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.
+- **Orphaned-handle cleanup (FinalizationRegistry).** Explicit `dispose()` is the primary path; this is the safety net for consumers who drop the handle without disposing it. Each handle from `observeResize` / `observeIntersection` / `observeMutation` is registered with a shared `FinalizationRegistry`. When the runtime garbage-collects the handle, the registry fires our inner cleanup, which disconnects (or unobserves) the underlying browser observer the same way an explicit dispose would. The held value passed to the registry is the bare cleanup closure -- it captures slot / element / Map references but never the handle itself, which is what makes finalisation possible.
+  - **Non-deterministic timing.** Finalisation runs "eventually" on the runtime's schedule, not on a guaranteed deadline. On a quiet page that may be milliseconds; on a heavily pressured page it may be measurably later. If you have a lifecycle hook (a framework unmount, a route teardown, an explicit close), call `dispose()` -- you'll save the GC a trip and free the underlying observer immediately. The registry is for the cases where you don't.
+  - **Double-fire safety.** Calling explicit `dispose()` unregisters the finalizer before running the cleanup, so a subsequent GC pass on the same handle does nothing. The inner cleanup's own `disposed` guard is a belt-and-braces second layer.
+  - **What it does not solve.** A consumer who holds the handle in long-lived state and *intends* to retain the observation continues to do so -- nothing about FinalizationRegistry changes that contract. It only catches the "I dropped my reference and forgot to dispose" footgun.
+- **MutationObserver targets and explicit retention.** The DOM spec requires `MutationObserver` (and structurally, the other observers) to retain references to their observed nodes internally so `disconnect()` knows what to deregister. As long as you hold the handle and have not disposed, the target stays alive even if you've removed it from the DOM tree. This is correct behaviour, not a leak -- the observer is still attached, so the node is still relevant. Dispose to release.
+
+## Roadmap
+
+Items deferred from 1.0.0, grouped by tier. Marks intent, not promises; honest scoping happens at each version cut.
+
+### 1.1.x -- additive surface
+
+- **Real-browser finalization smoke.** A page that creates handles, encourages GC via allocation pressure, and asserts on `_resizeSlotCount()` / `_intersectionBucketCount()` / `_mutationObserverCount()` going to zero. Current finalization tests rely on V8's `--expose-gc`; this would catch Safari / Firefox divergence in real-world timing characteristics.
+- **Adaptive `IntersectionObserver` threshold.** Expose `handle.setThreshold(thresholds)` so consumers can refine the threshold list without recreating the observer.
+- **`observeMutationSelector` performance refinement.** Current implementation allocates fresh arrays per batch with matches. For high-frequency mutation streams (live-updating leaderboards, log tails) where the allocation shows up, an opt-in `pooled: true` mode would reuse arrays across batches with a documented "do not retain" contract.
+- **Attribute-filtered `observeMutationSelector`.** Currently only `childList` mutations are filtered. An option to also surface attribute mutations matching the selector (e.g. "tell me when any `.option` becomes `aria-selected="true"`") would close a real ergonomics gap.
+
+### 1.2.x -- ergonomics and developer experience
+
+- **`onShow` / `onHide` convenience over `documentVisible`.** Thin wrappers that compose with `lite-signal`'s `effect` to schedule one-shot callbacks on transition. Strictly additive; the signal remains the primitive.
+- **Bench harness regression gates in CI.** Threshold checks that fail if `B/call` drifts above zero or if `ns/call` regresses by more than 25% across versions. The bench numbers we report should be auditable, not pinky-promise.
+- **`observeResize` logical-axis option (`box: 'logical'`).** Surface `inlineSize` / `blockSize` directly instead of width / height, for consumers building writing-mode-aware layouts. Strictly additive; the existing `'content'` / `'border'` options stay the default.
+
+### 2.0.x -- breaking-change tier
+
+- **Additional observer kinds.** `PerformanceObserver`, `ReportingObserver`, possibly `BroadcastChannel` if the signal-bridge fit is clean. Each adds public surface and is breaking-change-adjacent if any conflict with existing exports.
+- **WeakRef-based `observeMedia` cache (opt-in).** Current cache evicts on disconnect; consumers holding signals across an unobserved period get a fresh signal+MQL pair if they re-request the same query during that window. Briefly wasteful, never wrong. WeakRef would preserve identity at the cost of slightly delayed eviction. Opt-in `observeMedia(query, { weakCache: true })`. Marked 2.x because if it becomes the default it changes observable behaviour.
+- **Synchronous-dispatch contract formalisation.** Currently we assume browser observer callbacks do not re-enter -- the browser's own queueing handles it. Worth a stress test that proves it under adversarial conditions (dispatch fires while a consumer is mid-iteration through signals from a different element), and either documenting the contract or hardening against re-entry.
+
+### Not planned
+
+- **A coarse `rect` signal on `observeResize`.** The fine-grained `width` / `height` split is the design; collapsing them to a single rect would defeat the Object.is propagation gate. If you want a `rect`-shaped object, compose it from the two signals in a `computed`.
+- **`peekRecords` returning a copy.** Identity reuse across ticks is the contract; copying would force allocation on the hot path. Consumers needing snapshot semantics should iterate the array inside the effect that observed the tick change.
+- **Replacing `tick + peek` with a records-shaped signal.** Considered and rejected during the 0.1.x design phase. Mutation records are transient by spec; a records-shaped signal would either allocate per batch or break identity semantics. The current shape gives reactive wakeups and full record access without either.
+
+## Browser & runtime support
+
+All five bridged APIs (`ResizeObserver`, `IntersectionObserver`, `MutationObserver`, `matchMedia`, Page Visibility) are baseline in every evergreen browser. `observeMedia` falls back to the legacy `addListener` / `removeListener` on Safari < 14. The `FinalizationRegistry` orphan-cleanup net is used where available (all evergreen browsers, Node 14+) and is a no-op pass-through where it is not -- explicit `dispose()` works everywhere regardless. SSR-safe: under Node without the DOM globals, every entry point creates signals that stay at their initial values and importing the package never throws. Requires Node >= 18 for the test/bench tooling.
+
+## Testing
+
+- **Unit (Node, fast).** `npm test` runs the `node:test` suites against fake observer globals installed before the SUT loads. Covers shared-observer dedup, refcount teardown, per-field equality gating, the `box` option, selector filtering (including the deep-descendant subtree case), media cache eviction, and SSR no-throw.
+- **Memory (`--expose-gc`).** `npm run test:gc` additionally exercises the `FinalizationRegistry` orphan-cleanup tests, which skip gracefully without the flag.
+- **Allocation gate.** `npm run bench` fails if any dispatch path shows a scavenge or > 1 byte/call (see [Benchmarks](#benchmarks)).
+- **Real-browser smoke.** `npm run test:browser` serves `test/browser/smoke.html`, which runs the same assertions against real browser observers (real layout, real scroll, real `MutationObserver` microtask timing). `window.__SMOKE_RESULTS__` is set for scraping.
+
+## npm scripts
+
+| script | what it does |
+| --- | --- |
+| `test` | `node --test test/*.test.js` -- unit suite against fakes |
+| `test:gc` | as above, with `--expose-gc` for the finalization tests |
+| `test:browser` | serve the browser smoke page |
+| `demo` | serve the interactive demo (`demo/index.html`) |
+| `bench` | `node --expose-gc bench/lite-observe.bench.js` -- allocation gate |
+| `verify` | `npm test && npm run bench` |
+
+## Ecosystem
+
+`lite-observe` is part of the `@zakkster/lite-*` family of zero-GC, zero-dependency ESM micro-libraries built on `@zakkster/lite-signal`:
+
+- [`@zakkster/lite-signal`](https://www.npmjs.com/package/@zakkster/lite-signal) -- the reactive core (peer dependency).
+- `@zakkster/lite-floating` -- anchored-positioning primitives; its RO-driven update loop defers via `requestAnimationFrame`, the pattern recommended under [Edge cases](#edge-cases--guarantees).
+- `@zakkster/lite-signal-dom`, `@zakkster/lite-router`, `@zakkster/lite-persist`, and others compose the same signal model.
+
+## License
+
+MIT (c) Zahary Shinikchiev.