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

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).

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

@@ -0,0 +1,105 @@
+# swap
+
+```ts
+swap(target: Element, content: SwapContent, options?: SwapOptions): Promise<void>
+```
+
+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<unknown>;
+  self?: boolean;
+}
+```
+
+## Usage
+
+```ts
+import { swap } from '@studiometa/js-toolkit';
+
+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.md).
+
+## 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 `<tr>`, `<li>` and `<option>` survive. As an `Element` or a `DocumentFragment` it is read as the incoming counterpart of the target, and its **children** become the new content.
+
+## The modes
+
+```js
+import { SWAP_MODES } from '@studiometa/js-toolkit';
+
+SWAP_MODES.REPLACE; // 'replace' — the default
+SWAP_MODES.PREPEND; // 'prepend'
+SWAP_MODES.APPEND; // 'append'
+SWAP_MODES.MORPH; // 'morph'
+```
+
+`SwapMode` is derived from the frozen object — the pattern for every closed set of strings in the framework.
+
+`prepend` and `append` stay in core because they need the same before-and-after script diff as the other two.
+
+### `morph`
+
+Identity survives — nodes, focus, expandos, instances — **but markup that is not sent does not.** Two consequences are morphdom's policy, not `swap()`'s:
+
+- an element the incoming markup does not contain is discarded even from a preserved parent;
+- morphdom syncs the `value` of an input from the incoming markup.
+
+**Attributes are not synced on the target.** Core passes `childrenOnly: true` without `self`, because `data-component` and `data-mount` are lifecycle declarations of the target, not content.
+
+## `self`
+
+Replaces the target element **itself**, attributes included, instead of its children:
+
+```js
+await swap(el, html, { mode: 'replace', self: true });
+```
+
+It is the axis a caller that matches an element of a response to an element of the page needs: an id-matched section otherwise keeps the classes of the element it replaces.
+
+- With `self`, an `Element` content **is** the replacement rather than a container — the only way its own attributes reach the page. A string or a `DocumentFragment` contributes its **first top-level element**.
+- `replace` puts the replacement in the place of the target, so the target **leaves** the document.
+- `morph` morphs the target from the replacement without `childrenOnly`, so the element and its identity survive while its attributes are updated.
+- `append` and `prepend` add to the children by definition, so `self` with either is a `swap.self-ignored` warning — as is content holding no element.
+
+## Scripts
+
+A `<script>` produced by the fragment parser is flagged as **already started** by the HTML specification and stays inert wherever it is moved. It runs only if it is **recreated** — and a script that was already in the page runs **twice** if it is recreated.
+
+`swap()` owns that rule, once. Script adoption follows whatever ends up in the document, so a replacement carrying a script still runs it exactly once.
+
+## `wrap`
+
+The whole seam. It receives the single mutation of the swap and decides when it runs:
+
+```ts
+import { swap, viewTransition } from '@studiometa/js-toolkit';
+
+async function load(el: Element, html: string) {
+  await swap(el, html, { wrap: (mutate) => viewTransition(mutate) });
+}
+```
+
+[`domUpdate()`](domUpdate.md) produces that wrapper and nothing else, so an ancestor can claim the lane. **Resilience policy stays with `domUpdate()`** — `swap()` itself throws rather than swallowing.
+
+## What is deliberately not in core
+
+- **Attribute syncing in a default `morph`** — see above.
+- **Transitions, view transitions, history, `id` matching and response parsing.** All caller policy.
+
+## It is a free function
+
+Not a `Base` method. `morphdom` is a real, statically imported dependency, and the subpath layout contains the cost: it is reachable through `swap()` only, so a page that never swaps never downloads it.

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

