@studiometa/js-toolkit 4.0.0-alpha.1 → 4.0.0-alpha.3

package/skills/studiometa-js-toolkit/references/guide/going-further/mount-strategies.md

@@ -0,0 +1,95 @@
+# Mount strategies
+
+A mount strategy decides **when** the registry mounts an instance. It constructs nothing and it wraps nothing.
+
+## The seven values
+
+| Strategy                 | Mounts when                            | Reversible |
+| ------------------------ | -------------------------------------- | ---------- |
+| `eager` (default)        | the element enters the document        | no         |
+| `visible[:<rootMargin>]` | it first intersects the viewport       | no         |
+| `in-view[:<rootMargin>]` | it intersects the viewport             | **yes**    |
+| `idle`                   | the main thread becomes idle           | no         |
+| `interaction`            | the user first aims at **it**          | no         |
+| `interaction:page`       | the user first interacts with the page | no         |
+| `media:<query>`          | the query is not empty and it matches  | **yes**    |
+
+**One-shot and reversible are separate values.** `visible` mounts once and stays. `in-view` mounts and unmounts on each crossing.
+
+## Declaring one
+
+A component declares its default in its config; any element overrides it with `data-mount`:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Map extends Base {
+  static config = {
+    name: 'Map',
+    mountStrategy: 'visible',
+  };
+}
+```
+
+```html
+<!-- uses the component default -->
+<div data-component="Map"></div>
+
+<!-- overridden per element -->
+<div data-component="Map" data-mount="eager"></div>
+<div data-component="Map" data-mount="visible:200px"></div>
+<div data-component="Chat" data-mount="interaction:page"></div>
+<div data-component="Parallax" data-mount="media:(prefers-reduced-motion: no-preference)"></div>
+```
+
+The resolution chain is:
+
+```
+data-mount  >  manifest entry mountStrategy  >  config.mountStrategy  >  'eager'
+```
+
+## The grammar
+
+The accepted values are exactly `eager`, `visible`, `visible:`, `visible:<rootMargin>`, `in-view`, `in-view:`, `in-view:<rootMargin>`, `idle`, `interaction`, `interaction:`, `interaction:page` and `media:<non-empty query>`.
+
+- A viewport suffix is passed straight through as `IntersectionObserverInit.rootMargin`.
+- The empty suffix behaves as the bare strategy.
+- `page` is the only scope the interaction strategy takes.
+- There is **no** threshold, no root element, no JSON options and no second attribute.
+
+An unknown value, an empty media query, or a `rootMargin` the browser refuses leaves the component **unmounted** and reports `component.invalid-mount-strategy` once. The inert controller stays current while the declaration does not change, so it is not reported again; a corrected attribute replaces it. A failed strategy cannot stop the rest of a reconciliation.
+
+## `interaction` — intent on the element
+
+`pointerenter`, `pointerdown` and `focusin`, bound to the element itself, so the component mounts **before** the click arrives. Two of the three bubble, so an interaction anywhere inside the subtree counts; `pointerenter` fires for the root element only.
+
+## `interaction:page` — the visit, not the element
+
+This is the deferred-widget case: a chat panel, an embed, a third-party script, where nothing about the element predicts the moment and any sign of a live user does.
+
+- The events are the deliberate ones: `pointerdown`, `keydown` and `focusin`. Hovering is deliberately **not** one of them — aiming is intent for one element and noise for a document.
+- **One listener set for the page**, in the shared runtime, not one per waiting element. They attach with the first waiting element and release on the first interaction.
+- **They are captured**, so a handler that stops propagation cannot hide the visit.
+- **The signal is a fact about the visit.** An element that arrives after the interaction mounts at once — but only when the strategy was already listening, since nothing observes a page that has asked for nothing.
+
+## What a waiting component is
+
+**A component that waits has no instance.** It is invisible to `$query()`, `$closest()`, `$watchChildren()` and `getInstances()`, and it announces nothing. There is nothing to guard against and nothing to check.
+
+Once it has mounted and been stood down again — which only `in-view` and `media:` do — the instance exists and is unmounted, so it is what [`getUnmountedInstances()`](../../api/registry/getUnmountedInstances.md) answers.
+
+## Lifetime
+
+- **Several components on one element share that element's `data-mount`.** A component that needs its own policy declares it in its config.
+- **Teardown follows the element.** A strategy is disposed when its element leaves the document. A move ends as an unmount and a mount of the same instance.
+- **The attribute is live.** A change to `data-mount` disposes the old strategy and applies the final one. Controller identity guards a queued callback of a disposed strategy.
+
+## What this replaces
+
+The `withMountWhenInView`, `withMountOnMediaQuery` and `withMountWhenPrefersMotion` decorators of v3 are **deleted**. A decorator that wraps a constructor to decide whether to mount is the registry's job, and the registry does it without touching the class.
+
+`data-load` and `loadStrategy` are gone too: deferring the import and deferring the mount are one decision. See [Autoloading](autoloading.md).
+
+**`withInView` is a different thing**
+
+[`withInView`](../../api/services/mixins.md) observes a component that is **already mounted** and calls `intersected()`. It does not replace the `visible` or `in-view` mount strategy.

package/skills/studiometa-js-toolkit/references/guide/going-further/scheduling-work.md

@@ -0,0 +1,124 @@
+# The scheduler
+
+One frame-aligned scheduler is the clock of the framework. It replaces `domScheduler`, the `RafService` loop, `SmartQueue` and the view-transition scheduler of `@studiometa/ui`.
+
+## The lanes
+
+```
+frame start (rAF)
+  1. tick        — fan out to the subscribers of the clock
+  2. read        — measure: layout reads only
+  3. write       — mutate: DOM writes only
+style / layout / paint
+
+between frames, on its own turns
+  background     — time-sliced lane: mount and update lifecycle work,
+                   mutation-record processing, manifest loading
+```
+
+- **Frame alignment.** One flush per frame, at rAF. Every read runs before every write, once, before paint.
+- **No thrashing.** A `read` scheduled from a `write` runs in the **next** frame. A `write` scheduled from a `read` runs in the **same** frame.
+- **Bounded phases.** Each queue array is swapped for an empty one when its phase starts, so a task scheduled into the running phase lands in the next frame's batch. The `write` batch is taken after the reads run.
+- **Error isolation.** One try/catch per task. A task that throws is reported and dropped; the flush continues and the scheduler never deadlocks.
+- **Queued execution only.** There is no synchronous escape.
+
+## Reading and writing from a component
+
+`this.$read(fn)` and `this.$write(fn)` tie tasks to the instance, and unmount cancels the pending ones:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Reveal extends Base {
+  static config = { name: 'Reveal' };
+
+  async mounted() {
+    const box = await this.$read(() => this.$el.getBoundingClientRect()).promise;
+    await this.$write(() => {
+      this.$el.style.setProperty('--height', `${box?.height}px`);
+    }).promise;
+  }
+}
+```
+
+Scheduling returns a cancelable **handle** whose promise resolves with the return value of the task:
+
+```ts
+import { defaultScheduler } from '@studiometa/js-toolkit';
+
+const el = document.body;
+async function measure() {
+  const task = defaultScheduler.read(() => el.getBoundingClientRect());
+  const box = await task.promise;
+  task.cancel(); // idempotent
+  return box;
+}
+```
+
+## The tick
+
+`scheduler.tick(callback)` subscribes to the clock:
+
+```js
+import { defaultScheduler } from '@studiometa/js-toolkit';
+
+const unsubscribe = defaultScheduler.tick(({ time, delta }) => {
+  console.log(time, delta);
+});
+```
+
+- Tick callbacks run at the **start** of the flush, before `read`, so what they schedule belongs to the same frame. A callback measures in `read` and the render function it returns mutates in `write`.
+- **The subscription is the only handle, and it keeps the loop alive.** The scheduler requests the next frame when a queue inside the frame is not empty, or when a tick subscriber stays. There is no permanent rAF loop.
+- Tick subscribers are not queued work, so `whenIdle()` ignores them.
+- A tick callback that throws is reported and skipped, never unsubscribed.
+- **`delta` is clamped** to `[1, 40]` ms, and the first tick after the loop wakes reports `1000/60`. `time` stays the raw rAF timestamp.
+
+A component that needs the loop for part of a cycle uses [`toggle()`](../../api/services/toggle.md) rather than subscribing and unsubscribing by hand.
+
+## The background lane
+
+It posts its own turns through `scheduler.postTask({ priority: 'background' })`, and falls back to a `MessageChannel` message. Each turn runs a **5 ms slice** measured from the start of the drain, then gives the thread back and posts the next turn.
+
+Background work alone never requests an animation frame. `whenIdle()` counts background tasks and resolves at the end of a background drain as well as at the end of a flush.
+
+## `nextFrame()`
+
+```js
+import { nextFrame } from '@studiometa/js-toolkit';
+
+async function afterPaint() {
+  await nextFrame();
+}
+```
+
+## `afterWrite` is gone
+
+rAF callbacks run before style, layout and paint, so **no phase inside the frame can read post-layout geometry**. Measure in the `read` phase of the next frame, or use a `ResizeObserver`.
+
+## View transitions
+
+`viewTransition(update)` is a standalone export with a progressive-enhancement contract: where the platform has no `startViewTransition`, the update simply runs.
+
+```ts
+import { viewTransition } from '@studiometa/js-toolkit';
+
+async function swapPanel(el: Element, html: string) {
+  await viewTransition(() => {
+    el.innerHTML = html;
+  });
+}
+```
+
+- Updates queued in the **same flush** batch into one `startViewTransition()` call, so a backdrop and a panel animate as one transition. Each later batch is appended to one promise tail, so several flushes during one transition stay serialized.
+- The scheduler flushes the pending `write` tasks before the snapshot. Writes scheduled inside the update callback run within the transition.
+- The helper is standalone. `Base` has no view-transition method and no import of one.
+
+It composes with a negotiated `domUpdate()`, where the ancestor chooses the lane because it knows whether the region animates:
+
+| claim                                         | effect                                                               |
+| --------------------------------------------- | -------------------------------------------------------------------- |
+| `wrap(viewTransition)`                        | the change plays as one batched native view transition               |
+| `wrap((apply) => this.$write(apply).promise)` | the change lands in the `write` phase, batched, cancelled on unmount |
+| `wrap(motionView)`                            | any object with `update(mutate)`                                     |
+
+Neither runner is the default.

