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

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.

package/skills/studiometa-js-toolkit/references/guide/going-further/autoloading.md

@@ -0,0 +1,104 @@
+# Autoloading
+
+A page that declares its components in the markup does not have to import them all up front. Map each `data-component` token to a dynamic import and the registry downloads a chunk when an element needs one.
+
+## `registerManifest()`
+
+```js
+import { registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest({
+  Accordion: () => import('./components/Accordion.js'),
+  Slider: () => import('./components/Slider.js'),
+  Map: { load: () => import('./components/Map.js'), mountStrategy: 'visible' },
+});
+```
+
+An entry is either the importer itself, or an object with `load` and an optional `mountStrategy`.
+
+- **One name, one entry**, across eager classes and manifests alike. A token an eager class or an earlier manifest owns gives a `manifest.duplicate-token` warning and is ignored.
+- **No dependency and no bundler knowledge.** The value is a function that returns a promise. `import.meta.glob`, `import.meta.webpackContext` and a generated manifest all produce that shape.
+- **The registry stays the only constructor.** The import ends in `registerComponent(ComponentClass)`.
+- **One import per name, one failure report per name.** A failure emits one `component.load-failed` diagnostic and is never retried.
+- **A class whose `config.name` differs from its token** gives a `registry.lazy-name-mismatch` warning.
+- The class is resolved out of the imported module for you, so a hand-written entry is `Slider: () => import('./Slider.js')` with nothing to unwrap.
+
+## One knob, not two
+
+Deferring the import and deferring the mount are **one decision**:
+
+```
+data-mount  >  manifest entry mountStrategy  >  'eager'
+```
+
+The manifest entry stands in the middle slot for the `config.mountStrategy` of a class that cannot be read yet. Once the class registers, the chain reads `config.mountStrategy` and the entry is deleted from the map.
+
+There is **no `data-load`** and no compatibility shim for it. A page that used `data-load` renames one attribute.
+
+### What that buys
+
+One scheduling algorithm covers both halves. A name resolves to one source, and one controller holds the current decision of the element/component pair. The arrival of the class is a _change of source_, so the pass that replaces a controller turns a spent import trigger into a mount:
+
+- a **one-shot** trigger (`visible`, `idle`, `interaction`) mounts on the import that proved its condition;
+- a **reversible** one (`in-view`, `media:`) is observed again.
+
+An unloaded declaration is invisible to `$query()`, `$closest()`, `$watchChildren()` and `getInstances()`, because nothing is constructed at discovery.
+
+`whenDOMSettled()` covers an **eager** lazy component: the import promise joins the lifecycle-work set only for the eager trigger, so [`swap()`](../../api/dom/swap.md) waits for download, registration and mount — and still never waits on a viewport, an idle callback, an interaction or a media query.
+
+## Generating a manifest from a glob
+
+`defineManifest()` turns a bundler glob into a manifest, deriving each token from the path:
+
+```js
+import { defineManifest, fromMetaGlob } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  }),
+);
+```
+
+- `index.js` falls back to the parent directory name, so `./components/Slider/index.js` is `Slider`.
+- A package-wide `mountStrategy` emits entry wrappers only when it is not `eager`.
+- Duplicate tokens give a warning and keep the first path.
+
+For webpack, [`fromWebpackContext()`](../../api/registry/fromWebpackContext.md) takes an `import.meta.webpackContext` result. Neither adapter adds a bundler dependency — core names none of them.
+
+## Lazy children
+
+`config.components` takes a dynamic import too, and the key supplies the name:
+
+```js
+static config = {
+  name: 'Accordion',
+  components: {
+    AccordionItem: () => import('./AccordionItem.js'),
+    Icon: IconClass,
+  },
+};
+```
+
+`registerComponent()` defers a thunk instead of resolving it, and the value becomes a lazy entry of the same registry under its key. Everything after that is identical to a manifest entry.
+
+- **The key supplies the name**, so a lazy child is a name the registry knows with nothing downloaded — and `on<Child><Event>` resolution works on it immediately.
+- **A manifest can declare the parent only.** A child behind a thunk is its own chunk, so a family splits where the author splits it.
+- **First wins, quietly**, unlike `registerManifest()`. Several parents declaring the same lazy child is the normal case.
+- **The entry gets no `mountStrategy` field.** Until the class arrives the chain is `data-mount > eager`; after it, the usual chain reads the merged config, so a lazy child that is a subclass inherits the strategy of its base.
+- A value written with `class` that does not extend `Base` is reported as `component.invalid-family-declaration`, where it is declared.
+
+## What v3's autoload did that v4 does not need
+
+v3 shipped 1033 source lines of autoload across seven modules. The registry and the mount strategies absorb almost all of it:
+
+| v3                                                     | v4                                                            |
+| ------------------------------------------------------ | ------------------------------------------------------------- |
+| `ComponentLoader.start()` discovery observer           | the one document observer                                     |
+| the four load triggers of `__schedule()`               | `mount-strategies.ts`                                         |
+| per-element and per-record cleanup bookkeeping         | one controller map holding both halves                        |
+| recursive registration of configured children          | one `registerFamily()` loop over `config.components`          |
+| the `ComponentRecord` state machine                    | one `Map<string, Promise<void>>` — the promise _is_ the state |
+| `readEagerTokens` and `<meta name="js-toolkit:eager">` | `data-mount` on the element                                   |
+
+The `children` arrays of a v3 manifest are dead data.

