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

package/skills/studiometa-js-toolkit/references/api/diagnostics/DIAGNOSTICS.md

@@ -0,0 +1,137 @@
+# DIAGNOSTICS
+
+A deeply frozen object of every code the framework reports. `ToolkitDiagnosticCode` is the exact union of its strings, plus any `'<namespace>.<name>'` a consumer reports.
+
+```js
+import { DIAGNOSTICS } from '@studiometa/js-toolkit';
+
+DIAGNOSTICS.component.loadFailed; // 'component.load-failed'
+DIAGNOSTICS.responsive.unknownBreakpoint; // 'responsive.unknown-breakpoint'
+```
+
+## `attribute`
+
+| Key                | Code                          | Reported when                                                               |
+| ------------------ | ----------------------------- | --------------------------------------------------------------------------- |
+| `unknownQualifier` | `attribute.unknown-qualifier` | a watched namespace with a finite vocabulary gets an unknown qualifier head |
+
+## `callback`
+
+Every one of these is **reported and continued**: the failing callback is skipped, the others run.
+
+| Key                              | Code                                         |
+| -------------------------------- | -------------------------------------------- |
+| `signalFailed`                   | `callback.signal-failed`                     |
+| `contextSubscriptionFailed`      | `callback.context-subscription-failed`       |
+| `contextTeardownFailed`          | `callback.context-teardown-failed`           |
+| `attributeWatcherFailed`         | `callback.attribute-watcher-failed`          |
+| `serviceFailed`                  | `callback.service-failed`                    |
+| `schedulerTickFailed`            | `callback.scheduler-tick-failed`             |
+| `scheduledTaskFailed`            | `callback.scheduled-task-failed`             |
+| `domUpdateRunnerFailed`          | `callback.dom-update-runner-failed`          |
+| `extendableEventExtensionFailed` | `callback.extendable-event-extension-failed` |
+
+A scheduled task also **rejects its own promise** with the same value.
+
+## `component`
+
+| Key                        | Code                                   | Reported when                                                     |
+| -------------------------- | -------------------------------------- | ----------------------------------------------------------------- |
+| `loadFailed`               | `component.load-failed`                | a lazy import fails — once per name, never retried                |
+| `mountFailed`              | `component.mount-failed`               | a mount fails                                                     |
+| `lifecycleFailed`          | `component.lifecycle-failed`           | `mounted()` or `unmounted()` throws                               |
+| `invalidMountStrategy`     | `component.invalid-mount-strategy`     | a `data-mount` value is unusable — the component stays unmounted  |
+| `invalidFamilyDeclaration` | `component.invalid-family-declaration` | a `config.components` value is neither a `Base` class nor a thunk |
+| `configConflict`           | `component.config-conflict`            | `@component` and `static config` declare one key differently      |
+
+## `event`
+
+| Key                  | Code                         | Reported when                                  |
+| -------------------- | ---------------------------- | ---------------------------------------------- |
+| `invalidEmitPayload` | `event.invalid-emit-payload` | `$emit()` gets a payload that is not an object |
+
+The event still dispatches.
+
+## `manifest`
+
+| Key              | Code                       | Reported when                             |
+| ---------------- | -------------------------- | ----------------------------------------- |
+| `duplicateToken` | `manifest.duplicate-token` | a manifest declares a token already owned |
+
+## `option`
+
+| Key              | Code                     | Reported when                                              |
+| ---------------- | ------------------------ | ---------------------------------------------------------- |
+| `literalDefault` | `option.literal-default` | an `Array` or `Object` default is a literal, not a factory |
+
+The value is then used as declared and **shared** between instances.
+
+## `protocol`
+
+| Key                  | Code                            | Reported when                                                       |
+| -------------------- | ------------------------------- | ------------------------------------------------------------------- |
+| `lateRegistration`   | `protocol.late-registration`    | a negotiated-event listener calls `wrap`/`waitUntil` after dispatch |
+| `unappliedDomUpdate` | `protocol.unapplied-dom-update` | a claimed runner resolves without calling `apply`                   |
+
+In both cases the change still happens.
+
+## `ref`
+
+| Key        | Code           | Reported when                                                                        |
+| ---------- | -------------- | ------------------------------------------------------------------------------------ |
+| `mismatch` | `ref.mismatch` | `config.refs` and `data-ref` disagree on the `[]` suffix — once per instance and ref |
+
+## `registry`
+
+| Key                | Code                          | Reported when                                         |
+| ------------------ | ----------------------------- | ----------------------------------------------------- |
+| `conflict`         | `registry.conflict`           | a name is registered twice — the second is ignored    |
+| `lazyNameMismatch` | `registry.lazy-name-mismatch` | a loaded class's `config.name` differs from its token |
+
+## `responsive`
+
+| Key                 | Code                            | Reported when                                                               |
+| ------------------- | ------------------------------- | --------------------------------------------------------------------------- |
+| `unknownBreakpoint` | `responsive.unknown-breakpoint` | a `:<suffix>` names no configured breakpoint — including the v3 list syntax |
+
+## `scheduler`
+
+| Key                    | Code                               | Reported when                      |
+| ---------------------- | ---------------------------------- | ---------------------------------- |
+| `backgroundPostFailed` | `scheduler.background-post-failed` | a background turn cannot be posted |
+
+## `service`
+
+| Key             | Code                     | Reported when                                                                                        |
+| --------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `missingTarget` | `service.missing-target` | a caller-supplied mixin `target` resolver returns `undefined` or `null` — **no subscription starts** |
+
+## `storage`
+
+| Key                 | Code                         | Reported when                                    |
+| ------------------- | ---------------------------- | ------------------------------------------------ |
+| `accessFailed`      | `storage.access-failed`      | a provider's area is refused or full             |
+| `serializeFailed`   | `storage.serialize-failed`   | serialization throws — **nothing is written**    |
+| `deserializeFailed` | `storage.deserialize-failed` | deserialization throws — the default is returned |
+
+## `swap`
+
+| Key           | Code                | Reported when                                                         |
+| ------------- | ------------------- | --------------------------------------------------------------------- |
+| `selfIgnored` | `swap.self-ignored` | `self` is passed with `append`/`prepend`, or content holds no element |
+
+## Consumer codes
+
+`ToolkitDiagnosticCode` also accepts any `` `${string}.${string}` ``, so a consumer reports on the same channel with its own namespace:
+
+```ts
+import { warn } from '@studiometa/js-toolkit';
+
+warn('carousel.no-slides', 'A Carousel with no slide does nothing.', { component: 'Carousel' });
+```
+
+## Import it on its own
+
+```js
+import { DIAGNOSTICS } from '@studiometa/js-toolkit/DIAGNOSTICS';
+```

