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

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

@@ -0,0 +1,214 @@
+# Test helpers
+
+```js
+import { mount, settle, waitFor } from '@studiometa/js-toolkit/test';
+```
+
+Nine helpers a component test cannot write for itself.
+
+## Why the subpath exists
+
+**The timing recipe is not derivable.** "Has this component mounted and finished its writes?" is answered by five rounds of a 10 ms timer followed by `defaultScheduler.whenIdle()`, and those two numbers encode the mount observer's delivery latency and the scheduler's lane order.
+
+Neither half works alone: `whenIdle()` can resolve before the observer has reported the element, and a timer can return between two lanes. `defaultScheduler` and `nextFrame` were already public, so the pieces shipped and the recipe did not.
+
+**It depends on no test framework.** Nothing in the module imports a runner, an assertion library or a spy; it reads the DOM and the scheduler only, so it runs under Vitest, under Playwright and on a plain browser page. That is also why it is not on the root barrel: a page has no use for it, and the root export count stays what it was.
+
+## `mount()`
+
+```ts
+mount(html: string): Promise<HTMLElement>
+```
+
+Inserts the markup and resolves once the eager components have mounted.
+
+```js
+const root = await mount(`
+  <button data-component="Counter">
+    <span data-ref="output">0</span>
+  </button>
+`);
+```
+
+**It returns the wrapper `div` it created**, never the markup's own root, so a fragment of several siblings works and `querySelector()` has a stable handle. `.firstElementChild` is one property away.
+
+## `settle()`
+
+```ts
+settle(): Promise<void>
+```
+
+Resolves once the framework has caught up — the same recipe `mount()` uses.
+
+**Not for a transition's end state**
+
+`settle()` is generous rather than deterministic. See [Transitions](#transitions) below.
+
+## `frames()`
+
+```ts
+frames(count?: number): Promise<void>
+```
+
+Awaits animation frames. `nextFrame()` with a count.
+
+## `waitFor()`
+
+```ts
+waitFor<T>(predicate: () => T | false | null | undefined, options?: { timeout?: number; message?: string }): Promise<T>
+```
+
+Polls until the predicate is truthy and **returns that value**, which makes the same call either a guard or a query:
+
+```js
+// a guard
+await waitFor(() => el.classList.contains('is-open'));
+
+// a query
+const panel = await waitFor(() => root.querySelector('.panel'));
+```
+
+It polls on a **10 ms cadence and drains the scheduler between attempts**. On timeout it throws — with the caller's `message`, or one naming the timeout.
+
+## `captureDiagnostics()`
+
+```ts
+captureDiagnostics(target?: EventTarget): { codes: string[]; entries: ToolkitDiagnosticDetail[]; stop(): void }
+```
+
+```js
+const diagnostics = captureDiagnostics();
+// … exercise the component
+expect(diagnostics.codes).toContain('ref.mismatch');
+diagnostics.stop();
+```
+
+**It reads the channel, and asserting on `console.warn` does not.** A recovered failure is reported on a cancelable event whose _default behaviour_ is the console line; a spy on that line cannot see the code, the severity or the reporting component, and it passes for the wrong diagnostic.
+
+The helper **cancels each event as it arrives**, which is the same act that suppresses the sink — so collecting and silencing are one step, not two, and no spy is involved.
+
+`target` defaults to `document`, which sees everything a connected element reported, because diagnostics bubble and compose.
+
+## `recordEvents()`
+
+```ts
+recordEvents(target: EventTarget, ...types: string[]): { events: { type: string; detail: unknown }[]; stop(): void }
+```
+
+```js
+const recording = recordEvents(el, 'open', 'opened');
+
+el.querySelector('button').click();
+
+await waitFor(() => recording.events.length === 2);
+expect(recording.events.map(({ type }) => type)).toEqual(['open', 'opened']);
+expect(recording.events[1].detail).toEqual({ height: 120 });
+
+recording.stop();
+```
+
+**It keeps the order and the payloads.** A component's contract is "`open` came before `opened`, and `opened` carried the height it measured", and a call-counting spy throws both away.
+
+Recording several types into one array is the only place their **relative order** is visible. The richer `{ type, detail }` shape ships because a caller wanting names alone can map, and the reverse is impossible.
+
+`$emit` dispatches synchronously but is almost never _called_ synchronously, so the count is awaited with `waitFor`, not read.
+
+## `countRequestedFrames()`
+
+```ts
+countRequestedFrames(during: () => Promise<void> | void): Promise<number>
+```
+
+```js
+const frames = await countRequestedFrames(async () => {
+  for (let i = 0; i < 10; i += 1) el.dispatchEvent(new Event('scroll'));
+  await settle();
+});
+expect(frames).toBeLessThan(3);
+```
+
+**It patches a global, and says so.** It swaps `globalThis.requestAnimationFrame` for a counting wrapper that forwards to the original, and restores it in a `finally` — so it comes back whether `during` returns or throws.
+
+It is here despite the patch because the assertion it serves, "this did not schedule a frame per event", has no other seam: the framework's own scheduler makes the calls, so there is nothing of the component's for a spy to sit on.
+
+**Two concurrent calls would nest their wrappers. Do not.**
+
+## `resetDom()`
+
+```ts
+resetDom(): Promise<void>
+```
+
+Empties the document body and lets the teardown run.
+
+## `resetRegistry()`
+
+```ts
+resetRegistry(): void
+```
+
+**The inverse `registerComponent()` deliberately lacks.** A page registers once and keeps it; a test suite is the one caller for which a page-wide registry surviving `resetDom()` is wrong, and the workaround it forces is a counter minting `Widget-1`, `Widget-2`.
+
+It is **coarse on purpose**: the element→controller map is a `WeakMap`, so it cannot be enumerated, nothing can walk it to dispose live triggers, and a `querySelectorAll()` sweep would still miss detached elements. Clearing everything works because the mutation-observer path already disposes a controller as its element leaves the DOM — **hence the call belongs after `resetDom()`**.
+
+Two things it does not do: it cannot clear that `WeakMap`, so empty the DOM first; and it does not narrow the attribute filter the shared observer built from everything ever registered — an extra watched attribute costs a reconciliation pass that finds no owner, and nothing more.
+
+**Never in an `afterEach`**
+
+Spec files register at module top level, so this in an `afterEach` silently unregisters everything for every later test in the file. Put it in an `afterAll`, or call it and register again straight away:
+
+```js
+afterEach(async () => {
+  await resetDom();
+  resetRegistry();
+  registerComponents(Subject, Emitter);
+});
+```
+
+## Transitions {#transitions}
+
+**A transition's end state is asserted by polling, never by `settle()`.** A method that starts a transition does not hand it back, and a kept end state lands only after `nextFrame()`, the `from` and `active` states, and either a `transitionend` or one more frame. `settle()` is generous rather than deterministic, which is a flake that passes alone and fails under load.
+
+**Polling for an _absence_ is wrong** for the mirror-image reason: `leaveTransition()` clears the other direction's `to` state synchronously, so the poll passes before anything has happened.
+
+## What is deliberately not in it
+
+An instance lookup — [`getInstance()`](../registry/getInstance.md) and [`getInstances()`](../registry/getInstances.md) on the root barrel answer it — fetch stubs, and pointer sequences. Each is either specific to one spec or already served by `vi.fn()` and `@vitest/browser`'s `userEvent`.
+
+## A full example
+
+```js
+import { afterAll, expect, test } from 'vitest';
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+import { mount, resetDom, resetRegistry, waitFor } from '@studiometa/js-toolkit/test';
+
+class Counter extends Base {
+  static config = { name: 'Counter', refs: ['output'] };
+
+  count = 0;
+
+  onClick() {
+    this.count += 1;
+    this.$refs.output.textContent = String(this.count);
+  }
+}
+
+registerComponent(Counter);
+
+test('it counts clicks', async () => {
+  const root = await mount(`
+    <button data-component="Counter">
+      <span data-ref="output">0</span>
+    </button>
+  `);
+
+  root.querySelector('button').click();
+
+  await waitFor(() => root.querySelector('[data-ref="output"]').textContent === '1');
+});
+
+afterAll(async () => {
+  await resetDom();
+  resetRegistry();
+});
+```

package/skills/studiometa-js-toolkit/references/guide/concepts/attribute-grammar.md

@@ -0,0 +1,93 @@
+# The attribute grammar
+
+Every attribute the framework reads has one shape, and one module owns it:
+
+```
+data-<namespace>[:<qualifier>[.<part>…]]
+```
+
+## A namespace is a whole name
+
+There are two kinds.
+
+**A fixed namespace is written in a module** — `data-component`, `data-mount`, `data-ref`, and in `@studiometa/ui` `data-on`, `data-track`, `data-bind`.
+
+**A generated namespace comes from a declaration.** Every declared option owns the one built for it, so `columns` owns `data-option-columns`, and `data-option-` is a namespace _family_ rather than a namespace.
+
+An option's name is therefore **inside** its namespace, never a qualifier of a shared one: `data-option-columns:s`, never `data-option:columns:s`.
+
+## The colon has one meaning
+
+It selects one member of the vocabulary the namespace declares.
+
+`data-option-columns:s` and `data-on:click` are not two meanings of the separator. They differ in what the _namespace_ is — one already-declared option against an open family of bindings — and in both cases the colon picks one member.
+
+So **an attribute the framework reads holds at most one colon**, which is a rule you can check, and `attributes.spec.ts` does.
+
+`data-on:click:s` is not an attribute. Responsiveness belongs to declared options, the only vocabulary that is finite, ordered, and has a value to resolve through a cascade.
+
+## 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 a vocabulary the caller 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.**
+
+## The kind of namespace decides the mechanism
+
+What matters is whether the _whole set of names_ can be listed in advance — not whether the qualifier vocabulary is finite.
+
+| Namespace               | Names                                       | Mechanism                               |
+| ----------------------- | ------------------------------------------- | --------------------------------------- |
+| `data-option-columns`   | `attribute × breakpoint` — enumerable       | registered in the one `attributeFilter` |
+| `data-component`        | fixed plus one per breakpoint — enumerable  | registered in the one `attributeFilter` |
+| `data-on`, `data-track` | any DOM event — open                        | `watchAttributeNamespace()`             |
+| `data-bind`             | finite head, open name — **not** enumerable | `watchAttributeNamespace()`             |
+
+A generated namespace is enumerable _because_ it comes from a declaration, which is why the page-wide filter stays precise and no option costs a second observer.
+
+`data-bind` 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 — so the names cannot be listed and the namespace must be watched. Validating a finite head is an **independent** capability, available to a watched namespace and a registered one alike.
+
+## The two escape hatches
+
+`attributeFilter` takes exact names and the DOM has no wildcard, so the engine cannot see an attribute the framework cannot name.
+
+### `watchAttributes(element, callback)`
+
+Observes **every** attribute of that element, through a second, unfiltered observer. The page pays for the elements that ask.
+
+- **The caller owns it.** It returns one idempotent cleanup and knows nothing about `Base`.
+- **The records join the shared queue**, so they are drained wherever the engine drains its own, `whenDOMSettled()` included.
+- **A callback runs after the framework work of the batch.**
+- **Changes are coalesced**, with the rule of `option<Name>Changed()`.
+- **The payload is one object**: `{ name, value, previousValue }`, with raw attribute strings and `null` for an absent attribute. It covers the element's whole attribute set, framework names included, so a caller narrows by prefix.
+
+See [`watchAttributes()`](../../api/dom/watchAttributes.md).
+
+### `watchAttributeNamespace(element, namespace, bind, options?)`
+
+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.
+
+- **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: **added** attaches with nothing to release, **changed** releases then attaches, **removed** releases with nothing to attach. A memoised parse cannot express the middle one — and rewriting an attribute in place is not hypothetical, since `swap({ mode: 'morph' })` does it.
+- **The binder returns that binding's release**, or nothing when the declaration produced no binding, 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.
+- **An optional finite vocabulary validates the qualifier's head.** Given one, 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`.
+- **It is built on `watchAttributes()`**, so `whenDOMSettled()`, and therefore `swap()`, covers a namespaced declaration the way it covers a mount.
+- `Base` has no wrapper and owns no cleanup. A component calls it from `mounted()` and returns its cleanup.
+
+See [`watchAttributeNamespace()`](../../api/dom/watchAttributeNamespace.md).
+
+To watch a subtree, character data, or a node the framework does not know, use [`useMutation()`](../../api/services/useMutation.md).
+
+## The one module that owns the vocabulary
+
+`attributes.ts` owns every name in the filter and every test against one: `data-component`, `data-mount`, `data-ref`, the `data-option-` prefix with `optionAttributeFor()` and `isOptionAttribute()`, the responsive separator, and the coalescing rule. **It imports nothing from core.**
+
+`component-declarations.ts` consumes that vocabulary and reads the DOM through the responsive cascade.
+
+## The coalescing rule, written once
+
+Several writes to one attribute in a batch give **one** change, from the value before the first write to the value at the end of the batch. A write that ends where it started is not a change.
+
+`rememberPreviousValue()` and `isNetChange()` hold the rule. The comparison uses **raw strings**, so a breakpoint crossing and an attribute write are the same kind of event.

package/skills/studiometa-js-toolkit/references/guide/concepts/mutation-engine.md

@@ -0,0 +1,71 @@
+# The mutation engine
+
+One internal engine owns **one** MutationObserver, for component discovery, lifecycle, mount strategies, ref invalidation and declared options.
+
+## What it watches
+
+Its `attributeFilter` holds:
+
+- the fixed framework attributes — `data-component`, `data-mount`, `data-ref`;
+- the exact responsive `data-component:<breakpoint>` spellings of the configured breakpoints;
+- the option names of every registered config, and the negated spelling of each boolean option, with one scoped spelling per breakpoint.
+
+Writes to `class`, `style` and ARIA attributes create **no record**. That is the point of an exact filter: the attributes a page churns are not the attributes the framework reads.
+
+**The `attributeFilter` and the relevance test of the engine are one set.** A record is relevant if and only if it names an attribute the observer holds. A change to that set drains the records of the previous filter first.
+
+## The fixed order of a batch
+
+The engine snapshots the membership of a removed subtree when the records enter its queue, then processes each batch in a fixed order:
+
+1. **unmount** removed subtrees and dispose their strategies;
+2. **reconcile** the final plain and scoped `data-component` attributes, and `data-mount`;
+3. **deliver** coalesced declared-option changes to the mounted instances that stay;
+4. **scan** added subtrees once and schedule their registered component tokens;
+5. **report** coalesced attribute changes to the elements that asked to watch them.
+
+Teardown before setup, and the elements that stay hear about their options before anything new is built. Step 5 is last, which is why a component that stops its watcher during the same batch in which its own declaration is withdrawn hears nothing about the attribute change.
+
+## What each transition means
+
+| Transition                                                | Effect                                                                    |
+| --------------------------------------------------------- | ------------------------------------------------------------------------- |
+| the element is **disconnected**                           | `$unmount()`, and the instance stays on its element for a later insertion |
+| a component token is **removed** from a connected element | `$unmount()`, then the instance is dropped from the element               |
+| a breakpoint **withdraws** a declaration                  | the same: unmount, then drop                                              |
+| the node is **moved**                                     | one unmount and one mount cycle, same identity                            |
+
+The token later declared again gives a **new** instance, because the DOM no longer declared that identity.
+
+## Ref invalidation
+
+Ref lookups are cached, and the cache is invalidated by a counter this observer increases. Reading that counter drains the pending records with `takeRecords()`, so a read is current even inside the same task as the mutation. Detached elements are never cached.
+
+That is the whole implementation of "refs are live", and it is why there is no `$update()`.
+
+## `whenDOMSettled()`
+
+It is the completion boundary for morphing, fetch updates and breakpoint crossings. It:
+
+- drains the pending records;
+- follows the mutation chains of eager lifecycle work, so markup a `mounted()` inserts is covered too;
+- resolves after the eager mounts and the teardown.
+
+It does **not** wait for visibility, interaction, idle or media conditions, and it does **not** await the promises returned by `mounted()`. An eager lazy component _is_ covered: the import promise joins the lifecycle-work set for the eager trigger only.
+
+## The lanes it runs in
+
+Framework work runs through the scheduler's **background** lane: a 5 ms slice per turn, posted through `scheduler.postTask({ priority: 'background' })` with a `MessageChannel` fallback. Background work alone never requests an animation frame.
+
+Breakpoint work runs there too, so `whenDOMSettled()` includes the teardown, import and mount work of a crossing.
+
+See [The scheduler](../going-further/scheduling-work.md).
+
+## Watching something else
+
+The engine sees only what it can name. Two opt-ins cover the rest, and both are described in [The attribute grammar](attribute-grammar.md):
+
+- [`watchAttributes()`](../../api/dom/watchAttributes.md) — every attribute of one element, through a second observer, with the records joining the same queue.
+- [`watchAttributeNamespace()`](../../api/dom/watchAttributeNamespace.md) — a namespace whose names cannot be enumerated, with keyed bindings and per-declaration teardown.
+
+For a subtree, character data, or a node the framework does not know, [`useMutation()`](../../api/services/useMutation.md) is a general `MutationObserver` as a service. It delivers on the platform's timing; a subscriber that needs the framework's order awaits `whenDOMSettled()` in its callback.

package/skills/studiometa-js-toolkit/references/guide/concepts/philosophy.md

@@ -0,0 +1,78 @@
+# Philosophy
+
+> **The registry is the framework. The DOM is the component tree.**
+
+An instance exists because its element is in the document and its class is registered. Nothing else creates or unmounts an instance. Parent and child are DOM ancestry only, never ownership. Components find each other through queries and events.
+
+## Five objectives
+
+1. **Components are independent.** No component constructs another.
+2. **One registry.** One map from name to source, and one scheduling algorithm.
+3. **The DOM drives mount and unmount.** One MutationObserver, and the element is the truth.
+4. **Parents listen to child events.** A bubbling `CustomEvent` is the upward channel.
+5. **Children announce their existence to parents.** A mount is an announcement, not a registration.
+
+## The three forks
+
+| Fork                | Decision                                                                                                                                        |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Mount primitive** | `data-component` and one record-based MutationObserver. No tag names, no arbitrary selectors, no custom elements, no directive system.          |
+| **Shared state**    | provide/inject in core, with the shape of Vue and the mechanics of the WICG context protocol. `provideRootContext()` covers the page-wide case. |
+| **Child events**    | The `on<Child><Event>` method names stay. Delegation resolves them against the names in `config.components`.                                    |
+
+Custom elements were considered as the mount and lifecycle primitive and refused. So was a separate directive registry: a behaviour is a component on the one registry, so nothing more is needed.
+
+## What was removed, and what replaces it
+
+| Removed                                                        | Replacement                                                               |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `$parent`, `$children`, `$root`, `createApp()`                 | `$query()`, `$closest()`, `$watchChildren()`, `registerComponent()`       |
+| `$update()`                                                    | nothing — refs are live                                                   |
+| `config.emits`                                                 | the `$emits` props type, which leaves no runtime trace                    |
+| `withExtraConfig()`                                            | a class, since `$config` merges along the prototype chain                 |
+| `withMountWhenInView` and friends                              | [mount strategies](../going-further/mount-strategies.md)            |
+| `data-load` and `loadStrategy`                                 | one knob: `data-mount`                                                    |
+| `withGroup`                                                    | `provideRootContext()` and `createGroup()`                                |
+| `LoadService`                                                  | nothing — it was not ported                                               |
+| `domScheduler`, `SmartQueue`, the `RafService` loop            | [one scheduler](../going-further/scheduling-work.md)                |
+| `EVENTS.error` and its detail types                            | [one diagnostic protocol](../going-further/handling-diagnostics.md) |
+| `tween` and `animate`                                          | not shipped — a separate `ui-animation` package                           |
+| the `<tk-name>` tag sugar and arbitrary-selector registrations | `data-component` only                                                     |
+
+`config.use` and `config.siblings` are not planned.
+
+## Why "one" keeps recurring
+
+Three subsystems of v3 each had their own copy of the same work. v4 replaces each set with one.
+
+**One registry** replaces three mounting systems: the global registry observer, `ChildrenManager` and the autoload loader. A name resolves to one source, and one controller holds the current decision for an element/component pair. The arrival of a lazy class is a _change of source_, which is why an import trigger and a mount trigger are the same code.
+
+**One mutation engine** owns one MutationObserver for component discovery, lifecycle, mount strategies, ref invalidation and declared options. Its `attributeFilter` and its relevance test are the same set, so a record is relevant if and only if it names an attribute the observer holds.
+
+**One scheduler** is the clock. `RafService` subscribes to the tick instead of owning a loop; the scroll service coalesces into one `read` per frame; the view-transition helper batches within a flush. No service owns a loop.
+
+## Sugar is never a requirement
+
+Every decorator is a thin wrapper over a function API that works without it, because no engine ships stage-3 decorators. A page loaded from an ESM CDN with no build step keeps `registerComponent`, `$provide`, `$watchChildren`, `$read`, `$write` and the `on<Child><Event>` names.
+
+The same principle sets the limit of the sugar. A mixin names **one** hook per class; `on<Event>` names one handler per class. A component whose subscriptions are one per markup declaration has no method to name and no fixed count, so it subscribes itself and returns the release from `mounted()`. Reaching for that deliberately is cheaper than discovering that a hook cannot be dynamic.
+
+## Inputs and state are different things
+
+An option is an **input**. `$options` is a read-only view whose every property derives its value from the element and the viewport on access. Refs are live for the same reason: the DOM is the source, so reading it is the honest implementation and a cache that has to be refreshed is not.
+
+What follows from that: to change what the DOM says, write the attribute — the same statement the markup makes. To keep what the component has worked out, keep a field. The two are never the same value.
+
+## Failures are a channel, not a print
+
+Everything the framework recovers from is dispatched as one cancelable event before any console output, and nothing in core calls `console.warn()` or `console.error()` directly. Monitoring can read every code and suppress the noise without changing a single framework decision.
+
+Failures a **caller** owns stay throws and rejections: decorator misuse, a manifest adapter given the wrong shape, `swap()`, `viewTransition()`. A channel is for what the framework decided to survive.
+
+## Read next
+
+- [The registry](the-registry.md) — how one map and one controller cover eager, lazy and conditional mounting.
+- [The attribute grammar](attribute-grammar.md) — one shape for every attribute the framework reads.
+- [The mutation engine](mutation-engine.md) — the fixed order of one batch.
+
+The full design document and the decision record live in the repository: [DESIGN.md](https://github.com/studiometa/js-toolkit/blob/main/packages/js-toolkit/DESIGN.md) states what v4 does, [RATIONALE.md](https://github.com/studiometa/js-toolkit/blob/main/packages/js-toolkit/RATIONALE.md) states why, which options were refused, and what the measurements are.

package/skills/studiometa-js-toolkit/references/guide/concepts/the-registry.md

@@ -0,0 +1,110 @@
+# The registry
+
+One registry replaces the three mounting systems of v3: the global registry observer, `ChildrenManager` and the autoload loader.
+
+## The entry
+
+```
+RegistryEntry = {
+  name,
+  source: constructor | lazy loader (manifest entry),
+  mountStrategy,  // when to mount each instance
+}
+```
+
+- `registerComponent(Ctor)` registers an **eager** entry.
+- `registerManifest(…)` registers **lazy** entries in the same map.
+- A thunk in `config.components` becomes a lazy entry under its key.
+
+**One name gives one entry**, as with `customElements.define()`. A collision gives a `registry.conflict` warning and the entry is ignored — except for a lazy child declared by several parents, which is the normal case and wins quietly.
+
+## The controller
+
+**One element and component pair gives one controller.** The controller holds the strategy of the pair and the source it was scheduled against.
+
+That single object is what makes eager, lazy and conditional mounting one algorithm:
+
+- The arrival of a lazy class is a **change of source**, so the pass that replaces a controller turns a spent import trigger into a mount.
+- A trigger stands down without a teardown of its own: a controller marks itself spent, a spent controller is not the current pair, and so a second trigger is inert. The teardown runs from the ordinary controller replacement.
+- Controller identity guards a queued callback of a disposed strategy.
+
+There is no `loadStrategy` and no `data-load`. Deferring the import and deferring the mount are one decision:
+
+```
+data-mount  >  manifest entry mountStrategy  >  config.mountStrategy  >  'eager'
+```
+
+## What the registry constructs, and what it does not
+
+**The registry is the only code that constructs an instance.** `ChildrenManager` is gone and constructs nothing, because it does not exist. Autoload never touches `new`, the instance map, or a mount hook — an import ends in `registerComponent(ComponentClass)` and then the ordinary pipeline runs.
+
+`registerComponent()` walks `config.components` in one `registerFamily()` loop, so one call covers a whole tree. The recursive registration of v3's manifest `children` arrays is dead data.
+
+## Where the instances live
+
+An element publishes its instances under `Symbol.for('@studiometa/js-toolkit/instances')`. It is **not public API** — the four lookups are, and between them they express every read the map answers.
+
+In a console, one line reads it:
+
+```js
+$0[Symbol.for('@studiometa/js-toolkit/instances')];
+```
+
+### The four lookups
+
+```js
+getMountedInstances('Dialog'); // the live ones
+getInstances('Dialog', section); // every one built in a region
+getUnmountedInstances('Dialog'); // built, then stood down
+getInstance(el, 'Dialog'); // the one on this element, mounted or not
+getInstances(el); // everything on one element
+```
+
+They derive the answer from the DOM and keep **no registry of instances**.
+
+- **The name says which population it answers.** `getInstances()` returns every instance that exists; `getMountedInstances()` is the safe list to call a method on; `getUnmountedInstances()` is what a reversible `in-view` or `media:` strategy has stood down, plus a construct-then-mount-failure.
+- **A matching element with no instance is skipped, and that is the whole narrowing.** `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.
+- **There is no `getMountedInstance`.** The singular returns one object; a caller reads `.$isMounted` on it.
+- `root` is a `ParentNode` and the call is `querySelectorAll`, so an element root searches its **descendants** and never matches itself.
+- The element overload is the only form that reaches a **detached** element, since `querySelectorAll()` does not see one.
+
+## Responsive declarations
+
+The plain `data-component` token set is always active. One responsive set is added with the spelling of responsive options:
+
+```html
+<div
+  data-component="Action Analytics"
+  data-component:xxs="MobileMenu MobileSearch"
+  data-component:m="DesktopMenu DesktopSearch"></div>
+```
+
+- 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. An empty value is a stop: `data-component:s="TabletFeature" data-component:l=""` runs `TabletFeature` at `s` and `m`, and removes it at `l`.
+- The effective declaration is the **union** of the unconditional set and the selected responsive set, without duplicates.
+- A crossing compares that effective set against the element's current state. A shared name keeps its controller and its instance. A name no longer declared is unmounted and dropped from the element, so a crossing back gives a new identity. A new name enters the normal pipeline, so mount strategies, `data-mount`, lazy entries and lifecycle events keep their meaning. An inactive lazy declaration imports nothing.
+- The document observer registers the exact `data-component:<breakpoint>` names and replaces that slice of the filter after `setBreakpoints()`.
+- 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()` includes the teardown, import and mount work of a crossing.
+- A suffix naming no configured breakpoint is ignored with one warning. That includes the v3 list syntax `data-component:xxs:xs:s`. There is no range form and no breakpoint-list form.
+
+## The matching surface
+
+It is smaller than v3's, on purpose. Only plain and configured scoped `data-component` declarations are discovered, with whitespace-separated tokens for several components on one element.
+
+Removed: the `<tk-name>` tag sugar, the breakpoint-list suffixes, and the lowercase arbitrary-selector registrations.
+
+`data-component` still improves native elements — `<form>`, `<a>`, `<details>` and table markup all take it.
+
+## Duplicate copies of the package
+
+`shared-runtime.ts` owns `globalThis[Symbol.for('@studiometa/js-toolkit/runtime')]` and gives each subsystem a typed slot with a revision. Independently evaluated copies reuse the canonical `defaultScheduler`, the registry maps and controllers, the DOM mutation observer and queue, the root-context state, the breakpoint state and every built-in service cache.
+
+`Base` carries a separate inherited `Symbol.for` brand on its constructor, so family and imported-module resolution recognise a component from another copy. An incompatible root or slot revision throws. This is same-realm coordination only, and a `createService()` or `perTarget()` call of a consumer stays owned by that consumer.
+
+## What is not built
+
+- **Composing and overriding manifests.** v4 is first-wins-and-warn. An `{ override: true }` option is about five lines; the decision is the expensive part.
+- **A scoped `root`.** The registry is document-wide by construction, and no consumer has asked.
+- **Informational manifest metadata** (`packageName`, `subpath`, `exportName`, `group`, `styles`, `integrations`). It belongs in the output type of the generator, not in core.
+- **A `data-load` compatibility shim.** A page that used `data-load` renames one attribute.