package/skills/studiometa-js-toolkit/references/guide/going-further/sharing-state.md

@@ -0,0 +1,218 @@
+# Shared state
+
+Two components that must agree on something share it through **provide/inject** — the shape of Vue's `provide`/`inject`, with the mechanics of the WICG context protocol.
+
+## A typed key
+
+A key is a value, not a string, so keys cannot collide:
+
+```ts
+import { createContext, type Signal } from '@studiometa/js-toolkit';
+
+interface SliderApi {
+  state: Signal<{ index: number; total: number }>;
+  goNext(): void;
+}
+
+export const SliderContext = createContext<SliderApi>('slider');
+```
+
+The description is for debugging only. The identity of the key is what resolves.
+
+## Providing
+
+The coordinator provides what a control can ask for. **The value is provided as it is** — nothing is wrapped, so the type of the key is the contract from end to end:
+
+```ts
+import { Base, createContext, signal, type Signal } from '@studiometa/js-toolkit';
+
+interface SliderApi {
+  state: Signal<{ index: number; total: number }>;
+  goNext(): void;
+}
+const SliderContext = createContext<SliderApi>('slider');
+class Slider extends Base {
+  static config = { name: 'Slider' };
+
+  api = this.$provide(SliderContext, {
+    state: signal({ index: 0, total: 0 }), // what changes
+    goNext: () => this.goNext(), // what a control can command
+  });
+
+  goNext() {
+    this.api.state.value = {
+      ...this.api.state.value,
+      index: this.api.state.value.index + 1,
+    };
+  }
+}
+```
+
+- The **scope is the subtree**, and the nearest provider wins.
+- A reactive value is a provided `Signal`. A command surface is a provided object.
+- `$provide()` in a field initializer is **instance-scoped**: it is never released and dies with the element. A component whose declaration is withdrawn keeps providing until its element goes.
+
+## Injecting
+
+| Form               | Resolves                          | When nothing provides                                 |
+| ------------------ | --------------------------------- | ----------------------------------------------------- |
+| `$inject(key)`     | a promise, awaited in `mounted()` | it never settles: a missing provider means "not yet". |
+| `$injectSync(key)` | the value, synchronously          | `undefined`: the caller falls back or does nothing.   |
+
+```ts
+import { Base, createContext, type Signal } from '@studiometa/js-toolkit';
+
+interface SliderApi {
+  state: Signal<{ index: number; total: number }>;
+  goNext(): void;
+}
+const SliderContext = createContext<SliderApi>('slider');
+class SliderNext extends Base {
+  static config = { name: 'SliderNext' };
+
+  async mounted() {
+    const api = await this.$inject(SliderContext);
+    return api.state.subscribe(({ index, total }) => {
+      this.$el.toggleAttribute('disabled', index >= total - 1);
+    });
+  }
+}
+```
+
+The pending request of the async form is **unmount-scoped**. A new mount runs `mounted()` again and asks again.
+
+**Which form to reach for**
+
+`$inject()` from `mounted()` is the default: it waits, so mount order does not matter. `$injectSync()` is for the case where the answer is optional and the caller has a fallback. The [`@inject`](../../api/decorators/inject.md) field decorator asks once, at construction.
+
+## Page-wide state
+
+`provideRootContext(key, create)` makes the page-wide case the outermost scope of the same mechanism. The value is provided on `document.documentElement`, so a request from anywhere reaches it by bubbling — and a nearer provider still wins:
+
+```ts
+import { createContext, injectContextSync, provideRootContext } from '@studiometa/js-toolkit';
+
+const DataChannels = createContext<Map<string, unknown>>('channels');
+const el = document.body;
+// Scoped or page-wide, resolved the same way, nearest first.
+const channels =
+  injectContextSync(el, DataChannels) ?? provideRootContext(DataChannels, () => new Map());
+```
+
+`create` runs at most once per key, and nothing is created at import time. A root provider cannot be disposed and it outlives the instance that asked first, because it is page state.
+
+`withGroup` is not ported.
+
+## `Signal`
+
+`signal(initialValue)` is a factory over a closure. The accessor is `.value`:
+
+```ts
+import { signal } from '@studiometa/js-toolkit';
+
+const count = signal(0);
+
+const unsubscribe = count.subscribe((value) => console.log(value), { immediate: true });
+
+count.value = 1;
+count.value += 1;
+
+unsubscribe();
+```
+
+**A write settles synchronously and the newest value wins.** The delivery loop re-reads the value after each callback; if the value moved, the loop abandons the round and starts again on the new value, so a subscriber not reached yet skips the old value. Delivery stays in the same task.
+
+**A subscriber that writes on every delivery live-locks the loop**
+
+Guard the write, or move it out of the subscriber.
+
+## Reacting to a provider that appears later
+
+`subscribeContext(el, key, onProvide)` is the subscription behaviour of the WICG protocol. The callback runs synchronously for each answer and receives the value and the same unsubscribe function the helper returns:
+
+```ts
+import { Base, createContext, subscribeContext } from '@studiometa/js-toolkit';
+
+interface GroupApi {
+  join(peer: Base): () => void;
+}
+const DisclosureGroupContext = createContext<GroupApi>('disclosure-group');
+class Disclosure extends Base {
+  static config = { name: 'Disclosure' };
+
+  group?: GroupApi;
+
+  mounted() {
+    return subscribeContext(this.$el, DisclosureGroupContext, (group) => {
+      this.group = group;
+      const leave = group.join(this);
+      // The teardown for *this* value.
+      return () => {
+        leave();
+        this.group = undefined;
+      };
+    });
+  }
+}
+```
+
+- **The trigger is the mount announcement**, not a broadcast from the provider, and it runs after `mounted()`.
+- **A new answer replaces; it never accumulates.** The teardown runs before the next _different_ value and on unsubscribe. An identical value is not an answer.
+- **The registry holds nothing.** A subscription is anchored on its consumer element through a `WeakMap`, and the iterable index holds `WeakRef`s that the sweep prunes.
+- Callback and teardown failures are isolated, so one consumer cannot stop the shared sweep.
+- Two `contains()` calls bound the cost per mount. A mount that changes nothing checks nothing.
+
+## Groups of peers
+
+`createGroup()` holds a `Set` and a `Signal`. It names no group and resolves no scope — the coordinator owns the membership and gives out the ways in:
+
+```ts
+import { Base, createContext, createGroup, type Signal } from '@studiometa/js-toolkit';
+
+interface GroupApi {
+  members: Signal<readonly Base[]>;
+  join(peer: Base): () => void;
+  open(peer: Base): void;
+}
+const DisclosureGroupContext = createContext<GroupApi>('disclosure-group');
+class DisclosureGroup extends Base {
+  static config = { name: 'DisclosureGroup' };
+
+  #peers = createGroup<Base>();
+
+  api = this.$provide(DisclosureGroupContext, {
+    members: this.#peers.members, // the members to read, in document order
+    join: (peer: Base) => this.#peers.join(peer), // returns the leave function
+    open: (peer: Base) => this.open(peer), // the invariant stays here
+  });
+
+  open(peer: Base) {}
+}
+```
+
+- `join()` returns its own `leave`, so a member that moves to a nearer group leaves the old one first.
+- Scope comes from nearest-provider-wins, so a nested group takes its own members only.
+- **The membership is a value.** A coordinator subscribes to it and re-checks its invariant on each change.
+- **Document order is the tie-breaker**, so the markup decides which peer keeps its state.
+- Nothing sweeps disconnected members. The teardown of the member removes it.
+
+## How the mechanics work
+
+The consumer dispatches a bubbling, **module-private** `js-toolkit:context:request` event carrying a key, a callback and a subscription marker. It is deliberately not part of public `EVENTS`. The nearest mounted provider answers and stops propagation. `provideContext()` replays the requests that have no first answer yet, which is what makes mount order irrelevant. `injectContext()` and `$inject()` are one-shot.
+
+Outside a component the same three functions work on a bare element:
+
+```ts
+import {
+  createContext,
+  injectContext,
+  injectContextSync,
+  provideContext,
+} from '@studiometa/js-toolkit';
+
+const Key = createContext<number>('key');
+const el = document.body;
+const { value, dispose } = provideContext(el, Key, 42);
+const { promise, cancel } = injectContext(el, Key);
+const maybe = injectContextSync(el, Key);
+```

