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

package/dist/diagnostic-contract.js

@@ -0,0 +1,66 @@
+//#region src/diagnostic-contract.ts
+const attribute = Object.freeze({ unknownQualifier: "attribute.unknown-qualifier" });
+const callback = Object.freeze({
+	signalFailed: "callback.signal-failed",
+	contextSubscriptionFailed: "callback.context-subscription-failed",
+	contextTeardownFailed: "callback.context-teardown-failed",
+	attributeWatcherFailed: "callback.attribute-watcher-failed",
+	serviceFailed: "callback.service-failed",
+	schedulerTickFailed: "callback.scheduler-tick-failed",
+	scheduledTaskFailed: "callback.scheduled-task-failed",
+	domUpdateRunnerFailed: "callback.dom-update-runner-failed",
+	extendableEventExtensionFailed: "callback.extendable-event-extension-failed"
+});
+const component = Object.freeze({
+	loadFailed: "component.load-failed",
+	mountFailed: "component.mount-failed",
+	lifecycleFailed: "component.lifecycle-failed",
+	invalidMountStrategy: "component.invalid-mount-strategy",
+	invalidFamilyDeclaration: "component.invalid-family-declaration",
+	configConflict: "component.config-conflict"
+});
+const event = Object.freeze({ invalidEmitPayload: "event.invalid-emit-payload" });
+const manifest = Object.freeze({ duplicateToken: "manifest.duplicate-token" });
+const option = Object.freeze({ literalDefault: "option.literal-default" });
+const protocol = Object.freeze({
+	lateRegistration: "protocol.late-registration",
+	unappliedDomUpdate: "protocol.unapplied-dom-update"
+});
+const ref = Object.freeze({ mismatch: "ref.mismatch" });
+const registry = Object.freeze({
+	conflict: "registry.conflict",
+	lazyNameMismatch: "registry.lazy-name-mismatch"
+});
+const responsive = Object.freeze({ unknownBreakpoint: "responsive.unknown-breakpoint" });
+const scheduler = Object.freeze({ backgroundPostFailed: "scheduler.background-post-failed" });
+const swap = Object.freeze({ selfIgnored: "swap.self-ignored" });
+const service = Object.freeze({ missingTarget: "service.missing-target" });
+const storage = Object.freeze({
+	accessFailed: "storage.access-failed",
+	deserializeFailed: "storage.deserialize-failed",
+	serializeFailed: "storage.serialize-failed"
+});
+/**
+* Stable codes carried by toolkit diagnostics.
+* @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/DIAGNOSTICS.html
+*/
+const DIAGNOSTICS = Object.freeze({
+	attribute,
+	callback,
+	component,
+	event,
+	manifest,
+	option,
+	protocol,
+	ref,
+	registry,
+	responsive,
+	scheduler,
+	service,
+	storage,
+	swap
+});
+//#endregion
+export { DIAGNOSTICS };
+
+//# sourceMappingURL=diagnostic-contract.js.map

