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

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","names":[],"sources":["../src/manifest.ts"],"sourcesContent":["import type { ComponentImporter } from './Base.js';\nimport { warnOnce } from './diagnostics.js';\nimport type { MountStrategy } from './mount-strategies.js';\nimport type { ComponentManifest } from './registry.js';\n\n/** Lazy module importers keyed by the paths a bundler matched. */\nexport type ModuleRecord = Record<string, ComponentImporter>;\n\n/** Options accepted by {@link defineManifest}. */\nexport interface DefineManifestOptions {\n  /** Lazy module importers keyed by their matched paths. */\n  modules: ModuleRecord;\n  /** One mount strategy for every generated entry. Defaults to `eager`. */\n  mountStrategy?: MountStrategy;\n}\n\n/** The structural shape of a webpack context, with no webpack dependency. */\nexport interface WebpackContextLike {\n  keys(): string[];\n  (id: string): unknown;\n}\n\nfunction deriveToken(path: string): string {\n  const segments = path.split('/').filter((segment) => segment && segment !== '.');\n  const last = segments.at(-1) ?? '';\n  const base = last.replace(/\\.[^.]+$/, '');\n  return base === 'index' && segments.length >= 2 ? (segments.at(-2) as string) : base;\n}\n\n/**\n * Build a lazy component manifest from bundler module importers without importing or registering\n * anything. The registry resolves direct classes, named exports and default exports when needed.\n * @link https://js-toolkit-v4.studiometa.dev/api/registry/defineManifest.html\n */\nexport function defineManifest({\n  modules,\n  mountStrategy,\n}: DefineManifestOptions): ComponentManifest {\n  const manifest: ComponentManifest = {};\n  const paths = new Map<string, string>();\n\n  for (const [path, importer] of Object.entries(modules)) {\n    const token = deriveToken(path);\n    const firstPath = paths.get(token);\n    if (firstPath !== undefined) {\n      warnOnce(\n        modules,\n        `${token}\\0${firstPath}\\0${path}`,\n        'manifest.duplicate-token',\n        `\"${token}\" is already derived from \"${firstPath}\"; ignoring \"${path}\".`,\n      );\n      continue;\n    }\n\n    paths.set(token, path);\n    manifest[token] =\n      mountStrategy === undefined || mountStrategy === 'eager'\n        ? importer\n        : { load: importer, mountStrategy };\n  }\n\n  return manifest;\n}\n\n/**\n * Return a lazy Vite glob unchanged, and reject eager glob values immediately.\n * @link https://js-toolkit-v4.studiometa.dev/api/registry/fromMetaGlob.html\n */\nexport function fromMetaGlob(glob: Record<string, unknown>): ModuleRecord {\n  for (const [path, importer] of Object.entries(glob)) {\n    if (typeof importer !== 'function') {\n      throw new TypeError(\n        `[manifest] fromMetaGlob() expects a lazy glob; \"${path}\" is not an importer function. Remove the { eager: true } option.`,\n      );\n    }\n  }\n  return glob as ModuleRecord;\n}\n\n/**\n * Convert a webpack context to lazy importers without loading any matched module.\n * @link https://js-toolkit-v4.studiometa.dev/api/registry/fromWebpackContext.html\n */\nexport function fromWebpackContext(context: WebpackContextLike): ModuleRecord {\n  return Object.fromEntries(\n    context.keys().map((key) => [key, () => Promise.resolve(context(key))]),\n  );\n}\n"],"mappings":";;AAsBA,SAAS,YAAY,MAAsB;CACzC,MAAM,WAAW,KAAK,MAAM,GAAG,CAAC,CAAC,QAAQ,YAAY,WAAW,YAAY,GAAG;CAE/E,MAAM,QADO,SAAS,GAAG,EAAE,KAAK,GAAA,CACd,QAAQ,YAAY,EAAE;CACxC,OAAO,SAAS,WAAW,SAAS,UAAU,IAAK,SAAS,GAAG,EAAE,IAAe;AAClF;;;;;;AAOA,SAAgB,eAAe,EAC7B,SACA,iBAC2C;CAC3C,MAAM,WAA8B,CAAC;CACrC,MAAM,wBAAQ,IAAI,IAAoB;CAEtC,KAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,OAAO,GAAG;EACtD,MAAM,QAAQ,YAAY,IAAI;EAC9B,MAAM,YAAY,MAAM,IAAI,KAAK;EACjC,IAAI,cAAc,KAAA,GAAW;GAC3B,SACE,SACA,GAAG,MAAM,IAAI,UAAU,IAAI,QAC3B,4BACA,IAAI,MAAM,6BAA6B,UAAU,eAAe,KAAK,GACvE;GACA;EACF;EAEA,MAAM,IAAI,OAAO,IAAI;EACrB,SAAS,SACP,kBAAkB,KAAA,KAAa,kBAAkB,UAC7C,WACA;GAAE,MAAM;GAAU;EAAc;CACxC;CAEA,OAAO;AACT;;;;;AAMA,SAAgB,aAAa,MAA6C;CACxE,KAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,IAAI,GAChD,IAAI,OAAO,aAAa,YACtB,MAAM,IAAI,UACR,mDAAmD,KAAK,kEAC1D;CAGJ,OAAO;AACT;;;;;AAMA,SAAgB,mBAAmB,SAA2C;CAC5E,OAAO,OAAO,YACZ,QAAQ,KAAK,CAAC,CAAC,KAAK,QAAQ,CAAC,WAAW,QAAQ,QAAQ,QAAQ,GAAG,CAAC,CAAC,CAAC,CACxE;AACF"}

package/dist/mount-strategies.d.ts

@@ -0,0 +1,46 @@
+//#region src/mount-strategies.d.ts
+/**
+ * Control when an instance mounts.
+ * `in-view` and `media` are reversible; all other strategies mount once.
+ * Viewport suffixes are passed as `IntersectionObserverInit.rootMargin`.
+ */
+type MountStrategy = 'eager' | 'visible' | `visible:${string}` | 'in-view' | `in-view:${string}` | 'idle' | 'interaction' | 'interaction:' | 'interaction:page' | `media:${string}`;
+interface MountStrategyHooks {
+  mount: () => void;
+  unmount: () => void;
+}
+type AppliedMountStrategy = {
+  readonly valid: true;
+  dispose(): void;
+  /** Work which mounts eagerly; conditional strategies never expose one. */
+  eagerWork?: Promise<unknown>;
+  error?: never;
+} | {
+  readonly valid: false;
+  dispose(): void;
+  eagerWork?: never;
+  /** The original error for the registry diagnostic. */
+  error: unknown;
+};
+/** What a strategy does, known before it is applied to anything. */
+interface MountStrategyBehaviour {
+  /** Mounts as soon as it is applied: there is no condition to wait for. */
+  readonly eager: boolean;
+  /** Unmounts again when its condition stops holding, and can fire more than once. */
+  readonly reversible: boolean;
+}
+/**
+ * Describe a strategy without installing it.
+ *
+ * The registry needs both facts *before* `applyMountStrategy()` returns,
+ * because `media:` reads its query synchronously and can therefore call a hook
+ * from inside that call. Deriving them from the parse above is what keeps the
+ * list of reversible strategies in the module that owns the grammar.
+ */
+declare function mountStrategyBehaviour(strategy: string): MountStrategyBehaviour;
+/**
+ * Apply a strategy and return its teardown and any eager work that DOM settlement must await.
+ */
+declare function applyMountStrategy(el: HTMLElement, strategy: string, { mount, unmount }: MountStrategyHooks): AppliedMountStrategy;
+//#endregion
+export { AppliedMountStrategy, MountStrategy, MountStrategyBehaviour, MountStrategyHooks, applyMountStrategy, mountStrategyBehaviour };

