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

package/skills/studiometa-js-toolkit/references/api/registry/fromWebpackContext.md

@@ -0,0 +1,37 @@
+# fromWebpackContext
+
+```ts
+fromWebpackContext(context: WebpackContextLike): ModuleRecord
+```
+
+Adapts an `import.meta.webpackContext()` result for [`defineManifest()`](defineManifest.md).
+
+## Usage
+
+```js
+import { defineManifest, fromWebpackContext, registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromWebpackContext(
+      import.meta.webpackContext('./components', {
+        recursive: true,
+        regExp: /\/index\.js$/,
+        mode: 'lazy',
+      }),
+    ),
+  }),
+);
+```
+
+**Parameters**
+
+- `context` (`WebpackContextLike`) — anything with the `keys()` method and the callable shape of a webpack context.
+
+**Return value**
+
+- `ModuleRecord` — a map of path to a **deferred** importer, one per key.
+
+The import of each key is deferred rather than performed, so nothing is downloaded when the manifest is built. Use `mode: 'lazy'` so webpack emits a chunk per module.
+
+The adapter adds **no webpack dependency**. `WebpackContextLike` is a structural type, so the adapter is testable without a bundler and core names webpack nowhere.

package/skills/studiometa-js-toolkit/references/api/registry/getInstance.md

@@ -0,0 +1,52 @@
+# getInstance
+
+```ts
+getInstance<T extends Base = Base>(el: Element | null, name: string): T | undefined
+```
+
+The instance of `name` on `el`, mounted or not.
+
+## Usage
+
+```ts
+import { Base, getInstance } from '@studiometa/js-toolkit';
+
+class Dialog extends Base {
+  static config = { name: 'Dialog' };
+
+  close() {}
+}
+// `el` may be null — a querySelector() result passes straight through.
+const dialog = getInstance<Dialog>(document.querySelector('[data-component="Dialog"]'), 'Dialog');
+
+if (dialog?.$isMounted) dialog.close();
+```
+
+**Parameters**
+
+- `el` (`Element | null`) — the element to read.
+- `name` (`string`) — the component name.
+
+**Return value**
+
+- `T | undefined`.
+
+## Why it is a function of its own
+
+One map read and no scan. The caller already holds the element and the name, so there is nothing left to search — which is what makes it different from a filter over [`getInstances()`](getInstances.md).
+
+It is also the answer to "is this element's instance there yet", which every plural form loses by returning a list.
+
+## Why `el` accepts `null` but the return is not
+
+`el` accepts `null` so a `querySelector()` result can be passed straight through. The two ways of having no instance — no element, and an element without one — are the same answer to the caller, and `undefined` says it for both. Narrowing the parameter to `Element` would buy nothing back: the body reads an optional map either way, so the only thing a stricter type produces is a `!` at every call site asserting something the function never needed.
+
+The **return** stays `T | undefined`, and that asymmetry is deliberate. An absent element is a fact the caller may reasonably not know; an absent instance is a fact the caller must handle.
+
+## There is no `getMountedInstance`
+
+The result is one object, so a caller who needs the live one reads `.$isMounted` on it. A second export would only hide that check behind an `undefined` that means two things.
+
+## Detached elements
+
+This form reads the element's instance map directly and never consults the DOM, so it answers for a detached element as readily as for a connected one.

package/skills/studiometa-js-toolkit/references/api/registry/getInstances.md