package/skills/studiometa-js-toolkit/references/guide/going-further/swapping-content.md

@@ -0,0 +1,92 @@
+# Swapping content
+
+`swap()` replaces the **content** of an element with new markup and resolves once the framework has caught up: the mutation is applied, the new components are mounted and the old ones are unmounted.
+
+## The call
+
+```ts
+import { swap } from '@studiometa/js-toolkit';
+
+async function load(target: Element) {
+  const response = await fetch('/fragment');
+  await swap(target, await response.text());
+  // Every eager component in the new markup has mounted.
+}
+```
+
+`swap(target, content, options?)` returns a promise that resolves after [`whenDOMSettled()`](../../api/dom/whenDOMSettled.md).
+
+## What survives
+
+By default the element **itself** is never replaced, so the caller's reference, its `id` and any instance on it survive. Only its children change.
+
+`content` is a markup string parsed in the parsing context of the target, so `<tr>`, `<li>` and `<option>` survive. It can also be an `Element` or a `DocumentFragment`, read as the incoming counterpart of the target, whose children become the new content.
+
+## The four modes
+
+```js
+import { swap, SWAP_MODES } from '@studiometa/js-toolkit';
+
+await swap(el, html); // 'replace' — the default
+await swap(el, html, { mode: SWAP_MODES.PREPEND });
+await swap(el, html, { mode: SWAP_MODES.APPEND });
+await swap(el, html, { mode: SWAP_MODES.MORPH });
+```
+
+| Mode      | Effect                                              |
+| --------- | --------------------------------------------------- |
+| `replace` | the children are replaced                           |
+| `prepend` | the new content goes before the existing children   |
+| `append`  | the new content goes after them                     |
+| `morph`   | the children are morphed in place, keeping identity |
+
+`prepend` and `append` stay in core because they need the same before-and-after script diff as the other two.
+
+### `morph` keeps identity
+
+Nodes, focus, expandos and instances survive a morph — **but markup that is not sent does not**. Two consequences are morphdom's policy, not `swap()`'s:
+
+- an element the incoming markup does not contain is discarded even from a preserved parent;
+- morphdom syncs the `value` of an input from the incoming markup.
+
+Core passes `childrenOnly: true` without `self`, so **attributes are not synced** on the target: `data-component` and `data-mount` are lifecycle declarations of the target, not content.
+
+## `self` — replacing the element itself
+
+```js
+await swap(el, html, { mode: 'replace', self: true });
+```
+
+This is the axis a caller that matches an element of a response to an element of the page needs: an id-matched section otherwise keeps the classes of the element it replaces.
+
+- With `self`, an `Element` content **is** the replacement rather than a container — the only way its own attributes reach the page. A string or a `DocumentFragment` contributes its first top-level element.
+- `replace` puts the replacement in the place of the target, so the target **leaves** the document.
+- `morph` morphs the target from the replacement without `childrenOnly`, so the element and its identity survive while its attributes are updated.
+- `append` and `prepend` add to the children by definition, so `self` with either is a `swap.self-ignored` warning — as is content that holds no element.
+
+## Scripts
+
+A `<script>` produced by the fragment parser is flagged as already started by the HTML specification and stays inert wherever it is moved. It runs only if it is **recreated**, and a script that was already in the page runs **twice** if it is recreated.
+
+`swap()` owns that rule, once. Script adoption follows whatever ends up in the document, so a replacement carrying a script still runs it exactly once.
+
+## Wrapping the mutation
+
+`wrap` is the whole seam. It receives the single mutation of the swap and decides when it runs:
+
+```ts
+import { swap, viewTransition } from '@studiometa/js-toolkit';
+
+async function load(el: Element, html: string) {
+  await swap(el, html, { wrap: (mutate) => viewTransition(mutate) });
+}
+```
+
+[`domUpdate()`](../../api/dom/domUpdate.md) produces that wrapper and nothing else, so an ancestor can claim the lane. Resilience policy stays with `domUpdate()`.
+
+## What is deliberately not in core
+
+- **Attribute syncing in a default `morph`** — see above.
+- **Transitions, view transitions, history, `id` matching and response parsing.** All of these are caller policy.
+
+`swap()` is a free function, not a `Base` method. `morphdom` is a real, statically imported dependency, and the subpath layout contains the cost: it is reachable through `swap()` only, so a page that never swaps never downloads it.