package/skills/studiometa-js-toolkit/references/api/diagnostics/EVENTS.md

@@ -0,0 +1,45 @@
+# EVENTS
+
+A deeply frozen object of the events the framework itself dispatches, all namespaced `js-toolkit:`.
+
+```js
+import { EVENTS } from '@studiometa/js-toolkit';
+
+EVENTS.component.mounted; // 'js-toolkit:component:mounted'
+EVENTS.component.unmounted; // 'js-toolkit:component:unmounted'
+EVENTS.dom.update; // 'js-toolkit:dom:update'
+EVENTS.diagnostic; // 'js-toolkit:diagnostic'
+```
+
+## The events
+
+| Constant                     | Name                             | Dispatched from           | Cancelable |
+| ---------------------------- | -------------------------------- | ------------------------- | ---------- |
+| `EVENTS.component.mounted`   | `js-toolkit:component:mounted`   | the element, **bubbling** | no         |
+| `EVENTS.component.unmounted` | `js-toolkit:component:unmounted` | `document`                | no         |
+| `EVENTS.dom.update`          | `js-toolkit:dom:update`          | the given node, bubbling  | no         |
+| `EVENTS.diagnostic`          | `js-toolkit:diagnostic`          | the element or `document` | **yes**    |
+
+See [Instance events](../instance-events.md) for the lifecycle pair, [`domUpdate()`](../dom/domUpdate.md) for the update event, and [Diagnostics](index.md) for the diagnostic.
+
+## The convention
+
+- **Public framework events** use this object and the `js-toolkit:` namespace.
+- **Private framework transports** use module-local namespaced constants and **do not join `EVENTS`** — the context request is one.
+- **Component events** are typed lower-kebab string literals declared through the props type's `$emits` key. They have no namespace: a component event is `open`, not `js-toolkit:open`.
+- A payload is **one object** in `CustomEvent.detail`, or the platform value `null`.
+- Diagnostic events are cancelable, so monitoring can suppress the default output only.
+
+Only what a consumer can usefully listen to is exported. That is the whole rule for whether something belongs here.
+
+## Import it on its own
+
+```js
+import { EVENTS } from '@studiometa/js-toolkit/EVENTS';
+```
+
+The generated subpath keeps the frozen object importable without the root barrel — which matters on a page with no build step, where a barrel import downloads the barrel's whole graph.
+
+## `EVENTS.error` is removed
+
+With **no alias**. `EVENTS.error`, `ToolkitErrorDetail` and `ToolkitErrorStage` are gone; `EVENTS.diagnostic` and the [`DIAGNOSTICS`](DIAGNOSTICS.md) codes replace them.

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