package/dist/mount-strategies.js

@@ -0,0 +1,213 @@
+import { getSharedRuntimeSlot } from "./shared-runtime.js";
+import { defaultScheduler } from "./scheduler.js";
+//#region src/mount-strategies.ts
+/** The one scope `interaction` takes; bare `interaction` is the element. */
+const PAGE_SCOPE = "page";
+/**
+* Events that mount before the related interaction completes.
+* `pointerenter` also fires when an element appears under a resting cursor.
+*/
+const INTENT_EVENTS = [
+	"pointerenter",
+	"pointerdown",
+	"focusin"
+];
+/**
+* What counts as the user engaging with the **page**.
+*
+* Aiming is intent for one element and noise for a document: a pointer
+* crossing into the page says nothing about engagement, and `pointerenter` on
+* the document would fire on the first mouse move of almost every desktop
+* visit. So the page set keeps the deliberate acts only — a press, a key, a
+* focus — and drops the hover the element set is built around.
+*/
+const PAGE_INTENT_EVENTS = [
+	"pointerdown",
+	"keydown",
+	"focusin"
+];
+/**
+* Read the strategy grammar once, for every question asked about it.
+*
+* Applying a strategy and describing one are the same switch: a seventh
+* strategy is taught to the framework here, and both the observer it installs
+* and the facts the registry schedules against follow from that single branch.
+*/
+function parseMountStrategy(strategy) {
+	const separator = strategy.indexOf(":");
+	const name = separator < 0 ? strategy : strategy.slice(0, separator);
+	const parameter = separator < 0 ? "" : strategy.slice(separator + 1);
+	if (name === "visible" || name === "in-view") return {
+		kind: "viewport",
+		reversible: name === "in-view",
+		rootMargin: parameter || void 0
+	};
+	if (name === "media" && separator >= 0) return parameter.trim().length === 0 ? {
+		kind: "invalid",
+		error: /* @__PURE__ */ new TypeError("The media mount strategy requires a non-empty query.")
+	} : {
+		kind: "media",
+		query: parameter
+	};
+	if (name === "interaction") {
+		if (parameter === "" || parameter === PAGE_SCOPE) return {
+			kind: "interaction",
+			page: parameter === PAGE_SCOPE
+		};
+		return {
+			kind: "invalid",
+			error: /* @__PURE__ */ new TypeError(`The interaction mount strategy takes "${PAGE_SCOPE}" or nothing, not "${parameter}".`)
+		};
+	}
+	if (strategy === "eager" || strategy === "idle") return { kind: strategy };
+	return {
+		kind: "invalid",
+		error: /* @__PURE__ */ new TypeError(`Unknown mount strategy "${strategy}".`)
+	};
+}
+/**
+* Describe a strategy without installing it.
+*
+* The registry needs both facts *before* `applyMountStrategy()` returns,
+* because `media:` reads its query synchronously and can therefore call a hook
+* from inside that call. Deriving them from the parse above is what keeps the
+* list of reversible strategies in the module that owns the grammar.
+*/
+function mountStrategyBehaviour(strategy) {
+	const parsed = parseMountStrategy(strategy);
+	return {
+		eager: parsed.kind === "eager",
+		reversible: parsed.kind === "media" || parsed.kind === "viewport" && parsed.reversible
+	};
+}
+/** Keep an invalid strategy inert while exposing the exact failure. */
+function rejectMountStrategy(error) {
+	return {
+		valid: false,
+		dispose() {},
+		error
+	};
+}
+/**
+* The page-wide interaction signal, shared by every element waiting for it.
+*
+* One listener per event type for the whole page, not per waiting element: a
+* page deferring fifty components would otherwise put a hundred and fifty
+* listeners on the document to answer one question. `hasFired` is the other
+* half of that — the signal is a fact about the visit, so an element which
+* arrives after the user has already interacted mounts at once rather than
+* waiting for a second interaction that may never come.
+*/
+const pageInteraction = /* @__PURE__ */ getSharedRuntimeSlot("mount-strategy:page-interaction", 1, () => ({
+	waiting: /* @__PURE__ */ new Set(),
+	hasFired: false,
+	release: null
+}));
+/** Listen in the capture phase, so a handler stopping propagation cannot hide the visit. */
+function listenForPageInteraction() {
+	const onIntent = () => {
+		pageInteraction.hasFired = true;
+		pageInteraction.release?.();
+		const batch = [...pageInteraction.waiting];
+		pageInteraction.waiting.clear();
+		for (const mount of batch) mount();
+	};
+	for (const type of PAGE_INTENT_EVENTS) document.addEventListener(type, onIntent, { capture: true });
+	pageInteraction.release = () => {
+		pageInteraction.release = null;
+		for (const type of PAGE_INTENT_EVENTS) document.removeEventListener(type, onIntent, { capture: true });
+	};
+}
+/** Wait for the first interaction with the page, or mount now if it already happened. */
+function whenPageInteracted(mount) {
+	if (pageInteraction.hasFired) {
+		mount();
+		return {
+			valid: true,
+			dispose() {}
+		};
+	}
+	pageInteraction.waiting.add(mount);
+	if (!pageInteraction.release) listenForPageInteraction();
+	return {
+		valid: true,
+		dispose() {
+			pageInteraction.waiting.delete(mount);
+			if (pageInteraction.waiting.size === 0) pageInteraction.release?.();
+		}
+	};
+}
+/**
+* Apply a strategy and return its teardown and any eager work that DOM settlement must await.
+*/
+function applyMountStrategy(el, strategy, { mount, unmount }) {
+	const parsed = parseMountStrategy(strategy);
+	if (parsed.kind === "invalid") return rejectMountStrategy(parsed.error);
+	if (parsed.kind === "viewport") {
+		let observer;
+		try {
+			observer = new IntersectionObserver((entries) => {
+				for (const entry of entries) if (entry.isIntersecting) {
+					if (!parsed.reversible) observer.disconnect();
+					mount();
+				} else if (parsed.reversible) unmount();
+			}, parsed.rootMargin ? { rootMargin: parsed.rootMargin } : void 0);
+		} catch (error) {
+			return rejectMountStrategy(error);
+		}
+		observer.observe(el);
+		return {
+			valid: true,
+			dispose: () => observer.disconnect()
+		};
+	}
+	if (parsed.kind === "idle") {
+		if (typeof requestIdleCallback !== "function") {
+			const task = defaultScheduler.background(mount);
+			return {
+				valid: true,
+				dispose: () => task.cancel()
+			};
+		}
+		const handle = requestIdleCallback(() => mount());
+		return {
+			valid: true,
+			dispose: () => cancelIdleCallback(handle)
+		};
+	}
+	if (parsed.kind === "interaction") {
+		if (parsed.page) return whenPageInteracted(mount);
+		const onIntent = () => {
+			teardown();
+			mount();
+		};
+		const teardown = () => {
+			for (const type of INTENT_EVENTS) el.removeEventListener(type, onIntent);
+		};
+		for (const type of INTENT_EVENTS) el.addEventListener(type, onIntent, { once: true });
+		return {
+			valid: true,
+			dispose: teardown
+		};
+	}
+	if (parsed.kind === "media") {
+		const query = matchMedia(parsed.query);
+		const sync = () => query.matches ? mount() : unmount();
+		query.addEventListener("change", sync);
+		sync();
+		return {
+			valid: true,
+			dispose: () => query.removeEventListener("change", sync)
+		};
+	}
+	const task = defaultScheduler.background(mount);
+	return {
+		valid: true,
+		dispose: () => task.cancel(),
+		eagerWork: task.promise
+	};
+}
+//#endregion
+export { applyMountStrategy, mountStrategyBehaviour };
+
+//# sourceMappingURL=mount-strategies.js.map