package/skills/studiometa-js-toolkit/references/guide/going-further/handling-diagnostics.md

@@ -0,0 +1,104 @@
+# Diagnostics
+
+Everything the framework recovers from is reported on **one** cancelable event, and nothing in core calls `console.warn()` or `console.error()` directly.
+
+## The protocol
+
+`EVENTS.diagnostic` is `'js-toolkit:diagnostic'`. It carries a `ToolkitDiagnosticDetail`:
+
+| Field       | Type                    | Notes                                             |
+| ----------- | ----------------------- | ------------------------------------------------- |
+| `severity`  | `'warning' \| 'error'`  |                                                   |
+| `code`      | `ToolkitDiagnosticCode` | a namespaced string from `DIAGNOSTICS`            |
+| `message`   | `string`                |                                                   |
+| `component` | `string \| undefined`   | the reporting component's name, when there is one |
+| `error`     | `unknown`               | **required** for `error`, absent for `warning`    |
+
+Every diagnostic starts on its relevant connected element, or on `document` when there is none, and is dispatched with `{ bubbles: true, composed: true, cancelable: true }`.
+
+## Listening
+
+```ts
+import { DIAGNOSTICS, EVENTS, type ToolkitDiagnosticDetail } from '@studiometa/js-toolkit';
+
+declare function monitor(code: string, detail: ToolkitDiagnosticDetail): void;
+document.addEventListener(EVENTS.diagnostic, (rawEvent) => {
+  const event = rawEvent as CustomEvent<ToolkitDiagnosticDetail>;
+  monitor(event.detail.code, event.detail);
+
+  if (event.detail.code === DIAGNOSTICS.responsive.unknownBreakpoint) {
+    event.preventDefault();
+  }
+});
+```
+
+**Dispatch always happens before the default output.**
+
+- An uncancelled **warning** calls `console.warn()` once with exactly `[js-toolkit:<code>] <message>`.
+- An uncancelled **error** calls `reportError(detail.error)` with the original value.
+- `preventDefault()` suppresses that output **only**. It changes no framework decision.
+
+## The codes
+
+`DIAGNOSTICS` is a deeply frozen object, and `ToolkitDiagnosticCode` is the exact union of its strings:
+
+```js
+import { DIAGNOSTICS } from '@studiometa/js-toolkit';
+
+DIAGNOSTICS.component.loadFailed; // 'component.load-failed'
+DIAGNOSTICS.callback.serviceFailed; // 'callback.service-failed'
+DIAGNOSTICS.protocol.lateRegistration; // 'protocol.late-registration'
+```
+
+See the [full list](../../api/diagnostics/DIAGNOSTICS.md).
+
+## Report once, or report and continue
+
+| Behaviour                 | Cases                                                                                                                                                     |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Reported exactly once** | recovered load, mount, invalid-strategy and `Base` lifecycle failures                                                                                     |
+| **Report and continue**   | isolated signal, context subscription and teardown, attribute watcher, service, scheduler tick and task, DOM-update runner and extendable-event callbacks |
+| **Thrown or rejected**    | decorator and manifest-adapter misuse, shared-runtime incompatibility, service startup rollback, caller-owned teardown, `viewTransition()` and `swap()`   |
+
+A scheduled task also **rejects its own promise** with the same value. Direct, caller-owned failures stay throws: they are the caller's to handle, not a channel's.
+
+Warning deduplication is stored in a revisioned shared-runtime slot, keyed by weak owner plus a misuse key, so it works across independently evaluated copies of the package without retaining instances, elements, declarations, runners or manifest inputs.
+
+## Reporting your own
+
+`warn()` and `reportDiagnostic()` are public, and a consumer code is any `'<namespace>.<name>'` string:
+
+```ts
+import { reportDiagnostic, warn } from '@studiometa/js-toolkit';
+
+warn('carousel.no-slides', 'A Carousel with no slide does nothing.', { component: 'Carousel' });
+
+try {
+  JSON.parse('{');
+} catch (error) {
+  reportDiagnostic('carousel.bad-config', 'The config attribute is not valid JSON.', error);
+}
+```
+
+From inside a component, `$warn()` and `$error()` fill the component name in for you:
+
+```js
+this.$warn('carousel.no-slides', 'A Carousel with no slide does nothing.');
+```
+
+## What was removed
+
+`EVENTS.error`, `ToolkitErrorDetail` and `ToolkitErrorStage` are removed with **no alias**. `DIAGNOSTICS`, `ToolkitDiagnosticSeverity`, `ToolkitDiagnosticCode` and `ToolkitDiagnosticDetail` replace them.
+
+## In tests
+
+Asserting on `console.warn` cannot see the code, the severity or the reporting component, and it passes for the wrong diagnostic. [`captureDiagnostics()`](../../api/test/index.md) reads the channel instead — and cancelling each event as it arrives is the same act that silences the console, so collecting and silencing are one step:
+
+```js
+import { captureDiagnostics } from '@studiometa/js-toolkit/test';
+
+const diagnostics = captureDiagnostics();
+// … exercise the component
+expect(diagnostics.codes).toContain('ref.mismatch');
+diagnostics.stop();
+```