package/dist/diagnostic-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-contract.js","names":[],"sources":["../src/diagnostic-contract.ts"],"sourcesContent":["const attribute = Object.freeze({\n  unknownQualifier: 'attribute.unknown-qualifier',\n} as const);\n\nconst callback = Object.freeze({\n  signalFailed: 'callback.signal-failed',\n  contextSubscriptionFailed: 'callback.context-subscription-failed',\n  contextTeardownFailed: 'callback.context-teardown-failed',\n  attributeWatcherFailed: 'callback.attribute-watcher-failed',\n  serviceFailed: 'callback.service-failed',\n  schedulerTickFailed: 'callback.scheduler-tick-failed',\n  scheduledTaskFailed: 'callback.scheduled-task-failed',\n  domUpdateRunnerFailed: 'callback.dom-update-runner-failed',\n  extendableEventExtensionFailed: 'callback.extendable-event-extension-failed',\n} as const);\n\nconst component = Object.freeze({\n  loadFailed: 'component.load-failed',\n  mountFailed: 'component.mount-failed',\n  lifecycleFailed: 'component.lifecycle-failed',\n  invalidMountStrategy: 'component.invalid-mount-strategy',\n  invalidFamilyDeclaration: 'component.invalid-family-declaration',\n  configConflict: 'component.config-conflict',\n} as const);\n\nconst event = Object.freeze({\n  invalidEmitPayload: 'event.invalid-emit-payload',\n} as const);\n\nconst manifest = Object.freeze({\n  duplicateToken: 'manifest.duplicate-token',\n} as const);\n\nconst option = Object.freeze({\n  literalDefault: 'option.literal-default',\n} as const);\n\nconst protocol = Object.freeze({\n  lateRegistration: 'protocol.late-registration',\n  unappliedDomUpdate: 'protocol.unapplied-dom-update',\n} as const);\n\nconst ref = Object.freeze({\n  mismatch: 'ref.mismatch',\n} as const);\n\nconst registry = Object.freeze({\n  conflict: 'registry.conflict',\n  lazyNameMismatch: 'registry.lazy-name-mismatch',\n} as const);\n\nconst responsive = Object.freeze({\n  unknownBreakpoint: 'responsive.unknown-breakpoint',\n} as const);\n\nconst scheduler = Object.freeze({\n  backgroundPostFailed: 'scheduler.background-post-failed',\n} as const);\n\nconst swap = Object.freeze({\n  selfIgnored: 'swap.self-ignored',\n} as const);\n\nconst service = Object.freeze({\n  missingTarget: 'service.missing-target',\n} as const);\n\nconst storage = Object.freeze({\n  accessFailed: 'storage.access-failed',\n  deserializeFailed: 'storage.deserialize-failed',\n  serializeFailed: 'storage.serialize-failed',\n} as const);\n\n/**\n * Stable codes carried by toolkit diagnostics.\n * @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/DIAGNOSTICS.html\n */\nexport const DIAGNOSTICS = Object.freeze({\n  attribute,\n  callback,\n  component,\n  event,\n  manifest,\n  option,\n  protocol,\n  ref,\n  registry,\n  responsive,\n  scheduler,\n  service,\n  storage,\n  swap,\n} as const);\n\nexport type ToolkitDiagnosticSeverity = 'warning' | 'error';\n\ntype NestedValue<T> = T extends string ? T : { [K in keyof T]: NestedValue<T[K]> }[keyof T];\n\n/** One stable value from {@link DIAGNOSTICS}. */\nexport type ToolkitCoreDiagnosticCode = NestedValue<typeof DIAGNOSTICS>;\n\n/**\n * A code minted outside core, in the same `namespace.detail` shape.\n *\n * The channel is only worth having if a consumer can be told apart on it: a\n * listener filters by code, so a component reporting through a shared generic\n * code would be unfilterable, and one reporting through a core code would be\n * indistinguishable from core itself. The template literal is the loosest\n * thing that still keeps the shape a filter can rely on — `startsWith('figure.')`\n * works because the namespace is mandatory.\n */\nexport type ToolkitConsumerDiagnosticCode = `${string}.${string}`;\n\n/**\n * A diagnostic code: one of core's own, or a consumer's namespaced one.\n *\n * Core's set stays enumerated and documented as {@link DIAGNOSTICS}; the union\n * with the wider shape is what lets a component outside core report on the same\n * channel rather than reaching for `console.warn`.\n */\nexport type ToolkitDiagnosticCode = ToolkitCoreDiagnosticCode | ToolkitConsumerDiagnosticCode;\n\ninterface ToolkitDiagnosticBaseDetail {\n  readonly code: ToolkitDiagnosticCode;\n  readonly message: string;\n  readonly component?: string;\n}\n\n/** The payload of the public diagnostic event. */\nexport type ToolkitDiagnosticDetail =\n  | (ToolkitDiagnosticBaseDetail & {\n      readonly severity: 'warning';\n      readonly error?: never;\n    })\n  | (ToolkitDiagnosticBaseDetail & {\n      readonly severity: 'error';\n      readonly error: unknown;\n    });\n"],"mappings":";AAAA,MAAM,YAAY,OAAO,OAAO,EAC9B,kBAAkB,8BACpB,CAAU;AAEV,MAAM,WAAW,OAAO,OAAO;CAC7B,cAAc;CACd,2BAA2B;CAC3B,uBAAuB;CACvB,wBAAwB;CACxB,eAAe;CACf,qBAAqB;CACrB,qBAAqB;CACrB,uBAAuB;CACvB,gCAAgC;AAClC,CAAU;AAEV,MAAM,YAAY,OAAO,OAAO;CAC9B,YAAY;CACZ,aAAa;CACb,iBAAiB;CACjB,sBAAsB;CACtB,0BAA0B;CAC1B,gBAAgB;AAClB,CAAU;AAEV,MAAM,QAAQ,OAAO,OAAO,EAC1B,oBAAoB,6BACtB,CAAU;AAEV,MAAM,WAAW,OAAO,OAAO,EAC7B,gBAAgB,2BAClB,CAAU;AAEV,MAAM,SAAS,OAAO,OAAO,EAC3B,gBAAgB,yBAClB,CAAU;AAEV,MAAM,WAAW,OAAO,OAAO;CAC7B,kBAAkB;CAClB,oBAAoB;AACtB,CAAU;AAEV,MAAM,MAAM,OAAO,OAAO,EACxB,UAAU,eACZ,CAAU;AAEV,MAAM,WAAW,OAAO,OAAO;CAC7B,UAAU;CACV,kBAAkB;AACpB,CAAU;AAEV,MAAM,aAAa,OAAO,OAAO,EAC/B,mBAAmB,gCACrB,CAAU;AAEV,MAAM,YAAY,OAAO,OAAO,EAC9B,sBAAsB,mCACxB,CAAU;AAEV,MAAM,OAAO,OAAO,OAAO,EACzB,aAAa,oBACf,CAAU;AAEV,MAAM,UAAU,OAAO,OAAO,EAC5B,eAAe,yBACjB,CAAU;AAEV,MAAM,UAAU,OAAO,OAAO;CAC5B,cAAc;CACd,mBAAmB;CACnB,iBAAiB;AACnB,CAAU;;;;;AAMV,MAAa,cAAc,OAAO,OAAO;CACvC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAU"}

package/dist/diagnostics.d.ts

@@ -0,0 +1,41 @@
+import { ToolkitDiagnosticCode, ToolkitDiagnosticDetail } from "./diagnostic-contract.js";
+//#region src/diagnostics.d.ts
+interface DiagnosticContext {
+  component?: string;
+  target?: Element;
+}
+/**
+ * Report a recovered failure on the diagnostic channel.
+ *
+ * A component reports through {@link Base.$error}, which fills in its own name
+ * and element. This is the form for code with no instance to report as — a
+ * module-level helper, or a class which is not a `Base`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/reportDiagnostic.html
+ */
+declare function reportDiagnostic(code: ToolkitDiagnosticCode, message: string, error: unknown, { component, target }?: DiagnosticContext): CustomEvent<ToolkitDiagnosticDetail>;
+/**
+ * Run a callback the framework does not own, and report a throw instead of
+ * letting it out: one failing subscriber must not stop delivery to the others,
+ * nor turn a subscription into a failure for the caller.
+ *
+ * @internal
+ */
+declare function isolateCallbackFailure(code: ToolkitDiagnosticCode, message: string, run: () => void): void;
+/**
+ * Report a warning on the diagnostic channel.
+ *
+ * A component reports through {@link Base.$warn}, which fills in its own name
+ * and element. This is the form for code with no instance to report as — a
+ * module-level helper, or a class which is not a `Base`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/warn.html
+ */
+declare function warn(code: ToolkitDiagnosticCode, message: string, { component, target }?: DiagnosticContext): CustomEvent<ToolkitDiagnosticDetail>;
+/**
+ * Report one warning per weak owner and misuse key across evaluated package
+ * copies in this realm.
+ *
+ * @internal
+ */
+declare function warnOnce(owner: object, key: string, code: ToolkitDiagnosticCode, message: string, context?: DiagnosticContext): CustomEvent<ToolkitDiagnosticDetail> | undefined;
+//#endregion
+export { isolateCallbackFailure, reportDiagnostic, warn, warnOnce };

package/dist/diagnostics.js