@@ -0,0 +1,96 @@
+# watchAttributeNamespace
+
+```ts
+watchAttributeNamespace(
+  el: Element,
+  namespace: string,
+  bind: AttributeNamespaceBinder,
+  options?: { qualifiers?: readonly string[]; component?: string },
+): () => void
+```
+
+The mechanism for a namespace whose names **cannot be enumerated**. Declare the prefix, hand over a binder, and get the per-element observation, the keyed bindings and the teardown.
+
+```ts
+interface AttributeNamespaceDeclaration {
+  qualifier: string;
+  value: string;
+  attribute: string;
+}
+
+type AttributeNamespaceBinder = (declaration: AttributeNamespaceDeclaration) => (() => void) | void;
+```
+
+## Usage
+
+```js
+import { watchAttributeNamespace } from '@studiometa/js-toolkit';
+
+mounted() {
+  return watchAttributeNamespace(this.$el, 'data-on', ({ qualifier, value }) =>
+    new ActionEvent(this, qualifier, value).attach(),
+  );
+}
+```
+
+`Base` has no wrapper and owns no cleanup. A component calls it from `mounted()` and returns its cleanup.
+
+## One binding per attribute, keyed by the name that produced it
+
+That is what lets **one** code path cover all three shapes a change takes:
+
+| Change  | Effect                          |
+| ------- | ------------------------------- |
+| added   | attach, with nothing to release |
+| changed | release, then attach            |
+| removed | release, with nothing to attach |
+
+A memoised parse cannot express the middle one — and rewriting an attribute in place is not hypothetical: `swap({ mode: 'morph' })` does it, and so does any templating around the element.
+
+**The binder returns that binding's release**, or nothing when the declaration produced no binding. Returning nothing leaves nothing held, so a malformed value costs no bookkeeping.
+
+## Declaration order survives a rewrite
+
+The bindings are a `Map` keyed by attribute, and `set` on a key already there keeps its position — so a consumer applying its bindings in order is not reordered by an edit.
+
+## Validating the qualifier's head
+
+```js
+watchAttributeNamespace(el, 'data-bind', bind, {
+  qualifiers: ['class', 'prop', 'attr', 'style', 'text', 'html'],
+  component: 'Bind',
+});
+```
+
+Given a finite vocabulary, an unknown head warns **once per element and per name** with `attribute.unknown-qualifier` and binds nothing — so `data-bind:prpo.value` stops being an attribute that silently does nothing.
+
+Omitted, the vocabulary is **open** and anything binds, which is the only honest answer for `data-on`, whose qualifiers are any DOM event.
+
+## The qualifier and its parts
+
+```
+data-<namespace>:<qualifier>[.<part>…]
+```
+
+**A dot splits the qualifier, and core reads none of it.** Whether the first part names what a binding writes to (`data-bind:prop.value`) or modifies how it fires (`data-on:click.prevent`) is the business of whoever declared the namespace.
+
+Core reads the qualifier's **head** only, to check it against the vocabulary you handed over, and never past it.
+
+> Core owns when a declaration is re-parsed and how the attribute is observed. The namespace's owner owns what the string means.
+
+## It is built on `watchAttributes()`
+
+So its records join the one mutation engine's queue and are reported from the same batch: [`whenDOMSettled()`](whenDOMSettled.md), and therefore [`swap()`](swap.md), covers a namespaced declaration the way it covers a mount.
+
+## When a namespace does not need this
+
+If the whole set of names can be listed in advance, it belongs in the one page-wide `attributeFilter` instead:
+
+| Namespace               | Names                                       | Mechanism                 |
+| ----------------------- | ------------------------------------------- | ------------------------- |
+| `data-option-columns`   | `attribute × breakpoint` — enumerable       | the one `attributeFilter` |
+| `data-component`        | fixed plus one per breakpoint — enumerable  | the one `attributeFilter` |
+| `data-on`, `data-track` | any DOM event — open                        | **this**                  |
+| `data-bind`             | finite head, open name — **not** enumerable | **this**                  |
+
+`data-bind` is the case that shows why "finite or open" is the wrong axis on its own: its binding types are finite, but the class, property or attribute name after the dot is not. See [The attribute grammar](../../guide/concepts/attribute-grammar.md).

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