@@ -0,0 +1,58 @@
+# Diagnostics
+
+Everything the framework recovers from is reported on **one** cancelable event, and nothing in core calls `console.warn()` or `console.error()` directly.
+
+## The exports
+
+- [`EVENTS`](EVENTS.md) — the framework event names
+- [`DIAGNOSTICS`](DIAGNOSTICS.md) — every code
+- [`reportDiagnostic(code, message, error, ctx?)`](reportDiagnostic.md) — report an error
+- [`warn(code, message, ctx?)`](warn.md) — report a warning
+
+From inside a component, `$warn()` and `$error()` fill the component name in.
+
+## The detail
+
+```ts
+type ToolkitDiagnosticDetail =
+  | {
+      readonly severity: 'warning';
+      readonly code: ToolkitDiagnosticCode;
+      readonly message: string;
+      readonly component?: string;
+      readonly error?: never;
+    }
+  | {
+      readonly severity: 'error';
+      readonly code: ToolkitDiagnosticCode;
+      readonly message: string;
+      readonly component?: string;
+      readonly error: unknown;
+    };
+```
+
+An **error** detail requires the original caught value; a **warning** carries none. That is a union, not an optional field, so a listener that reads `detail.error` has already narrowed on `severity`.
+
+## 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();
+  }
+});
+```
+
+Every diagnostic starts on its relevant connected element, or on `document` when there is none, with `{ bubbles: true, composed: true, cancelable: true }`.
+
+**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** and changes no framework decision.
+
+## Read next
+
+[Diagnostics](../../guide/going-further/handling-diagnostics.md).

package/skills/studiometa-js-toolkit/references/api/diagnostics/reportDiagnostic.md

@@ -0,0 +1,67 @@
+# reportDiagnostic
+
+```ts
+reportDiagnostic(
+  code: ToolkitDiagnosticCode,
+  message: string,
+  error: unknown,
+  context?: { component?: string; target?: Element },
+): CustomEvent<ToolkitDiagnosticDetail>
+```
+
+Reports an **error** on the diagnostic channel. The original caught value is required.
+
+## Usage
+
+```ts
+import { reportDiagnostic } from '@studiometa/js-toolkit';
+
+try {
+  JSON.parse('{');
+} catch (error) {
+  reportDiagnostic('carousel.bad-config', 'The config attribute is not valid JSON.', error, {
+    component: 'Carousel',
+  });
+}
+```
+
+**Parameters**
+
+- `code` — a namespaced string. Core codes come from [`DIAGNOSTICS`](DIAGNOSTICS.md); a consumer uses its own `'<namespace>.<name>'`.
+- `message` — one sentence, and it should say what to do about it.
+- `error` — **required.** The original value, passed through untouched.
+- `context.component` — the reporting component's name.
+- `context.target` — the element to dispatch from. Defaults to `document`.
+
+**Return value**
+
+- the dispatched event, so a caller can read `defaultPrevented`.
+
+## What happens
+
+1. The event is dispatched — **always before any output** — with `{ bubbles: true, composed: true, cancelable: true }`.
+2. If nothing cancelled it, `reportError(detail.error)` is called with the original value.
+
+`preventDefault()` suppresses that call and nothing else.
+
+## From a component
+
+`$error(code, message, error)` is the same call with the component name filled in:
+
+```js
+this.$error('carousel.bad-config', 'The config attribute is not valid JSON.', error);
+```
+
+## When to report and when to throw
+
+| The failure is               | Do                  |
+| ---------------------------- | ------------------- |
+| something you recovered from | report it           |
+| the caller's to handle       | **throw or reject** |
+
+Core follows the same rule: decorator and manifest-adapter misuse, shared-runtime incompatibility, service startup rollback, caller-owned teardown, `viewTransition()` and `swap()` all throw. A channel is for what was survived.
+
+## See also
+
+- [`warn()`](warn.md) — a warning, with no error value
+- [`captureDiagnostics()`](../test/index.md) — reading the channel in a test

package/skills/studiometa-js-toolkit/references/api/diagnostics/warn.md

@@ -0,0 +1,54 @@
+# warn
+
+```ts
+warn(
+  code: ToolkitDiagnosticCode,
+  message: string,
+  context?: { component?: string; target?: Element },
+): CustomEvent<ToolkitDiagnosticDetail>
+```
+
+Reports a **warning** on the diagnostic channel. A warning carries no error value — that is the difference from [`reportDiagnostic()`](reportDiagnostic.md), and it is a union in the type rather than an optional field.
+
+## Usage
+
+```ts
+import { warn } from '@studiometa/js-toolkit';
+
+warn('carousel.no-slides', 'A Carousel with no slide does nothing. Add `data-component="Slide"`.', {
+  component: 'Carousel',
+});
+```
+
+**Return value**
+
+- the dispatched event, so a caller can read `defaultPrevented`.
+
+## What happens
+
+1. The event is dispatched — **always before any output**.
+2. If nothing cancelled it, `console.warn()` is called **once**, with exactly `[js-toolkit:<code>] <message>`:
+
+```
+[js-toolkit:option.literal-default] Panel: the `tween` option default must be a factory function.
+```
+
+That exact format is what makes the console output greppable and what lets a listener reproduce it.
+
+## From a component
+
+`$warn(code, message)` fills the component name in:
+
+```js
+this.$warn('carousel.no-slides', 'A Carousel with no slide does nothing.');
+```
+
+## Deduplication
+
+Core's own warnings are deduplicated by weak owner plus a misuse key, in a revisioned shared-runtime slot — so a misuse is reported once per instance, per element or per declaration, and it works across independently evaluated copies of the package **without retaining** instances, elements, declarations, runners or manifest inputs.
+
+The public `warn()` does not deduplicate. Call it where the condition is detected once.
+
+## Write a message that says what to do
+
+The framework's own messages name the component, the thing that is wrong and the correction — `option.literal-default` names the option and the factory form to write instead. A warning a reader cannot act on is noise on a channel meant for monitoring.

package/skills/studiometa-js-toolkit/references/api/dom/breakpoints.md

@@ -0,0 +1,81 @@
+# Breakpoints
+
+```ts
+BREAKPOINTS: Readonly<Record<string, string>>
+getBreakpoints(): Record<string, string>
+setBreakpoints(next: Record<string, string>): void
+```
+
+The named breakpoint set is the single source of truth for every responsive spelling in the framework.
+
+## The defaults
+
+```js
+import { BREAKPOINTS, getBreakpoints } from '@studiometa/js-toolkit';
+
+getBreakpoints(); // the current set
+BREAKPOINTS; // the defaults
+```
+
+| Name   | Min width |
+| ------ | --------- |
+| `xxs`  | `0rem`    |
+| `xs`   | `30rem`   |
+| `s`    | `48rem`   |
+| `m`    | `64rem`   |
+| `l`    | `80rem`   |
+| `xl`   | `90rem`   |
+| `xxl`  | `120rem`  |
+| `xxxl` | `160rem`  |
+
+These are the names every `data-component:<name>` and `data-option-<x>:<name>` suffix is checked against.
+
+## Replacing them
+
+```js
+import { setBreakpoints } from '@studiometa/js-toolkit';
+
+setBreakpoints({
+  xs: '0rem',
+  s: '48rem',
+  m: '64rem',
+  l: '80rem',
+  xl: '96rem',
+});
+```
+
+`setBreakpoints()` is the single source of breakpoint truth, and calling it does three things at once:
+
+1. **rebuilds the scoped attribute names** — every `data-component:<name>` and every `data-option-<x>:<name>` spelling;
+2. **replaces that slice of the observer's `attributeFilter`**, draining the records of the previous filter first;
+3. **emits at once** on [`useBreakpoint()`](../services/useBreakpoint.md), so a subscriber sees the new active name immediately.
+
+## The values are in `rem`
+
+And in a media query, `rem` resolves against the **initial** font size, not against the root element. That is deliberate: a breakpoint that moved when a component changed the root font size would not be a breakpoint.
+
+## What uses them
+
+| Feature                                                                        | How                                            |
+| ------------------------------------------------------------------------------ | ---------------------------------------------- |
+| [responsive options](../html/data-option.md#every-option-is-responsive)    | `data-option-x:<name>`, cascading upwards      |
+| [responsive components](../html/data-component.md#responsive-declarations) | `data-component:<name>`, replacing not merging |
+| [`useBreakpoint()`](../services/useBreakpoint.md)                          | the active name, as a service                  |
+
+**A suffix that names no configured breakpoint** gives one `responsive.unknown-breakpoint` warning and is ignored — including the v3 list syntax `:xxs:xs:s`.
+
+## What it costs
+
+- The `MediaQueryList` objects are built **once**.
+- The active name is **memoised for the length of one task**, through `utils/memo`. `setBreakpoints()` and the `change` handler of a running service clear that memo at once.
+- A `matchMedia` subscription opens only for a component that declares [`option<Name>Changed()`](../methods-hooks-options.md); connected elements with a scoped `data-component` share **one** reference-counted subscription. A page with plain declarations and read-only options opens **none**.
+
+The breakpoint service is part of the core graph on every page. What a page pays is the subscriptions it asks for.
+
+**The defaults and Tailwind**
+
+The current default breakpoints are **not** aligned with `@studiometa/tailwind-config`. That alignment is a separate product decision. Call `setBreakpoints()` to match your own scale.
+
+## There is no `defineFeatures()`
+
+Breakpoints are the one configurable feature, and `setBreakpoints()` is it. Attribute names and the attribute prefix are not configurable.

package/skills/studiometa-js-toolkit/references/api/dom/domUpdate.md

@@ -0,0 +1,70 @@
+# domUpdate
+
+```ts
+domUpdate(target: Node, mutate: () => void | Promise<void>, detail?: Record<string, unknown>): Promise<void>
+```
+
+Announces a DOM mutation before it happens, so anything above the node can **take it over**.
+
+This is the _take-over_ mode of the negotiated-event mechanism. The _delay_ mode is [`emitExtendable()`](emitExtendable.md).
+
+## Usage
+
+The code that mutates announces instead of mutating:
+
+```js
+import { domUpdate } from '@studiometa/js-toolkit';
+
+await domUpdate(this.$el, () => this.$el.replaceChildren(fragment));
+```
+
+An ancestor claims it:
+
+```js
+import { EVENTS, viewTransition } from '@studiometa/js-toolkit';
+
+this.$on(EVENTS.dom.update, ({ detail }) => detail.wrap(viewTransition));
+```
+
+## The detail
+
+```ts
+interface DomUpdateDetail {
+  wrap(runner: DomUpdateRunner): void;
+}
+
+type DomUpdateRunner =
+  | ((apply: () => void | Promise<void>) => void | Promise<unknown>)
+  | { update(mutate: () => void | Promise<void>): void | Promise<unknown> };
+```
+
+The event is `EVENTS.dom.update` — `'js-toolkit:dom:update'` — dispatched on `target` as a bubbling, **non-cancelable** `CustomEvent`.
+
+**The detail is one object**, like every other v4 event. A decorated handler reads `{ payload: { wrap } }` for what a raw listener reads as `event.detail`.
+
+## What a claim composes with
+
+| 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)` — which `MotionView` already is     |
+
+**Neither runner is the default.** The ancestor chooses the lane, because it knows whether the region animates.
+
+## The rules
+
+- **`defaultPrevented` is ignored.** The step is announced, not proposed.
+- **The last claim wins.** Take-over mode keeps one runner.
+- **A registration is valid only while the event dispatches.** A listener that keeps `wrap` and calls it later is reported as `protocol.late-registration` and ignored.
+- **The work of the emitter always completes.** A runner that throws, rejects, or resolves without calling `apply` loses the animation, never the change — and that last case is reported as `protocol.unapplied-dom-update`.
+- **An unclaimed `domUpdate()` is synchronous.** With no listener, the mutation runs before the returned promise exists.
+- A failing runner is reported as `callback.dom-update-runner-failed`.
+
+## It has no `Base` path
+
+The helper dispatches its own event and is absent from `$emits`, so the negotiation code and the optional view-transition import stay out of the `Base` module graph. **Plain DOM code uses the same function with no instance.**
+
+## With `swap()`
+
+`domUpdate()` produces exactly the `wrap` that [`swap()`](swap.md) takes, and nothing else. Resilience policy stays here.