@@ -0,0 +1,48 @@
+# getInstances
+
+```ts
+getInstances<T extends Base = Base>(name: string, root?: ParentNode): T[]
+getInstances<T extends Base = Base>(el: Element): T[]
+```
+
+**Every instance that exists** for a component name, mounted or not, in DOM order — or every instance on one element, in mount order.
+
+## Usage
+
+```ts
+import { getInstances } from '@studiometa/js-toolkit';
+
+const section = document.querySelector('section')!;
+
+getInstances('Dialog'); // every Dialog in the document
+getInstances('Dialog', section); // every Dialog built in a region
+getInstances(section); // everything on one element
+```
+
+Reach for it when the result is **counted or inspected**. When it is going to be _used_, prefer [`getMountedInstances()`](getMountedInstances.md) — every instance in that list has run `mounted()` and has not yet run `unmounted()`.
+
+## The two overloads
+
+```ts
+(name: string, root?: ParentNode): T[]
+(el: Element): T[]
+```
+
+- **The name form** searches the descendants of `root`, which defaults to the document. `root` is a `ParentNode` and the call is `querySelectorAll`, so it never matches `root` itself.
+- **The element form** reads the element's instance map directly and never consults the DOM, so it answers for a **detached** element as readily as for a connected one. The name form cannot: `document.querySelectorAll()` does not see a detached element. Pass the detached root as `root` when a name lookup has to reach inside it.
+
+## How the narrowing works
+
+`selectorFor(name)` over-matches on purpose — it lists the responsive spellings of `data-component` too — and **the instance-map read is what removes an inactive declaration**, because a breakpoint-withdrawn component is destroyed _and_ deleted from the map.
+
+A matching element with no instance is skipped, and that is the whole narrowing. There is no mount filter, because it never did that work.
+
+## Where the instances live
+
+An element publishes its instances under `Symbol.for('@studiometa/js-toolkit/instances')`. That map is **not public API**; these four lookups are, and between them they express every read it answers. In a console:
+
+```js
+$0[Symbol.for('@studiometa/js-toolkit/instances')];
+```
+
+The element overload exists rather than a second export because both forms answer "which instances are there" and the argument picks the scope — and it keeps the map read in one place, which matters more now that the key is a symbol and no longer spellable as `el.__base__`.

package/skills/studiometa-js-toolkit/references/api/registry/getMountedInstances.md

@@ -0,0 +1,39 @@
+# getMountedInstances
+
+```ts
+getMountedInstances<T extends Base = Base>(name: string, root?: ParentNode): T[]
+getMountedInstances<T extends Base = Base>(el: Element): T[]
+```
+
+**The live instances** of a component name, in DOM order — or the live ones on one element, in mount order.
+
+## Usage
+
+```js
+import { getMountedInstances } from '@studiometa/js-toolkit';
+
+// This is the safe list to call a method on.
+getMountedInstances('Dialog').forEach((dialog) => dialog.$unmount());
+```
+
+**This is the safe list to call a method on**: every instance in it has run `mounted()` and has not yet run `unmounted()`. Prefer it over [`getInstances()`](getInstances.md) whenever the result is going to be _used_ rather than counted or inspected.
+
+## The two overloads
+
+```ts
+(name: string, root?: ParentNode): T[]
+(el: Element): T[]
+```
+
+- **The name form** searches the descendants of `root`, which defaults to the document. `root` is a `ParentNode` and the call is `querySelectorAll`, so it never matches `root` itself.
+- **The element form** reads the element's instance map directly and never consults the DOM, so it answers for a **detached** element as readily as for a connected one. The name form cannot: `document.querySelectorAll()` does not see a detached element. Pass the detached root as `root` when a name lookup has to reach inside it.
+
+## How the narrowing works
+
+`selectorFor(name)` over-matches on purpose — it lists the responsive spellings of `data-component` too — and **the instance-map read is what removes an inactive declaration**, because a breakpoint-withdrawn component is destroyed _and_ deleted from the map.
+
+A matching element with no instance is skipped, and that is the whole narrowing. There is no mount filter, because it never did that work.
+
+## There is no `getMountedInstance`
+
+The singular [`getInstance()`](getInstance.md) returns one object, so a caller who needs the live one reads `.$isMounted` on it. A second export would only hide that check behind an `undefined` that means two things — no element, no instance, or an instance that is not mounted.

package/skills/studiometa-js-toolkit/references/api/registry/getUnmountedInstances.md

