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

package/dist/utils/history.js

@@ -1,4 +1,4 @@
-//#region src/utils/history.ts
+// src/utils/history.ts
 /**
 * Set one param, recursing into arrays and objects as bracketed names.
 *
@@ -60,7 +60,6 @@ function historyPush(options, data = {}, title = "") {
 function historyReplace(options, data = {}, title = "") {
 	history.replaceState(data, title, urlFor(options));
 }
-//#endregion
 export { historyPush, historyReplace, objectToURLSearchParams };
 
 //# sourceMappingURL=history.js.map

package/dist/utils/is.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/is.d.ts
 /** Type guards for the values a component reads from the DOM or its options. */
 /**
  * Whether a value is `null`.
@@ -39,5 +38,4 @@ declare function isFunction(value: unknown): value is (...args: unknown[]) => un
  * @link https://js-toolkit-v4.studiometa.dev/utils/is.html#isobject
  */
 declare function isObject(value: unknown): value is Record<string, unknown>;
-//#endregion
 export { isBoolean, isDefined, isFunction, isNull, isNumber, isObject, isString };

package/dist/utils/is.js

@@ -1,4 +1,4 @@
-//#region src/utils/is.ts
+// src/utils/is.ts
 /** Type guards for the values a component reads from the DOM or its options. */
 /**
 * Whether a value is `null`.
@@ -53,7 +53,6 @@ function isFunction(value) {
 function isObject(value) {
 	return Object.prototype.toString.call(value) === "[object Object]";
 }
-//#endregion
 export { isBoolean, isDefined, isFunction, isNull, isNumber, isObject, isString };
 
 //# sourceMappingURL=is.js.map

package/dist/utils/load.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/load.d.ts
 /** Loading a resource, as a promise that settles when the browser is done with it. */
 /**
  * Load an image, resolved once its bitmap is decoded.
@@ -42,5 +41,4 @@ declare function loadScript(src: string, attributes?: Record<string, string>): P
 declare function loadLink(href: string, attributes: {
   rel: string;
 } & Record<string, string>): Promise<HTMLLinkElement>;
-//#endregion
 export { loadImage, loadLink, loadScript };

package/dist/utils/load.js

@@ -1,5 +1,5 @@
 import { getSharedRuntimeSlot } from "../shared-runtime.js";
-//#region src/utils/load.ts
+// src/utils/load.ts
 /** Loading a resource, as a promise that settles when the browser is done with it. */
 /**
 * The pending loads for the elements that go in `<head>`, keyed by the URL the
@@ -138,7 +138,6 @@ function loadLink(href, attributes) {
 	state.links.set(key, promise);
 	return promise;
 }
-//#endregion
 export { loadImage, loadLink, loadScript };
 
 //# sourceMappingURL=load.js.map

package/dist/utils/maths.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/maths.d.ts
 /** Time-based functions take elapsed milliseconds. */
 /**
  * The default inertia factor.
@@ -118,5 +117,4 @@ interface SpringOptions {
  * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#spring
  */
 declare function spring(targetValue: number, currentValue: number, currentVelocity: number, elapsed: number, options?: SpringOptions): [value: number, velocity: number];
-//#endregion
 export { DEFAULT_DAMP_FACTOR, INERTIA_FRAME, MAX_SPRING_RATIO, SpringOptions, clamp, clamp01, clampDampFactor, createRange, damp, decayOver, fold, inertiaDecay, inertiaFinalValue, inertiaStep, inertiaTimeConstant, lerp, map, mean, round, spring, wrap };

package/dist/utils/maths.js