@@ -0,0 +1,102 @@
+import { getSharedRuntimeSlot } from "./shared-runtime.js";
+//#region src/diagnostics.ts
+function warningOwners() {
+	return getSharedRuntimeSlot("diagnostics:warnings", 1, () => ({ owners: /* @__PURE__ */ new WeakMap() })).owners;
+}
+function dispatchDiagnostic(detail, target) {
+	let runDefaultSink;
+	if (detail.severity === "warning") {
+		const output = `[js-toolkit:${detail.code}] ${detail.message}`;
+		runDefaultSink = () => console.warn(output);
+	} else {
+		const error = detail.error;
+		runDefaultSink = () => reportError(error);
+	}
+	const event = new CustomEvent("js-toolkit:diagnostic", {
+		bubbles: true,
+		composed: true,
+		cancelable: true,
+		detail
+	});
+	(target?.isConnected ? target : document).dispatchEvent(event);
+	if (!event.defaultPrevented) runDefaultSink();
+	return event;
+}
+/**
+* Report a recovered failure on the diagnostic channel.
+*
+* A component reports through {@link Base.$error}, which fills in its own name
+* and element. This is the form for code with no instance to report as — a
+* module-level helper, or a class which is not a `Base`.
+* @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/reportDiagnostic.html
+*/
+function reportDiagnostic(code, message, error, { component, target } = {}) {
+	return dispatchDiagnostic(component === void 0 ? {
+		severity: "error",
+		code,
+		message,
+		error
+	} : {
+		severity: "error",
+		code,
+		message,
+		component,
+		error
+	}, target);
+}
+/**
+* Run a callback the framework does not own, and report a throw instead of
+* letting it out: one failing subscriber must not stop delivery to the others,
+* nor turn a subscription into a failure for the caller.
+*
+* @internal
+*/
+function isolateCallbackFailure(code, message, run) {
+	try {
+		run();
+	} catch (error) {
+		reportDiagnostic(code, message, error);
+	}
+}
+/**
+* Report a warning on the diagnostic channel.
+*
+* A component reports through {@link Base.$warn}, which fills in its own name
+* and element. This is the form for code with no instance to report as — a
+* module-level helper, or a class which is not a `Base`.
+* @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/warn.html
+*/
+function warn(code, message, { component, target } = {}) {
+	return dispatchDiagnostic(component === void 0 ? {
+		severity: "warning",
+		code,
+		message
+	} : {
+		severity: "warning",
+		code,
+		message,
+		component
+	}, target);
+}
+/**
+* Report one warning per weak owner and misuse key across evaluated package
+* copies in this realm.
+*
+* @internal
+*/
+function warnOnce(owner, key, code, message, context) {
+	const owners = warningOwners();
+	let keys = owners.get(owner);
+	if (!keys) {
+		keys = /* @__PURE__ */ new Set();
+		owners.set(owner, keys);
+	}
+	const warningKey = `${code}\0${key}`;
+	if (keys.has(warningKey)) return;
+	keys.add(warningKey);
+	return warn(code, message, context);
+}
+//#endregion
+export { isolateCallbackFailure, reportDiagnostic, warn, warnOnce };
+
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","names":[],"sources":["../src/diagnostics.ts"],"sourcesContent":["import { type ToolkitDiagnosticCode, type ToolkitDiagnosticDetail } from './diagnostic-contract.js';\nimport { getSharedRuntimeSlot } from './shared-runtime.js';\n\ninterface DiagnosticContext {\n  component?: string;\n  target?: Element;\n}\n\ninterface DiagnosticWarningState {\n  owners: WeakMap<object, Set<string>>;\n}\n\nfunction warningOwners(): WeakMap<object, Set<string>> {\n  return getSharedRuntimeSlot<DiagnosticWarningState>('diagnostics:warnings', 1, () => ({\n    owners: new WeakMap(),\n  })).owners;\n}\n\nfunction dispatchDiagnostic(\n  detail: ToolkitDiagnosticDetail,\n  target?: Element,\n): CustomEvent<ToolkitDiagnosticDetail> {\n  let runDefaultSink: () => void;\n  if (detail.severity === 'warning') {\n    const output = `[js-toolkit:${detail.code}] ${detail.message}`;\n    runDefaultSink = () => console.warn(output);\n  } else {\n    const error = detail.error;\n    runDefaultSink = () => reportError(error);\n  }\n  const event = new CustomEvent<ToolkitDiagnosticDetail>('js-toolkit:diagnostic', {\n    bubbles: true,\n    composed: true,\n    cancelable: true,\n    detail,\n  });\n  (target?.isConnected ? target : document).dispatchEvent(event);\n\n  if (!event.defaultPrevented) {\n    runDefaultSink();\n  }\n\n  return event;\n}\n\n/**\n * Report a recovered failure on the diagnostic channel.\n *\n * A component reports through {@link Base.$error}, which fills in its own name\n * and element. This is the form for code with no instance to report as — a\n * module-level helper, or a class which is not a `Base`.\n * @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/reportDiagnostic.html\n */\nexport function reportDiagnostic(\n  code: ToolkitDiagnosticCode,\n  message: string,\n  error: unknown,\n  { component, target }: DiagnosticContext = {},\n): CustomEvent<ToolkitDiagnosticDetail> {\n  const detail: ToolkitDiagnosticDetail =\n    component === undefined\n      ? { severity: 'error', code, message, error }\n      : { severity: 'error', code, message, component, error };\n  return dispatchDiagnostic(detail, target);\n}\n\n/**\n * Run a callback the framework does not own, and report a throw instead of\n * letting it out: one failing subscriber must not stop delivery to the others,\n * nor turn a subscription into a failure for the caller.\n *\n * @internal\n */\nexport function isolateCallbackFailure(\n  code: ToolkitDiagnosticCode,\n  message: string,\n  run: () => void,\n): void {\n  try {\n    run();\n  } catch (error) {\n    reportDiagnostic(code, message, error);\n  }\n}\n\n/**\n * Report a warning on the diagnostic channel.\n *\n * A component reports through {@link Base.$warn}, which fills in its own name\n * and element. This is the form for code with no instance to report as — a\n * module-level helper, or a class which is not a `Base`.\n * @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/warn.html\n */\nexport function warn(\n  code: ToolkitDiagnosticCode,\n  message: string,\n  { component, target }: DiagnosticContext = {},\n): CustomEvent<ToolkitDiagnosticDetail> {\n  const detail: ToolkitDiagnosticDetail =\n    component === undefined\n      ? { severity: 'warning', code, message }\n      : { severity: 'warning', code, message, component };\n  return dispatchDiagnostic(detail, target);\n}\n\n/**\n * Report one warning per weak owner and misuse key across evaluated package\n * copies in this realm.\n *\n * @internal\n */\nexport function warnOnce(\n  owner: object,\n  key: string,\n  code: ToolkitDiagnosticCode,\n  message: string,\n  context?: DiagnosticContext,\n): CustomEvent<ToolkitDiagnosticDetail> | undefined {\n  const owners = warningOwners();\n  let keys = owners.get(owner);\n  if (!keys) {\n    keys = new Set();\n    owners.set(owner, keys);\n  }\n  const warningKey = `${code}\\0${key}`;\n  if (keys.has(warningKey)) {\n    return undefined;\n  }\n  keys.add(warningKey);\n  return warn(code, message, context);\n}\n"],"mappings":";;AAYA,SAAS,gBAA8C;CACrD,OAAO,qBAA6C,wBAAwB,UAAU,EACpF,wBAAQ,IAAI,QAAQ,EACtB,EAAE,CAAC,CAAC;AACN;AAEA,SAAS,mBACP,QACA,QACsC;CACtC,IAAI;CACJ,IAAI,OAAO,aAAa,WAAW;EACjC,MAAM,SAAS,eAAe,OAAO,KAAK,IAAI,OAAO;EACrD,uBAAuB,QAAQ,KAAK,MAAM;CAC5C,OAAO;EACL,MAAM,QAAQ,OAAO;EACrB,uBAAuB,YAAY,KAAK;CAC1C;CACA,MAAM,QAAQ,IAAI,YAAqC,yBAAyB;EAC9E,SAAS;EACT,UAAU;EACV,YAAY;EACZ;CACF,CAAC;CACD,CAAC,QAAQ,cAAc,SAAS,SAAA,CAAU,cAAc,KAAK;CAE7D,IAAI,CAAC,MAAM,kBACT,eAAe;CAGjB,OAAO;AACT;;;;;;;;;AAUA,SAAgB,iBACd,MACA,SACA,OACA,EAAE,WAAW,WAA8B,CAAC,GACN;CAKtC,OAAO,mBAHL,cAAc,KAAA,IACV;EAAE,UAAU;EAAS;EAAM;EAAS;CAAM,IAC1C;EAAE,UAAU;EAAS;EAAM;EAAS;EAAW;CAAM,GACzB,MAAM;AAC1C;;;;;;;;AASA,SAAgB,uBACd,MACA,SACA,KACM;CACN,IAAI;EACF,IAAI;CACN,SAAS,OAAO;EACd,iBAAiB,MAAM,SAAS,KAAK;CACvC;AACF;;;;;;;;;AAUA,SAAgB,KACd,MACA,SACA,EAAE,WAAW,WAA8B,CAAC,GACN;CAKtC,OAAO,mBAHL,cAAc,KAAA,IACV;EAAE,UAAU;EAAW;EAAM;CAAQ,IACrC;EAAE,UAAU;EAAW;EAAM;EAAS;CAAU,GACpB,MAAM;AAC1C;;;;;;;AAQA,SAAgB,SACd,OACA,KACA,MACA,SACA,SACkD;CAClD,MAAM,SAAS,cAAc;CAC7B,IAAI,OAAO,OAAO,IAAI,KAAK;CAC3B,IAAI,CAAC,MAAM;EACT,uBAAO,IAAI,IAAI;EACf,OAAO,IAAI,OAAO,IAAI;CACxB;CACA,MAAM,aAAa,GAAG,KAAK,IAAI;CAC/B,IAAI,KAAK,IAAI,UAAU,GACrB;CAEF,KAAK,IAAI,UAAU;CACnB,OAAO,KAAK,MAAM,SAAS,OAAO;AACpC"}