@@ -0,0 +1,46 @@
+# getUnmountedInstances
+
+```ts
+getUnmountedInstances<T extends Base = Base>(name: string, root?: ParentNode): T[]
+getUnmountedInstances<T extends Base = Base>(el: Element): T[]
+```
+
+The instances of a component name that **were built and are not mounted**, in DOM order — or the same on one element, in mount order.
+
+## Usage
+
+```js
+import { getUnmountedInstances } from '@studiometa/js-toolkit';
+
+getUnmountedInstances('Video').length;
+```
+
+## What this population is
+
+It is small and specific. It is what a **reversible** mount strategy leaves behind: `in-view` and `media:` unmount their instance when the condition stops holding and keep it for the crossing back, so the instance stays in the element's map with `$isMounted === false`.
+
+A constructor that succeeded before a failing `mounted()` lands here too.
+
+## What is _not_ here
+
+- **A declaration whose class never arrived.** A lazy entry that has not loaded has no instance at all.
+- **A declaration withdrawn by a breakpoint.** That instance is unmounted _and deleted_ from the map, so the name later declared again builds a new one.
+- **A component still waiting on a mount strategy.** It has never been constructed.
+
+Neither has an instance, so neither can be in a list of them.
+
+## The two overloads
+
+```ts
+(name: string, root?: ParentNode): T[]
+(el: Element): T[]
+```
+
+- **The name form** searches the descendants of `root`, which defaults to the document. `root` is a `ParentNode` and the call is `querySelectorAll`, so it never matches `root` itself.
+- **The element form** reads the element's instance map directly and never consults the DOM, so it answers for a **detached** element as readily as for a connected one. The name form cannot: `document.querySelectorAll()` does not see a detached element. Pass the detached root as `root` when a name lookup has to reach inside it.
+
+## How the narrowing works
+
+`selectorFor(name)` over-matches on purpose — it lists the responsive spellings of `data-component` too — and **the instance-map read is what removes an inactive declaration**, because a breakpoint-withdrawn component is destroyed _and_ deleted from the map.
+
+A matching element with no instance is skipped, and that is the whole narrowing. There is no mount filter, because it never did that work.

package/skills/studiometa-js-toolkit/references/api/registry/index.md

@@ -0,0 +1,49 @@
+# Registry
+
+The registry is the only code that constructs an instance. It holds one entry per name and one controller per element/component pair.
+
+## Registering
+
+- [`registerComponent(Ctor)`](registerComponent.md) — one eager entry, and its declared family
+- [`registerComponents(...ctors)`](registerComponents.md) — several at once
+- [`registerManifest(entries)`](registerManifest.md) — lazy entries in the same map
+
+## Building a manifest
+
+- [`defineManifest(options)`](defineManifest.md) — derive tokens from module paths
+- [`fromMetaGlob(glob)`](fromMetaGlob.md) — a Vite `import.meta.glob` result
+- [`fromWebpackContext(context)`](fromWebpackContext.md) — a webpack context
+
+## Looking instances up
+
+Four functions answer from the DOM. They keep **no registry of instances**.
+
+| Function                                                  | Population                                 |
+| --------------------------------------------------------- | ------------------------------------------ |
+| [`getInstances()`](getInstances.md)                   | every instance that exists, mounted or not |
+| [`getMountedInstances()`](getMountedInstances.md)     | the live ones — safe to call a method on   |
+| [`getUnmountedInstances()`](getUnmountedInstances.md) | built, then stood down                     |
+| [`getInstance(el, name)`](getInstance.md)             | the one on this element                    |
+
+```js
+getMountedInstances('Dialog').forEach((dialog) => dialog.close());
+getInstances('Dialog', section);
+getUnmountedInstances('Dialog');
+getInstance(el, 'Dialog');
+getInstances(el);
+```
+
+The three plural forms take the same two overloads: a **name** with an optional `ParentNode` root, or an **element**.
+
+- **A matching element with no instance is skipped, and that is the whole narrowing.** `selectorFor(name)` over-matches on purpose — it lists the responsive spellings of `data-component` too — and the instance-map read removes an inactive declaration, because a breakpoint-withdrawn component is destroyed _and_ deleted from the map.
+- `root` is a `ParentNode` and the call is `querySelectorAll`, so an element root searches its **descendants** and never matches itself.
+- **The element overload is the only form that reaches a detached element**, since `querySelectorAll()` does not see one. Pass the detached root as `root` when a name lookup has to reach inside it.
+- **There is no `getMountedInstance`.** The singular returns one object, so a caller reads `.$isMounted` on it.
+
+## In tests
+
+`resetRegistry()` is re-exported from [`/test`](../test/index.md) and drops every registration. It is not part of a page's vocabulary.
+
+## Read next
+
+[The registry](../../guide/concepts/the-registry.md) explains the entry, the controller and the one scheduling algorithm that covers eager, lazy and conditional mounting.

