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

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

@@ -0,0 +1,104 @@
+# Autoloading
+
+A page that declares its components in the markup does not have to import them all up front. Map each `data-component` token to a dynamic import and the registry downloads a chunk when an element needs one.
+
+## `registerManifest()`
+
+```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' },
+});
+```
+
+An entry is either the importer itself, or an object with `load` and an optional `mountStrategy`.
+
+- **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.
+- **The registry stays the only constructor.** The import ends in `registerComponent(ComponentClass)`.
+- **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.
+- 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.
+
+## One knob, not two
+
+Deferring the import and deferring the mount are **one decision**:
+
+```
+data-mount  >  manifest entry mountStrategy  >  'eager'
+```
+
+The manifest entry 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`** and no compatibility shim for it. A page that used `data-load` renames one attribute.
+
+### What that buys
+
+One scheduling algorithm covers both halves. A name resolves to one source, and one controller holds the current decision of the element/component pair. The arrival of the class is a _change of source_, so the pass that replaces a controller turns a spent import trigger into a mount:
+
+- a **one-shot** trigger (`visible`, `idle`, `interaction`) mounts on the import that proved its condition;
+- a **reversible** one (`in-view`, `media:`) is observed again.
+
+An unloaded declaration is invisible to `$query()`, `$closest()`, `$watchChildren()` and `getInstances()`, because nothing is constructed at discovery.
+
+`whenDOMSettled()` covers an **eager** lazy component: the import promise joins the lifecycle-work set only for the eager trigger, so [`swap()`](../../api/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.
+
+## Generating a manifest from a glob
+
+`defineManifest()` turns a bundler glob into a manifest, deriving each token from the path:
+
+```js
+import { defineManifest, fromMetaGlob } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  }),
+);
+```
+
+- `index.js` falls back to the parent directory name, so `./components/Slider/index.js` is `Slider`.
+- A package-wide `mountStrategy` emits entry wrappers only when it is not `eager`.
+- Duplicate tokens give a warning and keep the first path.
+
+For webpack, [`fromWebpackContext()`](../../api/registry/fromWebpackContext.md) takes an `import.meta.webpackContext` result. Neither adapter adds a bundler dependency — core names none of them.
+
+## Lazy children
+
+`config.components` takes a dynamic import too, and the key supplies the name:
+
+```js
+static config = {
+  name: 'Accordion',
+  components: {
+    AccordionItem: () => import('./AccordionItem.js'),
+    Icon: IconClass,
+  },
+};
+```
+
+`registerComponent()` defers a thunk instead of resolving it, and the value becomes a lazy entry of the same registry under its key. Everything after that is identical to a manifest entry.
+
+- **The key supplies the name**, so a lazy child is a name the registry knows with nothing downloaded — and `on<Child><Event>` resolution works on it immediately.
+- **A manifest can declare the parent only.** A child behind a thunk is its own chunk, so a family splits where the author splits it.
+- **First wins, quietly**, unlike `registerManifest()`. Several parents declaring the same lazy child is the normal case.
+- **The entry gets no `mountStrategy` field.** Until the class arrives the chain is `data-mount > eager`; after it, the usual chain reads the merged config, so a lazy child that is a subclass inherits the strategy of its base.
+- A value written with `class` that does not extend `Base` is reported as `component.invalid-family-declaration`, where it is declared.
+
+## What v3's autoload did that v4 does not need
+
+v3 shipped 1033 source lines of autoload across seven modules. The registry and the mount strategies absorb almost all of it:
+
+| v3                                                     | v4                                                            |
+| ------------------------------------------------------ | ------------------------------------------------------------- |
+| `ComponentLoader.start()` discovery observer           | the one document observer                                     |
+| the four load triggers of `__schedule()`               | `mount-strategies.ts`                                         |
+| per-element and per-record cleanup bookkeeping         | one controller map holding both halves                        |
+| recursive registration of configured children          | one `registerFamily()` loop over `config.components`          |
+| the `ComponentRecord` state machine                    | one `Map<string, Promise<void>>` — the promise _is_ the state |
+| `readEagerTokens` and `<meta name="js-toolkit:eager">` | `data-mount` on the element                                   |
+
+The `children` arrays of a v3 manifest are dead data.

package/skills/studiometa-js-toolkit/references/guide/going-further/handling-diagnostics.md

@@ -0,0 +1,104 @@
+# Diagnostics
+
+Everything the framework recovers from is reported on **one** cancelable event, and nothing in core calls `console.warn()` or `console.error()` directly.
+
+## The protocol
+
+`EVENTS.diagnostic` is `'js-toolkit:diagnostic'`. It carries a `ToolkitDiagnosticDetail`:
+
+| Field       | Type                    | Notes                                             |
+| ----------- | ----------------------- | ------------------------------------------------- |
+| `severity`  | `'warning' \| 'error'`  |                                                   |
+| `code`      | `ToolkitDiagnosticCode` | a namespaced string from `DIAGNOSTICS`            |
+| `message`   | `string`                |                                                   |
+| `component` | `string \| undefined`   | the reporting component's name, when there is one |
+| `error`     | `unknown`               | **required** for `error`, absent for `warning`    |
+
+Every diagnostic starts on its relevant connected element, or on `document` when there is none, and is dispatched with `{ bubbles: true, composed: true, cancelable: true }`.
+
+## Listening
+
+```ts
+import { DIAGNOSTICS, EVENTS, type ToolkitDiagnosticDetail } from '@studiometa/js-toolkit';
+
+declare function monitor(code: string, detail: ToolkitDiagnosticDetail): void;
+document.addEventListener(EVENTS.diagnostic, (rawEvent) => {
+  const event = rawEvent as CustomEvent<ToolkitDiagnosticDetail>;
+  monitor(event.detail.code, event.detail);
+
+  if (event.detail.code === DIAGNOSTICS.responsive.unknownBreakpoint) {
+    event.preventDefault();
+  }
+});
+```
+
+**Dispatch always happens before the default output.**
+
+- An uncancelled **warning** calls `console.warn()` once with exactly `[js-toolkit:<code>] <message>`.
+- An uncancelled **error** calls `reportError(detail.error)` with the original value.
+- `preventDefault()` suppresses that output **only**. It changes no framework decision.
+
+## The codes
+
+`DIAGNOSTICS` is a deeply frozen object, and `ToolkitDiagnosticCode` is the exact union of its strings:
+
+```js
+import { DIAGNOSTICS } from '@studiometa/js-toolkit';
+
+DIAGNOSTICS.component.loadFailed; // 'component.load-failed'
+DIAGNOSTICS.callback.serviceFailed; // 'callback.service-failed'
+DIAGNOSTICS.protocol.lateRegistration; // 'protocol.late-registration'
+```
+
+See the [full list](../../api/diagnostics/DIAGNOSTICS.md).
+
+## Report once, or report and continue
+
+| Behaviour                 | Cases                                                                                                                                                     |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Reported exactly once** | recovered load, mount, invalid-strategy and `Base` lifecycle failures                                                                                     |
+| **Report and continue**   | isolated signal, context subscription and teardown, attribute watcher, service, scheduler tick and task, DOM-update runner and extendable-event callbacks |
+| **Thrown or rejected**    | decorator and manifest-adapter misuse, shared-runtime incompatibility, service startup rollback, caller-owned teardown, `viewTransition()` and `swap()`   |
+
+A scheduled task also **rejects its own promise** with the same value. Direct, caller-owned failures stay throws: they are the caller's to handle, not a channel's.
+
+Warning deduplication is stored in a revisioned shared-runtime slot, keyed by weak owner plus a misuse key, so it works across independently evaluated copies of the package without retaining instances, elements, declarations, runners or manifest inputs.
+
+## Reporting your own
+
+`warn()` and `reportDiagnostic()` are public, and a consumer code is any `'<namespace>.<name>'` string:
+
+```ts
+import { reportDiagnostic, warn } from '@studiometa/js-toolkit';
+
+warn('carousel.no-slides', 'A Carousel with no slide does nothing.', { component: 'Carousel' });
+
+try {
+  JSON.parse('{');
+} catch (error) {
+  reportDiagnostic('carousel.bad-config', 'The config attribute is not valid JSON.', error);
+}
+```
+
+From inside a component, `$warn()` and `$error()` fill the component name in for you:
+
+```js
+this.$warn('carousel.no-slides', 'A Carousel with no slide does nothing.');
+```
+
+## What was removed
+
+`EVENTS.error`, `ToolkitErrorDetail` and `ToolkitErrorStage` are removed with **no alias**. `DIAGNOSTICS`, `ToolkitDiagnosticSeverity`, `ToolkitDiagnosticCode` and `ToolkitDiagnosticDetail` replace them.
+
+## In tests
+
+Asserting on `console.warn` cannot see the code, the severity or the reporting component, and it passes for the wrong diagnostic. [`captureDiagnostics()`](../../api/test/index.md) reads the channel instead — and cancelling each event as it arrives is the same act that silences the console, so collecting and silencing are one step:
+
+```js
+import { captureDiagnostics } from '@studiometa/js-toolkit/test';
+
+const diagnostics = captureDiagnostics();
+// … exercise the component
+expect(diagnostics.codes).toContain('ref.mismatch');
+diagnostics.stop();
+```

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);
+```