@@ -1,4 +1,4 @@
-//#region src/utils/maths.ts
+// src/utils/maths.ts
 /** Time-based functions take elapsed milliseconds. */
 /**
 * The default inertia factor.
@@ -171,7 +171,6 @@ function spring(targetValue, currentValue, currentVelocity, elapsed, options = {
 	if (Math.abs(targetValue - value) < precision && Math.abs(velocity) < precision) return [targetValue, 0];
 	return [value, velocity];
 }
-//#endregion
 export { DEFAULT_DAMP_FACTOR, INERTIA_FRAME, MAX_SPRING_RATIO, clamp, clamp01, clampDampFactor, createRange, damp, decayOver, fold, inertiaDecay, inertiaFinalValue, inertiaStep, inertiaTimeConstant, lerp, map, mean, round, spring, wrap };
 
 //# sourceMappingURL=maths.js.map

package/dist/utils/memo.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/memo.d.ts
 /** A memoised function with explicit cache invalidation. */
 interface Memo<Args extends unknown[], Value> {
   (...args: Args): Value;
@@ -12,5 +11,4 @@ interface Memo<Args extends unknown[], Value> {
  * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#memo
  */
 declare function memo<Args extends [] | [key: unknown], Value>(fn: (...args: Args) => Value): Memo<Args, Value>;
-//#endregion
 export { Memo, memo };

package/dist/utils/memo.js

@@ -1,4 +1,4 @@
-//#region src/utils/memo.ts
+// src/utils/memo.ts
 /** Whether a value can be a `WeakMap` key. */
 function isWeakKey(value) {
 	return typeof value === "object" && value !== null || typeof value === "function";
@@ -29,7 +29,6 @@ function memo(fn) {
 	};
 	return cached;
 }
-//#endregion
 export { memo };
 
 //# sourceMappingURL=memo.js.map

package/dist/utils/noop.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/noop.d.ts
 /** Placeholders for an optional callback, so a caller never branches on one. */
 /**
  * Do nothing, whatever it is called with.
@@ -10,5 +9,4 @@ declare function noop(): void;
  * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#noopvalue
  */
 declare function noopValue<T>(value: T): T;
-//#endregion
 export { noop, noopValue };

package/dist/utils/noop.js

@@ -1,4 +1,4 @@
-//#region src/utils/noop.ts
+// src/utils/noop.ts
 /** Placeholders for an optional callback, so a caller never branches on one. */
 /**
 * Do nothing, whatever it is called with.
@@ -12,7 +12,6 @@ function noop() {}
 function noopValue(value) {
 	return value;
 }
-//#endregion
 export { noop, noopValue };
 
 //# sourceMappingURL=noop.js.map

package/dist/utils/random.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/random.d.ts
 /** Random values, in the ranges a component describes. */
 /**
  * A random number between the two bounds, the second defaulting to `0`.
@@ -20,5 +19,4 @@ declare function randomInt(a: number, b?: number): number;
  */
 declare function randomItem<T>(items: readonly T[]): T | undefined;
 declare function randomItem(items: string): string | undefined;
-//#endregion
 export { random, randomInt, randomItem };

package/dist/utils/random.js

@@ -1,4 +1,4 @@
-//#region src/utils/random.ts
+// src/utils/random.ts
 /** Random values, in the ranges a component describes. */
 /**
 * A random number between the two bounds, the second defaulting to `0`.
@@ -22,7 +22,6 @@ function randomInt(a, b = 0) {
 function randomItem(items) {
 	return items.length > 0 ? items[randomInt(0, items.length - 1)] : void 0;
 }
-//#endregion
 export { random, randomInt, randomItem };
 
 //# sourceMappingURL=random.js.map

package/dist/utils/scroll-lock.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/scroll-lock.d.ts
 /**
  * Stop an element scrolling until every holder releases it.
  *
@@ -23,5 +22,4 @@
  * @link https://js-toolkit-v4.studiometa.dev/utils/scroll.html#lockscroll
  */
 declare function lockScroll(target?: HTMLElement): () => void;
-//#endregion
 export { lockScroll };

package/dist/utils/scroll-lock.js

@@ -1,5 +1,5 @@
 import { getSharedRuntimeSlot } from "../shared-runtime.js";
-//#region src/utils/scroll-lock.ts
+// src/utils/scroll-lock.ts
 /**
 * One counter per locked element, shared across evaluated copies of the
 * package: there is one scroll per document, so two copies must count the same
@@ -52,7 +52,6 @@ function lockScroll(target = document.documentElement) {
 		target.style.overflow = current.restore;
 	};
 }
-//#endregion
 export { lockScroll };
 
 //# sourceMappingURL=scroll-lock.js.map

package/dist/utils/scrollTo.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/scrollTo.d.ts
 /** Where a scroller stands on both axes, in pixels from the start. */
 interface ScrollPosition {
   left: number;
@@ -83,5 +82,4 @@ declare function scrollPosition(target: ScrollToTarget, options?: ScrollPosition
  * @link https://js-toolkit-v4.studiometa.dev/utils/scroll.html#scrollto
  */
 declare function scrollTo(target: ScrollToTarget, options?: ScrollToOptions): ScrollPosition;
-//#endregion
 export { SCROLL_ALIGNMENTS, SCROLL_AXES, ScrollAlign, ScrollAxis, ScrollPosition, ScrollPositionOptions, ScrollToOptions, ScrollToTarget, scrollPosition, scrollTo };

package/dist/utils/scrollTo.js

@@ -1,7 +1,7 @@
 import { clamp } from "./maths.js";
 import { usePrefersReducedMotion } from "../services/media.js";
 import { isNumber, isString } from "./is.js";
-//#region src/utils/scrollTo.ts
+// src/utils/scrollTo.ts
 /**
 * The axes a scroll is allowed to move.
 * @link https://js-toolkit-v4.studiometa.dev/utils/scroll.html#scroll-axes
@@ -157,7 +157,6 @@ function scrollTo(target, options = {}) {
 	});
 	return destination;
 }
-//#endregion
 export { SCROLL_ALIGNMENTS, SCROLL_AXES, scrollPosition, scrollTo };
 
 //# sourceMappingURL=scrollTo.js.map

package/dist/utils/selectors.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/selectors.d.ts
 /**
  * The registry selector for a component name.
  *
@@ -15,5 +14,4 @@
  * @link https://js-toolkit-v4.studiometa.dev/utils/dom.html#selectorfor
  */
 declare function selectorFor(name: string): string;
-//#endregion
 export { selectorFor };

package/dist/utils/selectors.js

@@ -1,6 +1,6 @@
 import { COMPONENT_ATTRIBUTE } from "../attributes.js";
 import { responsiveAttributeNames } from "../responsive-options.js";
-//#region src/utils/selectors.ts
+// src/utils/selectors.ts
 /**
 * The registry selector for a component name.
 *
@@ -19,7 +19,6 @@ import { responsiveAttributeNames } from "../responsive-options.js";
 function selectorFor(name) {
 	return [COMPONENT_ATTRIBUTE, ...responsiveAttributeNames(COMPONENT_ATTRIBUTE)].map((attribute) => `[${CSS.escape(attribute)}~="${name}"]`).join(",");
 }
-//#endregion
 export { selectorFor };
 
 //# sourceMappingURL=selectors.js.map

package/dist/utils/smoothTo.d.ts

@@ -1,5 +1,4 @@
 import { SpringOptions } from "./maths.js";
-//#region src/utils/smoothTo.d.ts
 interface SmoothToOptions extends Omit<SpringOptions, 'damping'> {
   /**
    * Damping factor, or spring friction in spring mode. Defaults to `0.6`.
@@ -73,5 +72,4 @@ declare function smoothTo(start?: number, options?: SmoothToOptions): SmoothTo;
  * consumer's own — a scale, an opacity or a progress as readily as a coordinate.
  */
 declare function smoothTo<K extends string>(start: Record<K, number>, options?: SmoothToOptions): SmoothToRecord<K>;
-//#endregion
 export { SmoothTo, SmoothToOptions, SmoothToRecord, smoothTo };

package/dist/utils/smoothTo.js

@@ -1,7 +1,7 @@
 import { damp, spring } from "./maths.js";
 import { toggle } from "../services/toggle.js";
 import { useRaf } from "../services/raf.js";
-//#region src/utils/smoothTo.ts
+// src/utils/smoothTo.ts
 /** The key a single value is held under, and the one its `damping` hook is asked about. */
 const SCALAR_KEY = "value";
 function smoothTo(start = 0, options = {}) {
@@ -87,7 +87,6 @@ function smoothTo(start = 0, options = {}) {
 	});
 	return api;
 }
-//#endregion
 export { smoothTo };
 
 //# sourceMappingURL=smoothTo.js.map

package/dist/utils/strings.d.ts

@@ -1,5 +1,4 @@
 import { Memo } from "./memo.js";
-//#region src/utils/strings.d.ts
 /**
  * String shapes the framework converts between: an option or handler name in
  * source, and the `data-` attribute or event type it corresponds to.
@@ -97,5 +96,4 @@ declare function withTrailingSlash(string: string): string;
  * @link https://js-toolkit-v4.studiometa.dev/utils/strings.html#withouttrailingslash
  */
 declare function withoutTrailingSlash(string: string): string;
-//#endregion
 export { camelCase, capitalize, kebabCase, lowerCase, pascalCase, snakeCase, upperCase, withLeadingCharacters, withLeadingSlash, withTrailingCharacters, withTrailingSlash, withoutLeadingCharacters, withoutLeadingCharactersRecursive, withoutLeadingSlash, withoutTrailingCharacters, withoutTrailingCharactersRecursive, withoutTrailingSlash };

package/dist/utils/strings.js

@@ -1,5 +1,5 @@
 import { memo } from "./memo.js";
-//#region src/utils/strings.ts
+// src/utils/strings.ts
 /**
 * String shapes the framework converts between: an option or handler name in
 * source, and the `data-` attribute or event type it corresponds to.
@@ -163,7 +163,6 @@ function withTrailingSlash(string) {
 function withoutTrailingSlash(string) {
 	return withoutTrailingCharacters(string, "/");
 }
-//#endregion
 export { camelCase, capitalize, kebabCase, lowerCase, pascalCase, snakeCase, upperCase, withLeadingCharacters, withLeadingSlash, withTrailingCharacters, withTrailingSlash, withoutLeadingCharacters, withoutLeadingCharactersRecursive, withoutLeadingSlash, withoutTrailingCharacters, withoutTrailingCharactersRecursive, withoutTrailingSlash };
 
 //# sourceMappingURL=strings.js.map

package/dist/utils/timing.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/timing.d.ts
 /** Rate limiting and delays, for the callbacks a component hands to the DOM. */
 /**
  * Delay a function until it stops being called for the given milliseconds.
@@ -17,5 +16,4 @@ declare function throttle<Args extends unknown[]>(fn: (...args: Args) => void, d
  * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#wait
  */
 declare function wait(delay?: number): Promise<void>;
-//#endregion
 export { debounce, throttle, wait };

package/dist/utils/timing.js

@@ -1,4 +1,4 @@
-//#region src/utils/timing.ts
+// src/utils/timing.ts
 /** Rate limiting and delays, for the callbacks a component hands to the DOM. */
 /**
 * Delay a function until it stops being called for the given milliseconds.
@@ -35,7 +35,6 @@ function wait(delay = 0) {
 		setTimeout(resolve, delay);
 	});
 }
-//#endregion
 export { debounce, throttle, wait };
 
 //# sourceMappingURL=timing.js.map

package/dist/utils/transform.d.ts

@@ -1,4 +1,3 @@
-//#region src/utils/transform.d.ts
 /**
  * CSS transform strings. Both helpers are pure: they format a value and the
  * caller hands the write to the scheduler.
@@ -63,5 +62,4 @@ interface MatrixProps {
  * @link https://js-toolkit-v4.studiometa.dev/utils/css.html#matrix
  */
 declare function matrix(props?: MatrixProps): string;
-//#endregion
 export { MatrixProps, TRANSFORM_PROPS, TransformProps, matrix, transform };

package/dist/utils/transform.js

@@ -1,4 +1,4 @@
-//#region src/utils/transform.ts
+// src/utils/transform.ts
 /**
 * The properties {@link transform} formats, for callers splitting a style patch.
 * @link https://js-toolkit-v4.studiometa.dev/utils/css.html#transform-props
@@ -68,7 +68,6 @@ function matrix(props = {}) {
 	const { scaleX = 1, skewY = 0, skewX = 0, scaleY = 1, translateX = 0, translateY = 0 } = props;
 	return `matrix(${scaleX}, ${skewY}, ${skewX}, ${scaleY}, ${translateX}, ${translateY})`;
 }
-//#endregion
 export { TRANSFORM_PROPS, matrix, transform };
 
 //# sourceMappingURL=transform.js.map

package/dist/utils/transition.d.ts

@@ -1,5 +1,4 @@
 import { OptionDefinition } from "../Base.js";
-//#region src/utils/transition.d.ts
 /**
  * CSS transition helpers for class names or inline styles. Apply `from`, then
  * `active` and `to`, and resolve after `transitionend` or on the next frame when no transition runs.
@@ -57,5 +56,4 @@ declare function enterTransition(el: HTMLElement, options: TransitionOptions): P
  * @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#leavetransition
  */
 declare function leaveTransition(el: HTMLElement, options: TransitionOptions): Promise<void>;
-//#endregion
 export { ClassesOrStyles, TRANSITION_OPTIONS, TransitionOptions, TransitionStyles, enterTransition, leaveTransition, setClassesOrStyles, transition };

package/dist/utils/transition.js

@@ -1,5 +1,5 @@
 import { nextFrame } from "../scheduler.js";
-//#region src/utils/transition.ts
+// src/utils/transition.ts
 const runs = /* @__PURE__ */ new WeakMap();
 function toClassList(value) {
 	return (Array.isArray(value) ? value : value.split(" ")).filter(Boolean);
@@ -128,7 +128,6 @@ async function leaveTransition(el, options) {
 		to: leaveTo
 	}, leaveKeep ? "keep" : "remove");
 }
-//#endregion
 export { TRANSITION_OPTIONS, enterTransition, leaveTransition, setClassesOrStyles, transition };
 
 //# sourceMappingURL=transition.js.map

package/dist/viewTransition.d.ts

@@ -1,4 +1,3 @@
-//#region src/viewTransition.d.ts
 type ViewTransitionUpdate = () => void | Promise<void>;
 /**
  * Run a DOM update inside a batched, native view transition.
@@ -13,5 +12,4 @@ type ViewTransitionUpdate = () => void | Promise<void>;
  * @link https://js-toolkit-v4.studiometa.dev/api/scheduler/viewTransition.html
  */
 declare function viewTransition(update: ViewTransitionUpdate): Promise<void>;
-//#endregion
 export { ViewTransitionUpdate, viewTransition };

package/dist/viewTransition.js

@@ -1,5 +1,5 @@
 import { defaultScheduler } from "./scheduler.js";
-//#region src/viewTransition.ts
+// src/viewTransition.ts
 let vtQueue = [];
 let vtIsScheduled = false;
 let vtTail = Promise.resolve();
@@ -46,7 +46,6 @@ async function runViewTransitionBatch(batch) {
 		for (const { reject } of batch) reject(error);
 	}
 }
-//#endregion
 export { viewTransition };
 
 //# sourceMappingURL=viewTransition.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit",
-  "version": "4.0.0-alpha.1",
+  "version": "4.0.0-alpha.3",
   "type": "module",
   "sideEffects": [
     "./dist/responsive-options.js"
@@ -21,6 +21,7 @@
   "homepage": "https://js-toolkit-v4.studiometa.dev",
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -812,7 +813,8 @@
     }
   },
   "scripts": {
-    "build": "node scripts/build.js",
+    "build": "node scripts/build.js && npm run build:skills",
+    "build:skills": "node ../../scripts/build-skills.js",
     "check:constant-subpaths": "node scripts/check-constant-subpaths.js",
     "check:diagnostics": "node scripts/check-diagnostics.js",
     "check:doc-links": "node scripts/check-doc-links.js",
@@ -822,6 +824,7 @@
     "demo:preview": "vite preview demo --host",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
+    "postdocs:build": "node ../../scripts/build-skills.js --well-known docs/.vitepress/dist",
     "docs:preview": "vitepress preview docs",
     "test": "npm run check:diagnostics && npm run check:doc-links && npm run test:fixtures && vitest run",
     "test:fixtures": "node scripts/build-runtime-fixtures.js",
@@ -848,7 +851,7 @@
     "playwright": "^1.50.0",
     "tailwindcss": "4.2.2",
     "tsdown": "0.22.14",
-    "vite": "8.2.1",
+    "vite": "8.2.4",
     "vitepress": "2.0.0-alpha.19",
     "vitepress-plugin-llms": "1.12.0",
     "vitest": "4.1.10"

package/skills/studiometa-js-toolkit/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: studiometa-js-toolkit
+description: Write components with @studiometa/js-toolkit v4 — classes that extend Base, registered with registerComponent and bound to the DOM through data-component, data-ref, data-option-* and data-mount attributes. Use when code imports @studiometa/js-toolkit, extends Base, uses $refs, $options, $emit, $query, $closest, on<Ref><Event> hooks, services (useScroll, useResize, useRaf, withScroll…), mount strategies, provide/inject, the scheduler or @studiometa/js-toolkit/utils, or when you migrate code from js-toolkit v3.
+---
+
+# @studiometa/js-toolkit
+
+`@studiometa/js-toolkit` binds JavaScript classes to server-rendered HTML. A component is a class that extends `Base`, a name in the registry, and a `data-component` attribute in the markup.
+
+This skill matches the installed package version. v4 is a full breaking major: most examples on the web and in training data are v3 code that does not work in v4. Read the references in this folder before the online docs.
+
+## References
+
+- `references/guide/introduction/`: components, refs, options, events, lifecycle, services. Start here.
+- `references/guide/going-further/`: autoloading, mount strategies, scheduling, shared state, swapping content, testing, TypeScript, decorators, storage, diagnostics.
+- `references/guide/migration/v3-to-v4.md`: every v3 API that changed, with its replacement. Read it before you change existing code.
+- `references/api/`: the exact API of `Base`, the registry, services, context, DOM helpers, scheduler, storage and diagnostics.
+- `references/utils/`: the utilities of `@studiometa/js-toolkit/utils`, by category.
+
+## A component
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class Counter extends Base {
+  static config = {
+    name: 'Counter',
+    refs: ['output'],
+    options: { step: { type: Number, default: 1 } },
+  };
+
+  count = 0;
+
+  onClick() {
+    this.count += this.$options.step;
+    this.$refs.output.textContent = String(this.count);
+  }
+}
+
+registerComponent(Counter);
+```
+
+```html
+<button data-component="Counter" data-option-step="5">
+  Clicked
+  <span data-ref="output">0</span>
+  times
+</button>
+```
+
+## v4 rules
+
+These are the v3 habits that break in v4:
+
+| Do not write (v3)                                   | Write (v4)                                                                                       |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `createApp(App)`                                    | `registerComponents(A, B, C)`: no root component                                                 |
+| `this.$children.Item`, `this.$parent`, `this.$root` | `this.$query('Item')`, `this.$watchChildren('Item')`, `this.$closest('Name')` (can be `null`)    |
+| `this.$update()`                                    | nothing: `$refs` reads the DOM on each access                                                    |
+| `data-ref="items"` for a list                       | `data-ref="items[]"`, same as `refs: ['items[]']`; read it as `this.$refs.items`                 |
+| `this.$options.open = true`                         | `$options` is read-only: change the `data-option-*` attribute                                    |
+| `data-option-open="false"`                          | remove the attribute, or `data-option-no-open` when the default is `true`                        |
+| `default: {}` or `default: []`                      | a factory: `default: () => ({})`                                                                 |
+| `this.$emit('go', 1, 'left')`                       | one payload object: `this.$emit('go', { index: 1, direction: 'left' })`                          |
+| `onItemClick(event, index)`                         | one object: `onItemsClick({ event, target, index })`, `onChildEvent({ event, target, payload })` |
+| `updated()`                                         | `option<Name>Changed()` or `watchAttributes()`                                                   |
+| `unmounted()` only to unsubscribe                   | return the cleanup from `mounted()`                                                              |
+| `data-load`, `withMountWhenInView`, `importWhen*`   | `data-mount="visible"` or a `registerManifest()` entry with `mountStrategy`                      |
+| `withExtraConfig()`                                 | a subclass with its own `static config`                                                          |
+| `withResponsiveOptions`, `data-option-x:s:m`        | every option is responsive: `data-option-x:s` cascades up                                        |
+| `domScheduler`, `afterWrite`                        | `this.$read()` / `this.$write()`, or `defaultScheduler`                                          |
+| `tween`, `animate`                                  | not in core: use `transition()`, `spring()`, `smoothTo()` or `@studiometa/ui-motion`             |
+
+## Practices
+
+- Let the registry construct instances. Never call `new MyComponent(el)`.
+- Declare `refs` and use `on<Ref><Event>` hooks instead of `querySelector` and `addEventListener`. Use `onWindow<Event>` and `onDocument<Event>` for global events.
+- Use a service before a custom listener or observer: the mixins `withScroll` (`scrolled`), `withResize` (`resized`), `withRaf` (`ticked`), `withPointer` (`moved`), `withDrag` (`dragged`), `withKey` (`keyed`), `withInView` (`intersected`), `withMutation` (`mutated`), `withScrollProgress` (`scrolledInView`), or the `use*()` functions.
+- Use mount strategies (`eager`, `visible`, `in-view`, `idle`, `interaction`, `media:<query>`) to defer work, not custom observers.
+- Share state with `provideRootContext()`, `$provide()` and `$inject()`, not with global variables.
+- Import utilities from `@studiometa/js-toolkit/utils` (for example `import { clamp, damp } from '@studiometa/js-toolkit/utils'`). Read `references/utils/` before you write a helper.
+- Diagnostics (`EVENTS.diagnostic`) explain wrong refs, options and payloads. Read the warning code in `references/api/diagnostics/DIAGNOSTICS.md`.
+
+## Related skills
+
+- `studiometa-ui`: ready-made components (Action, Dialog, Disclosure, Tabs, Carousel, Fetch, Transition, Data*…). Look for a component there before you write a custom one.
+- `studiometa-eslint-plugin-js-toolkit`: the lint rules for js-toolkit code.