package/skills/studiometa-js-toolkit/references/guide/going-further/testing-components.md

@@ -0,0 +1,137 @@
+# Testing
+
+`@studiometa/js-toolkit/test` ships the nine helpers a component test cannot write for itself.
+
+## Why a subpath exists
+
+**The timing recipe is not derivable.** "Has this component mounted and finished its writes?" is answered by five rounds of a 10 ms timer followed by `defaultScheduler.whenIdle()`, and those two numbers encode the mount observer's delivery latency and the scheduler's lane order.
+
+Neither half works alone: `whenIdle()` can resolve before the observer has reported the element, and a timer can return between two lanes. `defaultScheduler` and `nextFrame` were already public, so the pieces shipped and the recipe did not.
+
+**It depends on no test framework.** Nothing in the module imports a runner, an assertion library or a spy; it reads the DOM and the scheduler only, so it runs under Vitest, under Playwright and on a plain browser page. That is also why it is not on the root barrel: a page has no use for it.
+
+## A first test
+
+```js
+import { afterAll, expect, test } from 'vitest';
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+import { mount, resetDom, resetRegistry, waitFor } from '@studiometa/js-toolkit/test';
+
+class Counter extends Base {
+  static config = { name: 'Counter', refs: ['output'] };
+
+  count = 0;
+
+  onClick() {
+    this.count += 1;
+    this.$refs.output.textContent = String(this.count);
+  }
+}
+
+registerComponent(Counter);
+
+test('it counts clicks', async () => {
+  const root = await mount(`
+    <button data-component="Counter">
+      <span data-ref="output">0</span>
+    </button>
+  `);
+
+  root.querySelector('button').click();
+
+  await waitFor(() => root.querySelector('[data-ref="output"]').textContent === '1');
+});
+
+afterAll(async () => {
+  await resetDom();
+  resetRegistry();
+});
+```
+
+## The helpers
+
+| Helper                           | What it does                                                           |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| `mount(html)`                    | inserts the markup and resolves once the eager components have mounted |
+| `settle()`                       | resolves once the framework has caught up                              |
+| `frames(count?)`                 | awaits animation frames                                                |
+| `waitFor(predicate, options?)`   | polls until the predicate is truthy, and returns that value            |
+| `countRequestedFrames(during)`   | counts the `requestAnimationFrame()` calls made during `during`        |
+| `captureDiagnostics(target?)`    | collects diagnostics and silences their console output                 |
+| `recordEvents(target, ...types)` | records events in order, with their payloads                           |
+| `resetDom()`                     | empties the document body and lets the teardown run                    |
+| `resetRegistry()`                | drops every registration                                               |
+
+See the [full reference](../../api/test/index.md).
+
+## `mount()` returns the wrapper
+
+It returns the `div` it created, **never** the markup's own root, so a fragment of several siblings works and `querySelector()` has a stable handle. `.firstElementChild` is one property away.
+
+## `waitFor()` is a guard and a query
+
+It returns the predicate's truthy value, which makes the same call either:
+
+```js
+// a guard
+await waitFor(() => el.classList.contains('is-open'));
+
+// or a query
+const panel = await waitFor(() => root.querySelector('.panel'));
+```
+
+It polls on a 10 ms cadence and drains the scheduler between attempts. On timeout it throws — with the caller's `message`, or one naming the timeout.
+
+## Transitions: poll, never `settle()`
+
+**A transition's end state is asserted by polling.** A method that starts a transition does not hand it back, and a kept end state lands only after `nextFrame()`, the `from` and `active` states, and either a `transitionend` or one more frame. `settle()` is generous rather than deterministic, which is a flake that passes alone and fails under load.
+
+**Polling for an _absence_ is wrong** for the mirror-image reason: `leaveTransition()` clears the other direction's `to` state synchronously, so the poll passes before anything has happened.
+
+## `recordEvents()` keeps the order
+
+A component's contract is "`open` came before `opened`, and `opened` carried the height it measured", and a call-counting spy throws both away:
+
+```js
+const recording = recordEvents(el, 'open', 'opened');
+
+el.querySelector('button').click();
+
+await waitFor(() => recording.events.length === 2);
+expect(recording.events.map(({ type }) => type)).toEqual(['open', 'opened']);
+expect(recording.events[1].detail).toEqual({ height: 120 });
+
+recording.stop();
+```
+
+Recording several types into one array is the only place their relative order is visible. `$emit` dispatches synchronously but is almost never _called_ synchronously, so the count is awaited with `waitFor`, not read.
+
+## `resetRegistry()` — where the call belongs
+
+It is the inverse `registerComponent()` deliberately lacks, and it is **coarse on purpose**: the element→controller map is a `WeakMap`, so nothing can walk it to dispose live triggers, and a `querySelectorAll()` sweep would still miss detached elements.
+
+Clearing everything works because the mutation-observer path already disposes a controller as its element leaves the DOM — hence the call belongs **after** `resetDom()`.
+
+**Never in an `afterEach`**
+
+Spec files register at module top level, so `resetRegistry()` in an `afterEach` silently unregisters everything for every later test in the file. Put it in an `afterAll`, or call it and register again straight away:
+
+```js
+afterEach(async () => {
+  await resetDom();
+  resetRegistry();
+  registerComponents(Subject, Emitter);
+});
+```
+
+## `countRequestedFrames()` patches a global
+
+It swaps `globalThis.requestAnimationFrame` for a counting wrapper that forwards to the original, and restores it in a `finally` — so it comes back whether `during` returns or throws.
+
+It is here despite the patch because the assertion it serves, "this did not schedule a frame per event", has no other seam: the framework's own scheduler makes the calls, so there is nothing of the component's for a spy to sit on.
+
+**Two concurrent calls would nest their wrappers. Do not.**
+
+## What is deliberately not in it
+
+An instance lookup — `getInstance()` and `getInstances()` on the root barrel answer it — fetch stubs, and pointer sequences. Each is either specific to one spec or already served by `vi.fn()` and `@vitest/browser`'s `userEvent`.