@twobirds/microcomponents 0.11.0 → 0.12.1

package/dist/utils/autoload.js

@@ -0,0 +1,1451 @@
+//#region src/utils/events.ts
+/**
+@module Events
+
+This module provides event utilities for interfacing **between microcomponents and external
+frameworks or native DOM/JS environments**. It is not intended for communication between
+frontend microcomponents themselves — for that purpose, use the inherited methods
+( `.on()`, `.one()`, `.off()`, `.trigger()`) that exist when you extend `DC`.
+
+Import this module when you need to exchange information with microcomponents from outside
+the microcomponent system (e.g., vanilla JS, React via `useRef()`, or other frameworks).
+
+The core feature is the ability to explicitly control event flow direction when using {@link trigger}:
+- upward propagation to ancestor components ('u')
+- local dispatch only ('l') [default]
+- downward propagation to descendant components ('d').
+
+@example
+html:
+```html
+<div class="grandparent">
+<div class="parent">
+<div class="child">
+</div>
+</div>
+</div>
+```
+
+javascript:
+```javascript
+import { on, one, trigger, off } from '@twobirds/microcomponents/events';
+
+const grandParent = document.querySelector('.grandparent');
+const parent = document.querySelector('.parent');
+const child = document.querySelector('.child');
+if (!grandParent || !parent || !child) throw new Error('example markup missing');
+
+const grandParentHandler = on(grandParent, 'dataReady', (ev) => console.log(ev.detail.data));
+
+const parentHandler = on(parent, 'dataReady', (ev) => ev.detail.control.stop());
+
+trigger(child, 'dataReady', { value: 42 }, 'u');
+
+off(parent, 'dataReady', parentHandler);
+off(grandParent, 'dataReady', grandParentHandler);
+```
+
+The `dataReady` event bubbles upward from the innermost `div`, but `parentHandler`
+calls `ev.detail.control.stop()`, so the `grandParent` handler is never reached.
+Handlers are detached with `off()` once they are no longer needed.
+*/
+/**
+* Returns the correct event name to listen for on a DOM element.
+*
+* If `eventName` (case-insensitive) matches a native HTML event handler property
+* (`'on' + eventName.toLowerCase()`) on the target, returns the lowercase native
+* name so that standard DOM events like `'click'` are listened to correctly.
+* Otherwise, prefixes with `_mc` for microcomponent custom events.
+*
+* @hidden
+* @param target - The DOM element whose native event support is checked.
+* @param eventName - The event name as provided by the caller (e.g., `'click'`, `'Update'`).
+* @returns The resolved event name: lowercase native or `_mc`-prefixed custom.
+*
+* @example
+* ```ts
+* const btn = document.createElement('button');
+* console.log(trueEventName(btn, 'Click'));
+* console.log(trueEventName(btn, 'Update'));
+* ```
+*
+* `'Click'` resolves to the native `'click'` because the button has an `onclick` handler
+* property; `'Update'` has no native counterpart, so it becomes the `_mc`-prefixed custom
+* event name.
+*/
+function trueEventName(target, eventName) {
+	const lower = eventName.toLowerCase();
+	if ("on" + lower in target) return lower;
+	return "_mc" + eventName[0].toUpperCase() + eventName.substring(1);
+}
+/**
+Removes a previously attached event handler from the DOM node. See {@link on} and {@link one}.
+
+Uses internal microcomponent-prefixed naming for event handlers.
+This is primarily used to interface with external frameworks or vanilla JS environments.
+For communication between frontend microcomponents, use the `DC.off()` method instead.
+
+@param target - The DOM element from which to remove the listener.
+@param eventName - The name of the event (e.g., 'click', 'update').
+@param handler - The listener function or object to detach.
+
+@example
+```ts
+const handler = on(myElement, 'click', () => console.log('clicked'));
+off(myElement, 'click', handler);
+```
+@group Events
+*/
+function off(target, eventName, handler) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => off(el, eventName, handler));
+		return;
+	}
+	target.removeEventListener(trueEventName(target, eventName), handler);
+}
+/**
+Attaches a persistent event listener that will fire every time the specified event occurs.
+
+This is primarily used to interface with external frameworks or vanilla JS environments.
+For communication between frontend microcomponents, use the `DC.on()` method instead.
+
+The handler receives a `CustomEvent<McDetail<D>>`: the payload sits under
+`ev.detail.data`, the bubble-control handle under `ev.detail.control`.
+
+@param target - The DOM element to attach the listener to.
+@param eventName - The name of the event (e.g., 'click', 'update').
+@param handler - The callback function or object to invoke on each event.
+@param once - If true, remove the listener after first invocation.
+@returns The attached handler reference. Useful for later deletion with {@link off}.
+
+@example
+```ts
+const handler = on<{ value: number }>(myElement, 'update', (ev) => {
+console.log(ev.detail.data.value);
+});
+off(myElement, 'update', handler);
+```
+@group Events
+*/
+function on(target, eventName, handler, once = false) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => on(el, eventName, handler));
+		return;
+	}
+	target.addEventListener(trueEventName(target, eventName), handler, {
+		capture: false,
+		once
+	});
+	return handler;
+}
+/**
+Attaches an event listener that will fire only once.
+
+Internally calls {@link on} with the `once` flag set to true. The handler
+is automatically removed after its first invocation.
+This is primarily used to interface with external frameworks or vanilla JS environments.
+For communication between frontend microcomponents, use the `DC.one()` method instead.
+
+@param target - The DOM element to attach the listener to.
+@param eventName - The name of the event (e.g., 'click', 'update').
+@param handler - The callback function or object to invoke once.
+@returns The attached one-time handler reference. Useful for later deletion with {@link off}.
+
+@example
+```ts
+one<{ ready: boolean }>(myElement, 'dataReady', (ev) => console.log('received:', ev.detail.data));
+```
+
+The listener fires only once and detaches automatically.
+@group Events
+*/
+function one(target, eventName, handler) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => one(el, eventName, handler));
+		return;
+	}
+	on(target, eventName, handler, true);
+	return handler;
+}
+/**
+* @hidden
+* A controller object used to manage and potentially abort event bubbling.
+*
+* The `trigger()` function internally creates instance of this class,
+* allowing the an eventual handler to call `ev.detail.control.stop()` to
+* prevent further propagation in either direction (up/down).
+*
+* This is only used internally.
+* @example
+* ```ts
+* trigger(myElement, 'update', { value: 42 }, 'u');
+*
+* onUpdate(ev) {
+*     ev.detail.control.stop();
+* }
+* ```
+*/
+var BubbleController = class {
+	stopped = false;
+	constructor() {}
+	/**
+	* Signals that event bubbling should be halted.
+	*
+	* After calling this method, subsequent `trigger()` calls will abort
+	* before dispatching the event to any targets.
+	*
+	* @example
+	* ```ts
+	* trigger(myElement, 'update', { value: 42 }, 'u');
+	*
+	* onUpdate(ev) {
+	*     ev.detail.control.stop();
+	* }
+	* ```
+	*/
+	stop() {
+		this.stopped = true;
+	}
+};
+/**
+* Creates and dispatches a custom event on the specified DOM node.
+*
+* The event is namespaced with an `_mc` prefix by default, unless already prefixed.
+* Supports bidirectional bubbling (up/down the DOM tree) based on the `bubble` parameter:
+* - 'l': local dispatch only
+* - 'u': bubble up towards ancestors
+* - 'd': bubble down to descendants
+*
+* The dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload
+* under `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.
+*
+* Prefer a direct target over bubbling: name the receiving element in `target` and keep the
+* default `'l'`, so one `querySelectorAll` reaches it in a single step. Reserve `'u'`/`'d'`
+* for receivers that cannot be named in advance, since they walk the tree and re-dispatch the
+* event at every level. Pass a typed object as `data` rather than a bare string, so the
+* handler reads named fields from `ev.detail.data` and the flow stays readable as it grows.
+*
+* @param target - The DOM element on which to trigger the event, or a querySelectorAll(selector) selector string.
+* @param event - The name of the event (will be prefixed if needed).
+* @param data - Additional data payload attached to `event.detail.data`.
+* @param bubble - Bubbling direction ('l', 'u', 'd' or combinations).
+* @param controller - Optional controller for managing bubbling behavior.
+*
+* @example
+* ```ts
+* trigger(myElement, 'update', { value: 42 }, 'l');
+* trigger(myElement, 'dataReady', { ready: true }, 'u');
+* ```
+*
+* The first dispatch fires locally only; the second bubbles upward to ancestor components.
+*/
+function trigger(target, event, data = {}, bubble = "l", controller) {
+	/* v8 ignore next */
+	if (!target) return;
+	if (typeof target === "string") {
+		document.querySelectorAll(target).forEach((el) => trigger(el, event, data, bubble));
+		return;
+	}
+	const eventName = /^_mc/.test(event) ? event : trueEventName(target, event), bubbleController = controller ? controller : new BubbleController(), ev = new CustomEvent(eventName, {
+		detail: {
+			data,
+			control: bubbleController
+		},
+		bubbles: false
+	});
+	if (bubbleController.stopped) return;
+	if (/l/.test(bubble)) {
+		target.dispatchEvent(ev);
+		if (bubbleController.stopped) return;
+	}
+	if (/[ud]/.test(bubble)) queueMicrotask(() => {
+		if (bubble.indexOf("u") > -1) trigger(target.parentElement, eventName, data, "lu", bubbleController);
+		if (bubble.indexOf("d") > -1) for (const child of target.children) trigger(child, eventName, data, "ld");
+	});
+}
+//#endregion
+//#region src/utils/helpers.ts
+/**
+* Converts a PascalCase string to kebab-case.
+* Example: 'MyComponentName' -> 'my-component-name'
+* @param str - The PascalCase string to convert.
+* @returns The converted kebab-case string.
+*
+* @example
+* ```ts
+* console.log(pascalToKebab('MyElement'));
+* ```
+*/
+function pascalToKebab(str) {
+	return str.replace(/[A-Z]/g, (m, i) => (i ? "-" : "") + m.toLowerCase());
+}
+/**
+* Injects a CSS string into the given scope (document or shadow root) as an adopted stylesheet.
+* Enables css-in-js so that every custom element is self-contained and importable.
+*
+* @hidden
+* @param target - The scope to inject styles into: `document` for global styles, or a `ShadowRoot` for encapsulated component internals.
+* @param css - The CSS string to inject.
+* @returns The created `CSSStyleSheet` instance that was adopted into the target scope.
+*
+* When targeting **document**: selectors like `:host`, `::slotted()`, and shadow-internal classes are **not allowed** — they have no effect outside a shadow root. Use only global selectors, element tags, or layout presets.
+* When targeting **shadowRoot**: use `:host` for the custom element itself, standard selectors (`.inner`, `#id`) for internal structure, and `::slotted()` for projected light-DOM content.
+*
+* @example Inject global styles into the document:
+* ```ts
+* import { injectCSS } from '@twobirds/mc/utils/helpers';
+* injectCSS(document, 'body { display: block; }');
+* ```
+*
+* @example Inject global styles for a micro component into the document:
+* ```ts
+* import { injectCSS } from '@twobirds/mc/utils/helpers';
+* injectCSS(document, 'my-microcomponent { display: block; }');
+* ```
+*
+* @example Inject scoped styles into a shadow root:
+* ```ts
+* const shadow = element.attachShadow({ mode: 'open' });
+* injectCSS(shadow, ':host { color: var(--text); } .inner { padding: 8px; }');
+* ```
+* Styles can also be added using a compound innerHTML statement: `shadow.innerHTML = \`<style>${style}</style>${template}\``
+*/
+var _injectedCSS = /* @__PURE__ */ new WeakMap();
+function injectCSS(target, css) {
+	const injected = _injectedCSS.get(target) ?? /* @__PURE__ */ new Set();
+	if (injected.has(css)) return target.adoptedStyleSheets[0];
+	injected.add(css);
+	_injectedCSS.set(target, injected);
+	const sheet = new CSSStyleSheet();
+	sheet.replaceSync(css);
+	target.adoptedStyleSheets.push(sheet);
+	return sheet;
+}
+/**
+* Processes a record of asset strings and applies them to the given target element.
+* Supports injecting CSS into document or shadow root, and setting innerHTML for
+* both target and shadow DOM. Automatically attaches a shadow root if any key starts
+* with `'shadow'`.
+*
+* Recognized keys: `'css'`, `'targetCss'` (document-level styles), `'shadowCss'`
+* (shadow-root styles), `'shadowHtml'` (shadow innerHTML), `'targetHtml'` (target innerHTML).
+*
+* @param instance - The micro component to apply assets onto.
+* @param assets - A record mapping asset type keys to their string content.
+*
+* @example
+* ```ts
+* processAssets(this, {
+*   css: 'body { margin: 0; }',
+*   shadowCss: ':host { display: block; }',
+*   shadowHtml: '<slot></slot>'
+* });
+* ```
+*/
+function processAssets(instance, assets) {
+	const target = instance.target;
+	let shadow = target.shadowRoot;
+	if (!shadow && Object.keys(assets).some((key) => key.indexOf("shadow") === 0)) shadow = target.attachShadow({ mode: "open" });
+	Object.keys(assets).forEach((key) => {
+		switch (key) {
+			case "css":
+				injectCSS(document, assets[key]);
+				break;
+			case "targetCss":
+				injectCSS(document, assets[key]);
+				break;
+			case "shadowCss":
+				injectCSS(shadow, assets[key]);
+				break;
+			case "shadowHtml":
+				shadow.innerHTML = assets[key];
+				bindTemplateEvents(shadow, instance);
+				break;
+			case "targetHtml":
+				target.innerHTML = assets[key];
+				bindTemplateEvents(target, instance);
+				break;
+		}
+	});
+}
+/**
+* Loads companion asset files (CSS, HTML) for a given component basename from the server.
+*
+* Each entry in `assets` encodes an optional variant and extension in camelCase, e.g. `'shadowCss'` → `{name}.shadow.css`,
+* `'targetHtml'` → `{name}.target.html`. Plain entries like `'css'` or `'html'` resolve to
+* `{name}.css` / `{name}.html`.
+*
+* In bundled mode the Vite plugin replaces this call with an inline array literal, so `.then()`
+* fires synchronously — no async overhead.
+*
+* @hidden
+* @param name - The component basename (e.g. `'shop-catalog'`).
+* @param assets - Array of asset descriptors such as `'shadowCss'`, `'targetHtml'`, `'shadowHtml'`, `'css'`, `'html'`.
+* @returns A promise resolving to an array of file contents in the same order as `assets`. If a file is not found, the corresponding entry is `'file not found: ' + filename`.
+*
+* @example
+* ```ts
+* export const MyComponent = loadAssets('my-component', ['shadowCss', 'shadowHtml']).then(([shadowCss, shadowHtml]) => {
+*   class _MyComponent extends DC { ... }
+*   defineCE('my-component', _MyComponent);
+*   return _MyComponent;
+* });
+* ```
+*/
+function loadAssets(name, assets) {
+	const parseAsset = (asset) => {
+		const m = asset.match(/^([a-z]+)([A-Z][a-z]*)$/);
+		if (m) return `./${name.replace(/-/g, "/")}.${m[1]}.${m[2].toLowerCase()}`;
+		return `./${name.replace(/-/g, "/")}.${asset.toLowerCase()}`;
+	};
+	return Promise.all(assets.map(async (asset) => {
+		const filename = parseAsset(asset);
+		try {
+			const resp = await fetch(filename);
+			if (!resp.ok) return `file not found: ${filename}`;
+			if (filename.endsWith("json")) {
+				const text = await resp.text();
+				try {
+					return JSON.parse(text);
+				} catch {
+					console.error(`could not JSON.parse() asset '${asset}' from ${filename}:\n`, text);
+					return null;
+				}
+			}
+			return resp.text();
+		} catch {
+			return `file not found: ${filename}`;
+		}
+	}));
+}
+/**
+* Binds declarative event attributes in a template fragment to microcomponent triggers.
+*
+* Scans all elements under `root` for attributes whose names correspond to native DOM
+* events (e.g. `click`, `submit`, `change`). The attribute value encodes the target and
+* handler method in the form `target|methodName`:
+*
+* - `this|myHandler` — triggers locally on the component attached to this element.
+* - `other-comp|submit` — resolves elements via `querySelectorAll('other-comp')` and
+*   triggers the event on each matched host's `_mc`.
+*
+* An optional sibling `payload` attribute supplies the data argument for `trigger()`.
+* After binding, both the event attribute and the payload attribute are removed from the DOM.
+*
+* @param rootElement - The container element whose descendants should be scanned for bindings.
+* @param instance - The instance to trigger events on.
+*
+* @example
+* ```html
+* <button click='this|onSubmit|{"action":"go"}'>Submit</button>
+* <input change="|cart-form|refresh">
+* ```
+*/
+function bindTemplateEvents(rootElement, instance) {
+	const allElements = [...rootElement.querySelectorAll("*")];
+	for (const el of allElements) {
+		if (!(el instanceof HTMLElement)) continue;
+		const attrs = [...el.attributes];
+		for (const attr of attrs) {
+			const lowerName = attr.name.toLowerCase();
+			if (!("on" + lowerName in el)) continue;
+			const parts = attr.value.trim().split("|");
+			if (parts.length < 2) continue;
+			const [selector, event, payload] = parts;
+			el.removeAttribute(attr.name);
+			let payloadData;
+			if (payload) try {
+				payloadData = JSON.parse(payload);
+			} catch {
+				payloadData = payload;
+			}
+			if (selector === "this" || selector === "") on(el, lowerName, () => instance.trigger(event, payloadData));
+			else on(el, lowerName, () => trigger(selector, event, payloadData));
+		}
+	}
+}
+//#endregion
+//#region src/core/mcGuards.ts
+function isMcHost(element, key) {
+	if (typeof HTMLElement === "undefined" || !(element instanceof HTMLElement)) return false;
+	if (!("_mc" in element)) return false;
+	if (key === void 0) return true;
+	const mc = element._mc;
+	if (typeof mc !== "object" || mc === null) return false;
+	return key in mc;
+}
+//#endregion
+//#region src/core/MC.ts
+function add(targetHTMLElement, key, element = {}) {
+	const node = targetHTMLElement;
+	if (!("_mc" in targetHTMLElement)) node._mc = new DC(targetHTMLElement);
+	const _mc = node._mc;
+	if (key.length) {
+		_mc[key] = element;
+		if (targetHTMLElement instanceof HTMLElement && !targetHTMLElement.getAttribute("data-mc")) targetHTMLElement.setAttribute("data-mc", "");
+	}
+	return node;
+}
+/**
+Removes a named microcomponent from the internal `_mc` collection of a target DOM node.
+
+This function deletes the specified key from the element's `_mc` hash object and, if the
+collection becomes empty, removes the `data-mc` attribute from the DOM node.
+
+The bare poisoned value (`el._mc.gone` without member access) is `never`,
+which is assignable to anything — only member/method use of a removed entry is caught.
+
+@template T - A plain or already-enhanced element type.
+@template K - The literal registration key; its entry is poisoned in the registry type.
+@param target - The DOM element whose microcomponent should be removed.
+@param key - The property name/key corresponding to the microcomponent to remove.
+*/
+function remove(target, key) {
+	if (!key) return;
+	const _mc = target._mc;
+	if (!_mc) return;
+	if (_mc[key]) delete _mc[key];
+	if (!Object.keys(_mc).length && target instanceof HTMLElement && target.hasAttribute("data-mc")) target.removeAttribute("data-mc");
+}
+/**
+Runs the "Init" lifecycle event on a DOM microcomponent instance.
+
+This function schedules the `trigger('Init')` call in a microtask, ensuring
+that all synchronous initialization is complete before the lifecycle hook
+executes. The {@link DC} constructor calls it once the declared assets are in
+place — synchronously in a bundled build, after the fetch resolves in a
+dev/autoload build — so `oneInit()` always sees the loaded assets. Only `DC`
+instances have an Init lifecycle — the `DC` constructor calls this exclusively,
+so the signature encodes that invariant instead of re-checking it at runtime.
+
+@param element - The DOM microcomponent instance on which to trigger the Init event.
+*/
+function init(element) {
+	queueMicrotask(() => {
+		element.trigger("Init", null);
+	});
+}
+/**
+Attaches event listeners to DOM elements based on method naming conventions.
+
+Scans the prototype of the provided element and attaches listeners for methods
+prefixed with `on` or `one`, corresponding to either native HTML events (e.g.,
+'onclick') or microcomponent-prefixed custom events (e.g., '_mcUpdate').
+
+@param element - The instance whose prototype should be scanned for event handlers.
+*/
+function autoAttachListeners(element) {
+	const sourceTarget = element.target;
+	const prototype = Object.getPrototypeOf(element);
+	const sourceElement = element;
+	const definedEventHandlerNames = Object.getOwnPropertyNames(prototype).filter((key) => /^(on[A-Z]|one[A-Z])/.test(key) && typeof prototype[key] === "function");
+	for (const eventHandlerName of definedEventHandlerNames) {
+		const once = /^one/.test(eventHandlerName);
+		const eventName = eventHandlerName.replace(/^one?/, "");
+		const listener = (ev) => sourceElement[eventHandlerName](ev);
+		on(sourceTarget, eventName, listener, once);
+	}
+}
+/**
+Retrieves immediate child microcomponents of a DOM node.
+
+Queries the DOM for descendant elements marked with `data-mc` that are direct
+children of the provided element and returns their associated `_mc` instances.
+
+@param domNode - The DOM element whose child microcomponents to find.
+@returns An array of child microcomponent instances.
+*/
+function getMcChildNodes(domNode) {
+	return Array.from(domNode.querySelectorAll("[data-mc]:not(:scope [data-mc] [data-mc])")).filter((e) => e instanceof HTMLElement && "_mc" in e).map((e) => e._mc);
+}
+/**
+Walks up the DOM from `from`, returning the `_mc` controller of the nearest
+`data-mc` ancestor — restricted, when `key` is given, to hosts whose registry
+actually carries that key. Hosts marked `data-mc` but not (yet) carrying an
+`_mc` record (e.g. autoload pending) are skipped rather than returned.
+
+@param from - The element whose ancestors to search (exclusive).
+@param key - Optional registry key the ancestor's `_mc` must contain.
+@returns The nearest matching controller, or null.
+*/
+function findMcAncestor(from, key) {
+	let el = from.parentElement?.closest("[data-mc]");
+	while (el instanceof HTMLElement) {
+		/* v8 ignore next */
+		if ("_mc" in el) {
+			const mc = el._mc;
+			if (key === void 0 || key in mc) return mc;
+		}
+		el = el.parentElement?.closest("[data-mc]");
+	}
+	return null;
+}
+/**
+The base class for all microcomponents — shared root of both {@link MC} and {@link DC}.
+
+Holds a `WeakRef` to the target (a DOM element for `DC`, or any plain object for `MC`)
+to avoid circular references. It starts loading any `static assets` for `MC` and `DC`
+alike (shared per class through `_assetsPromise`), read through the {@link McBase.assets}
+getter. For `DC` subclasses it bootstraps one automatic behaviour:
+
+1. **Event listener auto-attachment** — methods whose names start with `on` or `one`
+(e.g. `onClick`, `oneInit`) are wired to the target element via {@link on} / {@link one}.
+
+The **"Init" lifecycle event** and the DOM attach of auto-attached assets are dispatched
+by the {@link DC} constructor — after the declared assets are in place — so that
+`oneInit()` runs once the instance is fully constructed and its assets are loaded. Plain
+`MC` instances fetch their assets server-side with no DOM attach and no `Init` lifecycle,
+keeping server-side usage lightweight.
+
+### Plugin extension points
+
+The prototype of `McBase` is the attachment point for optional plugins that curry
+additional instance methods onto every microcomponent. Two built-in plugins modify
+this class at runtime:
+
+- **{@link State.observePlugin}** — adds `notify()`, `subscribe()`, and `bind()` so that
+observable properties can be controlled directly on the component instance with
+fluent chaining. Call `observePlugin(DC)` once at module level to activate.
+
+- **{@link State.formValuePlugin}** — adds `formValues()` for two-way binding between DOM
+form controls and an observable property. Also pulls in all methods from
+{@link State.observePlugin}, so you can chain `.subscribe()` and `.bind()` after
+`.formValues()`. Call `formValuePlugin(DC)` once at module level to activate.
+
+Both plugins are idempotent — calling them multiple times has no side effects. They
+work by assigning methods onto `McBase.prototype` (reached via
+`Object.getPrototypeOf(Class.prototype)`) and use TypeScript module augmentation
+(`declare module`) so the added signatures appear in type-checking automatically.
+
+@template TTarget - The concrete type of the wrapped target; preserved by the
+{@link McBase.target} getter.
+
+@example Extending with plugins at runtime
+
+```ts
+import { DC, observePlugin, formValuePlugin } from '@twobirds/microcomponents';
+
+observePlugin(DC);
+formValuePlugin(DC);
+
+class MyForm extends DC {
+data = { name: '' };
+
+oneInit() {
+this
+.formValues(this.target, 'data')
+.subscribe('data', (v) => console.log(v))
+.bind('data', this.target);
+}
+}
+```
+
+`observePlugin(DC)` adds `notify()`, `subscribe()`, `bind()` to `McBase.prototype`;
+`formValuePlugin(DC)` adds `formValues()` and re-runs `observePlugin`. `oneInit()`
+runs once after the constructor.
+@group Micro Components
+*/
+var McBase = class {
+	#target;
+	/**
+	* Loaded asset cache, keyed by camelCase descriptor (`'targetHtml'` → `.target.html`).
+	* Inlined by the bundler in a bundled build, filled by `loadAssets()` in dev/autoload.
+	* Read through the {@link McBase.assets} getter.
+	*/
+	static _assets = {};
+	/**
+	* Declares companion files for auto-loading by convention (e.g. `['targetHtml', 'json']`).
+	* Asset names are camelCase and translated into file extensions: `'targetHtml'` → `.target.html`.
+	*/
+	static assets = [];
+	/**
+	* In-flight asset request, cached per class so that instances constructed while
+	* the first fetch is still pending (e.g. in a loop) share a single request
+	* instead of each triggering their own. Resolves to the freshly loaded assets.
+	*/
+	static _assetsPromise;
+	/**
+	The constructor for the base `McBase` class.
+	
+	Initializes a weak reference to the target, auto-attaches listeners for `DC`
+	subclasses, and starts loading any `static assets` for `MC` and `DC` alike —
+	a server-side `MC` fetches them with no DOM, a `DC` gets them attached by its
+	own constructor. The load is shared per class through `_assetsPromise`.
+	
+	@param target - The object or element this microcomponent represents.
+	*/
+	constructor(target) {
+		this.#target = new WeakRef(target || {});
+		const ctor = this.constructor;
+		if (this instanceof DC && this.constructor !== DC) autoAttachListeners(this);
+		const remaining = (ctor.assets ?? []).filter((key) => !ctor._assets[key]);
+		if (remaining.length && !ctor._assetsPromise) ctor._assetsPromise = loadAssets(ctor._originalTag || (this instanceof DC ? this.target.tagName.toLowerCase() : pascalToKebab(ctor.name)), remaining).then((res) => {
+			const loadedAssets = {};
+			remaining.forEach((key, i) => {
+				loadedAssets[key] = res[i];
+			});
+			ctor._assets = Object.assign({}, ctor._assets, loadedAssets);
+			return loadedAssets;
+		});
+	}
+	/**
+	Returns the current target object (DOM node or other data) referenced by this microcomponent.
+	
+	Uses a `WeakRef` internally to avoid circular references, and safely dereferences it here.
+	
+	The dereference is asserted non-null: the controller is stored on its target
+	(`element._mc`), so any code that can reach the controller through the element is
+	holding the target alive. Only a controller retained independently after its element
+	was garbage-collected could observe a stale reference — do not cache controllers
+	detached from their elements.
+	
+	@returns The target object.
+	*/
+	get target() {
+		return this.#target.deref();
+	}
+	/**
+	The loaded assets for this component instance.
+	
+	`static assets` are loaded before `oneInit()` fires on a `DC`, so this getter is
+	ready inside the `oneInit()` callback. A server-side `MC` fills it from `loadAssets()`;
+	await `MC._assetsPromise` before reading it. It returns the merged asset record keyed
+	by descriptor: `css` / `targetCss` / `shadowCss` / `shadowHtml` / `targetHtml` arrive
+	as strings, `*Json` entries arrive parsed, and a plain `html` template is returned as a
+	string for `parse()`. An empty object when no assets are declared.
+	
+	@returns A record mapping asset keys to their content.
+	*/
+	get assets() {
+		return this.constructor._assets || {};
+	}
+};
+/**
+@class DC
+---
+
+A DOM-centric microcomponent that operates on a specific HTML element.
+
+Extends {@link McBase} and associates itself with an actual DOM node via the
+`_target` reference. Provides methods for event handling, DOM traversal,
+and interaction with sibling or ancestor microcomponents.
+
+---
+
+## Static Configuration Properties
+
+DC classes support three static properties that configure custom elements
+before any instance is constructed:
+
+### `static tag?: string`
+
+Replaces the default target element with a semantic HTML element, or removes it entirely.
+
+- **Non-empty string** (e.g., `'header'`) — the original custom element is replaced
+with the specified built-in element. The original tag name is added as a CSS class.
+- **Empty string `''`** — the target element is removed from the DOM entirely.
+Useful for components that only inject global styles or act as style containers.
+
+@example static tag — replace with semantic element
+
+```ts
+class ShopHeader extends DC {
+static tag = 'header';
+}
+defineCE('shop-header', ShopHeader);
+```
+
+Produces `<header class="shop-header">` instead of `<shop-header>`.
+
+@example static tag — remove element entirely
+
+```ts
+class GlobalStyles extends DC {
+static tag = '';
+}
+defineCE('global-styles', GlobalStyles);
+```
+
+The element self-destructs; only side effects (e.g., injected styles) remain.
+
+### `static assets: string[]`
+
+Declares companion files for auto-loading by convention. Asset names are camelCase
+and translated into file extensions: `'targetHtml'` → `.target.html`, `'json'` → `.json`.
+
+The path is derived from the custom element tag segments, and the basename is the
+last segment. For `<cart-container-checkout>`, assets load from `/cart/container/checkout.*`.
+
+**Assets are loaded before `oneInit()` fires.** The constructor applies them to the
+target, then dispatches the `Init` lifecycle event — synchronously in a bundled build
+(assets inlined), after the fetch resolves in a dev/autoload build. Inside `oneInit()`
+the loaded assets are read through the {@link DC.assets} getter. Everything ending in
+`Json` arrives parsed; all other files arrive as text.
+
+**Auto-attached assets**: `.css`, `.target.css`, `.shadow.css`, `.target.html` and
+`.shadow.html` are attached automatically by `processAssets()` — CSS is injected into
+the document or shadow scope, HTML is set as `target.innerHTML` / `shadowRoot.innerHTML`,
+and native event handlers in the template (`<button click="this|go">`) are wired.
+
+**Plain `.html` is NOT auto-attached.** It is a template held in {@link DC.assets} for
+components created programmatically with a `data` parameter: in `oneInit()` you compile
+the target markup from template + data with `parse()`.
+
+**One-time global styles**: Assets named `'css'` and `'targetCss'` inject CSS into the
+global document scope via `injectCSS(document, ...)`. Because these are idempotent
+global side effects, they are processed only once — after the first instance loads them,
+the entries are dropped from `static _assets`. Subsequent instances skip re-processing
+them entirely.
+
+**CSS file roles**:
+
+- `.css` — design tokens only (CSS custom-property presets). Injected into the document
+scope once, like `targetCss`.
+- `.target.css` — layout rules for the light DOM. Also document-scoped and one-time.
+- `.shadow.css` — layout rules for the shadow DOM. Injected per instance into the
+component's own shadow root, so each instance gets its own copy.
+
+Every declared asset — CSS, HTML, JSON — is inlined into `static _assets` at build time by
+the bundler, which replaces the `static assets` declaration with `static _assets` (the
+`static assets` line is deleted from the bundled `.js`) and collapses each inlined
+`.[shadow/target].css` / `.html` to a single line, so a bundled build performs no fetches.
+
+In a bundled build the plain `.css` files are additionally concatenated into a single
+`bundle.css` by the bundling script. That file is a convenience listing of the available
+variables: copy the ones you want to change into your own stylesheet and override them
+there. It is not required at runtime, and it cannot drift from the inlined presets — both
+are read from the same source files.
+
+The runtime decides whether an asset still needs fetching with `!ctor._assets[key]`, so an
+inlined entry must never be an empty string: that would trigger a re-fetch of a file that
+does not exist in a bundled build.
+
+@example static assets read in oneInit
+
+```ts
+class CartCheckout extends DC {
+static assets = ['targetHtml', 'targetCss', 'configJson'];
+
+oneInit() {
+const { configJson } = this.assets;
+console.log(configJson);
+}
+}
+defineCE('cart-checkout', CartCheckout);
+```
+
+`configJson` arrives already parsed into an object.
+
+@example plain .html template compiled with data
+
+```ts
+class UserCard extends DC {
+static assets = ['html', 'targetCss'];
+
+constructor(target: HTMLElement, data: { name: string }) {
+super(target);
+this.data = data;
+}
+
+oneInit() {
+this.target.innerHTML = parse(this.assets.html, this.data);
+}
+}
+defineCE('user-card', UserCard);
+```
+
+`user-card.html` holds the `{name}` template; `parse()` fills it from `data`.
+
+### `static attributes?: object`
+
+Sets HTML attributes on every instance automatically.
+
+@example static attributes
+
+```ts
+class ProductCard extends DC {
+static attributes = { role: 'listitem' };
+}
+defineCE('product-card', ProductCard);
+```
+
+Every `<product-card>` carries `role="listitem"`.
+
+### Combined usage
+
+All three can be combined in one class:
+
+@example All static properties together
+
+```ts
+class ShopCatalog extends DC {
+static tag = 'section';
+static attributes = { role: 'list', 'aria-label': 'products' };
+static assets = ['targetHtml', 'targetCss'];
+}
+defineCE('shop-catalog', ShopCatalog);
+```
+
+Produces `<section role="list" aria-label="products">`.
+
+---
+
+## Event Handler Conventions
+
+Methods whose names start with `on` or `one` are automatically wired as event listeners
+on the target element. The prefix determines persistence:
+
+- **`on<EventName>`** — persistent listener (fires every time)
+- **`one<EventName>`** — one-time listener (fires once, then detaches)
+
+### Web Component Lifecycle Events
+
+When a DC is registered via {@link defineCE}, the custom element dispatches these
+internal events that can be caught with handler methods:
+
+| Method | When it fires |
+|--------|---------------|
+| `onConnected()` | Element was inserted into the DOM (`connectedCallback`) |
+| `onDisconnected()` | Element was removed from the DOM (`disconnectedCallback`) |
+| `onAdopted()` | Element was moved to a new document (`adoptedCallback`) |
+| `onAttributeChanged()` | An observed attribute changed (`attributeChangedCallback`) |
+| `oneInit()` | Constructor finished and declared assets loaded; read them via `this.assets` |
+
+@example Event handlers in action
+
+```ts
+class MyElement extends DC {
+onConnected() {
+console.log('entered the DOM');
+}
+
+onDisconnected() {
+console.log('left the DOM');
+}
+
+onClick() {
+this.trigger('something', 'payload');
+}
+
+oneSomething(ev) {
+console.log('first time only:', ev.detail.data);
+}
+}
+defineCE('my-element', MyElement);
+```
+
+---
+
+## Construction Patterns
+
+### Template usage (declarative)
+
+```ts
+class MyElement extends DC {}
+defineCE('my-element', MyElement);
+```
+
+The registered element is then used in HTML as `<my-element></my-element>`.
+
+### Programmatic construction with data
+
+When constructing programmatically via {@link getCE}, pass only the `data` payload —
+the target element is created automatically by the custom element constructor.
+
+@example Programmatic construction
+
+```ts
+class MyElement extends DC {
+data = {};
+
+constructor(target, data) {
+super(target);
+this.data = data;
+}
+}
+defineCE('my-element', MyElement);
+
+const Ctor = getCE('my-element');
+document.body.append(new Ctor({ name: 'John' }));
+```
+
+### Data from HTML attributes
+
+@example Reading data from an attribute
+
+```ts
+class MyElement extends DC {
+data = {};
+
+constructor(target) {
+super(target);
+this.data = JSON.parse(target.getAttribute('my-data'));
+}
+}
+defineCE('my-element', MyElement);
+```
+
+Used in HTML as `<my-element my-data='{"name":"John"}'></my-element>`.
+
+---
+
+## Plugin Extension Points
+
+The prototype of `DC` (inherited from {@link McBase}) is extended at runtime by optional
+plugins. See the {@link McBase} documentation for details on {@link State.observePlugin} and
+{@link State.formValuePlugin}.
+
+@template T - The concrete element type of the host element.
+@template EM - The component's custom event map (`event name → payload type`).
+Declaring it registers events on the type level: `trigger()` enforces the
+payload for registered names, and `on()`/`one()` handlers receive
+`CustomEvent<McDetail<Payload>>` with no annotation needed. Unregistered
+names keep the open `unknown`-payload behavior.
+
+@example Typed event map
+
+```ts
+class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {
+checkout() {
+this.trigger('CartUpdate', { count: 2 }, 'u');
+this.on('CartUpdate', (ev) => ev.detail.data.count);
+}
+}
+```
+
+`trigger()` checks the payload against the registered `CartUpdate` shape, and the `on()`
+handler receives a fully typed `ev`.
+@group Micro Components
+*/
+var DC = class DC extends McBase {
+	/**
+	* Replaces the target element with a semantic HTML tag, or removes it entirely.
+	* Set to `'header'` to swap `<my-element>` for `<header>`, or `''` to self-destruct.
+	*/
+	static tag;
+	/**
+	* Sets HTML attributes on every instance automatically.
+	* Example: `{ role: 'listitem', 'aria-label': 'nav' }`.
+	*/
+	static attributes = {};
+	/**
+	* Constructs a new DC instance and applies static configuration.
+	*
+	* The constructor performs these steps in order:
+	* 1. Calls {@link McBase} to establish the target reference and auto-attach listeners.
+	* 2. If `static tag` is set and differs from the current element, replaces the target
+	*    with a new built-in element (or removes it if `tag === ''`).
+	* 3. Applies any `static attributes` to the target element.
+	* 4. Loads `static assets` (inlined in a bundled build, fetched in dev/autoload),
+	*    applies the auto-attached ones to the target, then fires the `Init` lifecycle
+	*    event — so `oneInit()` runs with the assets loaded and readable via {@link DC.assets}.
+	*
+	* @param target - The host DOM element this component operates on.
+	*/
+	constructor(target) {
+		super(target);
+		const ctor = this.constructor;
+		if (ctor === DC) return;
+		const tagName = this.target.tagName.toLowerCase();
+		if (ctor["tag"] !== void 0 && tagName !== ctor.tag && ctor.tag !== "") {
+			const element = document.createElement(ctor.tag);
+			element.classList.add(tagName);
+			ctor._originalTag = tagName;
+			DC.add(element, ctor.name, new ctor(element));
+			delete ctor._originalTag;
+			if (tagName.includes("-") && !this.target.isConnected) this.on("connected", () => this.target.replaceWith(element));
+			else this.target.replaceWith(element);
+			return;
+		}
+		const attributes = ctor.attributes;
+		if (ctor.attributes) Object.keys(ctor.attributes).forEach((key) => {
+			this.target.setAttribute(key, attributes[key]);
+		});
+		if (Object.keys(ctor._assets).length) {
+			processAssets(this, ctor._assets);
+			for (const onceKey of ["css", "targetCss"]) delete ctor._assets[onceKey];
+			ctor.assets = ctor.assets.filter((key) => key !== "css" && key !== "targetCss");
+		}
+		if (ctor._assetsPromise) ctor._assetsPromise.then((loadedAssets) => {
+			processAssets(this, loadedAssets);
+			for (const onceKey of ["css", "targetCss"]) delete ctor._assets[onceKey];
+			ctor.assets = ctor.assets.filter((key) => key !== "css" && key !== "targetCss");
+			init(this);
+		});
+		else init(this);
+		if (ctor.tag === "") {
+			this.target.remove();
+			return;
+		}
+	}
+	/**
+	Static helper to attach a microcomponent instance to a DOM element.
+	
+	Wrapper around the `add()` utility function, providing a class-level API
+	for adding child microcomponents to a target node.
+	
+	@template T - The concrete element type of the target; preserved in the return type.
+	@template K - The literal registration key; becomes a known entry of the returned `_mc` registry.
+	@template E - The type of the attached element; retrievable as `result._mc[key]`.
+	@param target - The DOM element to which to attach the microcomponent.
+	@param key - The property name/key under which to store the instance in `_mc`.
+	@returns The target DOM element with the attached microcomponent.
+	*/
+	static add(target, key, element = {}) {
+		return add(target, key, element);
+	}
+	/**
+	Static helper to remove a named microcomponent from a DOM element.
+	
+	Wrapper around the `remove()` utility function, providing a class-level API
+	for removing child microcomponents.
+	
+	@template T - A plain or already-enhanced element type.
+	@template K - The literal registration key; its entry is poisoned in the registry type.
+	@param target - The DOM element from which to remove the microcomponent.
+	@param key - The property name/key corresponding to the microcomponent to remove.
+	*/
+	static remove(target, key) {
+		remove(target, key);
+	}
+	/**
+	Class-verified entry lookup: returns the component stored under `key` on the
+	element's `_mc` record — but only if it is an instance of `Klass`.
+	
+	This is the *sound* retrieval primitive: presence AND type identity are both
+	proven at runtime (`instanceof`), so it needs no global `McRegistry`
+	declaration and stays correct even when different elements use the same key
+	name for different component types. Accepts any value (including
+	`querySelector` results that may be null) — every failure mode returns
+	`undefined`.
+	
+	@template E - The component type, inferred from `Klass`.
+	@param element - The value to look the entry up on; anything non-host yields undefined.
+	@param key - The registry key name to look under.
+	@param elementMcClass - The class the entry must be an instance of.
+	@returns The verified instance, or undefined.
+	@example
+	```ts
+	const cart = DC.get(document.querySelector('form'), 'cart', Cart);
+	cart?.addItem(item);
+	```
+	
+	`cart` is `Cart | undefined` — presence and type identity are both proven by the
+	`instanceof` check inside `get()`, with no global declaration involved.
+	*/
+	static get(element, key, elementMcClass) {
+		if (!isMcHost(element)) return void 0;
+		const entry = element._mc[key];
+		return entry instanceof elementMcClass ? entry : void 0;
+	}
+	/**
+	Detaches an event listener from the DOM node.
+	
+	This is an instance method wrapper for `off()`, using the internal `_target` DOM reference.
+	
+	@param eventName - The name of the event (e.g., 'click', 'update').
+	@param handler - The previously attached callback function or object to remove.
+	*/
+	off(eventName, handler) {
+		off(this.target, eventName, handler);
+	}
+	/**
+	Attaches a persistent event listener to the DOM node.
+	
+	This is an instance method wrapper for `on()`, using the internal `_target` DOM reference.
+	
+	The handler receives a `CustomEvent<McDetail<Payload>>`. For event names
+	registered in the component's event map `EM` the payload is resolved from the
+	map — an unannotated arrow handler is fully typed. For unregistered names the
+	payload defaults to `unknown` and can be pinned via the type argument
+	(`on<Payload>('Name', handler)`) or the handler's own annotation.
+	
+	@param eventName - The name of the event (e.g., 'click', 'update').
+	@param handler - The callback function or object to invoke.
+	@returns The attached handler reference, unchanged — usable directly with {@link off}.
+	*/
+	on(eventName, handler) {
+		return on(this.target, eventName, handler);
+	}
+	/**
+	Attaches a one-time event listener to the DOM node.
+	
+	This is an instance method wrapper for `one()`, using the internal `_target` DOM reference.
+	Payload typing follows the same rules as {@link DC.on}.
+	
+	@param eventName - The name of the event (e.g., 'click', 'update').
+	@param handler - The callback function or object to invoke once.
+	@returns The attached one-time handler reference, unchanged — usable directly with {@link off}.
+	*/
+	one(eventName, handler) {
+		return one(this.target, eventName, handler);
+	}
+	/**
+	Triggers a custom event on the DOM node and optionally bubbles it.
+	
+	This is an instance method wrapper for `trigger()`, using the internal `_target` DOM reference.
+	
+	For event names registered in the component's event map `EM` the payload type
+	is enforced; unregistered names accept any payload (typed via inference or an
+	explicit `trigger<Payload>(...)` argument).
+	
+	@param eventName - The name of the event (will be prefixed if needed).
+	@param data - Additional data payload attached to `event.detail.data`.
+	@param bubble - Bubbling direction ('l', 'u', 'd' or combinations).
+	@param controller - Optional controller for managing bubbling behavior.
+	*/
+	trigger(eventName, data = {}, bubble = "l", controller) {
+		trigger(this.target, eventName, data, bubble, controller);
+	}
+	/**
+	Returns an array of all ancestor microcomponents up the DOM tree.
+	
+	Traverses upward from this element's target, collecting the `_mc` instances
+	of ancestor elements marked with `data-mc`. The keyed form only collects
+	hosts whose registry carries `key`, typed from the global {@link McRegistry}
+	binding — non-optional, since presence is checked during the walk.
+	
+	@template R - Known registry entries of the results; pass a record to assert
+	a site-specific shape: `ancestors<{ cart: Cart }>()`. Defaults to none.
+	@returns An array of ancestor microcomponent instances (empty if none found).
+	*/
+	ancestors(key) {
+		const result = [];
+		let current = findMcAncestor(this.target, key);
+		while (current) {
+			result.push(current);
+			current = findMcAncestor(current.target, key);
+		}
+		return result;
+	}
+	/**
+	Returns the closest ancestor microcomponent or null if none found.
+	
+	This method is equivalent to calling `ancestors()[0]`, but more concise.
+	The keyed form walks up to the nearest host whose registry carries `key`,
+	typed from the global {@link McRegistry} binding — non-optional, since
+	presence is checked during the walk.
+	
+	@template R - Known registry entries of the result; pass a record to assert
+	a site-specific shape: `closest<{ cart: Cart }>()?.cart.addItem(...)`.
+	Defaults to none.
+	@returns The nearest matching ancestor's `_mc`, or null if not found.
+	*/
+	closest(key) {
+		return findMcAncestor(this.target, key);
+	}
+	/**
+	Returns an array of direct child microcomponents.
+	
+	Calls `getMcChildNodes()` internally to find immediate descendants only,
+	excluding nested grandchildren and deeper levels. The keyed form filters to
+	hosts whose registry carries `key`; see {@link DC.closest}.
+	
+	@template R - Known registry entries of the results; see {@link DC.closest}.
+	@returns An array of child microcomponent instances (empty if none found).
+	*/
+	children(key) {
+		const kids = getMcChildNodes(this.target);
+		return key === void 0 ? kids : kids.filter((mc) => key in mc);
+	}
+	/**
+	Returns an array of all descendant microcomponents recursively.
+	
+	Uses a `querySelectorAll` query to collect every nested element marked with
+	`data-mc`, returning their associated `_mc` instances. The keyed form
+	filters to hosts whose registry carries `key`; see {@link DC.closest}.
+	
+	@template R - Known registry entries of the results; see {@link DC.closest}.
+	@returns An array of descendant microcomponent instances (empty if none found).
+	*/
+	descendants(key) {
+		return Array.from(this.target.querySelectorAll("[data-mc]")).filter((e) => e instanceof HTMLElement && "_mc" in e).map((e) => e._mc).filter((mc) => key === void 0 || key in mc);
+	}
+};
+//#endregion
+//#region src/utils/resolveComponentPath.ts
+/**
+@module Autoload
+
+Single source of truth for the tag-to-file convention: hyphens become path
+separators, so `my-card` resolves to `./my/card.js`. Imported by the runtime
+autoload loader and by build-time tooling so both agree on the path without
+either duplicating the rule.
+*/
+/**
+The tag-to-path primitive: hyphens become path separators, with no prefix or
+extension. `my-card` → `my/card`. The single source of truth for the
+convention; {@link resolveComponentPath} and build-time tooling both derive
+their paths from it so neither duplicates the rule.
+
+@example Returns `'my/card'` for `my-card`, and `'app/header'` for `app-header`.
+```ts
+tagPath('my-card');
+tagPath('app-header');
+```
+@hidden
+@group Autoload
+*/
+function tagPath(tag) {
+	return tag.split("-").join("/");
+}
+/**
+Resolves a microcomponent tag name to its autoload module path by prefixing and
+suffixing {@link tagPath}: `my-card` → `./my/card.js`.
+
+@example Returns `'./my/card.js'` for `my-card`, and `'./app/header.js'` for `app-header`.
+```ts
+resolveComponentPath('my-card');
+resolveComponentPath('app-header');
+```
+@group Autoload
+*/
+function resolveComponentPath(tag) {
+	return "./" + tagPath(tag) + ".js";
+}
+//#endregion
+//#region src/utils/autoload.ts
+/**
+@module Autoload
+
+The {@linkcode autoload} function enables automatic detection and instantiation of microcomponents in the DOM via a `MutationObserver`. When enabled, newly added elements with undefined custom tags or `data-mc` references will trigger dynamic script loading and component attachment.
+
+Kept in its own module so the core controller classes in MC.ts stay free of
+side-effect-bearing DOM machinery (`MutationObserver`, script injection):
+importing `DC`/`MC` never pulls a DOM observer into the bundle unless
+{@link autoload} itself is imported.
+*/
+var loadingDCs = /* @__PURE__ */ new Set();
+/**
+Creates a closure that attaches DOM elements with the specified tag name to
+their corresponding microcomponent instances.
+
+Used internally by `makeLoadScript()` when dynamically loading external
+custom element definitions. The returned function is invoked after the
+element definition becomes available, and performs:
+- Querying of all matching elements in the DOM
+- Instantiation of new `DC` instances
+- Attachment to each DOM node via `DC.add()`
+
+@param element - The tag name (custom element name) of the microcomponent to instantiate.
+@returns A closure that performs the attachment logic when invoked.
+@group Autoload
+*/
+function attachDC(element) {
+	return () => {
+		const elements = Array.from(document.querySelectorAll(`[data-mc~="${element}"]`)).filter((e) => e instanceof HTMLElement);
+		if (elements.length === 0) return;
+		const customElementClass = customElements.get(element);
+		for (let node of elements) {
+			try {
+				DC.add(node, customElementClass.name, new customElementClass(node));
+			} catch (error) {
+				/* v8 ignore start */
+				if ("create" in customElementClass && typeof customElementClass.create === "function") {
+					const customElement = customElementClass.create(node);
+					if (!isMcHost(customElement)) throw `create() of Class ${customElementClass.name} did not return a McHost.`;
+					customElement.setAttribute("data-mc", node.getAttribute("data-mc") ?? "");
+					node.replaceWith(customElement);
+					node = customElement;
+				} else throw `Class ${customElementClass.name} doesn't have a callable constructor AND class doesn't have a static .create() method.`;
+			}
+			const newMcName = node.getAttribute("data-mc").split(" ").filter((name) => name !== element && name !== "").join(" ").trim();
+			node.setAttribute("data-mc", newMcName);
+		}
+	};
+}
+/**
+Dynamically loads and registers a custom element definition from an external JS file.
+
+Constructs the script URL based on kebab-case naming (e.g., `my-element` → `./my/element.js`).
+Registers a handler to be executed once the element is defined, then appends the
+`<script>` tag to `<head>`. Handles both successful loading and error cases.
+
+@param element - The custom element tag name (e.g., 'mc-button', 'my-widget').
+*/
+function makeLoadScript(element) {
+	/* v8 ignore next */
+	if (loadingDCs.has(element)) return;
+	loadingDCs.add(element);
+	const fileName = resolveComponentPath(element);
+	const scriptElement = document.createElement("script");
+	scriptElement.setAttribute("src", fileName);
+	scriptElement.setAttribute("blocking", "render");
+	scriptElement.async = true;
+	scriptElement.setAttribute("type", "module");
+	scriptElement.setAttribute("data-name", element);
+	scriptElement.setAttribute("loading", "");
+	customElements.whenDefined(element).then(attachDC(element));
+	scriptElement.addEventListener("load", (ev) => {
+		loadingDCs.delete(element);
+		document.head.querySelector(`script[data-name="${element}"]`)?.remove();
+	});
+	scriptElement.addEventListener("error", (ev) => {
+		console.error("could not load DC code from", fileName);
+		loadingDCs.delete(element);
+	});
+	document.head.append(scriptElement);
+}
+/**
+Scans the DOM for undefined custom elements and pending microcomponents,
+then loads their definitions if necessary.
+
+This is the main driver function for the autoload mechanism. It performs:
+1. Finds all undefined custom elements in the document
+2. Checks whether they are already loading or defined
+3. Calls `makeLoadScript()` to fetch missing definitions
+4. Invokes `attachDC()` where element definitions exist but haven't been attached yet
+
+It is called both immediately after enabling autoload and on each DOM mutation.
+*/
+function loadUndefinedMCs() {
+	[...document.querySelectorAll(":not(:defined)")].filter((element) => !!element && !customElements.get(element.tagName.toLowerCase()) && !loadingDCs.has(element.tagName.toLowerCase())).forEach((el) => {
+		makeLoadScript(el.tagName.toLowerCase());
+	});
+	[...document.querySelectorAll("[data-mc]:not([data-mc=\"\"]")].filter((element) => !!element).forEach((el) => {
+		(el.getAttribute("data-mc")?.split(" ").filter((name) => name !== ""))?.forEach((element) => {
+			const isDefined = customElements.get(element);
+			if (!loadingDCs.has(element) && !isDefined) makeLoadScript(element);
+			else if (isDefined) attachDC(element)();
+		});
+	});
+}
+var observer = null;
+var armTimer = null;
+function autoload(enable = true) {
+	if (!enable) {
+		if (armTimer) {
+			clearTimeout(armTimer);
+			armTimer = null;
+		}
+		if (observer) {
+			observer.disconnect();
+			observer = null;
+		}
+		loadingDCs.clear();
+		return false;
+	}
+	if (!!observer) return true;
+	observer = new MutationObserver(loadUndefinedMCs);
+	armTimer = setTimeout(() => {
+		armTimer = null;
+		/* v8 ignore next */
+		if (!observer) return;
+		observer.observe(document.body, {
+			childList: true,
+			subtree: true
+		});
+		loadUndefinedMCs();
+	}, 5);
+	window.autoload ??= autoload;
+	return true;
+}
+autoload.state = loadingDCs;
+//#endregion
+export { autoload };