@twobirds/microcomponents 0.10.0 → 0.10.2

package/dist/mcp/api.json

@@ -1,75 +1,82 @@
 {
-  "libraryVersion": "0.10.0",
-  "exportedCount": 41,
+  "libraryVersion": "0.10.2",
+  "exportedCount": 57,
   "entries": {
     "MC": {
       "name": "MC",
       "kind": "class",
+      "group": "MicroComponents",
       "file": "src/core/MC.ts",
       "signatures": [
         "class MC<TTarget extends object = object> extends McBase<TTarget> {"
       ],
-      "description": "A general-purpose base microcomponent that does not require a DOM target.\n\nInherits from `McBase`, but is primarily used as a lightweight container or\nfor logic not directly tied to DOM elements."
+      "description": "A general-purpose base microcomponent that does not require a DOM target.\n\nInherits from `McBase`, but is primarily used as a lightweight container or\nfor logic not directly tied to DOM elements.\n\n`static assets` work here too: a server-side `MC` fetches its companion files\n(`.json`, `.html`, `.css`) with `loadAssets()` and reads them through the\nMcBase.assets getter — await `MC._assetsPromise` before reading. There is\nno DOM attach and no `Init` lifecycle; those are `DC`-only."
     },
     "DC": {
       "name": "DC",
       "kind": "class",
+      "group": "MicroComponents",
       "file": "src/core/MC.ts",
       "signatures": [
         "class DC< T extends HTMLElement = HTMLElement, EM extends Record<string, unknown> = Record<never, never>, > extends McBase<T> implements McController<T> {"
       ],
-      "description": "A DOM-centric microcomponent that operates on a specific HTML element.\n\nExtends McBase and associates itself with an actual DOM node via the\n`_target` reference. Provides methods for event handling, DOM traversal,\nand interaction with sibling or ancestor microcomponents.\n\n\n## Static Configuration Properties\n\nDC classes support three static properties that configure custom elements\nbefore any instance is constructed:\n\n### `static tag?: string`\n\nReplaces the default target element with a semantic HTML element, or removes it entirely.\n\n- **Non-empty string** (e.g., `'header'`) — the original custom element is replaced\nwith the specified built-in element. The original tag name is added as a CSS class.\n- **Empty string `''`** — the target element is removed from the DOM entirely.\nUseful for components that only inject global styles or act as style containers.\n\nProduces `<header class=\"shop-header\">` instead of `<shop-header>`.\n\nThe element self-destructs; only side effects (e.g., injected styles) remain.\n\n### `static assets: string[]`\n\nDeclares companion files for auto-loading by convention. Asset names are camelCase\nand translated into file extensions: `'targetHtml'` → `.target.html`, `'json'` → `.json`.\n\nThe path is derived from the custom element tag segments, and the basename is the\nlast segment. For `<cart-container-checkout>`, assets load from `/cart/container/checkout.*`.\n\nWhen assets finish loading, an `'assets'` event fires so that `oneAssets(ev)` can\nprocess them. Everything ending in `Json` arrives parsed; all other files arrive as text.\n\n*One-time global styles**: Assets named `'css'` and `'targetCss'` inject CSS into the\nglobal document scope via `injectCSS(document, ...)`. Because these are idempotent\nglobal side effects, they are processed only once — after the first instance loads them,\nthe entries are removed from both `static assets` and `static _assets`. Subsequent\ninstances skip loading and re-processing them entirely.\n\n*CSS file roles**:\n\n- `.css` — design tokens only (CSS custom-property presets). Injected into the document\nscope once, like `targetCss`.\n- `.target.css` — layout rules for the light DOM. Also document-scoped and one-time.\n- `.shadow.css` — layout rules for the shadow DOM. Injected per instance into the\ncomponent's own shadow root, so each instance gets its own copy.\n\nEvery declared asset — CSS, HTML, JSON — is inlined into `static _assets` at build time by\nthe load-assets plugin, so a bundled build performs no fetches at all.\n\nIn a bundled build the plain `.css` files are additionally concatenated into a single\n`bundle.css` by the bundling script. That file is a convenience listing of the available\nvariables: copy the ones you want to change into your own stylesheet and override them\nthere. It is not required at runtime, and it cannot drift from the inlined presets — both\nare read from the same source files.\n\nThe runtime decides whether an asset still needs fetching with `!ctor._assets[key]`, so an\ninlined entry must never be an empty string: that would trigger a re-fetch of a file that\ndoes not exist in a bundled build.\n\n`configJson` arrives already parsed into an object.\n\n### `static attributes?: object`\n\nSets HTML attributes on every instance automatically.\n\nEvery `<product-card>` carries `role=\"listitem\"`.\n\n### Combined usage\n\nAll three can be combined in one class:\n\nProduces `<section role=\"list\" aria-label=\"products\">`.\n\n\n## Event Handler Conventions\n\nMethods whose names start with `on` or `one` are automatically wired as event listeners\non the target element. The prefix determines persistence:\n\n- **`on<EventName>`** — persistent listener (fires every time)\n- **`one<EventName>`** — one-time listener (fires once, then detaches)\n\n### Web Component Lifecycle Events\n\nWhen a DC is registered via defineCE, the custom element dispatches these\ninternal events that can be caught with handler methods:\n\n| Method | When it fires |\n|--------|---------------|\n| `onConnected()` | Element was inserted into the DOM (`connectedCallback`) |\n| `onDisconnected()` | Element was removed from the DOM (`disconnectedCallback`) |\n| `onAdopted()` | Element was moved to a new document (`adoptedCallback`) |\n| `onAttributeChanged()` | An observed attribute changed (`attributeChangedCallback`) |\n| `oneInit()` | Constructor finished; all synchronous setup complete (microtask) |\n| `oneAssets()` | Constructor finished; all assets loaded and available; ev contains assets object |\n\n\n## Construction Patterns\n\n### Template usage (declarative)\n\n```ts\nclass MyElement extends DC {}\ndefineCE('my-element', MyElement);\n```\n\nThe registered element is then used in HTML as `<my-element></my-element>`.\n\n### Programmatic construction with data\n\nWhen constructing programmatically via getCE, pass only the `data` payload —\nthe target element is created automatically by the custom element constructor.\n\n### Data from HTML attributes\n\nUsed in HTML as `<my-element my-data='{\"name\":\"John\"}'></my-element>`.\n\n\n## Plugin Extension Points\n\nThe prototype of `DC` (inherited from McBase) is extended at runtime by optional\nplugins. See the McBase documentation for details on State.observePlugin and\nState.formValuePlugin.\n\n`trigger()` checks the payload against the registered `CartUpdate` shape, and the `on()`\nhandler receives a fully typed `ev`.",
+      "description": "A DOM-centric microcomponent that operates on a specific HTML element.\n\nExtends McBase and associates itself with an actual DOM node via the\n`_target` reference. Provides methods for event handling, DOM traversal,\nand interaction with sibling or ancestor microcomponents.\n\n\n## Static Configuration Properties\n\nDC classes support three static properties that configure custom elements\nbefore any instance is constructed:\n\n### `static tag?: string`\n\nReplaces the default target element with a semantic HTML element, or removes it entirely.\n\n- **Non-empty string** (e.g., `'header'`) — the original custom element is replaced\n  with the specified built-in element. The original tag name is added as a CSS class.\n- **Empty string `''`** — the target element is removed from the DOM entirely.\n  Useful for components that only inject global styles or act as style containers.\n\nProduces `<header class=\"shop-header\">` instead of `<shop-header>`.\n\nThe element self-destructs; only side effects (e.g., injected styles) remain.\n\n### `static assets: string[]`\n\nDeclares companion files for auto-loading by convention. Asset names are camelCase\nand translated into file extensions: `'targetHtml'` → `.target.html`, `'json'` → `.json`.\n\nThe path is derived from the custom element tag segments, and the basename is the\nlast segment. For `<cart-container-checkout>`, assets load from `/cart/container/checkout.*`.\n\n*Assets are loaded before `oneInit()` fires.** The constructor applies them to the\ntarget, then dispatches the `Init` lifecycle event — synchronously in a bundled build\n(assets inlined), after the fetch resolves in a dev/autoload build. Inside `oneInit()`\nthe loaded assets are read through the DC.assets getter. Everything ending in\n`Json` arrives parsed; all other files arrive as text.\n\n*Auto-attached assets**: `.css`, `.target.css`, `.shadow.css`, `.target.html` and\n`.shadow.html` are attached automatically by `processAssets()` — CSS is injected into\nthe document or shadow scope, HTML is set as `target.innerHTML` / `shadowRoot.innerHTML`,\nand native event handlers in the template (`<button click=\"this|go\">`) are wired.\n\n*Plain `.html` is NOT auto-attached.** It is a template held in DC.assets for\ncomponents created programmatically with a `data` parameter: in `oneInit()` you compile\nthe target markup from template + data with `parse()`.\n\n*One-time global styles**: Assets named `'css'` and `'targetCss'` inject CSS into the\nglobal document scope via `injectCSS(document, ...)`. Because these are idempotent\nglobal side effects, they are processed only once — after the first instance loads them,\nthe entries are dropped from `static _assets`. Subsequent instances skip re-processing\nthem entirely.\n\n*CSS file roles**:\n\n- `.css` — design tokens only (CSS custom-property presets). Injected into the document\n  scope once, like `targetCss`.\n- `.target.css` — layout rules for the light DOM. Also document-scoped and one-time.\n- `.shadow.css` — layout rules for the shadow DOM. Injected per instance into the\n  component's own shadow root, so each instance gets its own copy.\n\nEvery declared asset — CSS, HTML, JSON — is inlined into `static _assets` at build time by\nthe bundler, which replaces the `static assets` declaration with `static _assets` (the\n`static assets` line is deleted from the bundled `.js`) and collapses each inlined\n`.[shadow/target].css` / `.html` to a single line, so a bundled build performs no fetches.\n\nIn a bundled build the plain `.css` files are additionally concatenated into a single\n`bundle.css` by the bundling script. That file is a convenience listing of the available\nvariables: copy the ones you want to change into your own stylesheet and override them\nthere. It is not required at runtime, and it cannot drift from the inlined presets — both\nare read from the same source files.\n\nThe runtime decides whether an asset still needs fetching with `!ctor._assets[key]`, so an\ninlined entry must never be an empty string: that would trigger a re-fetch of a file that\ndoes not exist in a bundled build.\n\n`configJson` arrives already parsed into an object.\n\n`user-card.html` holds the `{name}` template; `parse()` fills it from `data`.\n\n### `static attributes?: object`\n\nSets HTML attributes on every instance automatically.\n\nEvery `<product-card>` carries `role=\"listitem\"`.\n\n### Combined usage\n\nAll three can be combined in one class:\n\nProduces `<section role=\"list\" aria-label=\"products\">`.\n\n\n## Event Handler Conventions\n\nMethods whose names start with `on` or `one` are automatically wired as event listeners\non the target element. The prefix determines persistence:\n\n- **`on<EventName>`** — persistent listener (fires every time)\n- **`one<EventName>`** — one-time listener (fires once, then detaches)\n\n### Web Component Lifecycle Events\n\nWhen a DC is registered via defineCE, the custom element dispatches these\ninternal events that can be caught with handler methods:\n\n| Method | When it fires |\n|--------|---------------|\n| `onConnected()` | Element was inserted into the DOM (`connectedCallback`) |\n| `onDisconnected()` | Element was removed from the DOM (`disconnectedCallback`) |\n| `onAdopted()` | Element was moved to a new document (`adoptedCallback`) |\n| `onAttributeChanged()` | An observed attribute changed (`attributeChangedCallback`) |\n| `oneInit()` | Constructor finished and declared assets loaded; read them via `this.assets` |\n\n\n## Construction Patterns\n\n### Template usage (declarative)\n\n```ts\nclass MyElement extends DC {}\ndefineCE('my-element', MyElement);\n```\n\nThe registered element is then used in HTML as `<my-element></my-element>`.\n\n### Programmatic construction with data\n\nWhen constructing programmatically via getCE, pass only the `data` payload —\nthe target element is created automatically by the custom element constructor.\n\n### Data from HTML attributes\n\nUsed in HTML as `<my-element my-data='{\"name\":\"John\"}'></my-element>`.\n\n\n## Plugin Extension Points\n\nThe prototype of `DC` (inherited from McBase) is extended at runtime by optional\nplugins. See the McBase documentation for details on State.observePlugin and\nState.formValuePlugin.\n\n`trigger()` checks the payload against the registered `CartUpdate` shape, and the `on()`\nhandler receives a fully typed `ev`.",
       "examples": [
         {
           "title": "static tag — replace with semantic element",
-          "code": "class ShopHeader extends DC {\nstatic tag = 'header';\n}\ndefineCE('shop-header', ShopHeader);"
+          "code": "class ShopHeader extends DC {\n\tstatic tag = 'header';\n}\ndefineCE('shop-header', ShopHeader);"
         },
         {
           "title": "static tag — remove element entirely",
-          "code": "class GlobalStyles extends DC {\nstatic tag = '';\n}\ndefineCE('global-styles', GlobalStyles);"
+          "code": "class GlobalStyles extends DC {\n\tstatic tag = '';\n}\ndefineCE('global-styles', GlobalStyles);"
         },
         {
-          "title": "static assets with autoload",
-          "code": "class CartCheckout extends DC {\nstatic assets = ['targetHtml', 'targetCss', 'configJson'];\n\noneAssets(ev) {\nconst { configJson } = ev.detail.data;\nconsole.log(configJson);\n}\n}\ndefineCE('cart-checkout', CartCheckout);"
+          "title": "static assets read in oneInit",
+          "code": "class CartCheckout extends DC {\n\tstatic assets = ['targetHtml', 'targetCss', 'configJson'];\n\n\toneInit() {\n\t\tconst { configJson } = this.assets;\n\t\tconsole.log(configJson);\n\t}\n}\ndefineCE('cart-checkout', CartCheckout);"
+        },
+        {
+          "title": "plain .html template compiled with data",
+          "code": "class UserCard extends DC {\n\tstatic assets = ['html', 'targetCss'];\n\n\tconstructor(target: HTMLElement, data: { name: string }) {\n\t\tsuper(target);\n\t\tthis.data = data;\n\t}\n\n\toneInit() {\n\t\tthis.target.innerHTML = parse(this.assets.html, this.data);\n\t}\n}\ndefineCE('user-card', UserCard);"
         },
         {
           "title": "static attributes",
-          "code": "class ProductCard extends DC {\nstatic attributes = { role: 'listitem' };\n}\ndefineCE('product-card', ProductCard);"
+          "code": "class ProductCard extends DC {\n\tstatic attributes = { role: 'listitem' };\n}\ndefineCE('product-card', ProductCard);"
         },
         {
           "title": "All static properties together",
-          "code": "class ShopCatalog extends DC {\nstatic tag = 'section';\nstatic attributes = { role: 'list', 'aria-label': 'products' };\nstatic assets = ['targetHtml', 'targetCss'];\n}\ndefineCE('shop-catalog', ShopCatalog);"
+          "code": "class ShopCatalog extends DC {\n\tstatic tag = 'section';\n\tstatic attributes = { role: 'list', 'aria-label': 'products' };\n\tstatic assets = ['targetHtml', 'targetCss'];\n}\ndefineCE('shop-catalog', ShopCatalog);"
         },
         {
           "title": "Event handlers in action",
-          "code": "class MyElement extends DC {\nonConnected() {\nconsole.log('entered the DOM');\n}\n\nonDisconnected() {\nconsole.log('left the DOM');\n}\n\nonClick() {\nthis.trigger('something', 'payload');\n}\n\noneSomething(ev) {\nconsole.log('first time only:', ev.detail.data);\n}\n}\ndefineCE('my-element', MyElement);"
+          "code": "class MyElement extends DC {\n\tonConnected() {\n\t\tconsole.log('entered the DOM');\n\t}\n\n\tonDisconnected() {\n\t\tconsole.log('left the DOM');\n\t}\n\n\tonClick() {\n\t\tthis.trigger('something', 'payload');\n\t}\n\n\toneSomething(ev) {\n\t\tconsole.log('first time only:', ev.detail.data);\n\t}\n}\ndefineCE('my-element', MyElement);"
         },
         {
           "title": "Programmatic construction",
-          "code": "class MyElement extends DC {\ndata = {};\n\nconstructor(target, data) {\nsuper(target);\nthis.data = data;\n}\n}\ndefineCE('my-element', MyElement);\n\nconst Ctor = getCE('my-element');\ndocument.body.append(new Ctor({ name: 'John' }));"
+          "code": "class MyElement extends DC {\n\tdata = {};\n\n\tconstructor(target, data) {\n\t\tsuper(target);\n\t\tthis.data = data;\n\t}\n}\ndefineCE('my-element', MyElement);\n\nconst Ctor = getCE('my-element');\ndocument.body.append(new Ctor({ name: 'John' }));"
         },
         {
           "title": "Reading data from an attribute",
-          "code": "class MyElement extends DC {\ndata = {};\n\nconstructor(target) {\nsuper(target);\nthis.data = JSON.parse(target.getAttribute('my-data'));\n}\n}\ndefineCE('my-element', MyElement);"
+          "code": "class MyElement extends DC {\n\tdata = {};\n\n\tconstructor(target) {\n\t\tsuper(target);\n\t\tthis.data = JSON.parse(target.getAttribute('my-data'));\n\t}\n}\ndefineCE('my-element', MyElement);"
         },
         {
           "title": "Typed event map",
-          "code": "class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {\ncheckout() {\nthis.trigger('CartUpdate', { count: 2 }, 'u');\nthis.on('CartUpdate', (ev) => ev.detail.data.count);\n}\n}"
+          "code": "class Cart extends DC<HTMLFormElement, { CartUpdate: { count: number } }> {\n\tcheckout() {\n\t\tthis.trigger('CartUpdate', { count: 2 }, 'u');\n\t\tthis.on('CartUpdate', (ev) => ev.detail.data.count);\n\t}\n}"
         }
       ]
     },
     "McBase": {
       "name": "McBase",
       "kind": "class",
+      "group": "MicroComponents",
       "file": "src/core/MC.ts",
       "signatures": [
         "class McBase<TTarget extends object = object> {"
       ],
-      "description": "The base class for all microcomponents — shared root of both MC and DC.\n\nHolds a `WeakRef` to the target (a DOM element for `DC`, or any plain object for `MC`)\nto avoid circular references. For `DC` subclasses it also bootstraps two automatic\nbehaviours:\n\n1. **Event listener auto-attachment** — methods whose names start with `on` or `one`\n(e.g. `onClick`, `oneInit`) are wired to the target element via on / one.\n2. **\"Init\" lifecycle event** — dispatched asynchronously in a microtask so that all\nsynchronous constructor work finishes first.\n\nBoth mechanisms run only when the instance is a `DC` (checked with `instanceof DC`).\nPlain `MC` instances skip them entirely, keeping server-side usage lightweight.\n\n### Plugin extension points\n\nThe prototype of `McBase` is the attachment point for optional plugins that curry\nadditional instance methods onto every microcomponent. Two built-in plugins modify\nthis class at runtime:\n\n- **State.observePlugin** — adds `notify()`, `subscribe()`, and `bind()` so that\nobservable properties can be controlled directly on the component instance with\nfluent chaining. Call `observePlugin(DC)` once at module level to activate.\n\n- **State.formValuePlugin** — adds `formValues()` for two-way binding between DOM\nform controls and an observable property. Also pulls in all methods from\nState.observePlugin, so you can chain `.subscribe()` and `.bind()` after\n`.formValues()`. Call `formValuePlugin(DC)` once at module level to activate.\n\nBoth plugins are idempotent — calling them multiple times has no side effects. They\nwork by assigning methods onto `McBase.prototype` (reached via\n`Object.getPrototypeOf(Class.prototype)`) and use TypeScript module augmentation\n(`declare module`) so the added signatures appear in type-checking automatically.\n\n`observePlugin(DC)` adds `notify()`, `subscribe()`, `bind()` to `McBase.prototype`;\n`formValuePlugin(DC)` adds `formValues()` and re-runs `observePlugin`. `oneInit()`\nruns once after the constructor.",
+      "description": "The base class for all microcomponents — shared root of both MC and DC.\n\nHolds a `WeakRef` to the target (a DOM element for `DC`, or any plain object for `MC`)\nto avoid circular references. It starts loading any `static assets` for `MC` and `DC`\nalike (shared per class through `_assetsPromise`), read through the McBase.assets\ngetter. For `DC` subclasses it bootstraps one automatic behaviour:\n\n1. **Event listener auto-attachment** — methods whose names start with `on` or `one`\n   (e.g. `onClick`, `oneInit`) are wired to the target element via on / one.\n\nThe **\"Init\" lifecycle event** and the DOM attach of auto-attached assets are dispatched\nby the DC constructor — after the declared assets are in place — so that\n`oneInit()` runs once the instance is fully constructed and its assets are loaded. Plain\n`MC` instances fetch their assets server-side with no DOM attach and no `Init` lifecycle,\nkeeping server-side usage lightweight.\n\n### Plugin extension points\n\nThe prototype of `McBase` is the attachment point for optional plugins that curry\nadditional instance methods onto every microcomponent. Two built-in plugins modify\nthis class at runtime:\n\n- **State.observePlugin** — adds `notify()`, `subscribe()`, and `bind()` so that\n  observable properties can be controlled directly on the component instance with\n  fluent chaining. Call `observePlugin(DC)` once at module level to activate.\n\n- **State.formValuePlugin** — adds `formValues()` for two-way binding between DOM\n  form controls and an observable property. Also pulls in all methods from\n  State.observePlugin, so you can chain `.subscribe()` and `.bind()` after\n  `.formValues()`. Call `formValuePlugin(DC)` once at module level to activate.\n\nBoth plugins are idempotent — calling them multiple times has no side effects. They\nwork by assigning methods onto `McBase.prototype` (reached via\n`Object.getPrototypeOf(Class.prototype)`) and use TypeScript module augmentation\n(`declare module`) so the added signatures appear in type-checking automatically.\n\n`observePlugin(DC)` adds `notify()`, `subscribe()`, `bind()` to `McBase.prototype`;\n`formValuePlugin(DC)` adds `formValues()` and re-runs `observePlugin`. `oneInit()`\nruns once after the constructor.",
       "examples": [
         {
           "title": "Extending with plugins at runtime",
-          "code": "import { DC, observePlugin, formValuePlugin } from '@twobirds/microcomponents';\n\nobservePlugin(DC);\nformValuePlugin(DC);\n\nclass MyForm extends DC {\ndata = { name: '' };\n\noneInit() {\nthis\n.formValues(this.target, 'data')\n.subscribe('data', (v) => console.log(v))\n.bind('data', this.target);\n}\n}"
+          "code": "import { DC, observePlugin, formValuePlugin } from '@twobirds/microcomponents';\n\nobservePlugin(DC);\nformValuePlugin(DC);\n\nclass MyForm extends DC {\n\tdata = { name: '' };\n\n\toneInit() {\n\t\tthis\n\t\t.formValues(this.target, 'data')\n\t\t.subscribe('data', (v) => console.log(v))\n\t\t.bind('data', this.target);\n\t}\n}"
         }
       ]
     },
@@ -84,7 +91,7 @@
         "export function defineCE< Tag extends `${string}-${string}`, T extends object, D, E extends keyof HTMLElementTagNameMap | undefined = undefined, >( tagName: Tag, DefinitionClass: new (target: TargetOf<E>, data: D) => T, observedAttributes?: string[], extend?: E",
         "export function defineCE< Tag extends `${string}-${string}`, T extends object, D = unknown, E extends keyof HTMLElementTagNameMap | undefined = undefined, >( tagName: Tag, DefinitionClass: new (target: TargetOf<E>, data?: D) => T, observedAttributes: string[] = [], extend?: E"
       ],
-      "description": "### Examples\n\n#### Define custom element in registry\n\n```ts\nclass MyElement extends DC {}\ndefineCE('my-element', MyElement);\n```\n\nThe registered element is then used in HTML as `<my-element></my-element>`.\n\n#### Define custom element in registry with observed attributes\n\n```ts\nclass MyElement extends DC {\nonAttributeChanged(ev){\nconst newValue = ev.detail.data.newValue;\n}\n}\ndefineCE('my-element', MyElement, ['observed']);\n```\n\nUsed in HTML as `<my-element observed></my-element>`. When the `observed` attribute\nchanges, `attributeChanged` is triggered, which calls `onAttributeChanged` with the\nchange data in the payload.\n\nDefines a custom HTML element with optional observed attributes and micro component integration.\nThe class provided in DefinitionClass will be added to the ._mc hash object appended to the custom element instance.\nAutomatically assigns a \"PascalCase\" class name derived from the <kebab-case> tagName.\nIf the provided definition class extends McBase (indicating a DC or MC class extension), it wraps the constructor to register\nthe element instance with DC (DomComponent)."
+      "description": "### Examples\n\n#### Define custom element in registry\n\n```ts\nclass MyElement extends DC {}\ndefineCE('my-element', MyElement);\n```\n\nThe registered element is then used in HTML as `<my-element></my-element>`.\n\n#### Define custom element in registry with observed attributes\n\n```ts\nclass MyElement extends DC {\n\tonAttributeChanged(ev){\n\t\tconst newValue = ev.detail.data.newValue;\n\t}\n}\ndefineCE('my-element', MyElement, ['observed']);\n```\n\nUsed in HTML as `<my-element observed></my-element>`. When the `observed` attribute\nchanges, `attributeChanged` is triggered, which calls `onAttributeChanged` with the\nchange data in the payload.\n\nDefines a custom HTML element with optional observed attributes and micro component integration.\nThe class provided in DefinitionClass will be added to the ._mc hash object appended to the custom element instance.\nAutomatically assigns a \"PascalCase\" class name derived from the <kebab-case> tagName.\nIf the provided definition class extends McBase (indicating a DC or MC class extension), it wraps the constructor to register\nthe element instance with DC (DomComponent)."
     },
     "getCE": {
       "name": "getCE",
@@ -100,7 +107,7 @@
       "examples": [
         {
           "title": "",
-          "code": "const MyElementClass = getCE('my-element');\nif (MyElementClass) {\ndocument.body.append(new MyElementClass());\n}"
+          "code": "const MyElementClass = getCE('my-element');\nif (MyElementClass) {\n\tdocument.body.append(new MyElementClass());\n}"
         }
       ]
     },