@@ -0,0 +1,56 @@
+# watchAttributes
+
+```ts
+watchAttributes(el: Element, callback: (change: AttributeChange) => void): () => void
+```
+
+Observes **every** attribute of one element, through a second, unfiltered observer.
+
+```ts
+interface AttributeChange {
+  name: string;
+  value: string | null;
+  previousValue: string | null;
+}
+```
+
+## Why it exists
+
+`attributeFilter` takes exact names and the DOM has no wildcard, so the engine cannot see an attribute the framework cannot name. This is the opt-in, and **the page pays for the elements that ask**.
+
+## Usage
+
+```js
+import { Base, watchAttributes } from '@studiometa/js-toolkit';
+
+class Bindings extends Base {
+  static config = { name: 'Bindings' };
+
+  mounted() {
+    return watchAttributes(this.$el, ({ name, value, previousValue }) => {
+      if (!name.startsWith('data-my-')) return;
+      // …
+    });
+  }
+}
+```
+
+**The caller owns it.** The helper returns one idempotent cleanup and knows nothing about `Base`: a component calls it from `mounted()` and returns the cleanup.
+
+## The contract
+
+- **The records join the shared queue.** They are drained wherever the engine drains its own, [`whenDOMSettled()`](whenDOMSettled.md) included, and they are reported from the same background task — as the last step of the batch.
+- **A callback runs after the framework work of the batch.** So a component that stops its watcher during the same batch in which its own declaration is withdrawn hears nothing about the attribute change.
+- **Changes are coalesced**, with the rule of [`option<Name>Changed()`](../methods-hooks-options.md): several writes in one batch give one change, from the value before the first write to the value at the end, and a write that ends where it started is not a change.
+- **The payload covers the element's whole attribute set**, framework names included, with raw strings and `null` for an absent attribute. **A caller narrows by prefix.**
+- A failing callback is reported as `callback.attribute-watcher-failed`, so one watcher cannot stop another.
+
+## What to reach for instead
+
+| Want                                         | Use                                                           |
+| -------------------------------------------- | ------------------------------------------------------------- |
+| a declared option                            | [`option<Name>Changed()`](../methods-hooks-options.md)    |
+| a whole namespace, with keyed bindings       | [`watchAttributeNamespace()`](watchAttributeNamespace.md) |
+| a subtree, character data, or a foreign node | [`useMutation()`](../services/useMutation.md)             |
+
+A declared option is already in the one page-wide filter, and costs no second observer.

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

@@ -0,0 +1,41 @@
+# whenDOMSettled
+
+```ts
+whenDOMSettled(): Promise<void>
+```
+
+The completion boundary for morphing, fetch updates and breakpoint crossings.
+
+## Usage
+
+```ts
+import { whenDOMSettled } from '@studiometa/js-toolkit';
+
+async function replace(el: Element, html: string) {
+  el.innerHTML = html;
+  await whenDOMSettled();
+  // Every eager component in the new markup has mounted.
+}
+```
+
+[`swap()`](swap.md) awaits it for you.
+
+## What it waits for
+
+- it **drains the pending mutation records**;
+- it **follows the mutation chains of eager lifecycle work**, so markup a `mounted()` inserts is covered too;
+- it resolves after the eager mounts **and the teardown**.
+
+An **eager lazy** component is covered: the import promise joins the lifecycle-work set for the eager trigger only, so an awaited `swap()` waits for download, registration and mount.
+
+Breakpoint work runs through the background lane, so a crossing's teardown, import and mount work is covered as well.
+
+## What it does not wait for
+
+- **visibility, interaction, idle or media conditions.** A component with `data-mount="visible"` has not mounted when this resolves, and that is the point: waiting on a viewport would mean never resolving on a page that is not scrolled.
+- **the promises returned by `mounted()`.** An async `mounted()` is the component's own business.
+
+## Where else it appears
+
+- `watchAttributes()` records join the same queue, so a namespaced declaration is covered the way a mount is.
+- A [`useMutation()`](../services/useMutation.md) subscriber that needs the framework's order rather than the platform's awaits this in its callback.

package/skills/studiometa-js-toolkit/references/api/html/data-component.md