package/dist/document-order.d.ts

@@ -0,0 +1,10 @@
+//#region src/document-order.d.ts
+/**
+ * Document order, the only order DOM-anchored peers can agree on without
+ * either the coordinator or the mount sequence arbitrating it.
+ *
+ * Imports nothing, so ordering costs a consumer no component graph.
+ */
+declare function compareDocumentOrder(a: Node, b: Node): number;
+//#endregion
+export { compareDocumentOrder };

package/dist/document-order.js

@@ -0,0 +1,17 @@
+//#region src/document-order.ts
+/**
+* Document order, the only order DOM-anchored peers can agree on without
+* either the coordinator or the mount sequence arbitrating it.
+*
+* Imports nothing, so ordering costs a consumer no component graph.
+*/
+function compareDocumentOrder(a, b) {
+	const position = a.compareDocumentPosition(b);
+	if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+	if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+	return 0;
+}
+//#endregion
+export { compareDocumentOrder };
+
+//# sourceMappingURL=document-order.js.map

package/dist/document-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-order.js","names":[],"sources":["../src/document-order.ts"],"sourcesContent":["/**\n * Document order, the only order DOM-anchored peers can agree on without\n * either the coordinator or the mount sequence arbitrating it.\n *\n * Imports nothing, so ordering costs a consumer no component graph.\n */\nexport function compareDocumentOrder(a: Node, b: Node): number {\n  const position = a.compareDocumentPosition(b);\n  if (position & Node.DOCUMENT_POSITION_FOLLOWING) {\n    return -1;\n  }\n  if (position & Node.DOCUMENT_POSITION_PRECEDING) {\n    return 1;\n  }\n  return 0;\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,qBAAqB,GAAS,GAAiB;CAC7D,MAAM,WAAW,EAAE,wBAAwB,CAAC;CAC5C,IAAI,WAAW,KAAK,6BAClB,OAAO;CAET,IAAI,WAAW,KAAK,6BAClB,OAAO;CAET,OAAO;AACT"}

package/dist/dom-mutations.d.ts

@@ -0,0 +1,77 @@
+//#region src/dom-mutations.d.ts
+interface DOMMutationRecord {
+  record: MutationRecord;
+  /** Removed subtree membership at observer delivery, before background work. */
+  removedSubtrees: ReadonlyMap<Node, readonly Element[]>;
+}
+type DOMMutationProcessor = (records: readonly DOMMutationRecord[]) => void;
+/**
+ * One attribute change on a watched element, as `watchAttributes()` reports
+ * it. Values are the raw attribute strings, `null` for an absent attribute —
+ * so a removal is `value: null` and an addition is `previousValue: null`.
+ */
+interface AttributeChange {
+  name: string;
+  value: string | null;
+  previousValue: string | null;
+}
+type AttributeWatcher = (change: AttributeChange) => void;
+/**
+ * Whether the engine has anything to do with an attribute.
+ *
+ * This is the **same set** `observeDocument()` hands the observer as its
+ * `attributeFilter`, and that is the point: any module may widen the filter
+ * through {@link registerDOMOptionAttributes}, and a relevance test written
+ * against the framework prefixes would silently drop the records a name
+ * matching neither prefix produces. Deriving both from one set makes the two
+ * impossible to separate.
+ *
+ * @internal Exported for the spec which asserts the filter and this test agree.
+ */
+declare function isObservedDOMAttribute(attribute: string | null): boolean;
+/**
+ * Add declared option attributes to the one observer's precise filter.
+ */
+declare function registerDOMOptionAttributes(attributes: Iterable<string>): void;
+/**
+ * Replace one derived slice of the exact attribute filter.
+ *
+ * Responsive attributes use this when `setBreakpoints()` replaces the named
+ * set. A name in both slices stays observed and is not disturbed.
+ */
+declare function replaceDOMOptionAttributes(previous: Iterable<string>, next: Iterable<string>): void;
+/**
+ * Observe all attributes of one element without observing its descendants.
+ * An element-scoped observer is required because `MutationObserver.attributeFilter` has no wildcard.
+ * Changes are coalesced and delivered after framework reconciliation through the shared queue.
+ *
+ * @param el The element to observe.
+ * @param callback Called once per coalesced attribute change.
+ * @returns An idempotent cleanup function.
+ * @link https://js-toolkit-v4.studiometa.dev/api/dom/watchAttributes.html
+ */
+declare function watchAttributes(el: Element, callback: AttributeWatcher): () => void;
+/**
+ * Install the one core processor which owns component lifecycle ordering.
+ */
+declare function setDOMMutationProcessor(next: DOMMutationProcessor): void;
+/**
+ * Return the component lookup version after retaining pending records for registry processing.
+ */
+declare function domVersion(): number;
+/**
+ * Track eager lifecycle work started while applying a mutation batch.
+ * Conditional mount strategies deliberately do not enter this set.
+ */
+declare function trackDOMLifecycleWork(work: Promise<unknown> | undefined): void;
+/**
+ * Resolve when every mutation currently observable by core has been
+ * processed and its eager lifecycle work has run.
+ *
+ * This does not wait for visibility, interaction, idle, or media
+ * conditions, and it does not await promises returned by `mounted()`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/dom/whenDOMSettled.html
+ */
+declare function whenDOMSettled(): Promise<void>;
+//#endregion
+export { AttributeChange, AttributeWatcher, DOMMutationProcessor, DOMMutationRecord, domVersion, isObservedDOMAttribute, registerDOMOptionAttributes, replaceDOMOptionAttributes, setDOMMutationProcessor, trackDOMLifecycleWork, watchAttributes, whenDOMSettled };

package/dist/dom-mutations.js

@@ -0,0 +1,238 @@
+import { FRAMEWORK_ATTRIBUTES, isComponentAttribute, isNetChange, rememberPreviousValue } from "./attributes.js";
+import { getSharedRuntimeSlot } from "./shared-runtime.js";
+import { reportDiagnostic } from "./diagnostics.js";
+import { defaultScheduler } from "./scheduler.js";
+//#region src/dom-mutations.ts
+const domMutationState = /* @__PURE__ */ getSharedRuntimeSlot("dom-mutations", 1, () => ({
+	observedAttributes: new Set(FRAMEWORK_ATTRIBUTES),
+	attributeWatchers: /* @__PURE__ */ new Set(),
+	observer: null,
+	processor: null,
+	processTask: null,
+	version: 0,
+	records: [],
+	lifecycleWork: /* @__PURE__ */ new Set()
+}));
+const { observedAttributes, attributeWatchers, lifecycleWork } = domMutationState;
+/**
+* Start the document's single mutation observer on demand.
+*
+* The attribute filter grows from fixed framework attributes and the option
+* names declared by registered components, so unrelated document writes do
+* not create mutation records.
+*/
+function observe() {
+	if (!domMutationState.observer) {
+		domMutationState.observer = new MutationObserver(ingest);
+		observeDocument();
+	}
+	return domMutationState.observer;
+}
+function observeDocument() {
+	domMutationState.observer?.observe(document.documentElement, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeOldValue: true,
+		attributeFilter: [...observedAttributes]
+	});
+}
+/**
+* Whether the engine has anything to do with an attribute.
+*
+* This is the **same set** `observeDocument()` hands the observer as its
+* `attributeFilter`, and that is the point: any module may widen the filter
+* through {@link registerDOMOptionAttributes}, and a relevance test written
+* against the framework prefixes would silently drop the records a name
+* matching neither prefix produces. Deriving both from one set makes the two
+* impossible to separate.
+*
+* @internal Exported for the spec which asserts the filter and this test agree.
+*/
+function isObservedDOMAttribute(attribute) {
+	return attribute !== null && observedAttributes.has(attribute);
+}
+/** Apply one change to the observed set, draining the records it already produced. */
+function updateObservedAttributes(removed, added) {
+	if (removed.length === 0 && added.length === 0) return;
+	ingest(domMutationState.observer?.takeRecords() ?? []);
+	for (const attribute of removed) observedAttributes.delete(attribute);
+	for (const attribute of added) observedAttributes.add(attribute);
+	if (domMutationState.observer) observeDocument();
+}
+/**
+* Add declared option attributes to the one observer's precise filter.
+*/
+function registerDOMOptionAttributes(attributes) {
+	updateObservedAttributes([], [...attributes].filter((attribute) => !observedAttributes.has(attribute)));
+}
+/**
+* Replace one derived slice of the exact attribute filter.
+*
+* Responsive attributes use this when `setBreakpoints()` replaces the named
+* set. A name in both slices stays observed and is not disturbed.
+*/
+function replaceDOMOptionAttributes(previous, next) {
+	const kept = new Set(next);
+	updateObservedAttributes([...previous].filter((attribute) => !kept.has(attribute) && observedAttributes.has(attribute)), [...kept].filter((attribute) => !observedAttributes.has(attribute)));
+}
+/**
+* Observe all attributes of one element without observing its descendants.
+* An element-scoped observer is required because `MutationObserver.attributeFilter` has no wildcard.
+* Changes are coalesced and delivered after framework reconciliation through the shared queue.
+*
+* @param el The element to observe.
+* @param callback Called once per coalesced attribute change.
+* @returns An idempotent cleanup function.
+* @link https://js-toolkit-v4.studiometa.dev/api/dom/watchAttributes.html
+*/
+function watchAttributes(el, callback) {
+	const entry = {
+		el,
+		callback,
+		pending: /* @__PURE__ */ new Map(),
+		observer: new MutationObserver((incoming) => ingestWatchedAttributes(entry, incoming))
+	};
+	entry.observer.observe(el, {
+		attributes: true,
+		attributeOldValue: true
+	});
+	attributeWatchers.add(entry);
+	return () => {
+		if (!attributeWatchers.delete(entry)) return;
+		entry.observer.disconnect();
+		entry.pending.clear();
+	};
+}
+function ingestWatchedAttributes(entry, incoming) {
+	for (const { attributeName, oldValue } of incoming) if (attributeName !== null) rememberPreviousValue(entry.pending, attributeName, oldValue);
+	scheduleProcessing();
+}
+function hasWatchedAttributes() {
+	for (const { pending } of attributeWatchers) if (pending.size > 0) return true;
+	return false;
+}
+/**
+* Move every element observer's pending records into the shared queue, so a
+* caller draining the document — `whenDOMSettled()` — cannot return while an
+* observer still holds an undelivered change.
+*/
+function takeWatchedAttributes() {
+	for (const entry of attributeWatchers) ingestWatchedAttributes(entry, entry.observer.takeRecords());
+}
+/**
+* Report coalesced changes using the final DOM value; omit net-zero changes.
+*/
+function deliverWatchedAttributes() {
+	for (const entry of attributeWatchers) {
+		if (entry.pending.size === 0) continue;
+		const changes = entry.pending;
+		entry.pending = /* @__PURE__ */ new Map();
+		for (const [name, previousValue] of changes) {
+			if (!attributeWatchers.has(entry)) break;
+			const value = entry.el.getAttribute(name);
+			if (!isNetChange(value, previousValue)) continue;
+			try {
+				entry.callback({
+					name,
+					value,
+					previousValue
+				});
+			} catch (error) {
+				reportDiagnostic("callback.attribute-watcher-failed", `The attribute watcher callback for "${name}" failed.`, error, { target: entry.el });
+			}
+		}
+	}
+}
+/**
+* Retain records before scheduling their processing. This is also used by
+* synchronous DOM reads after `takeRecords()`, so reading a ref can never
+* steal component-registry work from the observer callback.
+*/
+function ingest(incoming) {
+	const relevant = incoming.filter(({ type, attributeName }) => type === "childList" || isObservedDOMAttribute(attributeName));
+	if (relevant.length === 0) return;
+	if (relevant.some(({ type, attributeName }) => type === "childList" || isComponentAttribute(attributeName) || attributeName === "data-ref")) domMutationState.version += 1;
+	if (!domMutationState.processor) return;
+	domMutationState.records.push(...relevant.map((record) => {
+		const removedSubtrees = /* @__PURE__ */ new Map();
+		if (record.type === "childList") {
+			for (const node of record.removedNodes) if (node instanceof Element) removedSubtrees.set(node, [node, ...node.querySelectorAll("*")]);
+		}
+		return {
+			record,
+			removedSubtrees
+		};
+	}));
+	scheduleProcessing();
+}
+function scheduleProcessing() {
+	if (domMutationState.processTask) return;
+	if (!(Boolean(domMutationState.processor) && domMutationState.records.length > 0) && !hasWatchedAttributes()) return;
+	domMutationState.processTask = defaultScheduler.background(() => {
+		const batch = domMutationState.records;
+		domMutationState.records = [];
+		domMutationState.processor?.(batch);
+		deliverWatchedAttributes();
+	});
+	const finished = () => {
+		domMutationState.processTask = null;
+		scheduleProcessing();
+	};
+	domMutationState.processTask.promise.then(finished, finished);
+}
+/**
+* Install the one core processor which owns component lifecycle ordering.
+*/
+function setDOMMutationProcessor(next) {
+	domMutationState.processor ??= next;
+	ingest(observe().takeRecords());
+	scheduleProcessing();
+}
+/**
+* Return the component lookup version after retaining pending records for registry processing.
+*/
+function domVersion() {
+	ingest(observe().takeRecords());
+	return domMutationState.version;
+}
+/**
+* Track eager lifecycle work started while applying a mutation batch.
+* Conditional mount strategies deliberately do not enter this set.
+*/
+function trackDOMLifecycleWork(work) {
+	if (!work) return;
+	lifecycleWork.add(work);
+	const finished = () => lifecycleWork.delete(work);
+	work.then(finished, finished);
+}
+/**
+* Resolve when every mutation currently observable by core has been
+* processed and its eager lifecycle work has run.
+*
+* This does not wait for visibility, interaction, idle, or media
+* conditions, and it does not await promises returned by `mounted()`.
+* @link https://js-toolkit-v4.studiometa.dev/api/dom/whenDOMSettled.html
+*/
+async function whenDOMSettled() {
+	const currentObserver = observe();
+	while (true) {
+		ingest(currentObserver.takeRecords());
+		takeWatchedAttributes();
+		scheduleProcessing();
+		const pending = [...domMutationState.processTask ? [domMutationState.processTask.promise] : [], ...lifecycleWork];
+		if (pending.length > 0) {
+			await Promise.all(pending);
+			continue;
+		}
+		await Promise.resolve();
+		ingest(currentObserver.takeRecords());
+		takeWatchedAttributes();
+		scheduleProcessing();
+		if (!domMutationState.processTask && lifecycleWork.size === 0 && (!domMutationState.processor || domMutationState.records.length === 0) && !hasWatchedAttributes()) return;
+	}
+}
+//#endregion
+export { domVersion, isObservedDOMAttribute, registerDOMOptionAttributes, replaceDOMOptionAttributes, setDOMMutationProcessor, trackDOMLifecycleWork, watchAttributes, whenDOMSettled };
+
+//# sourceMappingURL=dom-mutations.js.map