package/skills/studiometa-js-toolkit/references/api/registry/registerComponent.md

@@ -0,0 +1,93 @@
+# registerComponent
+
+```ts
+registerComponent(ComponentClass: BaseConstructor): void
+```
+
+Registers a component and its merged family, then scans the document for matching elements.
+
+## Usage
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class Slider extends Base {
+  static config = { name: 'Slider' };
+}
+
+registerComponent(Slider);
+```
+
+**Parameters**
+
+- `ComponentClass` — a class extending `Base`, with a `config.name`.
+
+**Return value**
+
+- `void`. It is a registration, not an instantiation: the elements that match get their instances through the ordinary pipeline, and there is no list of instances to hand back. Use [`getInstances()`](getInstances.md) if you need them.
+
+## It registers the family too
+
+`config.components` is walked in one loop, so one call covers a whole tree:
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base {
+  static config = { name: 'AccordionItem' };
+}
+
+class Accordion extends Base {
+  static config = {
+    name: 'Accordion',
+    components: { AccordionItem },
+  };
+}
+
+// Registers both.
+registerComponent(Accordion);
+```
+
+A thunk in `config.components` is **deferred** rather than resolved, and becomes a lazy entry of the same registry under its key. See [Autoloading](../../guide/going-further/autoloading.md).
+
+## The name comes from the merged config
+
+Like the instance's `$id` and the instance-map key it publishes itself under. A subclass that extends a component with extra config and forgets to rename therefore **collides** with the name it inherited, rather than registering under `undefined`.
+
+## One name, one entry
+
+As with `customElements.define()`. A second registration under a name already taken gives a `registry.conflict` warning and is ignored.
+
+The exception is a lazy child declared by several parents: that is the normal case, and it is **first wins, quietly**. A token two components genuinely claim is caught by the class-name check when the import lands.
+
+## Registering a class you cannot edit
+
+Do it in expression position:
+
+```js
+registerComponent(
+  class extends Vendor {
+    static config = { name: 'CompactVendor', options: { compact: Boolean } };
+  },
+);
+```
+
+## What it does not do
+
+- **It does not construct anything itself.** The registry does, when the DOM and the mount strategy agree.
+- **It does not take a name or a selector.** `config.name` is the only name, and arbitrary selectors are removed.
+- **It does not take a promise or a thunk.** Use [`registerManifest()`](registerManifest.md) for a lazy entry.
+- **It has no inverse on a page.** `resetRegistry()` exists for tests only — see [`/test`](../test/index.md).
+
+## `@component`
+
+The decorator writes `static config` and calls this function in one step:
+
+```ts
+import { Base, component } from '@studiometa/js-toolkit';
+
+@component({ name: 'Slider', refs: ['next'] })
+class Slider extends Base {}
+```
+
+See [`@component`](../decorators/component.md).

package/skills/studiometa-js-toolkit/references/api/registry/registerComponents.md

@@ -0,0 +1,37 @@
+# registerComponents
+
+```ts
+registerComponents(...classes: BaseConstructor[]): void
+```
+
+[`registerComponent()`](registerComponent.md) for several classes, in order.
+
+## Usage
+
+```js
+import { Base, registerComponents } from '@studiometa/js-toolkit';
+
+class Accordion extends Base {
+  static config = { name: 'Accordion' };
+}
+class Slider extends Base {
+  static config = { name: 'Slider' };
+}
+class TodoList extends Base {
+  static config = { name: 'TodoList' };
+}
+
+registerComponents(Accordion, Slider, TodoList);
+```
+
+This is the whole bootstrap of a page. There is no `createApp()` and no root component: each of these registers its own declared family, and every registered name auto-mounts through the single MutationObserver.
+
+**Parameters**
+
+- `...classes` — classes extending `Base`.
+
+**Return value**
+
+- `void`.
+
+Order matters only for collisions: the first registration of a name wins and the second gives a `registry.conflict` warning.

