@twobirds/microcomponents 0.2.2 → 0.2.4

package/dist/core/MC.d.ts

@@ -1,219 +1,319 @@
+import { BubbleController } from '../utils/events.js';
+import type { BubbleDirections, McController, McEntriesOf, McEventHandler, McHost, McHostOf, McMerged, McPayloadOf, McRemoved } from '../types/mcTypes.js';
+export type { McBubbleController, McController, McDetail, McEntriesOf, McEvent, McEventHandler, McHost, McHostOf, McMerged, McNativeEventHandlers, McPayloadOf, McRemoved, } from '../types/mcTypes.js';
+export { isMcHost } from './mcGuards.js';
 /**
-@module
-## Overview
+The base class for all microcomponents — shared root of both {@link MC} and {@link DC}.
 
-MicroComponents (MC) is a lightweight pattern for creating self-contained, event-driven, and composable UI components. It provides two core base classes: {@link MC} and {@link DC}, which differ primarily in their target attachment strategy and runtime environment requirements.
+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:
 
-In general, your code extends from either of these classes depending on whether you need DOM interaction or pure logic encapsulation.
+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.
 
-## MC vs DC: Server vs Client
+### Plugin extension points
 
-The key distinction between the two base classes is their execution context:
+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:
 
-- **MC (MicroComponent)** – A general-purpose component that works in **any JavaScript environment**, including server-side runtimes (Node.js, Deno, etc.). It does not require a DOM and can be used for business logic, state management, or as a lightweight container. The `target` parameter is optional.
+- **{@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.
 
-- **DC (DOM Component)** – A DOM-centric component that operates wherever a real ( browser ) or simulated ( jsdom, etc. ) DOM exists. It attaches itself to an {@link HTMLElement} and provides event handling, DOM traversal, and lifecycle management. The `target` parameter is required and must be an HTMLElement.
+- **{@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.
 
-**HINT:** DCs can be attached to **any** DOM node ( HTMLElement ). That is you can connect them to <div>, <span> and the like. With a trick you can even define custom elements that convert themselves to e.g. a plain <div>.
+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.
 
-### When to use which?
+@template TTarget - The concrete type of the wrapped target; preserved by the
+    {@link McBase.target} getter.
 
-| Scenario | Recommended Class |
-|----------|-------------------|
-| Server-side rendering or logic | MC |
-| Pure data processing without DOM | MC |
-| Interactive UI elements in the browser | DC |
-| Event-driven components attached to HTML nodes | DC |
+@example Extending with plugins at runtime
 
----
-
-## The `target` Property: Backreference Concept
+```ts
+import { DC, observePlugin, formValuePlugin } from '@twobirds/microcomponents';
 
-Both MC and DC store a reference to their **host object** via the internal `_target` property (exposed as the `target` getter). This is a *backreference* — it points back to the object that contains or hosts this component instance.
+observePlugin(DC);       // adds notify(), subscribe(), bind() to McBase.prototype
+formValuePlugin(DC);     // adds formValues() (and re-runs observePlugin)
 
-- For **DC instances**, `this.target` refers to the {@link HTMLElement} in the DOM (or testing DOM such as jsdom) to which the component is attached.
-- For **MC instances**, `this.target` can be any arbitrary object, allowing flexible composition patterns.
+class MyForm extends DC {
+    data = { name: '' };
 
-The reference is held via a `WeakRef` ([MDN WeakRef](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef)) internally to avoid circular references and prevent memory leaks.
+    oneInit() { // runs once after the constructor
+        this
+        .formValues(this.target, 'data')
+        .subscribe('data', (v) => console.log(v))
+        .bind('data', this.target);
+    }
+}
+```
+@group Micro Components
+*/
+declare class McBase<TTarget extends object = object> {
+    private _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: TTarget);
+    /**
+    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(): TTarget;
+}
+/**
+A general-purpose base microcomponent that does not require a DOM target.
 
-## DOM Integration: The `_mc` Property and `data-mc` Attribute
+Inherits from `McBase`, but is primarily used as a lightweight container or
+for logic not directly tied to DOM elements.
 
-When a DC is attached to an element via {@linkcode DC.add}, two things happen:
+@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
+*/
+declare class MC<TTarget extends object = object> extends McBase<TTarget> {
+    /**
+    Constructs an instance of the general-purpose microcomponent.
+    
+    @param target - Target object or data.
+    */
+    constructor(target: TTarget);
+}
+/**
+@class DC
+---
 
-1. The element gains a `_mc` property (of type {@link McHost}) that holds references to all attached microcomponents, keyed by their unique identifiers.
-2. The element receives a `data-mc` attribute, signaling that it hosts at least one microcomponent. This attribute is used internally for DOM queries and selectors.
+A DOM-centric microcomponent that operates on a specific HTML element.
 
-This `_mc` property is the **only** interference with the native DOM structure, ensuring compatibility with other frameworks or libraries.
+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.
 
 ---
 
-## Lifecycle & Automatic Event Handler Attachment
+## Static Configuration Properties
 
-DC instances automatically trigger an `"Init"` lifecycle event asynchronously after construction. Additionally, methods prefixed with `on` or `one` (e.g., `onClick`, `oneUpdate`) are auto-attached as event listeners on the target element, supporting both native HTML events and custom microcomponent events.
+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.
 
-@example Understanding target in DC
+- **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.
 
-javascript:
-```javascript
-import { DC } from '@twobirds/microcomponents';
+@example static tag — replace with semantic element
 
-class MyButton extends DC {
-    constructor(target: HTMLElement) {
-        super(target);
-    }
-
-    logTarget() {
-        // this.target is the <button> element itself
-        console.log(this.target.tagName); // "BUTTON"
-    }
+```ts
+class ShopHeader extends DC {
+    static tag = 'header';
 }
+defineCE('shop-header', ShopHeader);
+```
 
-const btn = document.querySelector('button');
-if (btn) {
-    const host = DC.add(btn, 'myButton', new MyButton(btn));
-    host._mc.myButton.logTarget();
+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);
 ```
 
-@example Understanding target in MC
+The element self-destructs; only side effects (e.g., injected styles) remain.
 
+### `static assets: string[]`
 
-```javascript
-import { MC } from '@twobirds/microcomponents';
+Declares companion files for auto-loading by convention. Asset names are camelCase
+and translated into file extensions: `'targetHtml'` → `.target.html`, `'json'` → `.json`.
 
-class Counter extends MC {
-    private count = 0;
+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.*`.
 
-    constructor(target?: object) {
-        super(target);
-    }
+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.
 
-    increment() {
-        this.count++;
-    }
+@example static assets with autoload
 
-    getCount() {
-        return this.count;
+```ts
+class CartCheckout extends DC {
+    static assets = ['targetHtml', 'targetCss', 'configJson'];
+
+    oneAssets(ev) {
+        const { configJson } = ev.detail.data;
+        console.log(configJson); // parsed JSON object
     }
 }
+defineCE('cart-checkout', CartCheckout);
+```
+
+### `static attributes?: object`
 
-// Works without any DOM — usable on server or client
-const counter = new Counter();
-counter.increment();
-console.log(counter.getCount()); // 1
+Sets HTML attributes on every instance automatically.
+
+@example static attributes
+
+```ts
+class ProductCard extends DC {
+    static attributes = { role: 'listitem' };
+}
+defineCE('product-card', ProductCard);
 ```
 
-@example Usage
+Every `<product-card>` carries `role="listitem"`.
+
+### Combined usage
 
-Below is a complete example demonstrating how to create, attach, and interact with a custom microcomponent:
+All three can be combined in one class:
 
-html before:
-```html
-<div id="container"></div>
+@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);
 ```
 
-javascript:
-```javascript
-import { DC } from '@twobirds/microcomponents';
+Produces `<section role="list" aria-label="products">`.
 
-// 1. Create a custom micro component class extending DC
-class HelloWorld extends DC {
-    constructor(target: HTMLElement) {
-        super(target);
+---
+
+## 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) |
+
+@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');
     }
 
-    greet() {
-        console.log('Hello World');
+    oneSomething(ev) {
+        console.log('first time only:', ev.detail.data);
     }
 }
+defineCE('my-element', MyElement);
+```
 
-// 2. Get an element from the DOM
-const element = document.getElementById('container')!;
+---
 
-// 3. Attach the micro component instance to the target element
-DC.add(element, 'helloWorld', new HelloWorld(element));
+## Construction Patterns
 
-// 4. Invoke methods on the attached component
-element._mc.helloWorld.greet(); // "Hello World"
-```
+### Template usage (declarative)
 
-html after:
-```html
-<div id="container" data-mc></div>
+```ts
+class MyElement extends DC {}
+defineCE('my-element', MyElement);
+// Use in HTML: <my-element></my-element>
 ```
 
-The `data-mc` attribute indicates that this element contains at least one microcomponent. The `_mc` property provides direct programmatic access to the attached instances.
+### 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.
 
-*/
-import { BubbleController } from '../utils/events.js';
-import type { BubbleDirections, McController, McEntriesOf, McEventHandler, McHost, McHostOf, McMerged, McPayloadOf, McRemoved } from '../types/mcTypes.js';
-export type { McBubbleController, McController, McDetail, McEntriesOf, McEvent, McEventHandler, McHost, McHostOf, McMerged, McNativeEventHandlers, McPayloadOf, McRemoved, } from '../types/mcTypes.js';
-export { isMcDOM } from './mcGuards.js';
-/**
-The base class for all microcomponents.
+@example Programmatic construction
 
-Implements a `WeakRef` to the target DOM element or other data, avoiding
-circular references. Automatically triggers the "Init" lifecycle event and
-attaches listeners via `autoAttachListeners` upon construction.
-*/
-declare class McBase<TTarget extends object = object> {
-    private _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: TTarget);
-    /**
-    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.
+```ts
+class MyElement extends DC {
+    data = {};
 
-    @returns The target object.
-    */
-    get target(): TTarget;
+    constructor(target, data) {
+        super(target);
+        this.data = data;
+    }
 }
