] `; 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.html).
diff --git a/packages/v4/docs/api/diagnostics/reportDiagnostic.md b/packages/v4/docs/api/diagnostics/reportDiagnostic.md
new file mode 100644
index 000000000..b18edc429
--- /dev/null
+++ b/packages/v4/docs/api/diagnostics/reportDiagnostic.md
@@ -0,0 +1,68 @@
+# reportDiagnostic
+
+```ts
+reportDiagnostic(
+ code: ToolkitDiagnosticCode,
+ message: string,
+ error: unknown,
+ context?: { component?: string; target?: Element },
+): CustomEvent
+```
+
+Reports an **error** on the diagnostic channel. The original caught value is required.
+
+## Usage
+
+```ts twoslash
+// @twoslash-cache: {"v":1,"hash":"aaaf4942a2e7215127b30180e64831407c2571649449b97c19a0ef4b5220728a","data":"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"}
+import { reportDiagnostic } from '@studiometa/js-toolkit-v4';
+
+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.html); a consumer uses its own `'.'`.
+- `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.html) — a warning, with no error value
+- [`captureDiagnostics()`](/api/test/) — reading the channel in a test
diff --git a/packages/v4/docs/api/diagnostics/warn.md b/packages/v4/docs/api/diagnostics/warn.md
new file mode 100644
index 000000000..79aac4042
--- /dev/null
+++ b/packages/v4/docs/api/diagnostics/warn.md
@@ -0,0 +1,55 @@
+# warn
+
+```ts
+warn(
+ code: ToolkitDiagnosticCode,
+ message: string,
+ context?: { component?: string; target?: Element },
+): CustomEvent
+```
+
+Reports a **warning** on the diagnostic channel. A warning carries no error value — that is the difference from [`reportDiagnostic()`](./reportDiagnostic.html), and it is a union in the type rather than an optional field.
+
+## Usage
+
+```ts twoslash
+// @twoslash-cache: {"v":1,"hash":"84274af55f097b88f9c08b751191dc768138aa3dadafba9db16c558250aa973a","data":"N4Igdg9gJgpgziAXAbVAFwJ4AcZJACwgDcYAnEAGhDRgA808AKAQwBsBLZuASgAIAzAK5gAxmnYQwvAO7NSYRiOgxEvACoQIrANbs0AEU4BzSHHEiAwsoq8AtvDjMjK3mdLswRm8F5LbWSRgwNBs0OWc0XgBfAH5VQydTcytgujRuVQtBMwhbAFESYIAeDS1dA2Mk9hF9GDD2VgA+AB0wdn8IUkjZeUoQKAgRBEQQACUYAK7eZhk5Ns9eSV40fBheKEqIM2rffGYwMBhWADpW1oBBX1yAw+DeUgnOtDhl/FIIQSN8XlbgAAEOGBtD8wAAhLgwY4AEh6UlaUVaNmk+Gq334DVYLw8vD0Lwg0ikYGY9la+ygvCOMHswWO6hRWJeKzW/E6tgEnSusBkem+kBxYDM+xEazQEHujymXF4gBQCaatWzQQSsGAAWmVJFYvFWrBwpBsHJmIlYXBeyNROJekEiMwABuC4DAbcc+oKukgAJxUZWeFZIAAsVDCpAieFhfUBuEQAAYqCI9qRmGIyB6ohR0NhIwRiMnA2kmGxODxZvJFMpVKUdHoEiYtslrHYHE4XG4PF5eD4/DcgiFluE6tE4rxq1VLJIaPQMrwsjl8oU0CVNJWKola9VavUmq12pNunM+gMhnhxjvpsX5kZFlImetNtsRLt9ocTmcwJdO4E7g8d4y3h8viD/kBYFWntSEYTmEEETAJEUTjAQMSxKRcUWAleCJEkiTAclKWpNBaTUekLVeZlWXZUhOTWaQeTQsUPEFUQRTFL8nmmF5ZWYeVFWVNUYA1LUjl1fVyMNY04FNWDvnYS0IGtXg7QhJ0XSDBhEAAVgARi9IIjF9RAA2oPsVJAMMvQ8SMACZY3jRMaHIaNU3THA8EIEhyFzegmCwd5dUwPhh1XUdUnoY531uNBBxbBYAB9eGEWB0UOKAlLkFT1NU/TvR0/APUDQy8FC7twzMpAAGYrLkGzk0QcyogAXVjZQ8G3FifFhaIBHeNkAHI/jMQQNlyOpmAAegAKzgFVRTKPQVSIP0uoAbhfWFGC6kQ5A+B0TkgFU4A4WA4C6mwusuCwNuyI5uRWGjXH2tYBngGiVlbWlzigckbSgZgwhVArggAXmaEAAGU7qBp0jvbVpeCuDowtULqzveC7WCO+FuAWvp7DCJBQDSII4AkMA8GeEAoiiIA="}
+import { warn } from '@studiometa/js-toolkit-v4';
+
+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:] `:
+
+```
+[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.
diff --git a/packages/v4/docs/api/dom/breakpoints.md b/packages/v4/docs/api/dom/breakpoints.md
new file mode 100644
index 000000000..a35628260
--- /dev/null
+++ b/packages/v4/docs/api/dom/breakpoints.md
@@ -0,0 +1,85 @@
+# Breakpoints
+
+```ts
+BREAKPOINTS: Readonly>
+getBreakpoints(): Record
+setBreakpoints(next: Record): void
+```
+
+The named breakpoint set is the single source of truth for every responsive spelling in the framework.
+
+[[toc]]
+
+## The defaults
+
+```js twoslash
+// @twoslash-cache: {"v":1,"hash":"0ce7b9232ac76254edf98334e9b48f7142a30d2fae16e7bebb235881cb0cc822","data":"N4Igdg9gJgpgziAXAbVAFwJ4AcZJACwgDcYAnEAGhDRgA808AKAQwBsBLZuASgAIBjCGDhpeAIQBKAUQCCAaQAKAeQCSAOQAqAZUS8JMZlCGsMAHn2DSUUyNLswAcwq9b9hwD53AHTDsAtlgQpKKSsoqqmlqUIEb8CIggACIwAGbMAK6somDMfjBQvETsMADugcG8JexQaPhwzlz8MGBQbgB0vACy+ZwAtACO6WQYvAAGpDB+o7zpcPC8tTC8AEakECVzpADkcLz27GicrLwpQqJw7ABeMM6Qoou8axCiMKyTzWg7AhAB6TQFF2ubWiImYwSQAE4qG9HLUkABGeFUNBghwwBgJULyZTqbTRDhgXCIAAMVH4+DBzH4NHIiAhAF8KOhsESCMQyNEaPQmGxODwTukwNT2EJeGi0GIJswANaBexoOCMbi6CxBayuRzODUeHz+cqicWSgyyiDyhBUWLxED6NDpUhgXjMb5YEYQFILfBLKmHEgrKUm+UudHAqig8GIABMEehzQccMQ8IALMjUei8Ib/XKwAr8fYiaSQOTKdSOZGI4zmTg8IQSORkXQMSAWBwuHwM8aswqlSqYJZ1Wg7JqXAO3N5fAEggb0UaZZ3zTEIHE8Da7Q6nYIXbw3R6vcLfasO6bs0G0CGQGGMQB2ZMgGFx/AIm8o0ji9PTzNHnPQvNIaOFimkN6pbEhW1AstW7J1tQDY8i2/KCMIITSNiETaD2hjGGYqpWDYI5Dtqni6hOFRYuEuJRBai5WskaSZNkuT5IUxRlJOlTVLU9SOnATQtO0XQ9MwAxDKQIzjJM0yzPMDyrOsmxfPshxsCcZwuFcNy8HcO6PBAzy8K87zZl8gi/P8qlAiCz4YoiSK3rG8aIimL5ppiyFkZEuaEkgADMZIAUBtIgQAumS0CsnqrHAOIrk4pEzjtrOn67PSJxrH4vBbAAAiI6StD86LMAA9AAVnAvRoDprDSgcvREImWwANw+D48UBtmircPVvAFQVWn8HaEzHnMaA+KRMXaJ13VabAtFZPOeQokgoANs0FxCHgJUgPS9JAA==="}
+import { BREAKPOINTS, getBreakpoints } from '@studiometa/js-toolkit-v4';
+
+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:` and `data-option-:` suffix is checked against.
+
+## Replacing them
+
+```js twoslash
+// @twoslash-cache: {"v":1,"hash":"022218e137c9c60f940a899e48a5b8bf233a10c0fb1952074389d02fa008a070","data":"N4Igdg9gJgpgziAXAbVAFwJ4AcZJACwgDcYAnEAGhDRgA808AKAQwBsBLZuASgAIAzAK5gAxmnYQwvODDQAhUjGYBrLBHZg0cRmDppEvAEowREUlAA8cNKQ0BzCtJv2AfNwNF1UADph2AWzVSNGlZBSVVdU0EKigIEQREEGMsVmYRGF40fEyuDLAoe14wZn8YKF4AI0UVNQ0QmRDmAt5FfkU4fF508RJpQUq4EVtKsjgAOkoQa2ZgpABOKlYYMDtspABGABYqNFm7WTxG8NqorSmOXSQABioRfFmesgWAXwp0bFwkwhJyXb0mGxODxQvIapF6tpdPQDMZTOYrM5Vo5rLZVm4PF5fAEgg0wuC6tEpnEEngUmkMlkct0hitCqtiqVylUCWdQd0Wm0Ol0euw+nABkMRmNJlQZnNEAA2DZLFZrfCbHbUfaHJLHVmQi4aL4AJjuD1IT3IiGubw+ODwP2e/3oTCwpAgOGCGD4tDgBlR9im4oYiAAHLcQMtVutEHrlaQDr6QG6tVdEABmfWPMTPMNm6ifS3Ea3UAFJRj2x1kTB8d1ONF2b17CXzJXB+WbXYq6MxIPapBK+4pmjGnUZzAW745v5520FotO0u8fwepFVsU130ba5+2UhhWIGURqN4fxxr4AVmThtTfYHWeHvymNHHIELDqnLt4rDnlers2XOvDDdD25ru5JKwB5IJKJ5Gkg/bvJmQ4ECON75vek4ls+tCvhWXqLp+mwJmBQZyqG4YAaqMbAUsHaIAA7OBZ6QS8AC6dzQF8IA4mYITAKCJwQtEvAvAIDr+LwADkAAC1iCIUEBlHsAD0ABWcAALRoBAECsMo7BoEpRBbMJADcvi+OqESElojDAL4vC8G6BjCdcij+MJFBWdIdlbH6jnOa5s4iZKWxeS5UgvnZAaBa5aF2fMkrhWALzcPpUwycwSCgHoKxwBIYB4IpIAvC8QA==="}
+import { setBreakpoints } from '@studiometa/js-toolkit-v4';
+
+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:` and every `data-option-:` spelling;
+2. **replaces that slice of the observer's `attributeFilter`**, draining the records of the previous filter first;
+3. **emits at once** on [`useBreakpoint()`](/api/services/useBreakpoint.html), 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](/api/html/data-option.html#every-option-is-responsive) | `data-option-x:`, cascading upwards |
+| [responsive components](/api/html/data-component.html#responsive-declarations) | `data-component:`, replacing not merging |
+| [`useBreakpoint()`](/api/services/useBreakpoint.html) | 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 [`optionChanged()`](/api/methods-hooks-options.html); 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.
+
+::: info 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.
diff --git a/packages/v4/docs/api/dom/domUpdate.md b/packages/v4/docs/api/dom/domUpdate.md
new file mode 100644
index 000000000..4275ae532
--- /dev/null
+++ b/packages/v4/docs/api/dom/domUpdate.md
@@ -0,0 +1,72 @@
+# domUpdate
+
+```ts
+domUpdate(target: Node, mutate: () => void | Promise, detail?: Record): Promise
+```
+
+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.html).
+
+[[toc]]
+
+## 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 | Promise)
+ | { update(mutate: () => void | Promise): void | Promise };
+```
+
+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.html) takes, and nothing else. Resilience policy stays here.
diff --git a/packages/v4/docs/api/dom/emitExtendable.md b/packages/v4/docs/api/dom/emitExtendable.md
new file mode 100644
index 000000000..5635d0845
--- /dev/null
+++ b/packages/v4/docs/api/dom/emitExtendable.md
@@ -0,0 +1,70 @@
+# emitExtendable
+
+```ts
+emitExtendable(target: Node, event: string, detail?: Record): Promise
+```
+
+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.html).
+
+[[toc]]
+
+## 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) | Record;
+```
+
+`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.html) |
+| a **moment** someone may want to postpone | `emitExtendable()` |
diff --git a/packages/v4/docs/api/dom/index.md b/packages/v4/docs/api/dom/index.md
new file mode 100644
index 000000000..f16b0d8b0
--- /dev/null
+++ b/packages/v4/docs/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.html) — replace, prepend, append or morph, and wait for the framework to catch up
+- [`whenDOMSettled()`](./whenDOMSettled.html) — the completion boundary
+
+## Negotiating a change
+
+- [`domUpdate(target, mutate, detail?)`](./domUpdate.html) — announce a mutation so an ancestor can take it over
+- [`emitExtendable(target, event, detail?)`](./emitExtendable.html) — announce a step so an ancestor can delay it
+
+## Watching attributes
+
+- [`watchAttributes(el, callback)`](./watchAttributes.html) — every attribute of one element
+- [`watchAttributeNamespace(el, ns, bind, options?)`](./watchAttributeNamespace.html) — a namespace whose names cannot be enumerated
+
+## Breakpoints
+
+- [`BREAKPOINTS`, `getBreakpoints()`, `setBreakpoints()`](./breakpoints.html)
+
+## Read next
+
+[The mutation engine](/guide/concepts/mutation-engine.html) and [The attribute grammar](/guide/concepts/attribute-grammar.html).
diff --git a/packages/v4/docs/api/dom/swap.md b/packages/v4/docs/api/dom/swap.md
new file mode 100644
index 000000000..712589d45
--- /dev/null
+++ b/packages/v4/docs/api/dom/swap.md
@@ -0,0 +1,110 @@
+# swap
+
+```ts
+swap(target: Element, content: SwapContent, options?: SwapOptions): Promise
+```
+
+Replaces the **content** of an element and resolves once the framework has caught up.
+
+```ts
+type SwapContent = string | Element | DocumentFragment;
+
+interface SwapOptions {
+ mode?: 'replace' | 'prepend' | 'append' | 'morph';
+ wrap?: (mutate: () => void) => void | Promise;
+ self?: boolean;
+}
+```
+
+[[toc]]
+
+## Usage
+
+```ts twoslash
+// @twoslash-cache: {"v":1,"hash":"2437d3403c1db762b9fcc0b2492992495f429bd6ae9aaabfe2d324f20646ef39","data":"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="}
+import { swap } from '@studiometa/js-toolkit-v4';
+
+async function load(target: Element) {
+ const response = await fetch('/fragment');
+ await swap(target, await response.text());
+ // The mutation is applied, the new components are mounted, the old ones unmounted.
+}
+```
+
+The returned promise resolves after [`whenDOMSettled()`](./whenDOMSettled.html).
+
+## What survives
+
+**By default the element itself is never replaced**, so the caller's reference, its `id` and any instance on it survive. Only its children change.
+
+`content` as a **string** is parsed in the parsing context of the target, so ``, `` and `