package/skills/studiometa-js-toolkit/references/api/registry/registerManifest.md

@@ -0,0 +1,72 @@
+# registerManifest
+
+```ts
+registerManifest(entries: ComponentManifest): void
+```
+
+Registers lazy component entries in the same registry the eager classes use.
+
+## Usage
+
+```js
+import { registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest({
+  Accordion: () => import('./components/Accordion.js'),
+  Slider: () => import('./components/Slider.js'),
+  Map: { load: () => import('./components/Map.js'), mountStrategy: 'visible' },
+});
+```
+
+## Types
+
+```ts
+type ComponentManifest = Record<string, ComponentImporter | ComponentManifestEntry>;
+
+type ComponentImporter = () => Promise<unknown>;
+
+interface ComponentManifestEntry {
+  load: ComponentImporter;
+  mountStrategy?: MountStrategy;
+}
+```
+
+An entry is either the importer itself, or an object with `load` and an optional `mountStrategy`.
+
+## The contract
+
+- **One name, one entry**, across eager classes and manifests alike. A token an eager class or an earlier manifest owns gives a `manifest.duplicate-token` warning and is ignored.
+- **No dependency and no bundler knowledge.** The value is a function that returns a promise. `import.meta.glob`, `import.meta.webpackContext` and a generated manifest all produce that shape, and core names none of them.
+- **The class is resolved out of the imported module for you**, so a hand-written entry is `Slider: () => import('./Slider.js')` with nothing to unwrap.
+- **The registry stays the only constructor.** The import ends in [`registerComponent()`](registerComponent.md); autoload never touches `new`, the instance map or a mount hook.
+- **One import per name, one failure report per name.** A failure emits one `component.load-failed` diagnostic and is never retried.
+- **A class whose `config.name` differs from its token** gives a `registry.lazy-name-mismatch` warning.
+- **An unloaded declaration is invisible** to `$query()`, `$closest()`, `$watchChildren()` and `getInstances()`, because nothing is constructed at discovery.
+
+## The mount strategy chain
+
+```
+data-mount  >  manifest entry mountStrategy  >  'eager'
+```
+
+The entry's strategy stands in the middle slot for the `config.mountStrategy` of a class that cannot be read yet. Once the class registers, the chain reads `config.mountStrategy` and the entry is deleted from the map.
+
+There is **no `data-load`**: deferring the import and deferring the mount are one decision. See [Autoloading](../../guide/going-further/autoloading.md).
+
+## `whenDOMSettled()` covers an eager lazy component
+
+The import promise joins the lifecycle-work set for the **eager** trigger only, so [`swap()`](../dom/swap.md) waits for download, registration and mount — and still never waits on a viewport, an idle callback, an interaction or a media query.
+
+## From a glob
+
+```js
+import { defineManifest, fromMetaGlob, registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  }),
+);
+```
+
+See [`defineManifest()`](defineManifest.md).

package/skills/studiometa-js-toolkit/references/api/scheduler/defaultScheduler.md