package/dist/mount-strategies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-strategies.js","names":[],"sources":["../src/mount-strategies.ts"],"sourcesContent":["import { defaultScheduler } from './scheduler.js';\nimport { getSharedRuntimeSlot } from './shared-runtime.js';\n\n/**\n * Control when an instance mounts.\n * `in-view` and `media` are reversible; all other strategies mount once.\n * Viewport suffixes are passed as `IntersectionObserverInit.rootMargin`.\n */\nexport type MountStrategy =\n  | 'eager'\n  | 'visible'\n  | `visible:${string}`\n  | 'in-view'\n  | `in-view:${string}`\n  | 'idle'\n  | 'interaction'\n  | 'interaction:'\n  | 'interaction:page'\n  | `media:${string}`;\n\n/** The one scope `interaction` takes; bare `interaction` is the element. */\nconst PAGE_SCOPE = 'page';\n\n/**\n * Events that mount before the related interaction completes.\n * `pointerenter` also fires when an element appears under a resting cursor.\n */\nconst INTENT_EVENTS = ['pointerenter', 'pointerdown', 'focusin'] as const;\n\n/**\n * What counts as the user engaging with the **page**.\n *\n * Aiming is intent for one element and noise for a document: a pointer\n * crossing into the page says nothing about engagement, and `pointerenter` on\n * the document would fire on the first mouse move of almost every desktop\n * visit. So the page set keeps the deliberate acts only — a press, a key, a\n * focus — and drops the hover the element set is built around.\n */\nconst PAGE_INTENT_EVENTS = ['pointerdown', 'keydown', 'focusin'] as const;\n\nexport interface MountStrategyHooks {\n  mount: () => void;\n  unmount: () => void;\n}\n\nexport type AppliedMountStrategy =\n  | {\n      readonly valid: true;\n      dispose(): void;\n      /** Work which mounts eagerly; conditional strategies never expose one. */\n      eagerWork?: Promise<unknown>;\n      error?: never;\n    }\n  | {\n      readonly valid: false;\n      dispose(): void;\n      eagerWork?: never;\n      /** The original error for the registry diagnostic. */\n      error: unknown;\n    };\n\ntype ParsedMountStrategy =\n  | { kind: 'eager' }\n  | { kind: 'idle' }\n  | { kind: 'interaction'; page: boolean }\n  | { kind: 'media'; query: string }\n  | { kind: 'viewport'; reversible: boolean; rootMargin?: string }\n  | { kind: 'invalid'; error: unknown };\n\n/**\n * Read the strategy grammar once, for every question asked about it.\n *\n * Applying a strategy and describing one are the same switch: a seventh\n * strategy is taught to the framework here, and both the observer it installs\n * and the facts the registry schedules against follow from that single branch.\n */\nfunction parseMountStrategy(strategy: string): ParsedMountStrategy {\n  const separator = strategy.indexOf(':');\n  const name = separator < 0 ? strategy : strategy.slice(0, separator);\n  const parameter = separator < 0 ? '' : strategy.slice(separator + 1);\n\n  if (name === 'visible' || name === 'in-view') {\n    return { kind: 'viewport', reversible: name === 'in-view', rootMargin: parameter || undefined };\n  }\n  if (name === 'media' && separator >= 0) {\n    return parameter.trim().length === 0\n      ? {\n          kind: 'invalid',\n          error: new TypeError('The media mount strategy requires a non-empty query.'),\n        }\n      : { kind: 'media', query: parameter };\n  }\n  if (name === 'interaction') {\n    // An empty parameter reads as the bare name, as `visible:` does.\n    if (parameter === '' || parameter === PAGE_SCOPE) {\n      return { kind: 'interaction', page: parameter === PAGE_SCOPE };\n    }\n    return {\n      kind: 'invalid',\n      error: new TypeError(\n        `The interaction mount strategy takes \"${PAGE_SCOPE}\" or nothing, not \"${parameter}\".`,\n      ),\n    };\n  }\n  if (strategy === 'eager' || strategy === 'idle') {\n    return { kind: strategy };\n  }\n  return { kind: 'invalid', error: new TypeError(`Unknown mount strategy \"${strategy}\".`) };\n}\n\n/** What a strategy does, known before it is applied to anything. */\nexport interface MountStrategyBehaviour {\n  /** Mounts as soon as it is applied: there is no condition to wait for. */\n  readonly eager: boolean;\n  /** Unmounts again when its condition stops holding, and can fire more than once. */\n  readonly reversible: boolean;\n}\n\n/**\n * Describe a strategy without installing it.\n *\n * The registry needs both facts *before* `applyMountStrategy()` returns,\n * because `media:` reads its query synchronously and can therefore call a hook\n * from inside that call. Deriving them from the parse above is what keeps the\n * list of reversible strategies in the module that owns the grammar.\n */\nexport function mountStrategyBehaviour(strategy: string): MountStrategyBehaviour {\n  const parsed = parseMountStrategy(strategy);\n  return {\n    eager: parsed.kind === 'eager',\n    reversible: parsed.kind === 'media' || (parsed.kind === 'viewport' && parsed.reversible),\n  };\n}\n\n/** Keep an invalid strategy inert while exposing the exact failure. */\nfunction rejectMountStrategy(error: unknown): AppliedMountStrategy {\n  return { valid: false, dispose() {}, error };\n}\n\n/**\n * The page-wide interaction signal, shared by every element waiting for it.\n *\n * One listener per event type for the whole page, not per waiting element: a\n * page deferring fifty components would otherwise put a hundred and fifty\n * listeners on the document to answer one question. `hasFired` is the other\n * half of that — the signal is a fact about the visit, so an element which\n * arrives after the user has already interacted mounts at once rather than\n * waiting for a second interaction that may never come.\n */\nconst pageInteraction = /* @__PURE__ */ getSharedRuntimeSlot<{\n  waiting: Set<() => void>;\n  hasFired: boolean;\n  release: (() => void) | null;\n}>('mount-strategy:page-interaction', 1, () => ({\n  waiting: new Set(),\n  hasFired: false,\n  release: null,\n}));\n\n/** Listen in the capture phase, so a handler stopping propagation cannot hide the visit. */\nfunction listenForPageInteraction(): void {\n  const onIntent = () => {\n    pageInteraction.hasFired = true;\n    pageInteraction.release?.();\n    // Snapshot: a mount may register or dispose another waiting element.\n    const batch = [...pageInteraction.waiting];\n    pageInteraction.waiting.clear();\n    for (const mount of batch) {\n      mount();\n    }\n  };\n\n  for (const type of PAGE_INTENT_EVENTS) {\n    document.addEventListener(type, onIntent, { capture: true });\n  }\n\n  pageInteraction.release = () => {\n    pageInteraction.release = null;\n    for (const type of PAGE_INTENT_EVENTS) {\n      document.removeEventListener(type, onIntent, { capture: true });\n    }\n  };\n}\n\n/** Wait for the first interaction with the page, or mount now if it already happened. */\nfunction whenPageInteracted(mount: () => void): AppliedMountStrategy {\n  if (pageInteraction.hasFired) {\n    mount();\n    return { valid: true, dispose() {} };\n  }\n\n  pageInteraction.waiting.add(mount);\n  if (!pageInteraction.release) {\n    listenForPageInteraction();\n  }\n\n  return {\n    valid: true,\n    dispose() {\n      pageInteraction.waiting.delete(mount);\n      if (pageInteraction.waiting.size === 0) {\n        pageInteraction.release?.();\n      }\n    },\n  };\n}\n\n/**\n * Apply a strategy and return its teardown and any eager work that DOM settlement must await.\n */\nexport function applyMountStrategy(\n  el: HTMLElement,\n  strategy: string,\n  { mount, unmount }: MountStrategyHooks,\n): AppliedMountStrategy {\n  const parsed = parseMountStrategy(strategy);\n\n  if (parsed.kind === 'invalid') {\n    return rejectMountStrategy(parsed.error);\n  }\n\n  if (parsed.kind === 'viewport') {\n    let observer: IntersectionObserver;\n    try {\n      observer = new IntersectionObserver(\n        (entries) => {\n          for (const entry of entries) {\n            if (entry.isIntersecting) {\n              if (!parsed.reversible) {\n                observer.disconnect();\n              }\n              mount();\n            } else if (parsed.reversible) {\n              unmount();\n            }\n          }\n        },\n        parsed.rootMargin ? { rootMargin: parsed.rootMargin } : undefined,\n      );\n    } catch (error) {\n      // The browser owns the rootMargin grammar. Report author errors without\n      // changing the requested mount policy or stopping registry reconciliation.\n      return rejectMountStrategy(error);\n    }\n    observer.observe(el);\n    return { valid: true, dispose: () => observer.disconnect() };\n  }\n\n  if (parsed.kind === 'idle') {\n    // `requestIdleCallback` is not available everywhere; the background\n    // lane is already budgeted, so it is a fair fallback.\n    if (typeof requestIdleCallback !== 'function') {\n      const task = defaultScheduler.background(mount);\n      return { valid: true, dispose: () => task.cancel() };\n    }\n    const handle = requestIdleCallback(() => mount());\n    return { valid: true, dispose: () => cancelIdleCallback(handle) };\n  }\n\n  if (parsed.kind === 'interaction') {\n    if (parsed.page) {\n      return whenPageInteracted(mount);\n    }\n\n    const onIntent = () => {\n      teardown();\n      mount();\n    };\n    const teardown = () => {\n      for (const type of INTENT_EVENTS) {\n        el.removeEventListener(type, onIntent);\n      }\n    };\n    for (const type of INTENT_EVENTS) {\n      el.addEventListener(type, onIntent, { once: true });\n    }\n    return { valid: true, dispose: teardown };\n  }\n\n  if (parsed.kind === 'media') {\n    const query = matchMedia(parsed.query);\n    const sync = () => (query.matches ? mount() : unmount());\n    query.addEventListener('change', sync);\n    // The first evaluation is not deferred: a matching query mounts before\n    // this call returns, so a caller cannot assume it holds the teardown\n    // below by the time its hooks run.\n    sync();\n    return {\n      valid: true,\n      dispose: () => query.removeEventListener('change', sync),\n    };\n  }\n\n  const task = defaultScheduler.background(mount);\n  return { valid: true, dispose: () => task.cancel(), eagerWork: task.promise };\n}\n"],"mappings":";;;;AAqBA,MAAM,aAAa;;;;;AAMnB,MAAM,gBAAgB;CAAC;CAAgB;CAAe;AAAS;;;;;;;;;;AAW/D,MAAM,qBAAqB;CAAC;CAAe;CAAW;AAAS;;;;;;;;AAsC/D,SAAS,mBAAmB,UAAuC;CACjE,MAAM,YAAY,SAAS,QAAQ,GAAG;CACtC,MAAM,OAAO,YAAY,IAAI,WAAW,SAAS,MAAM,GAAG,SAAS;CACnE,MAAM,YAAY,YAAY,IAAI,KAAK,SAAS,MAAM,YAAY,CAAC;CAEnE,IAAI,SAAS,aAAa,SAAS,WACjC,OAAO;EAAE,MAAM;EAAY,YAAY,SAAS;EAAW,YAAY,aAAa,KAAA;CAAU;CAEhG,IAAI,SAAS,WAAW,aAAa,GACnC,OAAO,UAAU,KAAK,CAAC,CAAC,WAAW,IAC/B;EACE,MAAM;EACN,uBAAO,IAAI,UAAU,sDAAsD;CAC7E,IACA;EAAE,MAAM;EAAS,OAAO;CAAU;CAExC,IAAI,SAAS,eAAe;EAE1B,IAAI,cAAc,MAAM,cAAc,YACpC,OAAO;GAAE,MAAM;GAAe,MAAM,cAAc;EAAW;EAE/D,OAAO;GACL,MAAM;GACN,uBAAO,IAAI,UACT,yCAAyC,WAAW,qBAAqB,UAAU,GACrF;EACF;CACF;CACA,IAAI,aAAa,WAAW,aAAa,QACvC,OAAO,EAAE,MAAM,SAAS;CAE1B,OAAO;EAAE,MAAM;EAAW,uBAAO,IAAI,UAAU,2BAA2B,SAAS,GAAG;CAAE;AAC1F;;;;;;;;;AAkBA,SAAgB,uBAAuB,UAA0C;CAC/E,MAAM,SAAS,mBAAmB,QAAQ;CAC1C,OAAO;EACL,OAAO,OAAO,SAAS;EACvB,YAAY,OAAO,SAAS,WAAY,OAAO,SAAS,cAAc,OAAO;CAC/E;AACF;;AAGA,SAAS,oBAAoB,OAAsC;CACjE,OAAO;EAAE,OAAO;EAAO,UAAU,CAAC;EAAG;CAAM;AAC7C;;;;;;;;;;;AAYA,MAAM,kBAAkC,qCAIrC,mCAAmC,UAAU;CAC9C,yBAAS,IAAI,IAAI;CACjB,UAAU;CACV,SAAS;AACX,EAAE;;AAGF,SAAS,2BAAiC;CACxC,MAAM,iBAAiB;EACrB,gBAAgB,WAAW;EAC3B,gBAAgB,UAAU;EAE1B,MAAM,QAAQ,CAAC,GAAG,gBAAgB,OAAO;EACzC,gBAAgB,QAAQ,MAAM;EAC9B,KAAK,MAAM,SAAS,OAClB,MAAM;CAEV;CAEA,KAAK,MAAM,QAAQ,oBACjB,SAAS,iBAAiB,MAAM,UAAU,EAAE,SAAS,KAAK,CAAC;CAG7D,gBAAgB,gBAAgB;EAC9B,gBAAgB,UAAU;EAC1B,KAAK,MAAM,QAAQ,oBACjB,SAAS,oBAAoB,MAAM,UAAU,EAAE,SAAS,KAAK,CAAC;CAElE;AACF;;AAGA,SAAS,mBAAmB,OAAyC;CACnE,IAAI,gBAAgB,UAAU;EAC5B,MAAM;EACN,OAAO;GAAE,OAAO;GAAM,UAAU,CAAC;EAAE;CACrC;CAEA,gBAAgB,QAAQ,IAAI,KAAK;CACjC,IAAI,CAAC,gBAAgB,SACnB,yBAAyB;CAG3B,OAAO;EACL,OAAO;EACP,UAAU;GACR,gBAAgB,QAAQ,OAAO,KAAK;GACpC,IAAI,gBAAgB,QAAQ,SAAS,GACnC,gBAAgB,UAAU;EAE9B;CACF;AACF;;;;AAKA,SAAgB,mBACd,IACA,UACA,EAAE,OAAO,WACa;CACtB,MAAM,SAAS,mBAAmB,QAAQ;CAE1C,IAAI,OAAO,SAAS,WAClB,OAAO,oBAAoB,OAAO,KAAK;CAGzC,IAAI,OAAO,SAAS,YAAY;EAC9B,IAAI;EACJ,IAAI;GACF,WAAW,IAAI,sBACZ,YAAY;IACX,KAAK,MAAM,SAAS,SAClB,IAAI,MAAM,gBAAgB;KACxB,IAAI,CAAC,OAAO,YACV,SAAS,WAAW;KAEtB,MAAM;IACR,OAAO,IAAI,OAAO,YAChB,QAAQ;GAGd,GACA,OAAO,aAAa,EAAE,YAAY,OAAO,WAAW,IAAI,KAAA,CAC1D;EACF,SAAS,OAAO;GAGd,OAAO,oBAAoB,KAAK;EAClC;EACA,SAAS,QAAQ,EAAE;EACnB,OAAO;GAAE,OAAO;GAAM,eAAe,SAAS,WAAW;EAAE;CAC7D;CAEA,IAAI,OAAO,SAAS,QAAQ;EAG1B,IAAI,OAAO,wBAAwB,YAAY;GAC7C,MAAM,OAAO,iBAAiB,WAAW,KAAK;GAC9C,OAAO;IAAE,OAAO;IAAM,eAAe,KAAK,OAAO;GAAE;EACrD;EACA,MAAM,SAAS,0BAA0B,MAAM,CAAC;EAChD,OAAO;GAAE,OAAO;GAAM,eAAe,mBAAmB,MAAM;EAAE;CAClE;CAEA,IAAI,OAAO,SAAS,eAAe;EACjC,IAAI,OAAO,MACT,OAAO,mBAAmB,KAAK;EAGjC,MAAM,iBAAiB;GACrB,SAAS;GACT,MAAM;EACR;EACA,MAAM,iBAAiB;GACrB,KAAK,MAAM,QAAQ,eACjB,GAAG,oBAAoB,MAAM,QAAQ;EAEzC;EACA,KAAK,MAAM,QAAQ,eACjB,GAAG,iBAAiB,MAAM,UAAU,EAAE,MAAM,KAAK,CAAC;EAEpD,OAAO;GAAE,OAAO;GAAM,SAAS;EAAS;CAC1C;CAEA,IAAI,OAAO,SAAS,SAAS;EAC3B,MAAM,QAAQ,WAAW,OAAO,KAAK;EACrC,MAAM,aAAc,MAAM,UAAU,MAAM,IAAI,QAAQ;EACtD,MAAM,iBAAiB,UAAU,IAAI;EAIrC,KAAK;EACL,OAAO;GACL,OAAO;GACP,eAAe,MAAM,oBAAoB,UAAU,IAAI;EACzD;CACF;CAEA,MAAM,OAAO,iBAAiB,WAAW,KAAK;CAC9C,OAAO;EAAE,OAAO;EAAM,eAAe,KAAK,OAAO;EAAG,WAAW,KAAK;CAAQ;AAC9E"}

package/dist/negotiated-events.d.ts

@@ -0,0 +1,43 @@
+//#region src/negotiated-events.d.ts
+/** The DOM change itself: whatever the announcing component was about to do. */
+type DomMutation = () => void | Promise<void>;
+/** An object that can run a DOM change inside a transition. */
+interface DomUpdateTransitioner {
+  update(mutate: DomMutation): void | Promise<unknown>;
+}
+/** A function or transitioner that receives the DOM mutation callback. */
+type DomUpdateRunner = ((apply: DomMutation) => void | Promise<unknown>) | DomUpdateTransitioner;
+/** The `EVENTS.dom.update` payload: `wrap()` plus emitter context. */
+interface DomUpdateDetail {
+  /**
+   * Take over the announced change. Valid synchronously only, and the last
+   * call wins.
+   */
+  wrap(runner: DomUpdateRunner): void;
+}
+/** An object with a method whose name matches the announced event. */
+type ExtendableTransitioner = Record<string, unknown>;
+/** What `waitUntil()` accepts: something to await, or something to call. */
+type Extension = PromiseLike<unknown> | (() => unknown) | ExtendableTransitioner;
+/** The payload of an extendable event: `waitUntil()` plus the emitter's context. */
+interface ExtendableDetail {
+  /**
+   * Hold the announced step open until this settles. Valid synchronously only,
+   * and every registration is awaited.
+   */
+  waitUntil(extension: Extension): void;
+}
+/**
+ * Announce a DOM change and apply it exactly once.
+ * The mutation runs synchronously when no listener claims it.
+ * @link https://js-toolkit-v4.studiometa.dev/api/dom/domUpdate.html
+ */
+declare function domUpdate(target: Node, mutate: DomMutation, detail?: Record<string, unknown>): Promise<void>;
+/**
+ * Announce a step and await all registered extensions.
+ * Extension failures are reported and do not reject this function.
+ * @link https://js-toolkit-v4.studiometa.dev/api/dom/emitExtendable.html
+ */
+declare function emitExtendable(target: Node, event: string, detail?: Record<string, unknown>): Promise<void>;
+//#endregion
+export { DomMutation, DomUpdateDetail, DomUpdateRunner, DomUpdateTransitioner, ExtendableDetail, ExtendableTransitioner, Extension, domUpdate, emitExtendable };

package/dist/negotiated-events.js

@@ -0,0 +1,98 @@
+import { reportDiagnostic, warnOnce } from "./diagnostics.js";
+import { EVENTS } from "./events.js";
+//#region src/negotiated-events.ts
+/** Emit a bubbling event and collect synchronous registrations. */
+function negotiate({ target, event, key, detail, accept }) {
+	let isDispatching = true;
+	const register = (registration) => {
+		if (!isDispatching) {
+			warnOnce(target, `${event}\0${key}`, "protocol.late-registration", `\`${key}()\` must be called synchronously while the \`${event}\` event dispatches.`, { target: diagnosticTarget(target) });
+			return;
+		}
+		accept(registration);
+	};
+	const payload = {
+		...detail,
+		[key]: register
+	};
+	target.dispatchEvent(new CustomEvent(event, {
+		bubbles: true,
+		cancelable: false,
+		detail: payload
+	}));
+	isDispatching = false;
+}
+/** Return the target element used for diagnostics. */
+function diagnosticTarget(target) {
+	return target instanceof Element ? target : target.parentElement ?? void 0;
+}
+function invoke(registration, method, args) {
+	if (typeof registration === "function") return registration(...args);
+	const fn = registration?.[method];
+	if (typeof fn === "function") return fn.apply(registration, args);
+	return registration;
+}
+/**
+* Announce a DOM change and apply it exactly once.
+* The mutation runs synchronously when no listener claims it.
+* @link https://js-toolkit-v4.studiometa.dev/api/dom/domUpdate.html
+*/
+async function domUpdate(target, mutate, detail) {
+	let runner = null;
+	negotiate({
+		target,
+		detail,
+		event: EVENTS.dom.update,
+		key: "wrap",
+		accept: (registration) => {
+			runner = registration;
+		}
+	});
+	const claimed = runner;
+	let isApplied = false;
+	const apply = () => {
+		if (isApplied) return;
+		isApplied = true;
+		return mutate();
+	};
+	if (!claimed) return apply();
+	let hasFailed = false;
+	try {
+		await invoke(claimed, "update", [apply]);
+	} catch (error) {
+		hasFailed = true;
+		reportDiagnostic("callback.dom-update-runner-failed", `The \`${EVENTS.dom.update}\` runner failed.`, error, { target: diagnosticTarget(target) });
+	}
+	if (!isApplied) {
+		if (!hasFailed) warnOnce(claimed, "", "protocol.unapplied-dom-update", `The \`${EVENTS.dom.update}\` runner settled without applying the change; the change was applied directly.`, { target: diagnosticTarget(target) });
+		await apply();
+	}
+}
+/**
+* Announce a step and await all registered extensions.
+* Extension failures are reported and do not reject this function.
+* @link https://js-toolkit-v4.studiometa.dev/api/dom/emitExtendable.html
+*/
+async function emitExtendable(target, event, detail) {
+	const pending = [];
+	negotiate({
+		target,
+		detail,
+		event,
+		key: "waitUntil",
+		accept: (extension) => {
+			pending.push((async () => {
+				try {
+					await invoke(extension, event, []);
+				} catch (error) {
+					reportDiagnostic("callback.extendable-event-extension-failed", `An extension of the \`${event}\` event failed.`, error, { target: diagnosticTarget(target) });
+				}
+			})());
+		}
+	});
+	await Promise.all(pending);
+}
+//#endregion
+export { domUpdate, emitExtendable };
+
+//# sourceMappingURL=negotiated-events.js.map

package/dist/negotiated-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiated-events.js","names":[],"sources":["../src/negotiated-events.ts"],"sourcesContent":["import { reportDiagnostic, warnOnce } from './diagnostics.js';\nimport { EVENTS } from './events.js';\n\n/**\n * Negotiated event invariants:\n * registrations are synchronous, the last `wrap()` wins, and all `waitUntil()` calls are awaited.\n * Registration failures are reported without stopping the emitter's work.\n */\n\ninterface NegotiationOptions<R> {\n  /** The DOM node the bubbling event starts from. */\n  target: Node;\n  /** The event's name, for dispatch, warnings and duck-typed method lookup. */\n  event: string;\n  /** The key the registration function is exposed under: `wrap`, `waitUntil`. */\n  key: string;\n  /** Extra context merged into the detail, alongside the registration function. */\n  detail?: Record<string, unknown>;\n  /** Called for each registration made while the event dispatches. */\n  accept: (registration: R) => void;\n}\n\n/** Emit a bubbling event and collect synchronous registrations. */\nfunction negotiate<R>({ target, event, key, detail, accept }: NegotiationOptions<R>): void {\n  let isDispatching = true;\n  const register = (registration: R) => {\n    if (!isDispatching) {\n      warnOnce(\n        target,\n        `${event}\\0${key}`,\n        'protocol.late-registration',\n        `\\`${key}()\\` must be called synchronously while the \\`${event}\\` event dispatches.`,\n        { target: diagnosticTarget(target) },\n      );\n      return;\n    }\n    accept(registration);\n  };\n  const payload = {\n    ...detail,\n    [key]: register,\n  };\n\n  target.dispatchEvent(\n    new CustomEvent(event, { bubbles: true, cancelable: false, detail: payload }),\n  );\n  isDispatching = false;\n}\n\n/** Return the target element used for diagnostics. */\nfunction diagnosticTarget(target: Node): Element | undefined {\n  return target instanceof Element ? target : (target.parentElement ?? undefined);\n}\n\nfunction invoke(registration: unknown, method: string, args: unknown[]): unknown {\n  if (typeof registration === 'function') {\n    return (registration as (...rest: unknown[]) => unknown)(...args);\n  }\n  const fn = (registration as Record<string, unknown> | null | undefined)?.[method];\n  if (typeof fn === 'function') {\n    return (fn as (...rest: unknown[]) => unknown).apply(registration, args);\n  }\n  return registration;\n}\n\n/** The DOM change itself: whatever the announcing component was about to do. */\nexport type DomMutation = () => void | Promise<void>;\n\n/** An object that can run a DOM change inside a transition. */\nexport interface DomUpdateTransitioner {\n  update(mutate: DomMutation): void | Promise<unknown>;\n}\n\n/** A function or transitioner that receives the DOM mutation callback. */\nexport type DomUpdateRunner =\n  | ((apply: DomMutation) => void | Promise<unknown>)\n  | DomUpdateTransitioner;\n\n/** The `EVENTS.dom.update` payload: `wrap()` plus emitter context. */\nexport interface DomUpdateDetail {\n  /**\n   * Take over the announced change. Valid synchronously only, and the last\n   * call wins.\n   */\n  wrap(runner: DomUpdateRunner): void;\n}\n\n/** An object with a method whose name matches the announced event. */\nexport type ExtendableTransitioner = Record<string, unknown>;\n\n/** What `waitUntil()` accepts: something to await, or something to call. */\nexport type Extension = PromiseLike<unknown> | (() => unknown) | ExtendableTransitioner;\n\n/** The payload of an extendable event: `waitUntil()` plus the emitter's context. */\nexport interface ExtendableDetail {\n  /**\n   * Hold the announced step open until this settles. Valid synchronously only,\n   * and every registration is awaited.\n   */\n  waitUntil(extension: Extension): void;\n}\n\n/**\n * Announce a DOM change and apply it exactly once.\n * The mutation runs synchronously when no listener claims it.\n * @link https://js-toolkit-v4.studiometa.dev/api/dom/domUpdate.html\n */\nexport async function domUpdate(\n  target: Node,\n  mutate: DomMutation,\n  detail?: Record<string, unknown>,\n): Promise<void> {\n  let runner: DomUpdateRunner | null = null;\n\n  negotiate<DomUpdateRunner>({\n    target,\n    detail,\n    event: EVENTS.dom.update,\n    key: 'wrap',\n    // Bubbling order makes the last claim win.\n    accept: (registration) => {\n      runner = registration;\n    },\n  });\n\n  // Read through the declared type: the only assignment happens inside\n  // `accept`, which control-flow analysis does not follow, so the narrowing\n  // left by the initializer would claim `null` here.\n  const claimed = runner as DomUpdateRunner | null;\n\n  let isApplied = false;\n  const apply: DomMutation = () => {\n    // Exactly once, so a runner calling `apply()` twice cannot double-insert.\n    if (isApplied) {\n      return;\n    }\n    isApplied = true;\n    return mutate();\n  };\n\n  if (!claimed) {\n    return apply();\n  }\n\n  let hasFailed = false;\n  try {\n    await invoke(claimed, 'update', [apply]);\n  } catch (error) {\n    hasFailed = true;\n    reportDiagnostic(\n      'callback.dom-update-runner-failed',\n      `The \\`${EVENTS.dom.update}\\` runner failed.`,\n      error,\n      { target: diagnosticTarget(target) },\n    );\n  }\n\n  if (!isApplied) {\n    if (!hasFailed) {\n      warnOnce(\n        claimed,\n        '',\n        'protocol.unapplied-dom-update',\n        `The \\`${EVENTS.dom.update}\\` runner settled without applying the change; the change was applied directly.`,\n        { target: diagnosticTarget(target) },\n      );\n    }\n    await apply();\n  }\n}\n\n/**\n * Announce a step and await all registered extensions.\n * Extension failures are reported and do not reject this function.\n * @link https://js-toolkit-v4.studiometa.dev/api/dom/emitExtendable.html\n */\nexport async function emitExtendable(\n  target: Node,\n  event: string,\n  detail?: Record<string, unknown>,\n): Promise<void> {\n  const pending: Promise<unknown>[] = [];\n\n  negotiate<Extension>({\n    target,\n    detail,\n    event,\n    key: 'waitUntil',\n    // Every registration is awaited.\n    accept: (extension) => {\n      pending.push(\n        (async () => {\n          try {\n            await invoke(extension, event, []);\n          } catch (error) {\n            reportDiagnostic(\n              'callback.extendable-event-extension-failed',\n              `An extension of the \\`${event}\\` event failed.`,\n              error,\n              { target: diagnosticTarget(target) },\n            );\n          }\n        })(),\n      );\n    },\n  });\n\n  await Promise.all(pending);\n}\n"],"mappings":";;;;AAuBA,SAAS,UAAa,EAAE,QAAQ,OAAO,KAAK,QAAQ,UAAuC;CACzF,IAAI,gBAAgB;CACpB,MAAM,YAAY,iBAAoB;EACpC,IAAI,CAAC,eAAe;GAClB,SACE,QACA,GAAG,MAAM,IAAI,OACb,8BACA,KAAK,IAAI,gDAAgD,MAAM,uBAC/D,EAAE,QAAQ,iBAAiB,MAAM,EAAE,CACrC;GACA;EACF;EACA,OAAO,YAAY;CACrB;CACA,MAAM,UAAU;EACd,GAAG;GACF,MAAM;CACT;CAEA,OAAO,cACL,IAAI,YAAY,OAAO;EAAE,SAAS;EAAM,YAAY;EAAO,QAAQ;CAAQ,CAAC,CAC9E;CACA,gBAAgB;AAClB;;AAGA,SAAS,iBAAiB,QAAmC;CAC3D,OAAO,kBAAkB,UAAU,SAAU,OAAO,iBAAiB,KAAA;AACvE;AAEA,SAAS,OAAO,cAAuB,QAAgB,MAA0B;CAC/E,IAAI,OAAO,iBAAiB,YAC1B,OAAQ,aAAiD,GAAG,IAAI;CAElE,MAAM,KAAM,eAA8D;CAC1E,IAAI,OAAO,OAAO,YAChB,OAAQ,GAAuC,MAAM,cAAc,IAAI;CAEzE,OAAO;AACT;;;;;;AA4CA,eAAsB,UACpB,QACA,QACA,QACe;CACf,IAAI,SAAiC;CAErC,UAA2B;EACzB;EACA;EACA,OAAO,OAAO,IAAI;EAClB,KAAK;EAEL,SAAS,iBAAiB;GACxB,SAAS;EACX;CACF,CAAC;CAKD,MAAM,UAAU;CAEhB,IAAI,YAAY;CAChB,MAAM,cAA2B;EAE/B,IAAI,WACF;EAEF,YAAY;EACZ,OAAO,OAAO;CAChB;CAEA,IAAI,CAAC,SACH,OAAO,MAAM;CAGf,IAAI,YAAY;CAChB,IAAI;EACF,MAAM,OAAO,SAAS,UAAU,CAAC,KAAK,CAAC;CACzC,SAAS,OAAO;EACd,YAAY;EACZ,iBACE,qCACA,SAAS,OAAO,IAAI,OAAO,oBAC3B,OACA,EAAE,QAAQ,iBAAiB,MAAM,EAAE,CACrC;CACF;CAEA,IAAI,CAAC,WAAW;EACd,IAAI,CAAC,WACH,SACE,SACA,IACA,iCACA,SAAS,OAAO,IAAI,OAAO,kFAC3B,EAAE,QAAQ,iBAAiB,MAAM,EAAE,CACrC;EAEF,MAAM,MAAM;CACd;AACF;;;;;;AAOA,eAAsB,eACpB,QACA,OACA,QACe;CACf,MAAM,UAA8B,CAAC;CAErC,UAAqB;EACnB;EACA;EACA;EACA,KAAK;EAEL,SAAS,cAAc;GACrB,QAAQ,MACL,YAAY;IACX,IAAI;KACF,MAAM,OAAO,WAAW,OAAO,CAAC,CAAC;IACnC,SAAS,OAAO;KACd,iBACE,8CACA,yBAAyB,MAAM,mBAC/B,OACA,EAAE,QAAQ,iBAAiB,MAAM,EAAE,CACrC;IACF;GACF,EAAA,CAAG,CACL;EACF;CACF,CAAC;CAED,MAAM,QAAQ,IAAI,OAAO;AAC3B"}

package/dist/protocol-symbols.d.ts

@@ -0,0 +1,24 @@
+//#region src/protocol-symbols.d.ts
+/** Realm-stable private key with a `unique symbol` type. */
+declare const HANDLER_REGISTRATIONS: unique symbol;
+/**
+ * Where an element publishes the instances mounted on it, keyed by component
+ * name.
+ *
+ * A symbol rather than a string property: v3 keeps its own map under
+ * `el.__base__` and stores a `'terminated'` string in it, so a v4 registry
+ * reading that map found a string where an instance belongs and called
+ * `$unmount()` on it. `Symbol.for` is realm-global, so evaluated copies of
+ * this package still agree on the key.
+ *
+ * Not public API — `getInstance()`, `getInstances()`,
+ * `getMountedInstances()` and `getUnmountedInstances()` are how consumers
+ * resolve instances, by name, by element, or both. Between them they express
+ * every read this map answers, so nothing has to reach for the symbol. From a
+ * devtools console, where there is nothing to import, the realm-global key is
+ * the whole recipe:
+ * `$0[Symbol.for('@studiometa/js-toolkit/instances')]`.
+ */
+declare const INSTANCES: unique symbol;
+//#endregion
+export { HANDLER_REGISTRATIONS, INSTANCES };

package/dist/protocol-symbols.js

@@ -0,0 +1,26 @@
+//#region src/protocol-symbols.ts
+/** Realm-stable private key with a `unique symbol` type. */
+const HANDLER_REGISTRATIONS = Symbol.for("@studiometa/js-toolkit/handler-registrations");
+/**
+* Where an element publishes the instances mounted on it, keyed by component
+* name.
+*
+* A symbol rather than a string property: v3 keeps its own map under
+* `el.__base__` and stores a `'terminated'` string in it, so a v4 registry
+* reading that map found a string where an instance belongs and called
+* `$unmount()` on it. `Symbol.for` is realm-global, so evaluated copies of
+* this package still agree on the key.
+*
+* Not public API — `getInstance()`, `getInstances()`,
+* `getMountedInstances()` and `getUnmountedInstances()` are how consumers
+* resolve instances, by name, by element, or both. Between them they express
+* every read this map answers, so nothing has to reach for the symbol. From a
+* devtools console, where there is nothing to import, the realm-global key is
+* the whole recipe:
+* `$0[Symbol.for('@studiometa/js-toolkit/instances')]`.
+*/
+const INSTANCES = Symbol.for("@studiometa/js-toolkit/instances");
+//#endregion
+export { HANDLER_REGISTRATIONS, INSTANCES };
+
+//# sourceMappingURL=protocol-symbols.js.map

package/dist/protocol-symbols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-symbols.js","names":[],"sources":["../src/protocol-symbols.ts"],"sourcesContent":["/** Realm-stable private key with a `unique symbol` type. */\nexport const HANDLER_REGISTRATIONS: unique symbol = Symbol.for(\n  '@studiometa/js-toolkit/handler-registrations',\n);\n\n/**\n * Where an element publishes the instances mounted on it, keyed by component\n * name.\n *\n * A symbol rather than a string property: v3 keeps its own map under\n * `el.__base__` and stores a `'terminated'` string in it, so a v4 registry\n * reading that map found a string where an instance belongs and called\n * `$unmount()` on it. `Symbol.for` is realm-global, so evaluated copies of\n * this package still agree on the key.\n *\n * Not public API — `getInstance()`, `getInstances()`,\n * `getMountedInstances()` and `getUnmountedInstances()` are how consumers\n * resolve instances, by name, by element, or both. Between them they express\n * every read this map answers, so nothing has to reach for the symbol. From a\n * devtools console, where there is nothing to import, the realm-global key is\n * the whole recipe:\n * `$0[Symbol.for('@studiometa/js-toolkit/instances')]`.\n */\nexport const INSTANCES: unique symbol = Symbol.for('@studiometa/js-toolkit/instances');\n"],"mappings":";;AACA,MAAa,wBAAuC,OAAO,IACzD,8CACF;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,YAA2B,OAAO,IAAI,kCAAkC"}

package/dist/registry.d.ts

@@ -0,0 +1,68 @@
+import { MountStrategy } from "./mount-strategies.js";
+import { BaseConstructor, ComponentImporter } from "./Base.js";
+//#region src/registry.d.ts
+/** A lazy component importer and its optional pre-load mount strategy. */
+interface ComponentManifestEntry {
+  load: ComponentImporter;
+  mountStrategy?: MountStrategy;
+}
+/** `data-component` tokens mapped to the lazy entry which resolves them. */
+type ComponentManifest = Record<string, ComponentImporter | ComponentManifestEntry>;
+/**
+ * Register a component and its merged family, then scan matching elements.
+ *
+ * The name comes from the merged config, like the instance's `$id` and the
+ * `INSTANCES` map key it publishes itself under: a subclass which extends a
+ * component with extra config and forgets to rename would otherwise register
+ * under `undefined` instead of colliding with the name it inherited.
+ * @link https://js-toolkit-v4.studiometa.dev/api/registry/registerComponent.html
+ */
+declare function registerComponent(ComponentClass: BaseConstructor): void;
+/** @link https://js-toolkit-v4.studiometa.dev/api/registry/registerComponents.html */
+declare function registerComponents(...classes: BaseConstructor[]): void;
+/**
+ * Register lazy component entries. Element `data-mount` overrides the entry strategy; unloaded components have no instance.
+ * @link https://js-toolkit-v4.studiometa.dev/api/registry/registerManifest.html
+ */
+declare function registerManifest(entries: ComponentManifest): void;
+/**
+ * Drop every registration, so the names a test used are free again.
+ *
+ * `registerComponent()` has no inverse by design: a page registers once and
+ * keeps the registration for as long as it lives. A test suite is the one
+ * caller for which that is wrong — the registry is page-wide and it survives
+ * `resetDom()`, so a name registered by one spec is still taken in the next
+ * one, and the workaround is a counter that mints `Widget-1`, `Widget-2` and
+ * tells the reader nothing. This is the escape hatch, re-exported from
+ * `@studiometa/js-toolkit/test`; it is not part of a page's vocabulary.
+ *
+ * **It is coarse on purpose.** A targeted `unregisterComponent(name)` would
+ * have to find the elements holding that name's live triggers, and the map
+ * from element to controller is a `WeakMap`: it cannot be enumerated, so
+ * nothing can walk it to dispose them, and a `querySelectorAll()` sweep would
+ * still miss every detached element. Clearing the whole registry works because
+ * the mutation-observer path already disposes a controller as its element
+ * leaves the DOM — which is why the call belongs *after* `resetDom()`.
+ *
+ * Two things it therefore does not do. It cannot clear that `WeakMap`, so a
+ * controller whose element is still connected keeps its trigger; empty the DOM
+ * first. And it does not narrow the attribute filter the shared observer built
+ * from the options of everything ever registered — an extra watched attribute
+ * costs a reconciliation pass that finds no owner, and nothing more.
+ *
+ * **Where the call belongs.** 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:
+ *
+ * ```ts
+ * afterEach(async () => {
+ *   await resetDom();
+ *   resetRegistry();
+ *   registerComponents(Subject, Emitter);
+ * });
+ * ```
+ */
+declare function resetRegistry(): void;
+//#endregion
+export { type ComponentImporter, ComponentManifest, ComponentManifestEntry, registerComponent, registerComponents, registerManifest, resetRegistry };