package/skills/studiometa-js-toolkit/references/api/dom/emitExtendable.md

@@ -0,0 +1,68 @@
+# emitExtendable
+
+```ts
+emitExtendable(target: Node, event: string, detail?: Record<string, unknown>): Promise<void>
+```
+
+Announces a step before it happens, so anything above the node can **delay** it.
+
+This is the _delay_ mode of the negotiated-event mechanism. The _take-over_ mode is [`domUpdate()`](domUpdate.md).
+
+## Usage
+
+The choreography announces its step and waits:
+
+```js
+import { emitExtendable } from '@studiometa/js-toolkit';
+
+async close() {
+  await emitExtendable(this.$el, 'close');
+  this.$el.close();
+}
+```
+
+An ancestor asks for more time:
+
+```js
+this.$on('close', ({ detail }) => detail.waitUntil(this.leave()));
+```
+
+## The detail
+
+```ts
+interface ExtendableDetail {
+  waitUntil(extension: Extension): void;
+}
+
+type Extension = PromiseLike<unknown> | (() => unknown) | Record<string, unknown>;
+```
+
+`waitUntil()` accepts three shapes:
+
+| Shape                     | Example                         |
+| ------------------------- | ------------------------------- |
+| a thenable                | `waitUntil(this.leave())`       |
+| a function                | `waitUntil(() => this.enter())` |
+| an object with the method | `waitUntil(transitioner)`       |
+
+**The duck-typed method has the name of the event**: `close()` for the `close` step of a dialog, `update(mutate)` for a DOM change. The function form covers any pair of method names.
+
+The event is dispatched on `target` as a bubbling, **non-cancelable** `CustomEvent`.
+
+## The rules
+
+- **`defaultPrevented` is ignored.** The step is announced, not proposed.
+- **Every registration is kept and all are awaited**, because two components that animate out must both be awaited. This is where it differs from `domUpdate()`, which keeps one.
+- **A registration is valid only while the event dispatches.** A listener that keeps `waitUntil` and calls it later is reported as `protocol.late-registration` and ignored.
+- **The step happens anyway.** An extension that rejects is swallowed, and reported as `callback.extendable-event-extension-failed`.
+
+## It has no `Base` path
+
+The helper dispatches its own event and is absent from `$emits`. Plain DOM code uses the same function with no instance.
+
+## Which mode to reach for
+
+| You are announcing                                    | Use                               |
+| ----------------------------------------------------- | --------------------------------- |
+| an **action** someone may want to perform differently | [`domUpdate()`](domUpdate.md) |
+| a **moment** someone may want to postpone             | `emitExtendable()`                |

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

@@ -0,0 +1,26 @@
+# DOM
+
+The functions that change the document, negotiate a change, or watch an attribute the framework does not read.
+
+## Changing content
+
+- [`swap(target, content, options?)`](swap.md) — replace, prepend, append or morph, and wait for the framework to catch up
+- [`whenDOMSettled()`](whenDOMSettled.md) — the completion boundary
+
+## Negotiating a change
+
+- [`domUpdate(target, mutate, detail?)`](domUpdate.md) — announce a mutation so an ancestor can take it over
+- [`emitExtendable(target, event, detail?)`](emitExtendable.md) — announce a step so an ancestor can delay it
+
+## Watching attributes
+
+- [`watchAttributes(el, callback)`](watchAttributes.md) — every attribute of one element
+- [`watchAttributeNamespace(el, ns, bind, options?)`](watchAttributeNamespace.md) — a namespace whose names cannot be enumerated
+
+## Breakpoints
+
+- [`BREAKPOINTS`, `getBreakpoints()`, `setBreakpoints()`](breakpoints.md)
+
+## Read next
+
+[The mutation engine](../../guide/concepts/mutation-engine.md) and [The attribute grammar](../../guide/concepts/attribute-grammar.md).