@twobirds/microcomponents 0.10.3 → 0.12.1

package/dist/state/placeholders.js

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