@twobirds/microcomponents 0.8.0 → 0.10.0

package/dist/microcomponents.js

@@ -1,9 +1,2882 @@
-'use strict';
-export * from './utils/helpers.js';
-export * from './core/mcGuards.js';
-export * from './core/MC.js';
-export * from './utils/autoload.js';
-export * from './utils/events.js';
-export * from './core/elements.js';
-export * from './state/observables.js';
-export * from './state/formValues.js';
+//#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.
+*/
+/**
+* Converts a standard event name to its microcomponent-prefixed variant.
+*
+* This utility is used internally to namespace custom events (e.g., 'Click' → '_mcClick').
+*
+* @param eventName - The original event name (e.g., 'click', 'update').
+* @returns The microcomponent-prefixed event name.
+*
+* @example
+* ```ts
+* console.log(getMcEventName('update'));
+* ```
+*/
+function getMcEventName(eventName) {
+	return "_mc" + eventName[0].toUpperCase() + eventName.substring(1);
+}
+/**
+* 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
+/**
+* Determines whether the current runtime environment is a web browser.
+*
+* This function works by attempting to access `this` within an anonymous function
+* and checking if it refers to the global `window` object. It returns `true`
+* when executed in a browser context, and `false` otherwise (e.g., Node.js).
+*
+* Note: While modern environments typically provide more reliable detection mechanisms,
+* this fallback remains compatible across older runtimes where other detection techniques
+* may be unreliable.
+*
+* @returns `true` if the code is running in a browser environment, `false` otherwise.
+*
+* @example
+* ```ts
+* if (isBrowser()) {
+*   console.log('Running in a browser');
+* }
+* ```
+*/
+function isBrowser() {
+	return typeof window !== "undefined" && typeof window.document !== "undefined";
+}
+/**
+* Checks if a value is a native JavaScript object (created via {} or new Object()).
+* @param value - The value to check.
+* @returns True if the value is a plain object, false otherwise.
+*
+* @example
+* ```ts
+* console.log(isNativeObject({}));
+* console.log(isNativeObject(new Object()));
+* console.log(isNativeObject([]));
+* console.log(isNativeObject(null));
+* ```
+*/
+function isNativeObject(value) {
+	return typeof value === "object" && value !== null && value.constructor === Object;
+}
+/**
+* Recursively sorts all keys in an object alphabetically, preserving nested structure.
+* @param source - The object to sort.
+* @returns A new object with sorted keys at all levels.
+*
+* @example
+* ```ts
+* const obj = { z: 1, a: { y: 2, b: 3 } };
+* console.log(JSON.stringify(sortObject(obj)));
+* ```
+*/
+function sortObject(source) {
+	const result = {}, keys = Object.keys(source).sort();
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i], value = source[key];
+		if (isNativeObject(value)) result[key] = sortObject(value);
+		else result[key] = value;
+	}
+	return result;
+}
+/**
+* Flattens a nested object into a single-level object with dot-separated keys.
+* Optionally sorts the resulting flat keys alphabetically (default: true).
+* @param source - The object to flatten.
+* @param doSort - Whether to sort the resulting keys (default: true).
+* @returns A flattened object with dot-notation keys.
+*
+* @example
+* ```ts
+* const obj = { user: { name: 'Alice', age: 30 } };
+* console.log(JSON.stringify(flattenObject(obj)));
+* ```
+*/
+function flattenObject(source, doSort = true) {
+	const result = {};
+	const record = source;
+	const names = Object.getOwnPropertyNames(source);
+	for (let i = 0; i < names.length; i++) {
+		const propName = names[i], value = record[propName];
+		if (value instanceof Object) {
+			const temp = flattenObject(value, false);
+			for (const j in temp) result[propName + "." + j] = temp[j];
+		} else result[propName] = value;
+	}
+	return doSort ? sortObject(result) : result;
+}
+/**
+* Structural deep-equality using SameValueZero for primitives.
+*
+* See {@link https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevaluezero}.
+*
+* Note: `Map`/`Set` are not structurally compared.
+*
+* @param a - The first value to compare.
+* @param b - The second value to compare.
+* @returns True if the values are deeply equal, false otherwise.
+*
+* @example
+* ```ts
+* console.log(deepEqual({ a: 1 }, { a: 1 }));
+* console.log(deepEqual({ a: { b: 2 } }, { a: {} }));
+* console.log(deepEqual({ a: NaN }, { a: NaN }));
+* console.log(deepEqual({ a: NaN }, { a: null }));
+* ```
+*/
+function deepEqual(a, b) {
+	if (a === b || a !== a && b !== b) return true;
+	/* v8 ignore start */
+	if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+	if (a.constructor !== b.constructor) return false;
+	if (a instanceof Date) return a.getTime() === b.getTime();
+	if (a instanceof RegExp) return a.toString() === b.toString();
+	/* v8 ignore end */
+	if (Array.isArray(a)) {
+		const bArr = b;
+		/* v8 ignore next */
+		if (a.length !== bArr.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], bArr[i])) return false;
+		return true;
+	}
+	const aObj = a, bObj = b, keys = Object.keys(aObj);
+	if (keys.length !== Object.keys(bObj).length) return false;
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i];
+		if (!Object.prototype.hasOwnProperty.call(bObj, key) || !deepEqual(aObj[key], bObj[key])) return false;
+	}
+	return true;
+}
+/**
+* Retrieves a nested value from an object using a namespace path (dot-separated).
+* @param ns - The namespace string or array of keys representing the path.
+* @param obj - The object to traverse.
+* @returns The value at the specified namespace path, or undefined if not found.
+*
+* @example
+* ```ts
+* const data = { user: { profile: { name: 'Alice' } } };
+* console.log(nameSpace('user.profile.name', data));
+* console.log(nameSpace(['user', 'profile'], data));
+* ```
+*/
+function nameSpace(ns, obj = {}) {
+	const source = obj;
+	const nsa = typeof ns === "string" ? ns.split(".") : ns;
+	if (!source || !nsa[0] || !source[nsa[0]]) return;
+	if (nsa.length > 1) {
+		const next = source[nsa[0]];
+		if (isNativeObject(next)) return nameSpace(nsa.slice(1), next);
+		return;
+	}
+	return source[nsa[0]];
+}
+/**
+* Parses a template string or object, replacing placeholders in the form of {key.path} with
+* corresponding values from the provided data object using namespace resolution.
+* Also recursively processes objects and arrays within the input.
+* @param template - The string or object to parse (can contain {{placeholder}} expressions).
+* @param parseThis - The object containing values for placeholder substitution.
+* @returns The parsed result, with placeholders replaced by actual values.
+*
+* @example
+* ```ts
+* const data = { user: { name: 'Alice' } };
+* console.log(parse('Hello {user.name}!', data));
+* console.log(parse(['Hi {user.name}', 'Bye {user.name}'], data));
+* ```
+*/
+function parse(template, parseThis, ...rest) {
+	const args = [
+		template,
+		parseThis,
+		...rest
+	];
+	if (args.length > 2) {
+		while (args.length > 1) {
+			args[0] = parse(args[0], args[1]);
+			args.splice(1, 1);
+		}
+		return args[0];
+	}
+	if (typeof template === "string") {
+		let result = template;
+		template.match(/\{[^\{\}]*\}/g)?.forEach((pPropname) => {
+			const value = nameSpace(pPropname.substring(1, pPropname.length - 1), parseThis);
+			if (typeof value !== "undefined") result = result.replace(pPropname, String(value));
+		});
+		return result;
+	} else if (isNativeObject(template)) {
+		const record = template;
+		Object.keys(record).forEach((pKey) => {
+			/* v8 ignore next */
+			if (Object.prototype.hasOwnProperty.call(record, pKey)) record[pKey] = parse(record[pKey], parseThis);
+		});
+	}
+	return template;
+}
+/**
+* Converts a kebab-case string to PascalCase.
+* Example: 'my-component-name' -> 'MyComponentName'
+* @param str - The kebab-case string to convert.
+* @returns The converted PascalCase string.
+*
+* @example
+* ```ts
+* console.log(kebabToPascal('my-element'));
+* ```
+*/
+function kebabToPascal(str) {
+	return str.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+/**
+* Creates a debounced version of a function that delays execution until after the specified
+* number of milliseconds have elapsed since the last time this function was invoked.
+* Useful for rate-limiting expensive operations like event handlers or API calls.
+* @param func - The function to debounce.
+* @param milliseconds - The number of milliseconds to delay execution.
+* @returns A debounced version of the input function.
+*
+* @example
+* ```ts
+* const log = debounce(() => console.log('called'), 300);
+* log();
+* log();
+* ```
+*/
+function debounce(func, milliseconds) {
+	let timeout;
+	return (...args) => {
+		clearTimeout(timeout);
+		timeout = setTimeout(() => {
+			func(...args);
+		}, milliseconds);
+	};
+}
+/**
+* Parses an HTML string and returns an array of DOM elements.
+* Handles self-closing tags (XHTML style) by converting them to full closing tags first.
+* @hidden
+* @param html - The HTML string to parse.
+* @returns An array of HTMLElement objects representing the parsed HTML nodes.
+*
+* @example
+* ```ts
+* const elems = htmlToElements('<div>Hello</div><span>World</span>');
+* console.log(elems.map((el) => el.tagName));
+* ```
+*/
+function htmlToElements(html) {
+	const template = document.createElement("template");
+	html = html.replace(/<([A-Za-z0-9\-]*)([^>\/]*)(\/>)/gi, "<$1$2></$1>");
+	template.innerHTML = html;
+	template.content.normalize();
+	return Array.from(template.content.childNodes);
+}
+/**
+* Copies all getter and setter properties from a source object to a target object.
+* Does not copy methods or regular data properties—only accessor properties (get/set).
+* @hidden
+* @param source - The source object with getters and/or setters to copy.
+* @param target - The target object to which the accessors will be copied.
+*
+* @example
+* ```ts
+* const src = { get name() { return 'Alice'; } };
+* const tgt = {};
+* copyGettersSetters(src, tgt);
+* console.log(tgt.name);
+* ```
+*/
+function copyGettersSetters(source, target) {
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	for (const [key, descriptor] of Object.entries(descriptors)) if ("get" in descriptor || "set" in descriptor) Object.defineProperty(target, key, descriptor);
+}
+/**
+* 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) {
+	return typeof HTMLElement !== "undefined" && element instanceof HTMLElement && "_mc" in element && (key === void 0 || key in element._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]) {
+		_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 asynchronously.
+
+This function schedules the `trigger('Init')` call in a microtask, ensuring
+that all synchronous initialization is complete before the lifecycle hook
+executes. Only `DC` instances have an Init lifecycle — the `McBase`
+constructor calls this exclusively behind an `instanceof DC` check, 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. For `DC` subclasses it also bootstraps two automatic
+behaviours:
+
+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}.
+2. **"Init" lifecycle event** — dispatched asynchronously in a microtask so that all
+synchronous constructor work finishes first.
+
+Both mechanisms run only when the instance is a `DC` (checked with `instanceof DC`).
+Plain `MC` instances skip them entirely, 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;
+	/**
+	The constructor for the base `McBase` class.
+	
+	Initializes a weak reference to the target and triggers auto-attachment
+	of listeners and initialization lifecycle events.
+	
+	@param target - The object or element this microcomponent represents.
+	*/
+	constructor(target) {
+		this._target = new WeakRef(target || {});
+		if (this instanceof DC && this.constructor !== DC) {
+			autoAttachListeners(this);
+			const tag = this.constructor.tag;
+			if (tag === void 0 || tag.toUpperCase() === this.target.tagName) init(this);
+		}
+	}
+	/**
+	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();
+	}
+};
+/**
+A general-purpose base microcomponent that does not require a DOM target.
+
+Inherits from `McBase`, but is primarily used as a lightweight container or
+for logic not directly tied to DOM elements.
+
+@template TTarget - The concrete type of the wrapped target data; preserved by
+the `target` getter, so `new MC({ some: 'data' }).target.some` stays typed.
+@group Micro Components
+*/
+var MC = class extends McBase {
+	/**
+	Constructs an instance of the general-purpose microcomponent.
+	
+	@param target - Target object or data.
+	*/
+	constructor(target) {
+		super(target);
+	}
+};
+/**
+@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.*`.
+
+When assets finish loading, an `'assets'` event fires so that `oneAssets(ev)` can
+process them. Everything ending in `Json` arrives parsed; all other files arrive as text.
+
+**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 removed from both `static assets` and `static _assets`. Subsequent
+instances skip loading and 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 load-assets plugin, so a bundled build performs no fetches at all.
+
+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 with autoload
+
+```ts
+class CartCheckout extends DC {
+static assets = ['targetHtml', 'targetCss', 'configJson'];
+
+oneAssets(ev) {
+const { configJson } = ev.detail.data;
+console.log(configJson);
+}
+}
+defineCE('cart-checkout', CartCheckout);
+```
+
+`configJson` arrives already parsed into an object.
+
+### `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; all synchronous setup complete (microtask) |
+| `oneAssets()` | Constructor finished; all assets loaded and available; ev contains assets object |
+
+@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;
+	/**
+	* Result container for assets (e.g., `['targetHtml', 'json']`).
+	* Asset names (keys) are camelCase and translated into file extensions: `'targetHtml'` → `.target.html`.
+	*/
+	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;
+	/**
+	* 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. If `static assets` has entries, initiates asynchronous loading, fires an `'assets'` event when complete handled by `oneAssets(ev)`.
+	* 4. Applies any `static attributes` to the target element.
+	*
+	* @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]);
+		});
+		const that = this;
+		const remainingAssets = ctor.assets.filter((key) => !ctor._assets[key]);
+		if (Object.keys(ctor._assets).length) processAssets(this, ctor._assets);
+		if (remainingAssets.length) {
+			if (!ctor._assetsPromise) ctor._assetsPromise = loadAssets(ctor._originalTag || tagName, remainingAssets).then((res) => {
+				const loadedAssets = {};
+				remainingAssets.forEach((key, i) => {
+					loadedAssets[key] = res[i];
+				});
+				ctor._assets = Object.assign({}, ctor._assets, loadedAssets);
+				for (const onceKey of ["css", "targetCss"]) if (loadedAssets[onceKey] !== void 0) delete ctor._assets[onceKey];
+				ctor.assets = ctor.assets.filter((key) => key !== "css" && key !== "targetCss");
+				return loadedAssets;
+			});
+			ctor._assetsPromise.then((loadedAssets) => {
+				processAssets(this, loadedAssets);
+				that.trigger("assets", ctor._assets);
+			});
+		} else if ([...Object.keys(ctor._assets)].length) queueMicrotask(() => that.trigger("assets", ctor._assets));
+		if (ctor.tag === "") {
+			this.target.remove();
+			return;
+		}
+	}
+	/**
+	Returns the loaded assets for this component instance.
+	
+	Assets are loaded asynchronously when `static assets` is defined on the class.
+	This method returns the resolved asset map keyed by filename, or `undefined`
+	if assets have not yet been loaded.
+	
+	@returns A record mapping asset keys to their content strings, or undefined.
+	*/
+	getAssets() {
+		return this.constructor._assets || {};
+	}
+	/**
+	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);
+	});
+	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;
+function autoload(enable = true) {
+	if (!enable) {
+		if (observer) {
+			observer.disconnect();
+			observer = null;
+		}
+		return false;
+	}
+	if (!!observer) return true;
+	observer = new MutationObserver(loadUndefinedMCs);
+	setTimeout(() => {
+		observer.observe(document.body, {
+			childList: true,
+			subtree: true
+		});
+		loadUndefinedMCs();
+	}, 5);
+	window.autoload ??= autoload;
+	return true;
+}
+autoload.state = loadingDCs;
+//#endregion
+//#region src/core/elements.ts
+/**
+Custom element registration utilities — bridges DC microcomponents with the native
+`CustomElementRegistry`.
+
+This module provides:
+- {@link defineCE} — wraps `customElements.define()` to register a custom element that
+hosts a DC instance in its `_mc` registry. The defining class also controls observed
+attributes; all inner MCs receive lifecycle events (`connected`, `disconnected`, etc.).
+- {@link getCE} — typed wrapper for `customElements.get()`.
+- {@link listCE} — returns every tag name registered via {@link defineCE}.
+
+Familiarity with the [Custom Elements Web Standard](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) is recommended.
+
+For DC-specific documentation (static properties, event handlers, lifecycle events,
+construction patterns), see the {@link DC} class in `MC.ts`.
+
+@group Elements
+
+@example Define custom element in registry
+
+```ts
+class MyElement extends DC {}
+defineCE('my-element', MyElement);
+```
+
+The registered element is then used in HTML as `<my-element></my-element>`.
+
+@example Retrieve custom element from registry
+
+```ts
+const MyElementClass = getCE('my-element');
+if (MyElementClass) {
+document.body.append(new MyElementClass());
+}
+```
+
+@example List all custom element tags registered by defineCE 
+
+```ts
+defineCE('my-element', MyElement);
+defineCE('another-widget', AnotherWidget);
+console.log(listCE());
+```
+*/
+/**
+Creates a named class constructor with the specified name.
+@param name - The desired name for the class.
+@param targetClass - The class constructor to which the name will be assigned.
+@returns The class constructor with the name property set.
+
+@example
+```ts
+const MyNamedClass = createNamedClass('MyNamedClass', class { });
+console.log(MyNamedClass.name);
+```
+*/
+function createNamedClass(name, targetClass) {
+	return Object.defineProperty(targetClass, "name", { value: name });
+}
+function Base(ElementClass) {
+	return class extends ElementClass {
+		constructor(...args) {
+			super(...args);
+		}
+	};
+}
+/**
+### Examples
+---
+
+#### Define custom element in registry
+
+```ts
+class MyElement extends DC {}
+defineCE('my-element', MyElement);
+```
+
+The registered element is then used in HTML as `<my-element></my-element>`.
+
+#### Define custom element in registry with observed attributes
+
+```ts
+class MyElement extends DC {
+onAttributeChanged(ev){
+const newValue = ev.detail.data.newValue;
+}
+}
+defineCE('my-element', MyElement, ['observed']);
+```
+
+Used in HTML as `<my-element observed></my-element>`. When the `observed` attribute
+changes, `attributeChanged` is triggered, which calls `onAttributeChanged` with the
+change data in the payload.
+
+Defines a custom HTML element with optional observed attributes and micro component integration.
+The class provided in DefinitionClass will be added to the ._mc hash object appended to the custom element instance.
+Automatically assigns a "PascalCase" class name derived from the <kebab-case> tagName.
+If the provided definition class extends McBase (indicating a DC or MC class extension), it wraps the constructor to register
+the element instance with DC (DomComponent).
+
+@param tagName - The HTML tag name for the custom element (must contain at least one hyphen, enforced at compile time).
+@param DefinitionClass - The constructor function or class that defines the element's behavior. Its `target` parameter type follows `extend`; an optional second `data` parameter receives the payload passed on programmatic construction.
+@param observedAttributes - An optional array of attribute names to observe for changes.
+@param extend - DEPRECATED! An optional built-in HTML element tag name to extend, enabling customized built-in elements.
+@returns The registered custom element constructor, typed to accept the `data` payload
+and exposing the `_mc` entry under the PascalCase tag name — or `undefined` if the
+tag name was already defined. Feed it (or an equivalent `McElementConstructor`) to
+the global {@link McElementTagNameMap} to make `getCE()` return it typed by string.
+@group Elements
+*/
+function defineCE(tagName, DefinitionClass, observedAttributes = [], extend) {
+	if (customElements.get(tagName)) {
+		console.warn(`IGNORED: Custom element "${tagName}" is already defined!`);
+		return;
+	}
+	if (!tagName.includes("-")) throw new Error("createCustomElement: tagName must contain at least one hyphen (\"-\").");
+	let extendClass = HTMLElement;
+	if (extend) extendClass = document.createElement(extend).constructor;
+	const pascalCaseName = kebabToPascal(tagName);
+	if (!(DefinitionClass.prototype instanceof McBase)) {
+		customElements.define(tagName, DefinitionClass);
+		return DefinitionClass;
+	}
+	const McElementClass = createNamedClass(pascalCaseName, class extends Base(extendClass) {
+		constructor(data) {
+			super();
+			DC.add(this, pascalCaseName, new DefinitionClass(this, data));
+		}
+		connectedCallback() {
+			this.dispatchEvent(new CustomEvent("_mcConnected"));
+		}
+		connectedMoveCallback() {
+			this.dispatchEvent(new CustomEvent("_mcConnectedMove"));
+		}
+		disconnectedCallback() {
+			this.dispatchEvent(new CustomEvent("_mcDisconnected"));
+		}
+		adoptedCallback() {
+			this.dispatchEvent(new CustomEvent("_mcAdopted"));
+		}
+		attributeChangedCallback(name, oldValue, newValue) {
+			this.dispatchEvent(new CustomEvent("_mcAttributeChanged", { detail: {
+				name,
+				oldValue,
+				newValue
+			} }));
+		}
+		formResetCallback() {
+			this.dispatchEvent(new CustomEvent("_mcFormReset"));
+		}
+		static get observedAttributes() {
+			return [...observedAttributes];
+		}
+	});
+	customElements.define(tagName, McElementClass, { extends: extend });
+	if (!defineCE.list) defineCE.list = [];
+	defineCE.list.push(tagName);
+	return McElementClass;
+}
+function getCE(tagName) {
+	return customElements.get(tagName);
+}
+/**
+Returns an array of all tag names registered via {@link defineCE}.
+
+@example
+```ts
+defineCE('my-element', MyElement);
+defineCE('another-widget', AnotherWidget);
+console.log(listCE());
+```
+@group Elements
+*/
+function listCE() {
+	return defineCE.list ?? [];
+}
+//#endregion
+//#region src/state/placeholders.ts
+/**
+@hidden
+DOM placeholder binding: `{name}` templates in attributes and text nodes,
+kept up to date from observable data.
+
+Split from observables.ts so the pure observable machinery carries no DOM
+scanning/decoration code. The two modules reference each other only inside
+function bodies (`Placeholders` calls `observe(this)`; `bind()` calls
+{@link makePlaceholders}), never during module evaluation, so the circular
+import is benign under ESM live bindings.
+*/
+/**
+Extracts placeholder names from an HTML element's attributes and text content.
+
+Placeholders are strings enclosed in curly braces `{}`. This function scans
+all attributes and direct child text nodes of the target element for placeholders
+and returns them as an array of unique names (without braces).
+
+@param target - The HTMLElement to scan for placeholders.
+@returns An array of placeholder names found within the element's attributes and text content.
+*/
+function getPlaceholders(target) {
+	const placeholders = /* @__PURE__ */ new Set(), regEx = /\{[^\{\}]*\}/g;
+	(target.getAttributeNames ? target.getAttributeNames() : []).filter((attr) => target.getAttribute(attr)?.match(regEx)).forEach((attr) => {
+		new Set(target.getAttribute(attr)?.match(regEx)).forEach((attrPlaceholder) => placeholders.add(attrPlaceholder.replace(/[\{\}]/g, "")));
+	});
+	[...target.childNodes].filter((childNode) => {
+		return childNode.nodeType === 3 && (childNode.nodeValue || "").match(regEx);
+	}).forEach((childNode) => {
+		(childNode?.nodeValue || "").match(regEx).forEach((textNodePlaceholder) => placeholders.add(textNodePlaceholder.replace(/[\{\}]/g, "")));
+	});
+	return [...placeholders];
+}
+var inputTags = [
+	"INPUT",
+	"SELECT",
+	"TEXTAREA"
+];
+/**
+A class that manages placeholders within an HTML element and updates them dynamically.
+
+This class extends `DC` (Data Controller) and processes the target element to identify
+placeholder patterns in attributes and text nodes. It then observes changes on its internal
+data object and updates the corresponding DOM locations when notified of changes.
+*/
+var Placeholders = class extends DC {
+	data = {};
+	oldDisplay = "";
+	/**
+	Creates a new `Placeholders` instance for the given HTML element.
+	
+	Initializes the internal data with empty strings for each placeholder
+	found in the target and starts observing the data object. Attaches
+	callbacks to update placeholders as needed.
+	
+	@param target - The HTMLElement to process for placeholders.
+	*/
+	constructor(target) {
+		super(target);
+		getPlaceholders(target).forEach((property) => this.data[property] = "");
+		observe(this);
+		this.#attachCallbacks();
+	}
+	#attachCallbacks() {
+		const target = this.target;
+		let hide = false;
+		(target.getAttributeNames ? target.getAttributeNames() : []).filter((attr) => target.getAttribute(attr)?.match(/\{[^\{\}]*\}/g)).forEach((attr) => {
+			const placeholders = new Set(target.getAttribute(attr)?.match(/\{[^\{\}]*\}/g));
+			/* v8 ignore next -- attr passed the filter above, so its value is a non-null string */
+			const attrTemplate = target.getAttribute(attr) ?? "";
+			this.data.subscribe(((template) => (data) => {
+				let result = template;
+				placeholders.forEach((placeholder) => {
+					result = result.replace(placeholder, String(data[placeholder.replace(/[\{\}]/g, "")]));
+				});
+				target.setAttribute(attr, result);
+			})(attrTemplate));
+		});
+		[...target.childNodes].filter((childNode) => {
+			return childNode.nodeType === 3 && (childNode.nodeValue || "").match(/\{[^\{\}]*\}/g);
+		}).forEach((childNode) => {
+			hide = true;
+			/* v8 ignore next -- the filter above only admits text nodes with a non-empty
+			nodeValue, so the ?? fallback is unreachable */
+			const textTemplate = childNode.nodeValue ?? "";
+			const placeholders = new Set(textTemplate.match(/\{[^\{\}]*\}/g));
+			this.data.subscribe(((template) => (data) => {
+				let result = template;
+				placeholders.forEach((placeholder) => {
+					result = result.replace(placeholder, String(data[placeholder.replace(/[\{\}]/g, "")]));
+				});
+				if (this.oldDisplay) target.style = this.oldDisplay;
+				else target.removeAttribute("style");
+				delete this.oldDisplay;
+				childNode.nodeValue = result;
+			})(textTemplate));
+			this.oldDisplay = target.getAttribute("style") || "";
+			if (hide && !inputTags.includes(target.tagName) && target.tagName !== "FIELDSET") target.style.display = "none";
+		});
+	}
+	/**
+	Handles a `data` custom event to update the internal placeholder data.
+	
+	Extracts matching keys from the event's detail data and updates only those
+	properties in the internal `data` object that were previously defined as placeholders.
+	
+	@param ev - The CustomEvent containing new data to merge into the placeholders.
+	*/
+	onData(ev) {
+		const data = {};
+		Object.keys(ev.detail.data).forEach((key) => {
+			if (this.data.hasOwnProperty(key)) data[key] = ev.detail.data[key];
+		});
+		if (JSON.stringify(data) !== JSON.stringify(this.data)) Object.assign(this.data, data);
+	}
+};
+/**
+Finds all elements within a given scope that contain placeholders.
+
+@param target - The HTMLElement, DocumentFragment, or ShadowRoot to search.
+@returns An array of HTMLElements containing placeholder patterns.
+*/
+function getPlaceholderElements(target) {
+	return [target].concat([...target.querySelectorAll("*")]).filter((e) => !!getPlaceholders(e).length).filter((e) => e?.tagName !== "STYLE").reverse();
+}
+/**
+Applies placeholder support to an element and its descendants.
+
+This function scans the provided target for elements containing placeholders
+and attaches a `Placeholders` controller instance to each one if not already present.
+
+@param element - The HTMLElement, DocumentFragment, or ShadowRoot to process.
+*/
+function makePlaceholders(element) {
+	getPlaceholderElements(element).forEach((e) => {
+		if (e?._mc?._placeholders) return;
+		DC.add(e, "_placeholders", new Placeholders(e));
+	});
+}
+//#endregion
+//#region src/state/observables.ts
+/**
+Reactive data binding via observables — object properties trigger callbacks and update
+DOM placeholders automatically when their values change. Supports primitives, nested objects,
+and deep-change detection with debounced notifications.
+
+@module Observables
+
+Two APIs are provided for different contexts:
+
+- **`observe()`** — standalone function for general usage outside the MC ecosystem.
+Call it on any plain object to make its properties observable. You manage the resulting
+data object yourself (subscribe, bind, notify).
+
+- **`observePlugin()`** — used inside MC custom elements (classes extending `DC`).
+It attaches `.notify()`, `.subscribe()`, and `.bind()` as chainable instance methods
+that implicitly create the observable wrapper for you. Just declare a plain data property
+on your component and call `this.subscribe('data', …)` — the observable is generated on demand.
+
+> **Note:** `.bind()` only works with objects because their properties become the placeholder
+> names in HTML (e.g., `{name}`, `{count}`). Binding primitives to the DOM is silently ignored.
+
+@example Plugin — inside an MC custom element (recommended within DC classes)
+```ts
+import { DC, defineCE, observePlugin } from '@twobirds/microcomponents';
+
+observePlugin(DC);
+
+class Counter extends DC {
+data = { clicks: 1 };
+
+oneAssets() {
+this
+.subscribe('data', (v) => console.log('data →', v))
+.bind('data', this.target);
+}
+}
+
+defineCE('mc-counter', Counter);
+```
+
+@example Standalone — outside the MC ecosystem (plain objects, vanilla JS, etc.)
+```ts
+import { observe } from '@twobirds/microcomponents';
+
+const state = observe({ count: 0, label: 'hi' });
+state.count.subscribe((v) => console.log('count is now', v));
+state.count++;
+```
+
+Incrementing `state.count` triggers the subscribed callback.
+
+@example Deep change detection on a nested property
+```ts
+import { observe } from '@twobirds/microcomponents';
+
+const state = observe({ data: { name: 'John', age: 30 } });
+state.data.subscribe((d) => console.log('data changed:', d));
+state.data.name = 'Jane';
+```
+
+Writing into a nested property triggers the callback with the updated object.
+
+@example DOM binding — only observable properties that hold objects can be bound
+```ts
+import { observe } from '@twobirds/microcomponents';
+
+const state = observe({ user: { name: 'Alice', count: 0 } });
+state.user.bind(document.querySelector('.model'));
+```
+
+Inside the bound model, `<span>{name}</span>` and `<span>{count}</span>` update
+automatically on every change.
+
+*/
+/**
+@hidden
+Determines if a value is an observable object.
+
+@param value - The value to check.
+@returns `true` if the value is a non-null object, otherwise `false`.
+*/
+function isObservableObject(value) {
+	return value != null && typeof value === "object";
+}
+var classRepo = {};
+/**
+@hidden
+Creates a new observable wrapper class for the given value's constructor.
+
+Returns a subclass of the original constructor that implements the Observable interface,
+allowing observation and notification of changes. The new class is cached in `classRepo`.
+
+@param val - The value whose constructor should be wrapped with observable behavior.
+@returns A new Observable class that wraps the original constructor.
+*/
+function makeObservable(val) {
+	const Constructor = val.constructor, ConstructorName = Constructor.name;
+	const ObservableClass = class extends Constructor {
+		#notify = true;
+		#callbacks = [];
+		constructor(valArg) {
+			super(valArg);
+			const ctor = this.constructor;
+			ctor.callbacks = [];
+			if (isObservableObject(valArg)) Object.getOwnPropertyNames(valArg).forEach((key) => {
+				this[key] = valArg[key];
+			});
+		}
+		get callbacks() {
+			return this.#callbacks;
+		}
+		set callbacks(callbacks) {
+			this.#callbacks = callbacks;
+		}
+		/**
+		Coerces the observable to its underlying primitive value when used in
+		arithmetic, string interpolation, or other contexts requiring a primitive.
+		
+		This allows `observable + 1` or `` `${observable}` `` to work naturally
+		while still exposing `.subscribe()`, `.notify()`, etc. as methods on the object.
+		
+		@param hint - The coercion context: 'number', 'string', or 'default'.
+		@returns The underlying primitive value coerced to the requested type.
+		
+		@example
+		```ts
+		const state = observe({ count: 42 });
+		console.log(state.count + 10);
+		console.log(`${state.count}`);
+		state.count.subscribe((v) => console.log('changed to', v));
+		```
+		
+		Arithmetic coerces with `hint === 'number'` (logs `52`), interpolation with
+		`hint === 'string'` (logs `"42"`), and `.subscribe()` stays callable on the
+		wrapper.
+		*/
+		[Symbol.toPrimitive](hint) {
+			const value = this.valueOf();
+			if (hint === "string") return String(value);
+			if (hint === "number") return Number(value);
+			return value;
+		}
+		/**
+		Registers a callback function to be invoked when the observable object is notified.
+		
+		@param callback - The function to invoke on notification.
+		@returns This instance for chaining.
+		
+		@example
+		```ts
+		const state = observe({ count: 0 });
+		state.count.subscribe((v) => console.log('count changed to', v));
+		state.count++;
+		```
+		
+		The increment fires the callback, logging `count changed to 1`.
+		*/
+		subscribe(callback) {
+			this.#callbacks.push(callback);
+			return this;
+		}
+		/**
+		Removes a previously registered callback so it no longer fires on notify.
+		
+		Detaching by the same function reference that was passed to `subscribe()` —
+		unknown callbacks are a silent no-op. Long-lived subscribers should call
+		this when they are done to avoid leaking callbacks.
+		
+		@param callback - The exact callback reference to remove.
+		@returns This instance for chaining.
+		
+		@example
+		```ts
+		const state = observe({ count: 0 });
+		const log = (v) => console.log(v);
+		state.count.subscribe(log);
+		state.count.unsubscribe(log);
+		```
+		
+		After `unsubscribe(log)`, the callback no longer fires on changes.
+		*/
+		unsubscribe(callback) {
+			this.#callbacks = this.#callbacks.filter((registered) => registered !== callback);
+			return this;
+		}
+		/**
+		Binds the observable to a DOM target, setting up placeholder updates and
+		triggering initial callbacks.
+		
+		Scans the target and its descendants for placeholders and registers handlers
+		to update them with flattened data on notification. Only works in browser environments.
+		
+		@param target - The HTMLElement, DocumentFragment, or ShadowRoot to bind.
+		@returns This instance for chaining.
+		
+		@example
+		```ts
+		const state = observe({ user: { name: 'Alice', count: 0 } });
+		state.user.bind(document.querySelector('.model'));
+		```
+		
+		Only object-valued observables can be bound: inside the model, `{name}` and
+		`{count}` placeholders update on every change.
+		*/
+		bind(target) {
+			if (!isBrowser()) return;
+			if (isObservableObject(this.valueOf())) {
+				makePlaceholders(target);
+				const placeholders = [target, ...target.querySelectorAll("[data-mc]")].filter((e) => {
+					return !!e?._mc?._placeholders;
+				});
+				this.#callbacks.push(function callback(data) {
+					const flattenedData = flattenObject(data);
+					placeholders.forEach((node) => {
+						/* v8 ignore next */
+						if (!node) return;
+						trigger(node, "data", flattenedData);
+					});
+				});
+				this.notify();
+			} else console.warn("IGNORED - cannot bind a non-Object to the dom, IS:", typeof this.valueOf(), this);
+			return this;
+		}
+		/**
+		Notifies registered callbacks with the current observable data.
+		
+		Clones the internal value (if it's an object and not an array) before passing
+		to callbacks. Respects the internal `#notify` flag that can suppress notifications.
+		
+		@param notify - Optional boolean override for the notification state.
+		@returns This instance for chaining.
+		
+		@example
+		```ts
+		const state = observe({ count: 0 });
+		state.count.subscribe((v) => console.log('notified:', v));
+		state.count.notify();
+		```
+		
+		The manual `notify()` call pushes the current value to subscribers, logging
+		`notified: 0`.
+		*/
+		notify(notify) {
+			const data = isObservableObject(this.valueOf()) && this.valueOf() instanceof Array === false ? structuredClone(Object.assign({}, this)) : this.valueOf();
+			if (notify !== void 0) this.#notify = notify;
+			if (this.#notify) this.#callbacks.forEach((f) => {
+				f(data);
+			});
+			return this;
+		}
+	};
+	classRepo[ConstructorName] = ObservableClass;
+	return ObservableClass;
+}
+/**
+Retrieves or creates an observable wrapper class for the given value.
+
+@param val - The value whose constructor should be wrapped with observable behavior.
+@returns A class that wraps the original constructor and implements observable functionality.
+*/
+function getConstructor(val) {
+	return classRepo[val.constructor.name] || makeObservable(val);
+}
+/**
+@hidden
+Whether a value is already an observable wrapper — `subscribe` is reachable on its prototype chain.
+Used by {@link observe} to skip re-wrapping and to detect the "not yet observed" state on reassignment.
+
+@example
+```ts
+const state = observe({ count: 0 });
+console.log(isAlreadyObserved(state.count));
+console.log(isAlreadyObserved(42));
+```
+
+The wrapped property reports `true`, a plain primitive reports `false`.
+*/
+function isAlreadyObserved(value) {
+	return (typeof value === "object" || typeof value === "function") && value !== null && "subscribe" in value;
+}
+/**
+@hidden
+Makes a target object's properties observable by replacing them with wrapped values.
+
+Wraps each property of `target` that is not already observable (and meets criteria)
+in an observable wrapper. Also sets up deep change detection for objects and
+debounced notifications when the data changes.
+
+There are two sides to using it — pick per call site:
+
+**Declarative (typed class fields).** Declare the field as `Observable<T>` up
+front, then let `observe(this, 'field')` install the live wrapper in the
+constructor. The declaration needs the double cast once (`0 as unknown as
+Observable<number>`): the field starts life as a plain value and only becomes
+the wrapper when `observe()` runs. In exchange, every later use is fully typed —
+arithmetic, `subscribe`, `bind` — with no casts anywhere else.
+
+**Imperative (wrapping existing data).** Hand any object to `observe()` after
+the fact — no declarations, the return type is inferred: every property comes
+back as `Observable<PropertyType>`.
+
+@param target - The object whose properties should be made observable.
+@param propertyName - Optional specific property name to make one property observable instead of all properties.
+@returns The original target object, now with observable properties.
+
+@example Imperative usage — wrap an existing plain object:
+```ts
+const state = observe({ count: 0, label: 'hi' });
+state.count.subscribe((v) => console.log('count is now', v));
+state.count++;
+```
+
+Incrementing `state.count` triggers the subscribed callback.
+
+@example Declarative usage — typed class field with double cast:
+```ts
+class Counter {
+clicks: Observable<number> = 0 as unknown as Observable<number>;
+
+constructor() {
+observe(this, 'clicks');
+}
+
+bump() {
+this.clicks++;
+}
+}
+```
+
+Plain arithmetic compiles because the declaration carries the observable type.
+
+@example Schema-first usage — divergent read/write types via hand-declared interface:
+```ts
+interface CounterState {
+get count(): Observable<number>;
+set count(v: number);
+}
+
+const state = observe<CounterState>({ count: 0 });
+state.count.subscribe((v) => console.log(v));
+state.count = 5;
+```
+
+The seed object is validated against the schema, the subscription callback is fully
+typed, and plain assignment is legal because the declared setter type permits it.
+*/
+function observe(target, propertyName) {
+	const source = target;
+	(propertyName ? [propertyName] : [...Object.getOwnPropertyNames(target)]).forEach((key) => {
+		const current = source[key];
+		if (Object.prototype.hasOwnProperty.call(target, key) && typeof current !== "function" && !isAlreadyObserved(current)) {
+			if (key[0] === "_" || current === void 0) return;
+			const wrappedVal = current;
+			let o = new (getConstructor(wrappedVal))(wrappedVal);
+			const debouncedNotify = function() {
+				queueMicrotask(function() {
+					o.notify();
+				});
+			};
+			Object.defineProperty(target, key, {
+				enumerable: true,
+				get() {
+					if (isObservableObject(o.valueOf())) {
+						const snapshot = structuredClone(Object.assign({}, o));
+						queueMicrotask(function checkChanges() {
+							if (!deepEqual(structuredClone(Object.assign({}, o)), snapshot)) debouncedNotify();
+						});
+					}
+					return o;
+				},
+				set(val) {
+					if (typeof val === typeof o.valueOf()) if (isObservableObject(o.valueOf()) && o.valueOf() instanceof Array === false) {
+						/* v8 ignore next */
+						if (!isAlreadyObserved(o)) {
+							/* v8 ignore next */
+							o = new (getConstructor(val))(structuredClone(Object.assign({}, val)));
+							/* v8 ignore next */
+							copyGettersSetters(val, o);
+						}
+						Object.assign(o, val);
+						o.notify();
+					} else {
+						const old = o.valueOf(), callbacks = o.callbacks;
+						if (val !== old) {
+							o = new (getConstructor(val))(val);
+							o.callbacks = callbacks;
+							debouncedNotify();
+						}
+					}
+					else console.warn("IGNORED - cannot change observable types, IS:", typeof o.valueOf(), o, "- CANNOT BECOME:", typeof val);
+				}
+			});
+			source[key] = wrappedVal;
+		}
+	});
+	return target;
+}
+/**
+Attaches convenience methods `notify()`, `subscribe()`, and `bind()` to the prototype of a
+microcomponent class so that observable properties can be controlled directly on the instance.
+
+All three methods return the component instance, so you can chain them fluently.
+
+Call it once at module level before defining any component classes. The plugin is idempotent —
+subsequent calls are no-ops.
+
+@param Class - A constructor function whose prototype chain includes {@link Core.McBase}.
+
+@example
+```ts
+class Counter extends DC {
+data = { clicks: 1 };
+
+oneAssets() {
+this
+.subscribe('data', (v) => console.log('data →', v))
+.bind('data', this.target);
+}
+}
+```
+*/
+function observePlugin(Class) {
+	const McBaseProto = Object.getPrototypeOf(Class.prototype);
+	function makePropObservable(obj, propName) {
+		const obs = obj[propName];
+		if (!isAlreadyObserved(obs)) observe(obj, propName);
+	}
+	if (!Object.hasOwn(McBaseProto, "notify")) Object.assign(McBaseProto, {
+		/**
+		* Manually trigger a notification on an observable property.
+		* Ensures the property is observed first if it hasn't been yet.
+		* @param propName - The name of the observable property to notify.
+		* @returns This instance for chaining.
+		
+		@example
+		```ts
+		this.notify('count');
+		```
+		*/
+		notify: function(propName) {
+			makePropObservable(this, propName);
+			this[propName].notify();
+			return this;
+		},
+		/**
+		* Subscribe a callback to changes on an observable property.
+		* Ensures the property is observed first if it hasn't been yet.
+		* @param propName - The name of the observable property.
+		* @param callback - Function invoked with the new value on every change.
+		* @returns This instance for chaining.
+		
+		@example
+		```ts
+		this.subscribe('count', (v) => console.log('count →', v));
+		```
+		*/
+		subscribe: function(propName, callback) {
+			makePropObservable(this, propName);
+			this[propName].subscribe(callback);
+			return this;
+		},
+		/**
+		* Bind an observable property to a DOM target so that `{placeholder}` tokens are updated live.
+		* Ensures the property is observed first if it hasn't been yet.
+		* @param propName - The name of the observable property.
+		* @param target - HTMLElement, ShadowRoot, or DocumentFragment containing placeholders.
+		* @returns This instance for chaining.
+		
+		@example
+		```ts
+		this.bind('data', this.target);
+		```
+		*/
+		bind: function(propName, target) {
+			makePropObservable(this, propName);
+			this[propName].bind(target);
+			return this;
+		}
+	});
+}
+//#endregion
+//#region src/state/formValues.ts
+/**
+Two-way binding between DOM form controls (`input`, `select`, `textarea`) and an observable
+object property. Reads reflect live DOM values; writes update the controls synchronously.
+
+@module Form Values
+
+Two APIs are provided for different contexts:
+
+- **`formValues()`** — standalone function for general usage outside the MC ecosystem.
+Call it on any plain object to bind form controls to a new observable property. You manage
+subscriptions and bindings manually on the resulting data object.
+
+- **`formValuePlugin()`** — used inside MC custom elements (classes extending `DC`).
+It attaches `.formValues()` as a chainable instance method that implicitly creates both the
+form-values binding and the underlying observable wrapper. Just call
+`this.formValues(this.target, 'formData')` and chain `.subscribe()` / `.bind()` — everything
+is set up for you automatically.
+
+@example Plugin — inside an MC custom element (recommended within DC classes)
+```ts
+import { DC, defineCE, formValuePlugin } from '@twobirds/microcomponents';
+
+formValuePlugin(DC);
+
+class CheckoutForm extends DC {
+static assets = ['targetHtml'];
+
+oneAssets() {
+this
+.formValues(this.target, 'formData')
+.subscribe('formData', (data) => console.log(data))
+.bind('formData', this.target);
+}
+}
+
+defineCE('checkout-form', CheckoutForm);
+```
+
+@example Standalone — outside the MC ecosystem (plain objects, vanilla JS, etc.)
+```ts
+import { formValues } from '@twobirds/microcomponents/formValues';
+
+const state = {};
+formValues(state, 'formData', document.getElementById('myForm'));
+console.log(state.formData.username);
+state.formData.role = 'admin';
+```
+
+Reading `state.formData.username` reflects the live `<input name="username">` value;
+assigning `state.formData.role` writes straight back to the `<select>` control.
+*/
+observePlugin(DC);
+/**
+Extracts the lowercase tag name of an element (e.g., 'input', 'select', 'textarea').
+@param inputElement - The HTML element to extract the tag name from.
+@returns The lowercase tag name string.
+*/
+var getInputName = (inputElement) => {
+	return inputElement.tagName.toLowerCase();
+};
+/**
+Abstract base class for form input value handlers.
+Defines the interface that all handler classes must implement.
+*/
+var InputBase = class {
+	/**
+	Creates a new InputBase instance.
+	@param e - The HTML element being handled (input, select, or textarea).
+	*/
+	constructor(e) {}
+};
+/**
+Handler class specifically for radio button groups.
+Provides synchronized access to the selected value in a group of related radio buttons.
+*/
+var RadioHandler = class extends InputBase {
+	#e;
+	/**
+	Creates a new RadioHandler instance.
+	@param e - The first radio button element in the group (used to determine name and form scope).
+	*/
+	constructor(e) {
+		super(e);
+		this.#e = e;
+	}
+	/**
+	Gets the currently selected value of the radio button group using FormData API.
+	@returns The string value of the selected radio button, or null if none is selected.
+	*/
+	get val() {
+		if (!this.#e.form) return null;
+		return new FormData(this.#e.form).get(this.#e.name) ?? null;
+	}
+	/**
+	Sets the selected radio button by value.
+	Finds and checks the first radio input matching the specified value within the same group.
+	@param value - The value to match against radio inputs in this group.
+	*/
+	set val(value) {
+		/* v8 ignore next */
+		const arr = [...this.#e.form?.querySelectorAll(`input[type="radio"][name="${this.#e.name}"]`) ?? []];
+		arr.filter((e) => e.getAttribute("value") === value).shift().checked = true;
+	}
+};
+/**
+* Handler class for checkbhox inputs.
+* Provides synchronized get/set access to the checked state of a single checkbox.
+*/
+var CheckboxHandler = class extends InputBase {
+	#e;
+	/**
+	Creates a new CheckboxHandler instance.
+	@param e - The checkbox element to handle.
+	*/
+	constructor(e) {
+		super(e);
+		this.#e = e;
+	}
+	/**
+	Gets the checked state of the checkbox.
+	@returns True if the checkbox is checked, false otherwise.
+	*/
+	get val() {
+		return this.#e.checked;
+	}
+	/**
+	Sets the checked state of the checkbox.
+	@param value - The boolean value to assign as the new checked state.
+	*/
+	set val(value) {
+		this.#e.checked = value;
+	}
+};
+/**
+Handler class for standard single-line input fields (text, password, email, etc.).
+Provides synchronized get/set access to the value of an input field.
+*/
+var InputHandler = class extends InputBase {
+	#e;
+	/**
+	* Creates a new InputHandler instance.
+	* @param e - The HTML input element to handle.
+	*/
+	constructor(e) {
+		super(e);
+		this.#e = e;
+	}
+	/**
+	* Gets the current value of the input field.
+	* @returns The string content of the input element.
+	*/
+	get val() {
+		return this.#e.value;
+	}
+	/**
+	* Sets the value of the input field.
+	* @param value - The new string value for the input element.
+	*/
+	set val(value) {
+		this.#e.value = value;
+	}
+};
+/**
+Handler class for select dropdown elements, supporting both single and multiple selection modes.
+Provides synchronized get/set access to selected option values.
+*/
+var SelectHandler = class extends InputBase {
+	#e;
+	#multi = false;
+	/**
+	* Creates a new SelectHandler instance.
+	* @param e - The select element to handle.
+	*/
+	constructor(e) {
+		super(e);
+		this.#e = e;
+		this.#multi = e.multiple;
+	}
+	/**
+	* Gets the currently selected option value(s).
+	* For single selection, returns a string. For multiple selection, returns an json.stringify()'ied array of strings.
+	* @returns A string or JSON.stringify array of strings representing selected values.
+	*/
+	get val() {
+		const ret = [];
+		[...this.#e.querySelectorAll("option")].filter((o) => o.selected).forEach((o) => {
+			ret.push(o.value);
+		});
+		return this.#multi ? ret : ret[0];
+	}
+	/**
+	* Sets the selected option(s) by value.
+	* @param value - A string or array of strings representing values to select.
+	*/
+	set val(value) {
+		value = typeof value === "string" ? [value] : value;
+		[...this.#e.querySelectorAll("option")].forEach((o) => {
+			if (value.indexOf(o.value) > -1) o.selected = true;
+			else o.selected = false;
+		});
+	}
+};
+/**
+Handler class for textarea elements.
+Provides synchronized get/set access to the multi-line text content of a textarea.
+*/
+var TextAreaHandler = class extends InputBase {
+	#e;
+	/**
+	* Creates a new TextAreaHandler instance.
+	* @param e - The textarea element to handle.
+	*/
+	constructor(e) {
+		super(e);
+		this.#e = e;
+	}
+	/**
+	* Gets the current value of the textarea (defaults to empty string if null/undefined).
+	* @returns The string content of the textarea element.
+	*/
+	get val() {
+		return this.#e.value || "";
+	}
+	/**
+	* Sets the value of the textarea.
+	* @param value - The new string value for the textarea element.
+	*/
+	set val(value) {
+		this.#e.value = value;
+	}
+};
+/**
+Collects all form controls within a given DOM scope and creates handler objects
+that provide synchronized get/set access to their values.
+
+@param e - Optional root DOM element or shadow root to search within; defaults to document if omitted.
+@returns An object where each key is the name attribute of an input, select, or textarea,
+and each value is a proxy-like accessor object with `val` getter/setter methods.
+*/
+var getInputHandlers = (e) => {
+	const inputList = [...(e || document).querySelectorAll("input,select,textarea")], handlers = {};
+	inputList.forEach((input) => {
+		const name = input.getAttribute("name");
+		if (name) {
+			let handler = false;
+			switch (getInputName(input)) {
+				case "input":
+					switch (input.type) {
+						case "radio":
+							handler = new RadioHandler(input);
+							break;
+						case "checkbox":
+							handler = new CheckboxHandler(input);
+							break;
+						default: handler = new InputHandler(input);
+					}
+					break;
+				case "select":
+					handler = new SelectHandler(input);
+					break;
+				case "textarea":
+					handler = new TextAreaHandler(input);
+					break;
+			}
+			/* v8 ignore next */
+			if (handler) {
+				const h = handler;
+				DC.add(input, name, h);
+				Object.defineProperty(handlers, name, {
+					enumerable: true,
+					configurable: true,
+					get: () => h.val,
+					set: (value) => {
+						if (h.val !== value) h.val = value;
+					}
+				});
+			}
+		}
+	});
+	return handlers;
+};
+/**
+@hidden
+
+Attaches a form-values observable to a target object property, enabling two-way binding
+between DOM form controls and the object's state.
+
+Scans the given DOM subtree for `input`, `select`, and `textarea` elements with a `name`
+attribute and creates live getters/setters on the resulting observable. Input events trigger
+automatic notifications so subscribers react to user changes.
+
+@param targetObject - The object that will receive the form-data property.
+@param propertyName - The property name under which the bound form data is stored.
+@param dom - HTMLElement or ShadowRoot containing the form controls.
+
+@example Bind a plain object to an HTML form element
+```ts
+import { formValues } from '@twobirds/microcomponents/formValues';
+
+const state = {};
+formValues(state, 'formData', document.getElementById('myForm'));
+console.log(state.formData.username);
+state.formData.role = 'admin';
+```
+
+Reading `state.formData.username` reflects the live `<input name="username">` value;
+assigning `state.formData.role` writes straight back to the `<select>` control.
+
+@example Subscribe to form changes inside a component
+```ts
+import { DC, defineCE, formValues } from '@twobirds/microcomponents';
+
+class MyForm extends DC {
+static assets = ['targetHtml'];
+
+oneAssets() {
+formValues(this, 'formData', this.target);
+this.formData.subscribe((data) => console.log('form changed:', data));
+}
+}
+
+defineCE('my-form', MyForm);
+```
+*/
+function formValues(targetObject, propertyName, dom) {
+	/* v8 ignore next */
+	if (!isBrowser()) return;
+	const handlers = getInputHandlers(dom);
+	const source = targetObject;
+	source[propertyName] = Object.assign({}, handlers);
+	observe(targetObject, propertyName);
+	const observable = source[propertyName];
+	copyGettersSetters(handlers, observable);
+	[...dom.querySelectorAll("input, textarea, select")].forEach((input) => {
+		input.addEventListener("input", () => {
+			observable.notify();
+		});
+	});
+}
+/**
+Attaches a convenience method `formValues()` to the prototype of a microcomponent class so that
+form controls can be bound directly on the instance without importing the standalone function.
+
+This plugin also pulls in all observable methods from {@link observePlugin} — `notify()`,
+`subscribe()`, and `bind()` — so you can chain them fluently after binding form data.
+
+Call it once at module level before defining any component classes. The plugin is idempotent —
+subsequent calls are no-ops.
+
+@param Class - A constructor function whose prototype chain includes {@link Core.McBase}.
+
+@example
+```ts
+import { DC, defineCE, formValuePlugin } from '@twobirds/microcomponents';
+
+formValuePlugin(DC);
+
+class CheckoutForm extends DC {
+static assets = ['targetHtml'];
+
+oneAssets() {
+this
+.formValues(this.target, 'formData')
+.subscribe('formData', (data) => console.log(data))
+.bind('formData', this.target);
+}
+}
+
+defineCE('checkout-form', CheckoutForm);
+```
+*/
+function formValuePlugin(Class) {
+	const McBaseProto = Object.getPrototypeOf(Class.prototype);
+	if (!Object.hasOwn(McBaseProto, "formValues")) Object.assign(McBaseProto, { 
+	/**
+	* Bind all named form controls inside a DOM subtree to an observable property on this instance.
+	* Ensures the property becomes observable and stays in sync with input changes.
+	* @param target - HTMLElement or ShadowRoot containing the form controls.
+	* @param propName - The name of the property that will hold the bound form data.
+	* @returns This instance for chaining.
+	
+	@example
+	```ts
+	this.formValues(this.target, 'formData');
+	```
+	
+	After this call, `this.formData.username` reflects the live `<input name="username">` value.
+	*/
+formValues: function(target, propName) {
+		formValues(this, propName, target);
+		return this;
+	} });
+}
+//#endregion
+export { BubbleController, DC, MC, McBase, autoload, bindTemplateEvents, copyGettersSetters, debounce, deepEqual, defineCE, flattenObject, formValuePlugin, formValues, getCE, getMcEventName, htmlToElements, injectCSS, isAlreadyObserved, isBrowser, isMcHost, isNativeObject, kebabToPascal, listCE, loadAssets, nameSpace, observe, observePlugin, off, on, one, parse, processAssets, sortObject, trigger, trueEventName };