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

package/README.md

@@ -54,6 +54,16 @@ There is no build step to adopt: the same class runs from a `<script type="modul
 
 The design record lives in the repository: [DESIGN.md](./DESIGN.md) states what v4 does, and [RATIONALE.md](./RATIONALE.md) states why, which options were refused, and what the measurements are.
 
+## Agent skills
+
+The package ships the `studiometa-js-toolkit` [agent skill](https://agentskills.io). The skill teaches coding agents how to use the package, and it matches the installed version. Link the skills of your dependencies into your project with the [`skills` CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills experimental_sync
+```
+
+The command links each skill from `node_modules` into the agent folders (`.agents/skills/`, `.claude/skills/`…). When you update the package, the linked skill updates too.
+
 ## Contributing
 
 See the [repository README](https://github.com/studiometa/js-toolkit#contributing). Fixes for the 3.x line go to the [`3.x` branch](https://github.com/studiometa/js-toolkit/tree/3.x).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit",
-  "version": "4.0.0-alpha.1",
+  "version": "4.0.0-alpha.2",
   "type": "module",
   "sideEffects": [
     "./dist/responsive-options.js"
@@ -21,6 +21,7 @@
   "homepage": "https://js-toolkit-v4.studiometa.dev",
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -812,7 +813,8 @@
     }
   },
   "scripts": {
-    "build": "node scripts/build.js",
+    "build": "node scripts/build.js && npm run build:skills",
+    "build:skills": "node ../../scripts/build-skills.js",
     "check:constant-subpaths": "node scripts/check-constant-subpaths.js",
     "check:diagnostics": "node scripts/check-diagnostics.js",
     "check:doc-links": "node scripts/check-doc-links.js",
@@ -822,6 +824,7 @@
     "demo:preview": "vite preview demo --host",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
+    "postdocs:build": "node ../../scripts/build-skills.js --well-known docs/.vitepress/dist",
     "docs:preview": "vitepress preview docs",
     "test": "npm run check:diagnostics && npm run check:doc-links && npm run test:fixtures && vitest run",
     "test:fixtures": "node scripts/build-runtime-fixtures.js",

package/skills/studiometa-js-toolkit/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: studiometa-js-toolkit
+description: Write components with @studiometa/js-toolkit v4 — classes that extend Base, registered with registerComponent and bound to the DOM through data-component, data-ref, data-option-* and data-mount attributes. Use when code imports @studiometa/js-toolkit, extends Base, uses $refs, $options, $emit, $query, $closest, on<Ref><Event> hooks, services (useScroll, useResize, useRaf, withScroll…), mount strategies, provide/inject, the scheduler or @studiometa/js-toolkit/utils, or when you migrate code from js-toolkit v3.
+---
+
+# @studiometa/js-toolkit
+
+`@studiometa/js-toolkit` binds JavaScript classes to server-rendered HTML. A component is a class that extends `Base`, a name in the registry, and a `data-component` attribute in the markup.
+
+This skill matches the installed package version. v4 is a full breaking major: most examples on the web and in training data are v3 code that does not work in v4. Read the references in this folder before the online docs.
+
+## References
+
+- `references/guide/introduction/`: components, refs, options, events, lifecycle, services. Start here.
+- `references/guide/going-further/`: autoloading, mount strategies, scheduling, shared state, swapping content, testing, TypeScript, decorators, storage, diagnostics.
+- `references/guide/migration/v3-to-v4.md`: every v3 API that changed, with its replacement. Read it before you change existing code.
+- `references/api/`: the exact API of `Base`, the registry, services, context, DOM helpers, scheduler, storage and diagnostics.
+- `references/utils/`: the utilities of `@studiometa/js-toolkit/utils`, by category.
+
+## A component
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class Counter extends Base {
+  static config = {
+    name: 'Counter',
+    refs: ['output'],
+    options: { step: { type: Number, default: 1 } },
+  };
+
+  count = 0;
+
+  onClick() {
+    this.count += this.$options.step;
+    this.$refs.output.textContent = String(this.count);
+  }
+}
+
+registerComponent(Counter);
+```
+
+```html
+<button data-component="Counter" data-option-step="5">
+  Clicked
+  <span data-ref="output">0</span>
+  times
+</button>
+```
+
+## v4 rules
+
+These are the v3 habits that break in v4:
+
+| Do not write (v3)                                   | Write (v4)                                                                                       |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `createApp(App)`                                    | `registerComponents(A, B, C)`: no root component                                                 |
+| `this.$children.Item`, `this.$parent`, `this.$root` | `this.$query('Item')`, `this.$watchChildren('Item')`, `this.$closest('Name')` (can be `null`)    |
+| `this.$update()`                                    | nothing: `$refs` reads the DOM on each access                                                    |
+| `data-ref="items"` for a list                       | `data-ref="items[]"`, same as `refs: ['items[]']`; read it as `this.$refs.items`                 |
+| `this.$options.open = true`                         | `$options` is read-only: change the `data-option-*` attribute                                    |
+| `data-option-open="false"`                          | remove the attribute, or `data-option-no-open` when the default is `true`                        |
+| `default: {}` or `default: []`                      | a factory: `default: () => ({})`                                                                 |
+| `this.$emit('go', 1, 'left')`                       | one payload object: `this.$emit('go', { index: 1, direction: 'left' })`                          |
+| `onItemClick(event, index)`                         | one object: `onItemsClick({ event, target, index })`, `onChildEvent({ event, target, payload })` |
+| `updated()`                                         | `option<Name>Changed()` or `watchAttributes()`                                                   |
+| `unmounted()` only to unsubscribe                   | return the cleanup from `mounted()`                                                              |
+| `data-load`, `withMountWhenInView`, `importWhen*`   | `data-mount="visible"` or a `registerManifest()` entry with `mountStrategy`                      |
+| `withExtraConfig()`                                 | a subclass with its own `static config`                                                          |
+| `withResponsiveOptions`, `data-option-x:s:m`        | every option is responsive: `data-option-x:s` cascades up                                        |
+| `domScheduler`, `afterWrite`                        | `this.$read()` / `this.$write()`, or `defaultScheduler`                                          |
+| `tween`, `animate`                                  | not in core: use `transition()`, `spring()`, `smoothTo()` or `@studiometa/ui-motion`             |
+
+## Practices
+
+- Let the registry construct instances. Never call `new MyComponent(el)`.
+- Declare `refs` and use `on<Ref><Event>` hooks instead of `querySelector` and `addEventListener`. Use `onWindow<Event>` and `onDocument<Event>` for global events.
+- Use a service before a custom listener or observer: the mixins `withScroll` (`scrolled`), `withResize` (`resized`), `withRaf` (`ticked`), `withPointer` (`moved`), `withDrag` (`dragged`), `withKey` (`keyed`), `withInView` (`intersected`), `withMutation` (`mutated`), `withScrollProgress` (`scrolledInView`), or the `use*()` functions.
+- Use mount strategies (`eager`, `visible`, `in-view`, `idle`, `interaction`, `media:<query>`) to defer work, not custom observers.
+- Share state with `provideRootContext()`, `$provide()` and `$inject()`, not with global variables.
+- Import utilities from `@studiometa/js-toolkit/utils` (for example `import { clamp, damp } from '@studiometa/js-toolkit/utils'`). Read `references/utils/` before you write a helper.
+- Diagnostics (`EVENTS.diagnostic`) explain wrong refs, options and payloads. Read the warning code in `references/api/diagnostics/DIAGNOSTICS.md`.
+
+## Related skills
+
+- `studiometa-ui`: ready-made components (Action, Dialog, Disclosure, Tabs, Carousel, Fetch, Transition, Data*…). Look for a component there before you write a custom one.
+- `studiometa-eslint-plugin-js-toolkit`: the lint rules for js-toolkit code.

package/skills/studiometa-js-toolkit/references/api/configuration.md

@@ -0,0 +1,169 @@
+# Configuration
+
+`static config` declares everything the framework needs to know about a component before an instance exists.
+
+```ts
+interface BaseConfig {
+  name: string;
+  components?: Record<string, BaseConstructor | ComponentImporter>;
+  refs?: string[];
+  options?: Record<string, OptionDefinition>;
+  mountStrategy?: MountStrategy;
+}
+```
+
+## `config.name`
+
+**Required.** The name the registry registers under, the token `data-component` writes, and the prefix of every instance's [`$id`](instance-properties.md#id).
+
+The name comes from the **merged** config, so a subclass that extends a component and forgets to rename registers under the name it inherited — and collides — rather than under `undefined`.
+
+## `config.refs`
+
+The refs the component declares. A list ref keeps its `[]`:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Tabs extends Base {
+  static config = {
+    name: 'Tabs',
+    refs: ['list', 'tabs[]', 'panels[]'],
+  };
+}
+```
+
+See [Refs](../guide/introduction/managing-refs.md) and [`data-ref`](html/data-ref.md).
+
+## `config.options`
+
+Each entry is a type, a tuple of types, or an object with `type` and `default`:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Slider extends Base {
+  static config = {
+    name: 'Slider',
+    options: {
+      label: String, // short form
+      speed: { type: Number, default: 1 }, // primitive default
+      loop: { type: Boolean, default: true },
+      tween: { type: Object, default: () => ({}) }, // factory required
+      offset: [Number, Array], // a union, in order
+    },
+  };
+}
+```
+
+The five option types are `String`, `Number`, `Boolean`, `Array` and `Object`. `Function` is not one, which is what makes a function `default` unambiguously a factory.
+
+See [Options](../guide/introduction/managing-options.md) and [`data-option-<name>`](html/data-option.md).
+
+## `config.components`
+
+The declared **family**. It does two jobs, and neither is ownership:
+
+1. it registers those names when this component registers, so one `registerComponent()` call covers a whole tree;
+2. it gives the name set that `on<Child><Event>` resolution needs.
+
+```js
+static config = {
+  name: 'Accordion',
+  components: {
+    AccordionItem, // a class
+    Icon: () => import('./Icon.js'), // a thunk — its own chunk
+  },
+};
+```
+
+- **The key supplies the name**, so a lazy child is a name the registry knows with nothing downloaded.
+- A thunk is deferred rather than resolved, and becomes a lazy entry of the same registry.
+- **First wins, quietly.** Several parents declaring the same lazy child is the normal case.
+- A value written with `class` that does not extend `Base` is reported as `component.invalid-family-declaration`, where it is declared.
+
+See [Autoloading](../guide/going-further/autoloading.md).
+
+## `config.mountStrategy`
+
+The component's default answer to _when_. Any element overrides it with `data-mount`:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Map extends Base {
+  static config = {
+    name: 'Map',
+    mountStrategy: 'visible',
+  };
+}
+```
+
+See [Mount strategies](../guide/going-further/mount-strategies.md) and [`data-mount`](html/data-mount.md).
+
+## Merging along the prototype chain
+
+`$config` walks the prototype chain and merges every config it finds:
+
+| Key             | Merge rule                  |
+| --------------- | --------------------------- |
+| `refs`          | union                       |
+| `options`       | entry by entry              |
+| `components`    | entry by entry              |
+| `name`          | the most derived class wins |
+| `mountStrategy` | the most derived class wins |
+
+A subclass that states a `components` key again wins for **that key only**.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class AbstractControl extends Base {
+  static config = {
+    name: 'AbstractControl',
+    refs: ['button'],
+    options: { label: String },
+  };
+}
+
+class NavigationControl extends AbstractControl {
+  static config = {
+    name: 'NavigationControl',
+    refs: ['compass'], // merged: ['button', 'compass']
+    options: { showCompass: Boolean }, // merged with `label`
+  };
+}
+```
+
+An intermediate class should declare `static config: BaseConfig`, or let TypeScript infer a literal type every subclass matches.
+
+**The registry reads the merged config too**, before any instance exists, through `resolveConfig()`. That is how it knows the mount strategy of a pair, the family to register, and the name a class registers under.
+
+## There is no `withExtraConfig()`
+
+To extend a component with a different config, declare a class. To extend one you cannot edit, do it in expression position:
+
+```js
+registerComponent(
+  class extends Vendor {
+    static config = { name: 'CompactVendor', options: { compact: Boolean } };
+  },
+);
+```
+
+## `@component()`
+
+The decorator writes `static config` and calls `registerComponent()` in one step, and the two forms merge:
+
+```ts
+import { Base, component } from '@studiometa/js-toolkit';
+
+@component({ name: 'Slider', refs: ['next'] })
+class Slider extends Base {
+  static config = { name: 'Slider', options: { speed: Number } };
+}
+```
+
+They merge in a class initializer, which runs after the fields and inside the class definition, so `registerComponent()` reads the finished config. A key both sides declare differently is reported as `component.config-conflict`.
+
+See [`@component`](decorators/component.md).

package/skills/studiometa-js-toolkit/references/api/context/createContext.md

@@ -0,0 +1,46 @@
+# createContext
+
+```ts
+createContext<T = unknown>(description?: string): ContextKey<T>
+```
+
+Creates a typed injection key.
+
+## Usage
+
+```ts
+import { createContext, type Signal } from '@studiometa/js-toolkit';
+
+interface SliderApi {
+  state: Signal<{ index: number }>;
+  goNext(): void;
+}
+
+export const SliderContext = createContext<SliderApi>('slider');
+```
+
+**Parameters**
+
+- `description` (`string`, optional) — for debugging only.
+
+**Return value**
+
+- `ContextKey<T>` — an opaque value carrying the phantom type `T`.
+
+## Why a value and not a string
+
+**The identity of the key is what resolves.** Two keys with the same description are two different keys, so nothing collides — and the type parameter is what makes `$inject(key)` give a typed value with no cast at the call site.
+
+Declare the key beside the interface it carries, and export both:
+
+```ts
+// slider-context.ts
+export interface SliderApi { … }
+export const SliderContext = createContext<SliderApi>('slider');
+```
+
+Provider and consumer then import one module and agree by construction.
+
+## The default is `unknown`
+
+`createContext('name')` with no type parameter gives `ContextKey<unknown>`, so `$inject()` resolves with `unknown` and the consumer has to narrow. Give it the type.

package/skills/studiometa-js-toolkit/references/api/context/createGroup.md

@@ -0,0 +1,67 @@
+# createGroup
+
+```ts
+createGroup<T extends GroupMember = GroupMember>(): Group<T>
+```
+
+A membership set whose members list is a reactive value.
+
+```ts
+interface Group<T extends GroupMember = GroupMember> {
+  readonly members: Signal<readonly T[]>;
+  join(member: T): () => void;
+}
+```
+
+A `GroupMember` is anything with a `readonly $el: Element` — which every `Base` instance is.
+
+## Usage
+
+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
+  });
+
+  mounted() {
+    // The membership is a value: re-check the invariant on each change.
+    return this.#peers.members.subscribe((members) => this.enforce(members));
+  }
+
+  open(peer: Base) {}
+
+  enforce(members: readonly Base[]) {}
+}
+```
+
+A member joins the nearest group whenever that group appears — see [`subscribeContext()`](subscribeContext.md).
+
+## What it does, and what it does not
+
+- **`join()` returns its own `leave`**, so a member that moves to a nearer group leaves the old one first.
+- **The membership is a value.** A coordinator subscribes to it and re-checks its invariant on each change, rather than being called back on a mutation.
+- **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.
+- **It names no group and resolves no scope.** Scope comes from nearest-provider-wins, so a nested group takes its own members only.
+
+The helper holds a `Set` and a [`Signal`](signal.md), and nothing else. That is the whole implementation.
+
+## It replaces `withGroup`
+
+`withGroup` is not ported. A group is a provided value now, so its scope is the provider's subtree rather than a name in a global table — and a nested group is a nested provider, with nothing to configure.

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

@@ -0,0 +1,69 @@
+# Shared state
+
+provide/inject in core, with the shape of Vue and the mechanics of the WICG context protocol.
+
+## The functions
+
+| Function                                                       | Does                                          |
+| -------------------------------------------------------------- | --------------------------------------------- |
+| [`createContext(description?)`](createContext.md)          | a typed key                                   |
+| [`signal(initialValue)`](signal.md)                        | a reactive value                              |
+| [`provideContext(el, key, value)`](provideContext.md)      | provide on an element                         |
+| [`provideRootContext(key, create)`](provideRootContext.md) | provide page-wide, created at most once       |
+| [`injectContext(el, key)`](injectContext.md)               | a promise for the nearest value               |
+| [`injectContextSync(el, key)`](injectContextSync.md)       | the nearest value, or `undefined`             |
+| [`subscribeContext(el, key, cb)`](subscribeContext.md)     | every answer, as providers come and go        |
+| [`createGroup()`](createGroup.md)                          | a membership set with a reactive members list |
+
+From inside a component, `$provide()`, `$inject()` and `$injectSync()` are the same three, with the element filled in. The [`@provide`](../decorators/provide.md) and [`@inject`](../decorators/inject.md) decorators are field sugar over them.
+
+## The model
+
+- **The injection key is typed**, so strings cannot collide.
+- **The scope is the subtree**, and the nearest provider wins.
+- **The value is provided as it is.** Nothing is wrapped, so the type of the key is the contract from end to end. A reactive value is a provided `Signal`. A command surface is a provided object.
+
+```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: () => {}, // what a control can command
+  });
+}
+```
+
+## Two ways to ask
+
+| 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.   |
+
+The pending request of the async form is **unmount-scoped**. A new mount runs `mounted()` again and asks again. The `@inject` field decorator asks once, at construction; a consumer that can wait through several cycles calls `$inject()` from `mounted()`.
+
+## The mechanics
+
+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.
+
+Duplicate bundles share the basic provider and pending-request state through the `context` shared-runtime slot at schema revision 2. The optional owner map, weak index and listener flag use the `context-subscription` slot at revision 1 — and `context.ts` and the `Base` graph import none of that optional state.
+
+## Scopes
+
+`$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.
+
+A **root** provider cannot be disposed and it outlives the instance that asked first, because it is page state. `withGroup` is not ported.
+
+## Read next
+
+[Shared state](../../guide/going-further/sharing-state.md) walks the whole pattern, from a coordinator's provided API to a member joining the nearest group.

package/skills/studiometa-js-toolkit/references/api/context/injectContext.md

@@ -0,0 +1,58 @@
+# injectContext
+
+```ts
+injectContext<T>(el: Element, key: ContextKey<T>): { promise: Promise<T>; cancel: () => void }
+```
+
+Asks the nearest provider for a value, once.
+
+## Usage
+
+```ts
+import { createContext, injectContext } from '@studiometa/js-toolkit';
+
+const Key = createContext<number>('answer');
+const el = document.body;
+const { promise, cancel } = injectContext(el, Key);
+```
+
+**Return value**
+
+- `promise` — resolves with the nearest provided value.
+- `cancel` — withdraws the request.
+
+## It never settles when nothing provides
+
+**A missing provider means "not yet", not "no".** The request stays pending, and it resolves when a provider appears and replays it — which is what makes mount order irrelevant.
+
+If you need an answer now, or none, use [`injectContextSync()`](injectContextSync.md).
+
+## From a component
+
+`$inject()` is the same call with the element filled in, and it returns the promise directly:
+
+```ts
+import { Base, createContext, type Signal } from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+class Output extends Base {
+  static config = { name: 'Output' };
+
+  async mounted() {
+    const count = await this.$inject(CountContext);
+    return count.subscribe((value) => {
+      this.$el.textContent = String(value);
+    });
+  }
+}
+```
+
+**The pending request is unmount-scoped**
+
+`$unmount()` cancels it, and a new mount runs `mounted()` again and asks again. That is why `mounted()` is the right place: a component that outlives several cycles asks once per cycle, and never holds a request for a scope it has left.
+
+The [`@inject`](../decorators/inject.md) field decorator asks once, at construction, instead.
+
+## It is one-shot
+
+`injectContext()` and `$inject()` resolve with the **first** answer and stop. To follow providers as they come and go, use [`subscribeContext()`](subscribeContext.md).

package/skills/studiometa-js-toolkit/references/api/context/injectContextSync.md

@@ -0,0 +1,44 @@
+# injectContextSync
+
+```ts
+injectContextSync<T>(el: Element, key: ContextKey<T>): T | undefined
+```
+
+The nearest provided value, synchronously, or `undefined`.
+
+## Usage
+
+```ts
+import { createContext, injectContextSync } from '@studiometa/js-toolkit';
+
+const Key = createContext<number>('answer');
+const el = document.body;
+const value = injectContextSync(el, Key);
+
+if (value === undefined) {
+  // no provider — fall back, or do nothing
+}
+```
+
+## When to reach for it
+
+When the answer is **optional and the caller has a fallback**. `undefined` means "no provider right now", which is a different statement from `$inject()`'s "not yet".
+
+The canonical pair is a look-up-or-create:
+
+```ts
+import { createContext, injectContextSync, provideRootContext } from '@studiometa/js-toolkit';
+
+const DataChannels = createContext<Map<string, unknown>>('channels');
+const el = document.body;
+const channels =
+  injectContextSync(el, DataChannels) ?? provideRootContext(DataChannels, () => new Map());
+```
+
+## From a component
+
+`$injectSync(key)` is the same call with the element filled in.
+
+**It answers for right now**
+
+A provider that mounts later is not seen, because there is no request left pending. If mount order is not something you control, use [`injectContext()`](injectContext.md) or [`subscribeContext()`](subscribeContext.md).

package/skills/studiometa-js-toolkit/references/api/context/provideContext.md

@@ -0,0 +1,61 @@
+# provideContext
+
+```ts
+provideContext<T>(el: Element, key: ContextKey<T>, value: T): { value: T; dispose: () => void }
+```
+
+Provides a value to the subtree of `el`.
+
+## Usage
+
+```ts
+import { createContext, provideContext } from '@studiometa/js-toolkit';
+
+const Key = createContext<number>('answer');
+const el = document.body;
+const { value, dispose } = provideContext(el, Key, 42);
+```
+
+**Parameters**
+
+- `el` — the element that owns the scope.
+- `key` — a [`ContextKey`](createContext.md).
+- `value` — provided **as it is**. Nothing is wrapped.
+
+**Return value**
+
+- `value` — the value, so the call can be an expression.
+- `dispose` — stops answering for this key on this element.
+
+## From a component
+
+`$provide()` is the same call with the element filled in, and it returns the value directly so it reads as a field initializer:
+
+```ts
+import { Base, createContext, signal, type Signal } from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+class Counter extends Base {
+  static config = { name: 'Counter' };
+
+  count = this.$provide(CountContext, signal(0));
+}
+```
+
+**`$provide()` is instance-scoped**
+
+It is never released, and it dies with the instance or its element. A component whose declaration is withdrawn keeps providing until its element goes — which is why the call belongs in the constructor or a field initializer, not in `mounted()`.
+
+## Nearest wins
+
+The scope is the subtree, and a nearer provider shadows a further one by answering first and stopping propagation.
+
+## It replays pending requests
+
+A consumer that asked before any provider existed has a pending request with no first answer. `provideContext()` **replays those requests**, which is what makes mount order irrelevant: a child that mounts before its coordinator still gets its answer when the coordinator arrives.
+
+Only a **mounted** provider answers.
+
+## Page-wide
+
+For state that belongs to the page rather than to a subtree, use [`provideRootContext()`](provideRootContext.md).