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

package/skills/studiometa-js-toolkit/references/api/methods-hooks-lifecycle.md

@@ -0,0 +1,90 @@
+# Lifecycle hooks
+
+```ts
+mounted(): MountedReturn
+unmounted(): void
+```
+
+```ts
+type MountedReturn = void | (() => void) | MountedReturn[] | Promise<MountedReturn>;
+```
+
+Both are meant to be overridden and neither needs a `super` call.
+
+## `mounted()`
+
+Runs when the element is in the document and the component's mount conditions are met. It runs **after** every `option<Name>Changed()` hook of the same cycle.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Player extends Base {
+  static config = { name: 'Player' };
+
+  mounted() {
+    this.$el.setAttribute('aria-live', 'polite');
+  }
+}
+```
+
+### It returns its cleanup
+
+A function, an array of functions, sync or async. They run on the next `$unmount()`:
+
+```js
+import { Base, useScroll } from '@studiometa/js-toolkit';
+
+class Header extends Base {
+  static config = { name: 'Header' };
+
+  mounted() {
+    return useScroll().subscribe(({ directionY }) => {
+      this.$el.classList.toggle('is-hidden', directionY > 0);
+    });
+  }
+}
+```
+
+If an async `mounted()` resolves **after** the unmount, the cleanup runs immediately.
+
+## `unmounted()`
+
+Runs at the end of `$unmount()`, after the cycle's listeners are unbound, the `mounted()` cleanups have run and the scheduled tasks are cancelled.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Player extends Base {
+  static config = { name: 'Player' };
+
+  unmounted() {
+    this.$el.removeAttribute('aria-live');
+  }
+}
+```
+
+It stays available for the cases the returned cleanup does not fit. When both exist, the returned cleanup runs first.
+
+## What triggers each
+
+| Cause                                       | Calls                                         |
+| ------------------------------------------- | --------------------------------------------- |
+| the element enters the document             | `mounted()`                                   |
+| a mount strategy's condition becomes true   | `mounted()`                                   |
+| the element leaves the document             | `unmounted()`                                 |
+| the component token leaves `data-component` | `unmounted()`, then the instance is dropped   |
+| a breakpoint withdraws the declaration      | `unmounted()`, then the instance is dropped   |
+| a reversible strategy's condition ends      | `unmounted()`                                 |
+| the node is **moved**                       | `unmounted()` then `mounted()`, same identity |
+
+**Unmounting a parent does not unmount its children.**
+
+## What is not a lifecycle hook
+
+- **`updated()` does not exist.** For an option that chooses a resource, use [`option<Name>Changed()`](methods-hooks-options.md). For an attribute the framework does not read, use [`watchAttributes()`](dom/watchAttributes.md).
+- **There is no permanent state.** A component never declares that its work is over. "Once per element" is a plain field — see [Lifecycle](../guide/introduction/lifecycle-hooks.md#do-this-once-per-element).
+- **A service mixin never occupies either hook.** It overrides `$mount()`/`$unmount()`, so a class that writes its own `mounted()` without `super.mounted()` still subscribes.
+
+## Failures
+
+A hook that throws is reported once as `component.lifecycle-failed` and the cycle continues. It does not stop the other instances in the same batch.

package/skills/studiometa-js-toolkit/references/api/methods-hooks-options.md

@@ -0,0 +1,96 @@
+# Options hooks
+
+```ts
+option<Name>Changed(change: OptionChange): OptionChangedReturn
+```
+
+A declared method named after an option makes that option a **live effect**. A component without the convention pays no setup cost and reads its options directly.
+
+## Usage
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+function connect(url) {
+  return { dispose() {} };
+}
+
+class Feed extends Base {
+  static config = {
+    name: 'Feed',
+    options: { source: String },
+  };
+
+  optionSourceChanged({ value, previousValue, initial }) {
+    const connection = connect(value);
+    // The cleanup for *this* value.
+    return () => connection.dispose();
+  }
+}
+```
+
+The method name is the option name in pascal case: `dragThreshold` is `optionDragThresholdChanged`.
+
+## The payload
+
+```ts
+interface OptionChange<T = unknown> {
+  name: string;
+  value: T;
+  previousValue: T | undefined;
+  rawValue: string | null;
+  previousRawValue: string | null;
+  initial: boolean;
+}
+```
+
+| Field              | Meaning                                               |
+| ------------------ | ----------------------------------------------------- |
+| `name`             | the option name                                       |
+| `value`            | the parsed value now                                  |
+| `previousValue`    | the parsed value before, `undefined` on the first run |
+| `rawValue`         | the raw attribute string, `null` when absent          |
+| `previousRawValue` | the raw string before, `null` when it was absent      |
+| `initial`          | `true` on the first run of a mount cycle              |
+
+```ts
+import { Base, type OptionChange } from '@studiometa/js-toolkit';
+
+class Feed extends Base {
+  static config = { name: 'Feed', options: { source: String } };
+
+  optionSourceChanged({ value, previousValue, initial }: OptionChange<string>) {
+    console.log(value, previousValue, initial);
+  }
+}
+```
+
+## The return value
+
+```ts
+type OptionChangedReturn = void | (() => void);
+```
+
+Return a function to release what this value acquired. The previous cleanup runs **before** an update, and every active cleanup runs on `$unmount()`.
+
+## When it runs
+
+- **Before `mounted()`**, on each mount cycle, with `initial: true`.
+- On an attribute change, once the batch is processed.
+- On a **breakpoint crossing** that changes the resolved raw value.
+- Removal of the attribute applies the declared default, which is a change like any other.
+- A new mount starts each effect again with `initial: true`.
+
+## Coalescing
+
+Several writes to one attribute in one batch give **one** change, from the first old raw value to the final DOM value. A write that ends where it started is **not** a change.
+
+The comparison uses raw strings, so a breakpoint crossing and an attribute write are the same kind of event. A crossing to the same resolved value announces nothing, and a write to `data-option-columns:s` while the viewport is at `l` announces nothing.
+
+## What it costs
+
+**A `matchMedia` subscription opens only for a component that declares one of these hooks.** `$unmount()` releases it. A page that only reads options holds no listener at all.
+
+## Not for arbitrary attributes
+
+This hook is for **declared options**. For an attribute the framework does not read, use [`watchAttributes()`](dom/watchAttributes.md), which shares the same coalescing rule and the same batch.

package/skills/studiometa-js-toolkit/references/api/methods-hooks-services.md

@@ -0,0 +1,164 @@
+# Services hooks
+
+A service mixin binds one subscription per mount cycle, under the **one method name the service owns**. There is no `hook` option.
+
+| Mixin                | Hook             | Props type            |
+| -------------------- | ---------------- | --------------------- |
+| `withRaf`            | `ticked`         | `RafProps`            |
+| `withScroll`         | `scrolled`       | `ScrollProps`         |
+| `withResize`         | `resized`        | `ResizeProps`         |
+| `withPointer`        | `moved`          | `PointerProps`        |
+| `withDrag`           | `dragged`        | `DragProps`           |
+| `withKey`            | `keyed`          | `KeyProps`            |
+| `withInView`         | `intersected`    | `InViewProps`         |
+| `withMutation`       | `mutated`        | `MutationProps`       |
+| `withScrollProgress` | `scrolledInView` | `ScrollProgressProps` |
+
+## Usage
+
+```js
+import { Base, withScroll } from '@studiometa/js-toolkit';
+
+class Header extends withScroll(Base) {
+  static config = { name: 'Header' };
+
+  scrolled({ y, directionY, isScrolling }) {
+    this.$el.classList.toggle('is-hidden', directionY > 0 && y > 100);
+  }
+}
+```
+
+Mixins stack, and their `$services` keys accumulate:
+
+```js
+import { Base, withRaf, withResize } from '@studiometa/js-toolkit';
+
+class Parallax extends withRaf(withResize(Base)) {
+  static config = { name: 'Parallax' };
+
+  #height = 0;
+
+  resized({ height }) {
+    this.#height = height;
+  }
+
+  ticked({ delta }) {
+    // …
+  }
+}
+```
+
+## A mixin never occupies a lifecycle hook
+
+`mounted()` and `unmounted()` belong to the component author, so **nothing has to be chained**. A class that mixes a service in and writes its own `mounted()` without `super.mounted()` still subscribes: the framework's own `$mount()`/`$unmount()` pair carries the subscription.
+
+The consequences are worth knowing:
+
+- The subscription starts **once the whole of `mounted()` has run** — including an `immediate` first delivery, which therefore reaches a component that is fully set up.
+- It is released **before `unmounted()`**, exactly where the mount cleanup used to release it.
+- `$unmount()` releases unconditionally, so a manual subscription started outside a mount cycle is released too.
+
+**A userland mixin still chains**
+
+The rule is about what the mixin **overrides**, not about who wrote it. A mixin that puts its work in `mounted()` needs its subclasses to call `super.mounted()` — and the way not to need that is to override `$mount()`.
+
+## Mixin options
+
+```ts
+interface ServiceMixinOptions<Target, Host = Base> {
+  target?: (instance: Host) => Target;
+  manual?: boolean;
+  immediate?: boolean;
+}
+```
+
+**The options of a mixin are not the options of the service.** `target`, `manual` and `immediate` describe the subscription. They are removed before the underlying `use*()` call and they are absent from its options type.
+
+A service's own options are passed in the same object and forwarded:
+
+```js
+class Slide extends withDrag(Base, { axis: 'x', inertia: false, immediate: true }) {}
+```
+
+### `target`
+
+```js
+withResize(Base, { target: (instance) => instance.$refs.inner });
+```
+
+A resolver that comes back with `undefined` or `null` reports `service.missing-target` and starts **no** subscription — because a renamed ref arrives here as nothing, and a service with a default target would otherwise observe the wrong thing and look like it worked.
+
+A service whose **own** default target is nothing, like `withRaf`, is untouched.
+
+**The resolver is typed against the host as declared**
+
+A mixin is applied while the extends clause of its class is still being evaluated, so `withDrag(Base, …)` types its resolver against `Base`. A component reaching further names the shape it needs — `(instance as Base & { readonly target: HTMLElement }).target` — which is an assertion rather than a check. That is why core checks the result at runtime.
+
+### `manual`
+
+Declares the hook without running it. `$services.<hook>` is the switch:
+
+```js
+import { Base, withRaf } from '@studiometa/js-toolkit';
+
+class SliderItem extends withRaf(Base, { manual: true }) {
+  static config = { name: 'SliderItem' };
+
+  ticked({ delta }) {}
+
+  onSelected() {
+    this.$services.ticked.start();
+  }
+
+  onSettled() {
+    this.$services.ticked.stop();
+  }
+}
+```
+
+`$services` is declared in the type as `ServiceHandles<'ticked'>`, so the key completes and a wrong name is a type error. Each handle is a [`Toggle`](services/toggle.md).
+
+### `immediate`
+
+Asks for the first delivery at subscribe time. The sources with a current value honour it; the ones without do nothing. `withInView` defaults it to `true`.
+
+## `ticked` can return a render function
+
+`withRaf` is the one hook whose return value is used: return a function and it runs in the `write` phase of the same frame.
+
+```js
+import { Base, withRaf } from '@studiometa/js-toolkit';
+
+class Follower extends withRaf(Base) {
+  static config = { name: 'Follower' };
+
+  ticked({ delta }) {
+    const x = this.measure(delta);
+    return () => {
+      this.$el.style.transform = `translateX(${x}px)`;
+    };
+  }
+
+  measure(delta) {
+    return delta;
+  }
+}
+```
+
+The raf service collects the render functions of its callbacks and cancels a render whose subscriber left between the two phases.
+
+## One hook per class, and that is the limit
+
+A mixin binds one subscription, under one name, for each mount cycle. A component whose subscriptions are **one per markup declaration** — one per attribute, with its own modifiers and its own threshold, known only when the element is read — has no method to name and no fixed count. It calls `subscribe()` itself:
+
+```js
+mounted() {
+  return useScroll(this.$refs.panel).subscribe((props) => {});
+}
+```
+
+`on<Event>` has the same shape: a handler name belongs to the class, while a set of events can be data. Neither limit is about a build step — `withRaf(Base)` is an ordinary call, and the name is fixed by how the class is written.
+
+## Failures
+
+A subscriber that throws is skipped and reported as `callback.service-failed`. Core dispatches the diagnostic first and calls `reportError()` only when no listener cancelled the event.

package/skills/studiometa-js-toolkit/references/api/registry/defineManifest.md

@@ -0,0 +1,57 @@
+# defineManifest
+
+```ts
+defineManifest({ modules, mountStrategy }: DefineManifestOptions): ComponentManifest
+```
+
+Turns a map of module paths into a [manifest](registerManifest.md), deriving each `data-component` token from its path.
+
+## Usage
+
+```js
+import { defineManifest, fromMetaGlob, registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  }),
+);
+```
+
+**Parameters**
+
+- `modules` (`ModuleRecord`) — a map of path to importer, from [`fromMetaGlob()`](fromMetaGlob.md), [`fromWebpackContext()`](fromWebpackContext.md), or written by hand.
+- `mountStrategy` (`MountStrategy`, optional) — a package-wide default.
+
+**Return value**
+
+- `ComponentManifest`, ready for `registerManifest()`.
+
+## Token derivation
+
+The token is the file's base name, and **`index` falls back to the parent directory**:
+
+| Path                           | Token    |
+| ------------------------------ | -------- |
+| `./components/Slider.js`       | `Slider` |
+| `./components/Slider/index.js` | `Slider` |
+| `./components/nav/Menu.js`     | `Menu`   |
+
+Duplicate tokens give a warning and **keep the first path**.
+
+## The package-wide strategy
+
+```js
+defineManifest({
+  modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  mountStrategy: 'visible',
+});
+```
+
+Entry wrappers are emitted **only when the strategy is not `eager`**, so the default costs nothing in the output.
+
+Any element still overrides it with `data-mount`, and a class's own `config.mountStrategy` takes over once it has loaded.
+
+## What it is not
+
+It carries the importer and the strategy, and nothing else. Informational metadata — `packageName`, `subpath`, `exportName`, `group`, `styles`, `integrations` — belongs in the output type of a generator, not in core.

package/skills/studiometa-js-toolkit/references/api/registry/fromMetaGlob.md

@@ -0,0 +1,33 @@
+# fromMetaGlob
+
+```ts
+fromMetaGlob(glob: Record<string, unknown>): ModuleRecord
+```
+
+Adapts a Vite `import.meta.glob()` result for [`defineManifest()`](defineManifest.md).
+
+## Usage
+
+```js
+import { defineManifest, fromMetaGlob, registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  }),
+);
+```
+
+**Parameters**
+
+- `glob` — the object `import.meta.glob()` returns, mapping each path to a lazy importer.
+
+**Return value**
+
+- `ModuleRecord` — a map of path to importer.
+
+**Use the lazy form**
+
+`import.meta.glob(pattern)` is lazy and gives one importer per path, which is the point. `import.meta.glob(pattern, { eager: true })` downloads everything up front, so a manifest built from it defers nothing — and the adapter **throws a `TypeError`** naming the first path that is not an importer function, rather than building a manifest that silently does nothing lazily.
+
+The adapter adds **no bundler dependency**. It reads a plain object of functions, and core names Vite nowhere.

package/skills/studiometa-js-toolkit/references/api/registry/fromWebpackContext.md

@@ -0,0 +1,37 @@
+# fromWebpackContext
+
+```ts
+fromWebpackContext(context: WebpackContextLike): ModuleRecord
+```
+
+Adapts an `import.meta.webpackContext()` result for [`defineManifest()`](defineManifest.md).
+
+## Usage
+
+```js
+import { defineManifest, fromWebpackContext, registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromWebpackContext(
+      import.meta.webpackContext('./components', {
+        recursive: true,
+        regExp: /\/index\.js$/,
+        mode: 'lazy',
+      }),
+    ),
+  }),
+);
+```
+
+**Parameters**
+
+- `context` (`WebpackContextLike`) — anything with the `keys()` method and the callable shape of a webpack context.
+
+**Return value**
+
+- `ModuleRecord` — a map of path to a **deferred** importer, one per key.
+
+The import of each key is deferred rather than performed, so nothing is downloaded when the manifest is built. Use `mode: 'lazy'` so webpack emits a chunk per module.
+
+The adapter adds **no webpack dependency**. `WebpackContextLike` is a structural type, so the adapter is testable without a bundler and core names webpack nowhere.

package/skills/studiometa-js-toolkit/references/api/registry/getInstance.md

@@ -0,0 +1,52 @@
+# getInstance
+
+```ts
+getInstance<T extends Base = Base>(el: Element | null, name: string): T | undefined
+```
+
+The instance of `name` on `el`, mounted or not.
+
+## Usage
+
+```ts
+import { Base, getInstance } from '@studiometa/js-toolkit';
+
+class Dialog extends Base {
+  static config = { name: 'Dialog' };
+
+  close() {}
+}
+// `el` may be null — a querySelector() result passes straight through.
+const dialog = getInstance<Dialog>(document.querySelector('[data-component="Dialog"]'), 'Dialog');
+
+if (dialog?.$isMounted) dialog.close();
+```
+
+**Parameters**
+
+- `el` (`Element | null`) — the element to read.
+- `name` (`string`) — the component name.
+
+**Return value**
+
+- `T | undefined`.
+
+## Why it is a function of its own
+
+One map read and no scan. The caller already holds the element and the name, so there is nothing left to search — which is what makes it different from a filter over [`getInstances()`](getInstances.md).
+
+It is also the answer to "is this element's instance there yet", which every plural form loses by returning a list.
+
+## Why `el` accepts `null` but the return is not
+
+`el` accepts `null` so a `querySelector()` result can be passed straight through. The two ways of having no instance — no element, and an element without one — are the same answer to the caller, and `undefined` says it for both. Narrowing the parameter to `Element` would buy nothing back: the body reads an optional map either way, so the only thing a stricter type produces is a `!` at every call site asserting something the function never needed.
+
+The **return** stays `T | undefined`, and that asymmetry is deliberate. An absent element is a fact the caller may reasonably not know; an absent instance is a fact the caller must handle.
+
+## There is no `getMountedInstance`
+
+The result is one object, so a caller who needs the live one reads `.$isMounted` on it. A second export would only hide that check behind an `undefined` that means two things.
+
+## Detached elements
+
+This form reads the element's instance map directly and never consults the DOM, so it answers for a detached element as readily as for a connected one.

package/skills/studiometa-js-toolkit/references/api/registry/getInstances.md

@@ -0,0 +1,48 @@
+# getInstances
+
+```ts
+getInstances<T extends Base = Base>(name: string, root?: ParentNode): T[]
+getInstances<T extends Base = Base>(el: Element): T[]
+```
+
+**Every instance that exists** for a component name, mounted or not, in DOM order — or every instance on one element, in mount order.
+
+## Usage
+
+```ts
+import { getInstances } from '@studiometa/js-toolkit';
+
+const section = document.querySelector('section')!;
+
+getInstances('Dialog'); // every Dialog in the document
+getInstances('Dialog', section); // every Dialog built in a region
+getInstances(section); // everything on one element
+```
+
+Reach for it when the result is **counted or inspected**. When it is going to be _used_, prefer [`getMountedInstances()`](getMountedInstances.md) — every instance in that list has run `mounted()` and has not yet run `unmounted()`.
+
+## The two overloads
+
+```ts
+(name: string, root?: ParentNode): T[]
+(el: Element): T[]
+```
+
+- **The name form** searches the descendants of `root`, which defaults to the document. `root` is a `ParentNode` and the call is `querySelectorAll`, so it never matches `root` itself.
+- **The element form** reads the element's instance map directly and never consults the DOM, so it answers for a **detached** element as readily as for a connected one. The name form cannot: `document.querySelectorAll()` does not see a detached element. Pass the detached root as `root` when a name lookup has to reach inside it.
+
+## How the narrowing works
+
+`selectorFor(name)` over-matches on purpose — it lists the responsive spellings of `data-component` too — and **the instance-map read is what removes an inactive declaration**, because a breakpoint-withdrawn component is destroyed _and_ deleted from the map.
+
+A matching element with no instance is skipped, and that is the whole narrowing. There is no mount filter, because it never did that work.
+
+## Where the instances live
+
+An element publishes its instances under `Symbol.for('@studiometa/js-toolkit/instances')`. That map is **not public API**; these four lookups are, and between them they express every read it answers. In a console:
+
+```js
+$0[Symbol.for('@studiometa/js-toolkit/instances')];
+```
+
+The element overload exists rather than a second export because both forms answer "which instances are there" and the argument picks the scope — and it keeps the map read in one place, which matters more now that the key is a symbol and no longer spellable as `el.__base__`.

package/skills/studiometa-js-toolkit/references/api/registry/getMountedInstances.md

@@ -0,0 +1,39 @@
+# getMountedInstances
+
+```ts
+getMountedInstances<T extends Base = Base>(name: string, root?: ParentNode): T[]
+getMountedInstances<T extends Base = Base>(el: Element): T[]
+```
+
+**The live instances** of a component name, in DOM order — or the live ones on one element, in mount order.
+
+## Usage
+
+```js
+import { getMountedInstances } from '@studiometa/js-toolkit';
+
+// This is the safe list to call a method on.
+getMountedInstances('Dialog').forEach((dialog) => dialog.$unmount());
+```
+
+**This is the safe list to call a method on**: every instance in it has run `mounted()` and has not yet run `unmounted()`. Prefer it over [`getInstances()`](getInstances.md) whenever the result is going to be _used_ rather than counted or inspected.
+
+## The two overloads
+
+```ts
+(name: string, root?: ParentNode): T[]
+(el: Element): T[]
+```
+
+- **The name form** searches the descendants of `root`, which defaults to the document. `root` is a `ParentNode` and the call is `querySelectorAll`, so it never matches `root` itself.
+- **The element form** reads the element's instance map directly and never consults the DOM, so it answers for a **detached** element as readily as for a connected one. The name form cannot: `document.querySelectorAll()` does not see a detached element. Pass the detached root as `root` when a name lookup has to reach inside it.
+
+## How the narrowing works
+
+`selectorFor(name)` over-matches on purpose — it lists the responsive spellings of `data-component` too — and **the instance-map read is what removes an inactive declaration**, because a breakpoint-withdrawn component is destroyed _and_ deleted from the map.
+
+A matching element with no instance is skipped, and that is the whole narrowing. There is no mount filter, because it never did that work.
+
+## There is no `getMountedInstance`
+
+The singular [`getInstance()`](getInstance.md) returns one object, so a caller who needs the live one reads `.$isMounted` on it. A second export would only hide that check behind an `undefined` that means two things — no element, no instance, or an instance that is not mounted.

package/skills/studiometa-js-toolkit/references/api/registry/getUnmountedInstances.md

@@ -0,0 +1,46 @@
+# getUnmountedInstances
+
+```ts
+getUnmountedInstances<T extends Base = Base>(name: string, root?: ParentNode): T[]
+getUnmountedInstances<T extends Base = Base>(el: Element): T[]
+```
+
+The instances of a component name that **were built and are not mounted**, in DOM order — or the same on one element, in mount order.
+
+## Usage
+
+```js
+import { getUnmountedInstances } from '@studiometa/js-toolkit';
+
+getUnmountedInstances('Video').length;
+```
+
+## What this population is
+
+It is small and specific. It is what a **reversible** mount strategy leaves behind: `in-view` and `media:` unmount their instance when the condition stops holding and keep it for the crossing back, so the instance stays in the element's map with `$isMounted === false`.
+
+A constructor that succeeded before a failing `mounted()` lands here too.
+
+## What is _not_ here
+
+- **A declaration whose class never arrived.** A lazy entry that has not loaded has no instance at all.
+- **A declaration withdrawn by a breakpoint.** That instance is unmounted _and deleted_ from the map, so the name later declared again builds a new one.
+- **A component still waiting on a mount strategy.** It has never been constructed.
+
+Neither has an instance, so neither can be in a list of them.
+
+## The two overloads
+
+```ts
+(name: string, root?: ParentNode): T[]
+(el: Element): T[]
+```
+
+- **The name form** searches the descendants of `root`, which defaults to the document. `root` is a `ParentNode` and the call is `querySelectorAll`, so it never matches `root` itself.
+- **The element form** reads the element's instance map directly and never consults the DOM, so it answers for a **detached** element as readily as for a connected one. The name form cannot: `document.querySelectorAll()` does not see a detached element. Pass the detached root as `root` when a name lookup has to reach inside it.
+
+## How the narrowing works
+
+`selectorFor(name)` over-matches on purpose — it lists the responsive spellings of `data-component` too — and **the instance-map read is what removes an inactive declaration**, because a breakpoint-withdrawn component is destroyed _and_ deleted from the map.
+
+A matching element with no instance is skipped, and that is the whole narrowing. There is no mount filter, because it never did that work.