-/**
-A general-purpose base microcomponent that does not require a DOM target.
+defineCE('my-element', MyElement);
 
-Inherits from `McBase`, but is primarily used as a lightweight container or
-for logic not directly tied to DOM elements.
+const Ctor = getCE('my-element');
+document.body.append(new Ctor({ name: 'John' }));
+```
 
-@template TTarget - The concrete type of the wrapped target data; preserved by
-    the `target` getter, so `new MC({ some: 'data' }).target.some` stays typed.
-*/
-declare class MC<TTarget extends object = object> extends McBase<TTarget> {
-    /**
-    Constructs an instance of the general-purpose microcomponent.
-    
-    @param target - Target object or data.
-    */
-    constructor(target: TTarget);
+### 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'));
+    }
 }
-/**
-A DOM-centric microcomponent that operates on a specific HTML element.
+defineCE('my-element', MyElement);
+// Use in HTML: <my-element my-data='{"name":"John"}'></my-element>
+```
 
-Extends `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.
+---
+
+## 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`).
@@ -221,7 +321,9 @@ and interaction with sibling or ancestor microcomponents.
     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
+
+@example Typed event map
+
 ```ts
 class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {
     checkout() {
@@ -230,25 +332,52 @@ class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {
     }
 }
 ```
+@group Micro Components
 */
 declare class DC<T extends HTMLElement = HTMLElement, EM extends Record<string, unknown> = Record<never, never>> extends McBase<T> implements McController<T> {
+    /**
+     * 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?: string;
+    /**
+     * Result container for assets (e.g., `['targetHtml', 'json']`).
+     * Asset names (keys) are camelCase and translated into file extensions: `'targetHtml'` → `.target.html`.
+     */
+    static _assets: Record<string, any>;
+    /**
+     * 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: string[];
+    /**
+     * Sets HTML attributes on every instance automatically.
+     * Example: `{ role: 'listitem', 'aria-label': 'nav' }`.
+     */
     static attributes?: object;
+    /**
+     * 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: T);
     /**
-    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.
+    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(): Record<string, string | Record<string, any>> | {};
     static add<T extends HTMLElement>(target: T, key: string): McHost<McHostOf<T>, McEntriesOf<T>>;
     /** @param element - The microcomponent instance or config object to attach. When
         omitted, a bare `{}` marker is stored and no typed entry is claimed. */
@@ -288,43 +417,10 @@ declare class DC<T extends HTMLElement = HTMLElement, EM extends Record<string,
     ```
     */
     static get<E extends object>(element: unknown, key: string, elementMcClass: abstract new (...args: never[]) => E): E | undefined;
-    /**
-    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<D = unknown, K extends string = string>(eventName: K, handler: McEventHandler<McPayloadOf<EM, K, D>>): void;
     off(eventName: string, handler: EventListenerOrEventListenerObject): void;
-    /**
-    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<D = unknown, K extends string = string>(eventName: K, handler: McEventHandler<McPayloadOf<EM, K, D>>): McEventHandler<McPayloadOf<EM, K, D>>;
     on(eventName: string, handler: EventListenerOrEventListenerObject): EventListenerOrEventListenerObject;
-    /**
-    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<D = unknown, K extends string = string>(eventName: K, handler: McEventHandler<McPayloadOf<EM, K, D>>): McEventHandler<McPayloadOf<EM, K, D>>;
     one(eventName: string, handler: EventListenerOrEventListenerObject): EventListenerOrEventListenerObject;
     /**
@@ -342,60 +438,15 @@ declare class DC<T extends HTMLElement = HTMLElement, EM extends Record<string,
     @param controller - Optional controller for managing bubbling behavior.
     */
     trigger<D = unknown, K extends string = keyof EM & string>(eventName: K, data?: McPayloadOf<EM, K, D>, bubble?: BubbleDirections, controller?: BubbleController): void;
-    /**
-    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<R extends Record<string, unknown> = Record<never, never>>(): (McController & R)[];
     /** @param key - Optional registry key each collected ancestor must carry. */
     ancestors<K extends keyof McRegistry & string>(key: K): (McController & Pick<McRegistry, K>)[];
-    /**
-    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<R extends Record<string, unknown> = Record<never, never>>(): (McController & R) | null;
     /** @param key - Optional registry key the ancestor must carry. */
     closest<K extends keyof McRegistry & string>(key: K): (McController & Pick<McRegistry, K>) | null;
-    /**
-    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<R extends Record<string, unknown> = Record<never, never>>(): (McController & R)[];
     /** @param key - Optional registry key each child must carry. */
     children<K extends keyof McRegistry & string>(key: K): (McController & Pick<McRegistry, K>)[];
-    /**
-    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<R extends Record<string, unknown> = Record<never, never>>(): (McController & R)[];
     /** @param key - Optional registry key each descendant must carry. */
     descendants<K extends keyof McRegistry & string>(key: K): (McController & Pick<McRegistry, K>)[];