@@ -0,0 +1,105 @@
+# `data-component`
+
+Declares which components run on an element. **The instance exists because this attribute is here and the name is registered.**
+
+## One component
+
+```html
+<div data-component="Slider"></div>
+```
+
+The token is the component's `config.name`.
+
+## Several components
+
+The value is a whitespace-separated token list, and each token gets its own instance:
+
+```html
+<a href="/next" data-component="Action Analytics Prefetch">Next</a>
+```
+
+The instances are independent. They share the element and nothing else.
+
+## On native elements
+
+`data-component` improves a native element rather than replacing it:
+
+```html
+<form data-component="Fetch">…</form>
+<details data-component="Disclosure">…</details>
+<a href="/page" data-component="Prefetch">…</a>
+<tr data-component="Row">…</tr>
+```
+
+## Nesting
+
+A nested declaration is discovered by the same registry, on its own. Nesting is DOM ancestry, never ownership:
+
+```html
+<div data-component="Accordion">
+  <div data-component="AccordionItem">…</div>
+  <div data-component="AccordionItem">…</div>
+</div>
+```
+
+Unmounting the parent does not unmount the children.
+
+## Responsive declarations
+
+One breakpoint-scoped companion attribute exists, with the spelling of responsive options:
+
+```html
+<div
+  data-component="Action Analytics"
+  data-component:xxs="MobileMenu MobileSearch"
+  data-component:m="DesktopMenu DesktopSearch"></div>
+```
+
+- The plain token set is **always active**.
+- At the active breakpoint the registry walks from the widest active suffix **down** and takes the first attribute present.
+- That value is the **complete** responsive set. A wider value **replaces** every lower value; it does not merge with it.
+- An empty value is a **stop**, so a name can be removed above a breakpoint.
+- The effective declaration is the **union** of the unconditional set and the selected responsive set, without duplicates.
+
+`TabletFeature` below runs at `s` and `m`, and is removed at `l`:
+
+```html
+<div data-component="Base" data-component:s="TabletFeature" data-component:l=""></div>
+```
+
+### What a crossing does
+
+A crossing compares the effective set against the element's current state:
+
+| Case                      | Effect                                                                |
+| ------------------------- | --------------------------------------------------------------------- |
+| a name is in both         | it keeps its controller and its instance — nothing happens            |
+| a name is no longer there | `$unmount()`, then the instance is dropped from the element           |
+| a name is new             | the normal pipeline: mount strategy, `data-mount`, lazy entry, events |
+
+A crossing back gives a **new** identity, because the DOM stopped declaring that one. An inactive lazy declaration imports nothing.
+
+Connected elements with a scoped declaration share **one** reference-counted `useBreakpoint()` subscription. A page with plain declarations opens none. Breakpoint work runs through the background lane, so `whenDOMSettled()` covers the teardown, import and mount work of a crossing.
+
+**A suffix must name a configured breakpoint**
+
+An unknown suffix is ignored with one `responsive.unknown-breakpoint` warning. That includes the v3 list syntax `data-component:xxs:xs:s`.
+
+See [`setBreakpoints()`](../dom/breakpoints.md).
+
+## Changing it from code
+
+The attribute is live. Adding a token mounts a new instance; removing one unmounts and drops it:
+
+```js
+el.dataset.component = 'Slider Analytics';
+await whenDOMSettled();
+```
+
+## Where the instances go
+
+Each instance is published on the element under `Symbol.for('@studiometa/js-toolkit/instances')`. That map is not public API — [`getInstance()`](../registry/getInstance.md) and its three siblings are. In a console:
+
+```js
+$0[Symbol.for('@studiometa/js-toolkit/instances')];
+```

package/skills/studiometa-js-toolkit/references/api/html/data-mount.md

@@ -0,0 +1,69 @@
+# `data-mount`
+
+Overrides, for one element, **when** its components mount.
+
+```html
+<div data-component="Map" data-mount="visible"></div>
+```
+
+## The values
+
+| Value                    | Mounts when                            | Reversible |
+| ------------------------ | -------------------------------------- | ---------- |
+| `eager`                  | 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**    |
+
+```html
+<div data-component="Hero" data-mount="eager"></div>
+<div data-component="Gallery" data-mount="visible:200px"></div>
+<div data-component="Video" data-mount="in-view:-10% 0px"></div>
+<div data-component="Analytics" data-mount="idle"></div>
+<div data-component="Tooltip" data-mount="interaction"></div>
+<div data-component="Chat" data-mount="interaction:page"></div>
+<div data-component="Parallax" data-mount="media:(min-width: 64rem)"></div>
+```
+
+## 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.
+
+## Precedence
+
+```
+data-mount  >  manifest entry mountStrategy  >  config.mountStrategy  >  'eager'
+```
+
+**Several components on one element share that element's `data-mount`.** A component that needs its own policy declares `config.mountStrategy` instead.
+
+## Invalid values
+
+An unknown value, an empty media query, or a `rootMargin` the browser refuses leaves the component **unmounted** and dispatches one cancelable `js-toolkit:diagnostic` with the code `component.invalid-mount-strategy`, the severity `error`, the component name and the original error.
+
+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.
+
+## It 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.
+
+```js
+el.dataset.mount = 'eager';
+await whenDOMSettled();
+```
+
+## A waiting component has no instance
+
+It is invisible to `$query()`, `$closest()`, `$watchChildren()` and `getInstances()`, and it announces nothing. There is nothing to guard against.
+
+Once it has mounted and been stood down again — which only `in-view` and `media:` do — the instance exists and is unmounted, which is what [`getUnmountedInstances()`](../registry/getUnmountedInstances.md) answers.
+
+See [Mount strategies](../../guide/going-further/mount-strategies.md) for the full behaviour of each value.