@@ -172,13 +179,14 @@
       "examples": [
         {
           "title": "",
-          "code": "declare global {\ninterface McRegistry {\ncart: Cart;\n}\n}\n\nconst el = document.querySelector('form');\nif (el && isMcHost(el)) {\nel._mc.trigger('Ping');\n}\nif (el && isMcHost(el, 'cart')) {\nel._mc.cart.addItem(item);\n}"
+          "code": "declare global {\n    interface McRegistry {\n        cart: Cart;\n    }\n}\n\nconst el = document.querySelector('form');\nif (el && isMcHost(el)) {\n    el._mc.trigger('Ping');\n}\nif (el && isMcHost(el, 'cart')) {\n    el._mc.cart.addItem(item);\n}"
         }
       ]
     },
     "observe": {
       "name": "observe",
       "kind": "function",
+      "group": "State",
       "file": "src/state/observables.ts",
       "signatures": [
         "export function observe<T extends object, K extends keyof T>( target: T, propertyName: K ): ObservedKey<T, K>;",
@@ -194,17 +202,18 @@
         },
         {
           "title": "Declarative usage — typed class field with double cast:",
-          "code": "class Counter {\nclicks: Observable<number> = 0 as unknown as Observable<number>;\n\nconstructor() {\nobserve(this, 'clicks');\n}\n\nbump() {\nthis.clicks++;\n}\n}"
+          "code": "class Counter {\n\tclicks: Observable<number> = 0 as unknown as Observable<number>;\n\n\tconstructor() {\n\t\tobserve(this, 'clicks');\n\t}\n\n\tbump() {\n\t\tthis.clicks++;\n\t}\n}"
         },
         {
           "title": "Schema-first usage — divergent read/write types via hand-declared interface:",
-          "code": "interface CounterState {\nget count(): Observable<number>;\nset count(v: number);\n}\n\nconst state = observe<CounterState>({ count: 0 });\nstate.count.subscribe((v) => console.log(v));\nstate.count = 5;"
+          "code": "interface CounterState {\n\tget count(): Observable<number>;\n\tset count(v: number);\n}\n\nconst state = observe<CounterState>({ count: 0 });\nstate.count.subscribe((v) => console.log(v));\nstate.count = 5;"
         }
       ]
     },
     "observePlugin": {
       "name": "observePlugin",
       "kind": "function",
+      "group": "State",
       "file": "src/state/observables.ts",
       "signatures": [
         "export function observePlugin(Class: any) {"
@@ -213,13 +222,14 @@
       "examples": [
         {
           "title": "",
-          "code": "class Counter extends DC {\ndata = { clicks: 1 };\n\noneAssets() {\nthis\n.subscribe('data', (v) => console.log('data →', v))\n.bind('data', this.target);\n}\n}"
+          "code": "class Counter extends DC {\n\tdata = { clicks: 1 };\n\n\toneInit() {\n\t\tthis\n\t\t.subscribe('data', (v) => console.log('data →', v))\n\t\t.bind('data', this.target);\n\t}\n}"
         }
       ]
     },
     "isAlreadyObserved": {
       "name": "isAlreadyObserved",
       "kind": "function",
+      "group": "State",
       "file": "src/state/observables.ts",
       "signatures": [
         "export function isAlreadyObserved(value: unknown): boolean {"
@@ -235,6 +245,7 @@
     "Observable": {
       "name": "Observable",
       "kind": "type alias",
+      "group": "State",
       "file": "src/state/observables.ts",
       "signatures": [
         "export type Observable<T = unknown> = T & {"
@@ -250,6 +261,7 @@
     "Callback": {
       "name": "Callback",
       "kind": "type alias",
+      "group": "State",
       "file": "src/state/observables.ts",
       "signatures": [
         "export type Callback<T = unknown> = (value: T) => void;"
@@ -265,11 +277,12 @@
     "Observed": {
       "name": "Observed",
       "kind": "type alias",
+      "group": "State",
       "file": "src/state/observables.ts",
       "signatures": [
         "export type Observed<T> = { [K in keyof T]: Observable<T[K]> };"
       ],
-      "description": "Every property of `T` mapped to an observable of its value.\n\nKNOWN LIMIT: the runtime property *setter* accepts a plain value\n(`state.count = 5` re-wraps it), but this mapped type cannot say so — mapped\ntypes cannot declare divergent read/write (get/set) types, so the wrapper type\ngoverns writes too and plain assignment to a primitive observable is rejected.\nTracked upstream as https://github.com/microsoft/TypeScript/issues/43826\n(variant accessors for mapped types); when it lands, the write type here\nbecomes `T[K] | Observable<T[K]>` and the limit disappears.\n\nUntil then, use one of the supported write paths:\n- the `observed` variant, a single container whose `.value` gives \ntyped reads and writes today (`state.value.count = 5`, deep\nwrites included) — the limitation never applies;\n- `state.count++` (compiles today; TS does not re-check the `++` write-back);\n- the schema-first `observe<S>()` overload with a hand-declared get/set\ninterface, where the divergence IS expressible (and plain `=` becomes\nlegal) — see Unobserved.\n\nEvery property is mapped to an observable: `State` is\n`{ count: Observable<number>, name: Observable<string> }`.",
+      "description": "Every property of `T` mapped to an observable of its value.\n\nKNOWN LIMIT: the runtime property *setter* accepts a plain value\n(`state.count = 5` re-wraps it), but this mapped type cannot say so — mapped\ntypes cannot declare divergent read/write (get/set) types, so the wrapper type\ngoverns writes too and plain assignment to a primitive observable is rejected.\nTracked upstream as https://github.com/microsoft/TypeScript/issues/43826\n(variant accessors for mapped types); when it lands, the write type here\nbecomes `T[K] | Observable<T[K]>` and the limit disappears.\n\nUntil then, use one of the supported write paths:\n- the `observed` variant, a single container whose `.value` gives \n  typed reads and writes today (`state.value.count = 5`, deep\n  writes included) — the limitation never applies;\n- `state.count++` (compiles today; TS does not re-check the `++` write-back);\n- the schema-first `observe<S>()` overload with a hand-declared get/set\n  interface, where the divergence IS expressible (and plain `=` becomes\n  legal) — see Unobserved.\n\nEvery property is mapped to an observable: `State` is\n`{ count: Observable<number>, name: Observable<string> }`.",
       "examples": [
         {
           "title": "",
@@ -280,6 +293,7 @@
     "ObservedKey": {
       "name": "ObservedKey",
       "kind": "type alias",
+      "group": "State",
       "file": "src/state/observables.ts",
       "signatures": [
         "export type ObservedKey<T, K extends keyof T> = {"
@@ -295,6 +309,7 @@
     "Unobserved": {
       "name": "Unobserved",
       "kind": "type alias",
+      "group": "State",
       "file": "src/state/observables.ts",
       "signatures": [
         "export type Unobserved<S> = {"
@@ -303,13 +318,14 @@
       "examples": [
         {
           "title": "",
-          "code": "interface CounterState {\nget count(): Observable<number>;\nset count(v: number);\n}\ntype Seed = Unobserved<CounterState>;\nconst state = observe<CounterState>({ count: 0 });"
+          "code": "interface CounterState {\n\tget count(): Observable<number>;\n\tset count(v: number);\n}\ntype Seed = Unobserved<CounterState>;\nconst state = observe<CounterState>({ count: 0 });"
         }
       ]
     },
     "formValues": {
       "name": "formValues",
       "kind": "function",
+      "group": "State",
       "file": "src/state/formValues.ts",
       "signatures": [
         "export function formValues<T extends object>( targetObject: T, propertyName: keyof T & string, dom: HTMLElement | ShadowRoot ) {"
@@ -322,13 +338,14 @@
         },
         {
           "title": "Subscribe to form changes inside a component",
-          "code": "import { DC, defineCE, formValues } from '@twobirds/microcomponents';\n\nclass MyForm extends DC {\nstatic assets = ['targetHtml'];\n\noneAssets() {\nformValues(this, 'formData', this.target);\nthis.formData.subscribe((data) => console.log('form changed:', data));\n}\n}\n\ndefineCE('my-form', MyForm);"
+          "code": "import { DC, defineCE, formValues } from '@twobirds/microcomponents';\n\nclass MyForm extends DC {\n\tstatic assets = ['targetHtml'];\n\n\toneInit() {\n\t\tformValues(this, 'formData', this.target);\n\t\tthis.formData.subscribe((data) => console.log('form changed:', data));\n\t}\n}\n\ndefineCE('my-form', MyForm);"
         }
       ]
     },
     "formValuePlugin": {
       "name": "formValuePlugin",
       "kind": "function",
+      "group": "State",
       "file": "src/state/formValues.ts",
       "signatures": [
         "export function formValuePlugin(Class: any) {"
@@ -337,13 +354,14 @@
       "examples": [
         {
           "title": "",
-          "code": "import { DC, defineCE, formValuePlugin } from '@twobirds/microcomponents';\n\nformValuePlugin(DC);\n\nclass CheckoutForm extends DC {\nstatic assets = ['targetHtml'];\n\noneAssets() {\nthis\n.formValues(this.target, 'formData')\n.subscribe('formData', (data) => console.log(data))\n.bind('formData', this.target);\n}\n}\n\ndefineCE('checkout-form', CheckoutForm);"
+          "code": "import { DC, defineCE, formValuePlugin } from '@twobirds/microcomponents';\n\nformValuePlugin(DC);\n\nclass CheckoutForm extends DC {\n\tstatic assets = ['targetHtml'];\n\n\toneInit() {\n\t\tthis\n\t\t\t.formValues(this.target, 'formData')\n\t\t\t.subscribe('formData', (data) => console.log(data))\n\t\t\t.bind('formData', this.target);\n\t}\n}\n\ndefineCE('checkout-form', CheckoutForm);"
         }
       ]
     },
     "getMcEventName": {
       "name": "getMcEventName",
       "kind": "function",
+      "group": "Events",
       "file": "src/utils/events.ts",
       "signatures": [
         "export function getMcEventName(eventName: string): string {"
@@ -359,6 +377,7 @@
     "trueEventName": {
       "name": "trueEventName",
       "kind": "function",
+      "group": "Events",
       "file": "src/utils/events.ts",
       "signatures": [
         "export function trueEventName(target: HTMLElement, eventName: string): string {"
@@ -374,6 +393,7 @@
     "off": {
       "name": "off",
       "kind": "function",
+      "group": "Events",
       "file": "src/utils/events.ts",
       "signatures": [
         "export function off<D = unknown>( target: TargetSelect, eventName: string, handler: McEventHandler<D> ): void;",
@@ -391,6 +411,7 @@
     "on": {
       "name": "on",
       "kind": "function",
+      "group": "Events",
       "file": "src/utils/events.ts",
       "signatures": [
         "export function on<D = unknown>( target: TargetSelect, eventName: string, handler: McEventHandler<D>, once?: boolean ): McEventHandler<D>;",
@@ -401,13 +422,14 @@
       "examples": [
         {
           "title": "",
-          "code": "const handler = on<{ value: number }>(myElement, 'update', (ev) => {\nconsole.log(ev.detail.data.value);\n});\noff(myElement, 'update', handler);"
+          "code": "const handler = on<{ value: number }>(myElement, 'update', (ev) => {\n    console.log(ev.detail.data.value);\n});\noff(myElement, 'update', handler);"
         }
       ]
     },
     "one": {
       "name": "one",
       "kind": "function",
+      "group": "Events",
       "file": "src/utils/events.ts",
       "signatures": [
         "export function one<D = unknown>( target: TargetSelect, eventName: string, handler: McEventHandler<D> ): McEventHandler<D>;",
@@ -425,6 +447,7 @@
     "trigger": {
       "name": "trigger",
       "kind": "function",
+      "group": "Events",
       "file": "src/utils/events.ts",
       "signatures": [
         "export function trigger<D = unknown>( target: HTMLElement | string | undefined | null, event: string, data: D = {} as D, bubble: BubbleDirections = 'l', // direction of bubbling controller?: BubbleController ) {"
@@ -440,6 +463,7 @@
     "BubbleController": {
       "name": "BubbleController",
       "kind": "class",
+      "group": "Events",
       "file": "src/utils/events.ts",
       "signatures": [
         "export class BubbleController implements McBubbleController {"
@@ -452,9 +476,268 @@
         }
       ]
     },
+    "autoload": {
+      "name": "autoload",
+      "kind": "function",
+      "group": "Autoload",
+      "file": "src/utils/autoload.ts",
+      "signatures": [
+        "export function autoload(enable: boolean = true): boolean {"
+      ],
+      "description": "/**\n  The internal `loadingDCs` set, exposed for external inspection.\n\n  This property is attached to the `autoload()` function itself and contains\n  the names of microcomponent classes currently being loaded (or queued to load)."
+    },
+    "isBrowser": {
+      "name": "isBrowser",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function isBrowser(): boolean {"
+      ],
+      "description": "Determines whether the current runtime environment is a web browser.\n\nThis function works by attempting to access `this` within an anonymous function\nand checking if it refers to the global `window` object. It returns `true`\nwhen executed in a browser context, and `false` otherwise (e.g., Node.js).\n\nNote: While modern environments typically provide more reliable detection mechanisms,\nthis fallback remains compatible across older runtimes where other detection techniques\nmay be unreliable.",
+      "examples": [
+        {
+          "title": "",
+          "code": "if (isBrowser()) {\n  console.log('Running in a browser');\n}"
+        }
+      ]
+    },
+    "isNativeObject": {
+      "name": "isNativeObject",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function isNativeObject(value: unknown): value is Record<string, unknown> {"
+      ],
+      "description": "Checks if a value is a native JavaScript object (created via {} or new Object()).",
+      "examples": [
+        {
+          "title": "",
+          "code": "console.log(isNativeObject({}));\nconsole.log(isNativeObject(new Object()));\nconsole.log(isNativeObject([]));\nconsole.log(isNativeObject(null));"
+        }
+      ]
+    },
+    "sortObject": {
+      "name": "sortObject",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function sortObject<T extends Record<string, unknown>>(source: T): T {"
+      ],
+      "description": "Recursively sorts all keys in an object alphabetically, preserving nested structure.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const obj = { z: 1, a: { y: 2, b: 3 } };\nconsole.log(JSON.stringify(sortObject(obj)));"
+        }
+      ]
+    },
+    "flattenObject": {
+      "name": "flattenObject",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function flattenObject(source: object, doSort: boolean = true): Record<string, unknown> {"
+      ],
+      "description": "Flattens a nested object into a single-level object with dot-separated keys.\nOptionally sorts the resulting flat keys alphabetically (default: true).",
+      "examples": [
+        {
+          "title": "",
+          "code": "const obj = { user: { name: 'Alice', age: 30 } };\nconsole.log(JSON.stringify(flattenObject(obj)));"
+        }
+      ]
+    },
+    "deepEqual": {
+      "name": "deepEqual",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function deepEqual(a: unknown, b: unknown): boolean {"
+      ],
+      "description": "Structural deep-equality using SameValueZero for primitives.\n\nSee https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevaluezero.\n\nNote: `Map`/`Set` are not structurally compared.",
+      "examples": [
+        {
+          "title": "",
+          "code": "console.log(deepEqual({ a: 1 }, { a: 1 }));\nconsole.log(deepEqual({ a: { b: 2 } }, { a: {} }));\nconsole.log(deepEqual({ a: NaN }, { a: NaN }));\nconsole.log(deepEqual({ a: NaN }, { a: null }));"
+        }
+      ]
+    },
+    "nameSpace": {
+      "name": "nameSpace",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function nameSpace(ns: string | string[], obj: object = {}): unknown {"
+      ],
+      "description": "Retrieves a nested value from an object using a namespace path (dot-separated).",
+      "examples": [
+        {
+          "title": "",
+          "code": "const data = { user: { profile: { name: 'Alice' } } };\nconsole.log(nameSpace('user.profile.name', data));\nconsole.log(nameSpace(['user', 'profile'], data));"
+        }
+      ]
+    },
+    "parse": {
+      "name": "parse",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function parse<T = string | object | unknown[]>( template: T, parseThis: object, ...rest: unknown[] ): T {"
+      ],
+      "description": "Parses a template string or object, replacing placeholders in the form of {key.path} with\ncorresponding values from the provided data object using namespace resolution.\nAlso recursively processes objects and arrays within the input.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const data = { user: { name: 'Alice' } };\nconsole.log(parse('Hello {user.name}!', data));\nconsole.log(parse(['Hi {user.name}', 'Bye {user.name}'], data));"
+        }
+      ]
+    },
+    "kebabToPascal": {
+      "name": "kebabToPascal",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function kebabToPascal(str: string) {"
+      ],
+      "description": "Converts a kebab-case string to PascalCase.\nExample: 'my-component-name' -> 'MyComponentName'",
+      "examples": [
+        {
+          "title": "",
+          "code": "console.log(kebabToPascal('my-element'));"
+        }
+      ]
+    },
+    "debounce": {
+      "name": "debounce",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function debounce<A extends unknown[]>( func: (...args: A) => unknown, milliseconds: number ): (...args: A) => void {"
+      ],
+      "description": "Creates a debounced version of a function that delays execution until after the specified\nnumber of milliseconds have elapsed since the last time this function was invoked.\nUseful for rate-limiting expensive operations like event handlers or API calls.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const log = debounce(() => console.log('called'), 300);\nlog();\nlog();"
+        }
+      ]
+    },
+    "htmlToElements": {
+      "name": "htmlToElements",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function htmlToElements(html: string): HTMLElement[] {"
+      ],
+      "description": "Parses an HTML string and returns an array of DOM elements.\nHandles self-closing tags (XHTML style) by converting them to full closing tags first.",
+      "examples": [
+        {
+          "title": "",
+          "code": "const elems = htmlToElements('<div>Hello</div><span>World</span>');\nconsole.log(elems.map((el) => el.tagName));"
+        }
+      ]
+    },
+    "copyGettersSetters": {
+      "name": "copyGettersSetters",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function copyGettersSetters(source: object, target: object): void {"
+      ],
+      "description": "Copies all getter and setter properties from a source object to a target object.\nDoes not copy methods or regular data properties—only accessor properties (get/set).",
+      "examples": [
+        {
+          "title": "",
+          "code": "const src = { get name() { return 'Alice'; } };\nconst tgt = {};\ncopyGettersSetters(src, tgt);\nconsole.log(tgt.name);"
+        }
+      ]
+    },
+    "injectCSS": {
+      "name": "injectCSS",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function injectCSS(target: Document | ShadowRoot, css: string): CSSStyleSheet {"
+      ],
+      "description": "Injects a CSS string into the given scope (document or shadow root) as an adopted stylesheet.\nEnables css-in-js so that every custom element is self-contained and importable.\n\nWhen 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.\nWhen targeting **shadowRoot**: use `:host` for the custom element itself, standard selectors (`.inner`, `#id`) for internal structure, and `::slotted()` for projected light-DOM content.\n\nStyles can also be added using a compound innerHTML statement: `shadow.innerHTML = \\`<style>${style}</style>${template}\\``",
+      "examples": [
+        {
+          "title": "Inject global styles into the document:",
+          "code": "import { injectCSS } from '@twobirds/mc/utils/helpers';\ninjectCSS(document, 'body { display: block; }');"
+        },
+        {
+          "title": "Inject global styles for a micro component into the document:",
+          "code": "import { injectCSS } from '@twobirds/mc/utils/helpers';\ninjectCSS(document, 'my-microcomponent { display: block; }');"
+        },
+        {
+          "title": "Inject scoped styles into a shadow root:",
+          "code": "const shadow = element.attachShadow({ mode: 'open' });\ninjectCSS(shadow, ':host { color: var(--text); } .inner { padding: 8px; }');"
+        }
+      ]
+    },
+    "processAssets": {
+      "name": "processAssets",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function processAssets(instance: McController, assets: Record<string, string>): void {"
+      ],
+      "description": "Processes a record of asset strings and applies them to the given target element.\nSupports injecting CSS into document or shadow root, and setting innerHTML for\nboth target and shadow DOM. Automatically attaches a shadow root if any key starts\nwith `'shadow'`.\n\nRecognized keys: `'css'`, `'targetCss'` (document-level styles), `'shadowCss'`\n(shadow-root styles), `'shadowHtml'` (shadow innerHTML), `'targetHtml'` (target innerHTML).",
+      "examples": [
+        {
+          "title": "",
+          "code": "processAssets(this, {\n  css: 'body { margin: 0; }',\n  shadowCss: ':host { display: block; }',\n  shadowHtml: '<slot></slot>'\n});"
+        }
+      ]
+    },
+    "loadAssets": {
+      "name": "loadAssets",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function loadAssets(name: string, assets: string[]): Promise<Array<any>> {"
+      ],
+      "description": "Loads companion asset files (CSS, HTML) for a given component basename from the server.\n\nEach entry in `assets` encodes an optional variant and extension in camelCase, e.g. `'shadowCss'` → `{name}.shadow.css`,\n`'targetHtml'` → `{name}.target.html`. Plain entries like `'css'` or `'html'` resolve to\n`{name}.css` / `{name}.html`.\n\nIn bundled mode the Vite plugin replaces this call with an inline array literal, so `.then()`\nfires synchronously — no async overhead.",
+      "examples": [
+        {
+          "title": "",
+          "code": "export const MyComponent = loadAssets('my-component', ['shadowCss', 'shadowHtml']).then(([shadowCss, shadowHtml]) => {\n  class _MyComponent extends DC { ... }\n  defineCE('my-component', _MyComponent);\n  return _MyComponent;\n});"
+        }
+      ]
+    },
+    "bindTemplateEvents": {
+      "name": "bindTemplateEvents",
+      "kind": "function",
+      "group": "Helpers",
+      "file": "src/utils/helpers.ts",
+      "signatures": [
+        "export function bindTemplateEvents( rootElement: HTMLElement | ShadowRoot, instance: McController ): void {"
+      ],
+      "description": "Binds declarative event attributes in a template fragment to microcomponent triggers.\n\nScans all elements under `root` for attributes whose names correspond to native DOM\nevents (e.g. `click`, `submit`, `change`). The attribute value encodes the target and\nhandler method in the form `target|methodName`:\n\n- `this|myHandler` — triggers locally on the component attached to this element.\n- `other-comp|submit` — resolves elements via `querySelectorAll('other-comp')` and\n  triggers the event on each matched host's `_mc`.\n\nAn optional sibling `payload` attribute supplies the data argument for `trigger()`.\nAfter binding, both the event attribute and the payload attribute are removed from the DOM.",
+      "examples": [
+        {
+          "title": "",
+          "code": "<button click='this|onSubmit|{\"action\":\"go\"}'>Submit</button>\n<input change=\"|cart-form|refresh\">"
+        }
+      ]
+    },
     "McBubbleController": {
       "name": "McBubbleController",
       "kind": "interface",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export interface McBubbleController {"
@@ -464,6 +747,7 @@
     "BubbleDirection": {
       "name": "BubbleDirection",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type BubbleDirection = 'l' | 'u' | 'd';"
@@ -473,6 +757,7 @@
     "BubbleDirections": {
       "name": "BubbleDirections",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type BubbleDirections = | BubbleDirection | `${BubbleDirection}${BubbleDirection}` | `${BubbleDirection}${BubbleDirection}${BubbleDirection}`;"
@@ -482,6 +767,7 @@
     "McDetail": {
       "name": "McDetail",
       "kind": "interface",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export interface McDetail<D = unknown> {"
@@ -491,6 +777,7 @@
     "McEventHandler": {
       "name": "McEventHandler",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type McEventHandler<D = unknown> = (ev: McEvent<D>) => void;"
@@ -500,6 +787,7 @@
     "McEvent": {
       "name": "McEvent",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type McEvent<D = unknown> = CustomEvent<McDetail<D>>;"
@@ -508,13 +796,14 @@
       "examples": [
         {
           "title": "",
-          "code": "cart.on('CartUpdate', (ev: McEvent<{ count: number }>) => {\nconsole.log(ev.detail.data.count);\nev.detail.control.stop();\n});"
+          "code": "cart.on('CartUpdate', (ev: McEvent<{ count: number }>) => {\n    console.log(ev.detail.data.count);\n    ev.detail.control.stop();\n});"
         }
       ]
     },
     "McPayloadOf": {
       "name": "McPayloadOf",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type McPayloadOf<EM, K extends string, D = unknown> = K extends keyof EM ? EM[K] : D;"
@@ -524,6 +813,7 @@
     "McController": {
       "name": "McController",
       "kind": "interface",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export interface McController<T extends HTMLElement = HTMLElement> {"
@@ -533,6 +823,7 @@
     "McNativeEventHandlers": {
       "name": "McNativeEventHandlers",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type McNativeEventHandlers = {"
@@ -541,13 +832,14 @@
       "examples": [
         {
           "title": "",
-          "code": "class Panel extends DC implements McNativeEventHandlers {\nonClick(ev: MouseEvent) {}\n}"
+          "code": "class Panel extends DC implements McNativeEventHandlers {\n    onClick(ev: MouseEvent) {}\n}"
         }
       ]
     },
     "McHost": {
       "name": "McHost",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type McHost< T extends HTMLElement = HTMLElement, R extends Record<string, unknown> = Record<never, never>, > = T & {"
@@ -563,6 +855,7 @@
     "McHostOf": {
       "name": "McHostOf",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type McHostOf<T extends HTMLElement> = T extends { _mc: McController<infer U> } ? U : T;"
@@ -572,6 +865,7 @@
     "McEntriesOf": {
       "name": "McEntriesOf",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type McEntriesOf<T> = T extends { _mc: infer M } ? {"
@@ -581,6 +875,7 @@
     "McMerged": {
       "name": "McMerged",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type McMerged<A, B> = A & B extends infer U ? { [K in keyof U]: U[K] } : never;"
@@ -590,6 +885,7 @@
     "McRemoved": {
       "name": "McRemoved",
       "kind": "type alias",
+      "group": "Types",
       "file": "src/types/mcTypes.ts",
       "signatures": [
         "export type McRemoved<T extends HTMLElement, K extends string> = T extends { _mc: McController } ? { _mc: Record<K, never> } : unknown;"