package/dist/dom-mutations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-mutations.js","names":[],"sources":["../src/dom-mutations.ts"],"sourcesContent":["import {\n  FRAMEWORK_ATTRIBUTES,\n  isComponentAttribute,\n  isNetChange,\n  REF_ATTRIBUTE,\n  rememberPreviousValue,\n} from './attributes.js';\nimport { reportDiagnostic } from './diagnostics.js';\nimport { defaultScheduler, type ScheduledTask } from './scheduler.js';\nimport { getSharedRuntimeSlot } from './shared-runtime.js';\n\nexport interface DOMMutationRecord {\n  record: MutationRecord;\n  /** Removed subtree membership at observer delivery, before background work. */\n  removedSubtrees: ReadonlyMap<Node, readonly Element[]>;\n}\n\nexport type DOMMutationProcessor = (records: readonly DOMMutationRecord[]) => void;\n\n/**\n * One attribute change on a watched element, as `watchAttributes()` reports\n * it. Values are the raw attribute strings, `null` for an absent attribute —\n * so a removal is `value: null` and an addition is `previousValue: null`.\n */\nexport interface AttributeChange {\n  name: string;\n  value: string | null;\n  previousValue: string | null;\n}\n\nexport type AttributeWatcher = (change: AttributeChange) => void;\n\ninterface AttributeWatcherEntry {\n  el: Element;\n  observer: MutationObserver;\n  callback: AttributeWatcher;\n  /**\n   * The first old value seen per attribute in the current batch, kept under\n   * the one coalescing rule declared options answer to — see\n   * {@link rememberPreviousValue}.\n   */\n  pending: Map<string, string | null>;\n}\n\ninterface DOMMutationRuntimeState {\n  observedAttributes: Set<string>;\n  attributeWatchers: Set<AttributeWatcherEntry>;\n  observer: MutationObserver | null;\n  processor: DOMMutationProcessor | null;\n  processTask: ScheduledTask<void> | null;\n  version: number;\n  records: DOMMutationRecord[];\n  lifecycleWork: Set<Promise<unknown>>;\n}\n\nconst domMutationState = /* @__PURE__ */ getSharedRuntimeSlot<DOMMutationRuntimeState>(\n  'dom-mutations',\n  1,\n  () => ({\n    observedAttributes: new Set<string>(FRAMEWORK_ATTRIBUTES),\n    attributeWatchers: new Set(),\n    observer: null,\n    processor: null,\n    processTask: null,\n    version: 0,\n    records: [],\n    lifecycleWork: new Set(),\n  }),\n);\nconst { observedAttributes, attributeWatchers, lifecycleWork } = domMutationState;\n\n/**\n * Start the document's single mutation observer on demand.\n *\n * The attribute filter grows from fixed framework attributes and the option\n * names declared by registered components, so unrelated document writes do\n * not create mutation records.\n */\nfunction observe(): MutationObserver {\n  if (!domMutationState.observer) {\n    domMutationState.observer = new MutationObserver(ingest);\n    observeDocument();\n  }\n  return domMutationState.observer;\n}\n\nfunction observeDocument(): void {\n  domMutationState.observer?.observe(document.documentElement, {\n    childList: true,\n    subtree: true,\n    attributes: true,\n    attributeOldValue: true,\n    attributeFilter: [...observedAttributes],\n  });\n}\n\n/**\n * Whether the engine has anything to do with an attribute.\n *\n * This is the **same set** `observeDocument()` hands the observer as its\n * `attributeFilter`, and that is the point: any module may widen the filter\n * through {@link registerDOMOptionAttributes}, and a relevance test written\n * against the framework prefixes would silently drop the records a name\n * matching neither prefix produces. Deriving both from one set makes the two\n * impossible to separate.\n *\n * @internal Exported for the spec which asserts the filter and this test agree.\n */\nexport function isObservedDOMAttribute(attribute: string | null): boolean {\n  return attribute !== null && observedAttributes.has(attribute);\n}\n\n/** Apply one change to the observed set, draining the records it already produced. */\nfunction updateObservedAttributes(removed: readonly string[], added: readonly string[]): void {\n  if (removed.length === 0 && added.length === 0) {\n    return;\n  }\n  // Records are classified by the vocabulary which delivered them, so what the\n  // current filter produced enters the queue before the set moves under it.\n  ingest(domMutationState.observer?.takeRecords() ?? []);\n  for (const attribute of removed) {\n    observedAttributes.delete(attribute);\n  }\n  for (const attribute of added) {\n    observedAttributes.add(attribute);\n  }\n  if (domMutationState.observer) {\n    observeDocument();\n  }\n}\n\n/**\n * Add declared option attributes to the one observer's precise filter.\n */\nexport function registerDOMOptionAttributes(attributes: Iterable<string>): void {\n  const added = [...attributes].filter((attribute) => !observedAttributes.has(attribute));\n  updateObservedAttributes([], added);\n}\n\n/**\n * Replace one derived slice of the exact attribute filter.\n *\n * Responsive attributes use this when `setBreakpoints()` replaces the named\n * set. A name in both slices stays observed and is not disturbed.\n */\nexport function replaceDOMOptionAttributes(\n  previous: Iterable<string>,\n  next: Iterable<string>,\n): void {\n  const kept = new Set(next);\n  const removed = [...previous].filter(\n    (attribute) => !kept.has(attribute) && observedAttributes.has(attribute),\n  );\n  const added = [...kept].filter((attribute) => !observedAttributes.has(attribute));\n  updateObservedAttributes(removed, added);\n}\n\n/**\n * Observe all attributes of one element without observing its descendants.\n * An element-scoped observer is required because `MutationObserver.attributeFilter` has no wildcard.\n * Changes are coalesced and delivered after framework reconciliation through the shared queue.\n *\n * @param el The element to observe.\n * @param callback Called once per coalesced attribute change.\n * @returns An idempotent cleanup function.\n * @link https://js-toolkit-v4.studiometa.dev/api/dom/watchAttributes.html\n */\nexport function watchAttributes(el: Element, callback: AttributeWatcher): () => void {\n  const entry: AttributeWatcherEntry = {\n    el,\n    callback,\n    pending: new Map(),\n    observer: new MutationObserver((incoming) => ingestWatchedAttributes(entry, incoming)),\n  };\n  entry.observer.observe(el, { attributes: true, attributeOldValue: true });\n  attributeWatchers.add(entry);\n\n  return () => {\n    if (!attributeWatchers.delete(entry)) {\n      return;\n    }\n    entry.observer.disconnect();\n    entry.pending.clear();\n  };\n}\n\nfunction ingestWatchedAttributes(\n  entry: AttributeWatcherEntry,\n  incoming: readonly MutationRecord[],\n): void {\n  for (const { attributeName, oldValue } of incoming) {\n    if (attributeName !== null) {\n      rememberPreviousValue(entry.pending, attributeName, oldValue);\n    }\n  }\n  scheduleProcessing();\n}\n\nfunction hasWatchedAttributes(): boolean {\n  for (const { pending } of attributeWatchers) {\n    if (pending.size > 0) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * Move every element observer's pending records into the shared queue, so a\n * caller draining the document — `whenDOMSettled()` — cannot return while an\n * observer still holds an undelivered change.\n */\nfunction takeWatchedAttributes(): void {\n  for (const entry of attributeWatchers) {\n    ingestWatchedAttributes(entry, entry.observer.takeRecords());\n  }\n}\n\n/**\n * Report coalesced changes using the final DOM value; omit net-zero changes.\n */\nfunction deliverWatchedAttributes(): void {\n  // A callback may end a subscription mid-flush: `Set` iteration skips an\n  // entry deleted before it is reached, which is the wanted behaviour, and a\n  // watcher subscribed from a callback has nothing pending to report yet.\n  for (const entry of attributeWatchers) {\n    if (entry.pending.size === 0) {\n      continue;\n    }\n    const changes = entry.pending;\n    entry.pending = new Map();\n    for (const [name, previousValue] of changes) {\n      // The callback just run may have ended this very subscription.\n      if (!attributeWatchers.has(entry)) {\n        break;\n      }\n      const value = entry.el.getAttribute(name);\n      if (!isNetChange(value, previousValue)) {\n        continue;\n      }\n      try {\n        entry.callback({ name, value, previousValue });\n      } catch (error) {\n        reportDiagnostic(\n          'callback.attribute-watcher-failed',\n          `The attribute watcher callback for \"${name}\" failed.`,\n          error,\n          { target: entry.el },\n        );\n      }\n    }\n  }\n}\n\n/**\n * Retain records before scheduling their processing. This is also used by\n * synchronous DOM reads after `takeRecords()`, so reading a ref can never\n * steal component-registry work from the observer callback.\n */\nfunction ingest(incoming: MutationRecord[]): void {\n  const relevant = incoming.filter(\n    ({ type, attributeName }) => type === 'childList' || isObservedDOMAttribute(attributeName),\n  );\n  if (relevant.length === 0) {\n    return;\n  }\n\n  if (\n    relevant.some(\n      ({ type, attributeName }) =>\n        type === 'childList' ||\n        isComponentAttribute(attributeName) ||\n        attributeName === REF_ATTRIBUTE,\n    )\n  ) {\n    domMutationState.version += 1;\n  }\n\n  // Before the first component is registered, the current document scan is\n  // sufficient. Keeping historical records here would retain detached\n  // subtrees with nobody able to process them.\n  if (!domMutationState.processor) {\n    return;\n  }\n  domMutationState.records.push(\n    ...relevant.map((record): DOMMutationRecord => {\n      const removedSubtrees = new Map<Node, readonly Element[]>();\n      if (record.type === 'childList') {\n        for (const node of record.removedNodes) {\n          if (node instanceof Element) {\n            removedSubtrees.set(node, [node, ...node.querySelectorAll('*')]);\n          }\n        }\n      }\n      return { record, removedSubtrees };\n    }),\n  );\n  scheduleProcessing();\n}\n\nfunction scheduleProcessing(): void {\n  if (domMutationState.processTask) {\n    return;\n  }\n  const hasFrameworkWork =\n    Boolean(domMutationState.processor) && domMutationState.records.length > 0;\n  if (!hasFrameworkWork && !hasWatchedAttributes()) {\n    return;\n  }\n\n  domMutationState.processTask = defaultScheduler.background(() => {\n    const batch = domMutationState.records;\n    domMutationState.records = [];\n    domMutationState.processor?.(batch);\n    // Lifecycle and declared options must run before attribute watchers.\n    deliverWatchedAttributes();\n  });\n  const finished = () => {\n    domMutationState.processTask = null;\n    scheduleProcessing();\n  };\n  void domMutationState.processTask.promise.then(finished, finished);\n}\n\n/**\n * Install the one core processor which owns component lifecycle ordering.\n */\nexport function setDOMMutationProcessor(next: DOMMutationProcessor): void {\n  domMutationState.processor ??= next;\n  const currentObserver = observe();\n  // Reconcile pending declarations before the registration scan can enqueue\n  // mounts for their final token set.\n  ingest(currentObserver.takeRecords());\n  scheduleProcessing();\n}\n\n/**\n * Return the component lookup version after retaining pending records for registry processing.\n */\nexport function domVersion(): number {\n  ingest(observe().takeRecords());\n  return domMutationState.version;\n}\n\n/**\n * Track eager lifecycle work started while applying a mutation batch.\n * Conditional mount strategies deliberately do not enter this set.\n */\nexport function trackDOMLifecycleWork(work: Promise<unknown> | undefined): void {\n  if (!work) {\n    return;\n  }\n  lifecycleWork.add(work);\n  const finished = () => lifecycleWork.delete(work);\n  void work.then(finished, finished);\n}\n\n/**\n * Resolve when every mutation currently observable by core has been\n * processed and its eager lifecycle work has run.\n *\n * This does not wait for visibility, interaction, idle, or media\n * conditions, and it does not await promises returned by `mounted()`.\n * @link https://js-toolkit-v4.studiometa.dev/api/dom/whenDOMSettled.html\n */\nexport async function whenDOMSettled(): Promise<void> {\n  const currentObserver = observe();\n\n  while (true) {\n    ingest(currentObserver.takeRecords());\n    takeWatchedAttributes();\n    scheduleProcessing();\n\n    const pending = [\n      ...(domMutationState.processTask ? [domMutationState.processTask.promise] : []),\n      ...lifecycleWork,\n    ];\n    if (pending.length > 0) {\n      await Promise.all(pending);\n      continue;\n    }\n\n    // MutationObserver delivery and lifecycle-triggered microtasks can add\n    // records after the last tracked task resolves. Cross one microtask and\n    // take records once more before declaring the document stable.\n    await Promise.resolve();\n    ingest(currentObserver.takeRecords());\n    takeWatchedAttributes();\n    scheduleProcessing();\n\n    if (\n      !domMutationState.processTask &&\n      lifecycleWork.size === 0 &&\n      (!domMutationState.processor || domMutationState.records.length === 0) &&\n      !hasWatchedAttributes()\n    ) {\n      return;\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,17 @@
+//#region src/events.d.ts
+/**
+ * Public framework event names.
+ * @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/EVENTS.html
+ */
+declare const EVENTS: Readonly<{
+  readonly component: Readonly<{
+    readonly mounted: 'js-toolkit:component:mounted';
+    readonly unmounted: 'js-toolkit:component:unmounted';
+  }>;
+  readonly dom: Readonly<{
+    readonly update: 'js-toolkit:dom:update';
+  }>;
+  readonly diagnostic: 'js-toolkit:diagnostic';
+}>;
+//#endregion
+export { EVENTS };