@@ -0,0 +1,104 @@
+# defaultScheduler
+
+The one scheduler instance. Duplicate copies of the package reuse the canonical one through the shared runtime.
+
+```ts
+class Scheduler {
+  get phase(): SchedulerPhase;
+  tick(callback: TickCallback): () => void;
+  read<T>(fn: () => T): ScheduledTask<T>;
+  write<T>(fn: () => T): ScheduledTask<T>;
+  whenIdle(): Promise<void>;
+}
+```
+
+## `read()` and `write()`
+
+```ts
+import { defaultScheduler } from '@studiometa/js-toolkit';
+
+const el = document.body;
+async function resize() {
+  const box = await defaultScheduler.read(() => el.getBoundingClientRect()).promise;
+  await defaultScheduler.write(() => {
+    el.style.height = `${box?.height}px`;
+  }).promise;
+}
+```
+
+Both return a handle:
+
+```ts
+interface ScheduledTask<T = unknown> {
+  promise: Promise<T | undefined>;
+  cancel(): void;
+}
+```
+
+- The promise resolves with the **return value of the task**, so a read hands its measurement back.
+- `cancel()` is idempotent, and a cancelled task's promise never resolves with a value.
+- **Queued execution only.** There is no synchronous escape.
+
+### The thrash rule
+
+| Scheduled from | Runs in        |
+| -------------- | -------------- |
+| a `read`       | the same frame |
+| a `write`      | the next frame |
+
+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.
+
+## `tick()`
+
+```js
+import { defaultScheduler } from '@studiometa/js-toolkit';
+
+const unsubscribe = defaultScheduler.tick(({ time, delta }) => {
+  console.log(time, delta);
+});
+```
+
+```ts
+interface TickProps {
+  readonly time: DOMHighResTimeStamp;
+  readonly delta: number;
+}
+```
+
+- Tick callbacks run at the **start** of the flush, before `read`, so what they schedule belongs to the same frame.
+- **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 as `callback.scheduler-tick-failed` 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.
+
+For a subscription that comes and goes within a cycle, use [`toggle()`](../services/toggle.md) rather than subscribing and unsubscribing by hand.
+
+## `whenIdle()`
+
+```js
+await defaultScheduler.whenIdle();
+```
+
+Resolves at the end of a flush **and** at the end of a background drain, because it counts background tasks too.
+
+It is one half of the timing recipe the [`/test`](../test/index.md) helpers encode — the other half is the mutation observer's delivery latency, which is why `whenIdle()` alone is not enough to know a component has mounted.
+
+## `phase`
+
+```ts
+type SchedulerPhase = 'idle' | 'tick' | 'read' | 'write' | 'background';
+```
+
+Reading it is a diagnostic, not a control. Code that branches on the phase is usually code that should schedule instead.
+
+## 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.**
+
+A failure to post is reported as `scheduler.background-post-failed`.
+
+## Error isolation
+
+One try/catch per task. A task that throws is reported as `callback.scheduled-task-failed`, **rejects its own promise with the same value**, and is dropped. The flush continues and the scheduler never deadlocks.

package/skills/studiometa-js-toolkit/references/api/scheduler/index.md

@@ -0,0 +1,27 @@
+# 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`.
+
+```
+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
+```
+
+## The exports
+
+- [`defaultScheduler`](defaultScheduler.md) — the instance, with `tick`, `read`, `write`, `whenIdle` and `phase`
+- [`nextFrame()`](nextFrame.md) — await one frame
+- [`viewTransition(update)`](viewTransition.md) — a batched native view transition
+
+From a component, `$read()` and `$write()` tie tasks to the instance so unmount cancels them. See [Instance methods](../instance-methods.md#read-and-write).
+
+## Read next
+
+[The scheduler](../../guide/going-further/scheduling-work.md) explains the lanes, the thrash rule and why `afterWrite` is gone.

package/skills/studiometa-js-toolkit/references/api/scheduler/nextFrame.md

@@ -0,0 +1,31 @@
+# nextFrame
+
+```ts
+nextFrame(): Promise<void>
+```
+
+Resolves on the next animation frame.
+
+## Usage
+
+```ts
+import { nextFrame } from '@studiometa/js-toolkit';
+
+async function afterOneFrame(el: HTMLElement) {
+  el.classList.add('is-entering');
+  await nextFrame();
+  el.classList.add('is-active');
+}
+```
+
+## What it is for
+
+Letting the browser see a style before the next one is applied — the two-step every CSS transition needs. `transition()`, `enterTransition()` and `leaveTransition()` are built on exactly this.
+
+## What it is not
+
+It does **not** mean "after paint". rAF callbacks run **before** style, layout and paint, so no phase inside a frame can read post-layout geometry. `afterWrite` is removed for that reason.
+
+To measure after a layout has happened, measure in the `read` phase of the next frame — [`defaultScheduler.read()`](defaultScheduler.md) or `$read()` — or use a `ResizeObserver`.
+
+For a test that needs several frames, [`frames(count?)`](../test/index.md) is the same idea with a count.