@twobirds/microcomponents 0.10.1 → 0.10.2

package/dist/core/elements.js

@@ -286,6 +286,20 @@ function kebabToPascal(str) {
 	return str.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
 }
 /**
+* Converts a PascalCase string to kebab-case.
+* Example: 'MyComponentName' -> 'my-component-name'
+* @param str - The PascalCase string to convert.
+* @returns The converted kebab-case string.
+*
+* @example
+* ```ts
+* console.log(pascalToKebab('MyElement'));
+* ```
+*/
+function pascalToKebab(str) {
+	return str.replace(/[A-Z]/g, (m, i) => (i ? "-" : "") + m.toLowerCase());
+}
+/**
 * Injects a CSS string into the given scope (document or shadow root) as an adopted stylesheet.
 * Enables css-in-js so that every custom element is self-contained and importable.
 *
@@ -509,13 +523,15 @@ function remove(target, key) {
 	if (!Object.keys(_mc).length && target instanceof HTMLElement && target.hasAttribute("data-mc")) target.removeAttribute("data-mc");
 }
 /**
-Runs the "Init" lifecycle event on a DOM microcomponent instance asynchronously.
+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. Only `DC` instances have an Init lifecycle — the `McBase`
-constructor calls this exclusively behind an `instanceof DC` check, so the
-signature encodes that invariant instead of re-checking it at runtime.
+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.
 */
@@ -583,16 +599,18 @@ function findMcAncestor(from, key) {
 The base class for all microcomponents — shared root of both {@link MC} and {@link DC}.
 
 Holds a `WeakRef` to the target (a DOM element for `DC`, or any plain object for `MC`)
-to avoid circular references. For `DC` subclasses it also bootstraps two automatic
-behaviours:
+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}.
-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.
+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
 
@@ -645,20 +663,45 @@ runs once after the constructor.
 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 and triggers auto-attachment
-	of listeners and initialization lifecycle events.
+	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 || {});
-		if (this instanceof DC && this.constructor !== DC) {
-			autoAttachListeners(this);
-			const tag = this.constructor.tag;
-			if (tag === void 0 || tag.toUpperCase() === this.target.tagName) init(this);
-		}
+		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.
@@ -676,6 +719,21 @@ var McBase = class {
 	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
@@ -733,14 +791,26 @@ and translated into file extensions: `'targetHtml'` → `.target.html`, `'json'`
 The path is derived from the custom element tag segments, and the basename is the
 last segment. For `<cart-container-checkout>`, assets load from `/cart/container/checkout.*`.
 
-When assets finish loading, an `'assets'` event fires so that `oneAssets(ev)` can
-process them. Everything ending in `Json` arrives parsed; all other files arrive as text.
+**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 removed from both `static assets` and `static _assets`. Subsequent
-instances skip loading and re-processing them entirely.
+the entries are dropped from `static _assets`. Subsequent instances skip re-processing
+them entirely.
 
 **CSS file roles**:
 
@@ -751,7 +821,9 @@ scope once, like `targetCss`.
 component's own shadow root, so each instance gets its own copy.
 
 Every declared asset — CSS, HTML, JSON — is inlined into `static _assets` at build time by
-the load-assets plugin, so a bundled build performs no fetches at all.
+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
@@ -763,14 +835,14 @@ The runtime decides whether an asset still needs fetching with `!ctor._assets[ke
 inlined entry must never be an empty string: that would trigger a re-fetch of a file that
 does not exist in a bundled build.
 
-@example static assets with autoload
+@example static assets read in oneInit
 
 ```ts
 class CartCheckout extends DC {
 static assets = ['targetHtml', 'targetCss', 'configJson'];
 
-oneAssets(ev) {
-const { configJson } = ev.detail.data;
+oneInit() {
+const { configJson } = this.assets;
 console.log(configJson);
 }
 }
@@ -779,6 +851,26 @@ 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.
@@ -832,8 +924,7 @@ internal events that can be caught with handler methods:
 | `onDisconnected()` | Element was removed from the DOM (`disconnectedCallback`) |
 | `onAdopted()` | Element was moved to a new document (`adoptedCallback`) |
 | `onAttributeChanged()` | An observed attribute changed (`attributeChangedCallback`) |
-| `oneInit()` | Constructor finished; all synchronous setup complete (microtask) |
-| `oneAssets()` | Constructor finished; all assets loaded and available; ev contains assets object |
+| `oneInit()` | Constructor finished and declared assets loaded; read them via `this.assets` |
 
 @example Event handlers in action
 
@@ -948,22 +1039,6 @@ var DC = class DC extends McBase {
 	*/
 	static tag;
 	/**
-	* Result container for assets (e.g., `['targetHtml', 'json']`).
-	* Asset names (keys) are camelCase and translated into file extensions: `'targetHtml'` → `.target.html`.
-	*/
-	static _assets = {};
-	/**
-	* Declares companion files for auto-loading by convention (e.g., `['targetHtml', 'json']`).
-	* Asset names are camelCase and translated into file extensions: `'targetHtml'` → `.target.html`.
-	*/
-	static assets = [];
-	/**
-	* In-flight asset request, cached per class so that instances constructed while
-	* the first fetch is still pending (e.g. in a loop) share a single request
-	* instead of each triggering their own. Resolves to the freshly loaded assets.
-	*/
-	static _assetsPromise;
-	/**
 	* Sets HTML attributes on every instance automatically.
 	* Example: `{ role: 'listitem', 'aria-label': 'nav' }`.
 	*/
@@ -975,8 +1050,10 @@ var DC = class DC extends McBase {
 	* 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.
+	* 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.
 	*/
@@ -999,43 +1076,24 @@ var DC = class DC extends McBase {
 		if (ctor.attributes) Object.keys(ctor.attributes).forEach((key) => {
 			this.target.setAttribute(key, attributes[key]);
 		});
-		const that = this;
-		const remainingAssets = ctor.assets.filter((key) => !ctor._assets[key]);
-		if (Object.keys(ctor._assets).length) processAssets(this, ctor._assets);
-		if (remainingAssets.length) {
-			if (!ctor._assetsPromise) ctor._assetsPromise = loadAssets(ctor._originalTag || tagName, remainingAssets).then((res) => {
-				const loadedAssets = {};
-				remainingAssets.forEach((key, i) => {
-					loadedAssets[key] = res[i];
-				});
-				ctor._assets = Object.assign({}, ctor._assets, loadedAssets);
-				for (const onceKey of ["css", "targetCss"]) if (loadedAssets[onceKey] !== void 0) delete ctor._assets[onceKey];
-				ctor.assets = ctor.assets.filter((key) => key !== "css" && key !== "targetCss");
-				return loadedAssets;
-			});
-			ctor._assetsPromise.then((loadedAssets) => {
-				processAssets(this, loadedAssets);
-				that.trigger("assets", ctor._assets);
-			});
-		} else if ([...Object.keys(ctor._assets)].length) queueMicrotask(() => that.trigger("assets", ctor._assets));
+		if (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;
 		}
 	}
 	/**
-	Returns the loaded assets for this component instance.
-	
-	Assets are loaded asynchronously when `static assets` is defined on the class.
-	This method returns the resolved asset map keyed by filename, or `undefined`
-	if assets have not yet been loaded.
-	
-	@returns A record mapping asset keys to their content strings, or undefined.
-	*/
-	getAssets() {
-		return this.constructor._assets || {};
-	}
-	/**
 	Static helper to attach a microcomponent instance to a DOM element.
 	
 	Wrapper around the `add()` utility function, providing a class-level API

package/dist/core/index.d.ts

@@ -54,11 +54,12 @@ This `_mc` property is the **only** interference with the native DOM structure,
 
 ## Lifecycle
 
-- DC instances automatically trigger an `"Init"` lifecycle event asynchronously - using queueMicrotask() - after construction. A component with a 'oneInit()' method will catch that lifecycle event, and when it runs it is guaranteed that the constructor() has run.
+- DC instances trigger the `"Init"` lifecycle event after construction **and after their declared assets are loaded** — synchronously in a bundled build (assets inlined), after the fetch resolves in a dev/autoload build. A component with a `oneInit()` method catches that event; when it runs, the constructor has finished and the assets are readable through the `this.assets` getter.
 - 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.
-- When using the static `assets` property to on-demand load shadow/target templates and css
-  - those are automatically attached to their respective target locations
-  - and all native event handlers in template code (<button click="...">) are automatically attached also
+- When using the static `assets` property to load companion files:
+  - `.css`, `.target.css`, `.shadow.css`, `.target.html` and `.shadow.html` are automatically attached to their respective target locations, and native event handlers in template code (`<button click="...">`) are wired automatically
+  - a plain `.html` is NOT auto-attached — it is a template held in `this.assets` for components created programmatically with a `data` parameter, compiled with `parse()` inside `oneInit()`
+  - assets are loaded before `oneInit()` fires, so `oneInit()` always sees them
 ---
 
 @module Core

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiEE;AAEF,6BAA6B;AAC7B,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACzC,sBAAsB;AACtB,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACxD,mBAAmB;AACnB,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAClF,qBAAqB;AACrB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkEE;AAEF,6BAA6B;AAC7B,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACzC,sBAAsB;AACtB,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACxD,mBAAmB;AACnB,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAClF,qBAAqB;AACrB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/docs/api-external.d.ts

@@ -0,0 +1,101 @@
+/**
+@page api-external Overview
+@order 1
+
+Micro Components are not a framework that owns the page — they are functions you can call
+from anywhere. The library exports a plain-function API (Tier 2) that works on any DOM
+node, in vanilla JS, inside React/Vue/Svelte lifecycle code, or in Node. Inside a `DC`
+or `MC` class you use the instance conventions (Tier 1); outside, you use these exports.
+
+The contract that makes coexistence safe: a host element gains only a `_mc` property and
+a `data-mc` attribute. A framework that renders markup, diffing, hydration, or its own
+event delegation is untouched by that.
+
+## Talking to micro components from vanilla JS
+
+`on()` and `trigger()` are the two ends of the wire. A custom event name is prefixed
+with `_mc` automatically, so the same name works on both sides:
+
+```js
+import { on, trigger } from '@twobirds/microcomponents';
+
+// a micro component listens for 'CartUpdate' with onCartUpdate()
+on(document.querySelector('cart-summary'), 'CartUpdate', (ev) => {
+    console.log(ev.detail.data.count); // payload lives under detail.data
+});
+
+// vanilla code fires it — the host's _mc receives the event
+trigger('cart-summary', 'CartUpdate', { count: 1 });
+```
+
+Direction is the third argument: `'l'` local only (default), `'u'` up to ancestors,
+`'d'` down to descendants, combinable (`'lu'`, `'ld'`, `'lud'`). Prefer naming the
+target — a single `querySelectorAll` reaches it in one step. Reserve `'u'`/`'d'` for
+receivers you cannot name in advance. A receiver stops a bubbling event with
+`ev.detail.control.stop()`.
+
+`one()` attaches a listener that fires once, `off()` detaches any handler.
+
+## Attaching logic to nodes a framework renders
+
+React, Vue, or Svelte own the markup; an MC attaches to a node they rendered:
+
+```tsx
+function Cart() {
+    const ref = useRef<HTMLDivElement>(null);
+    useEffect(() => {
+        DC.add(ref.current!, 'summary', new CartSummary(ref.current!));
+    }, []);
+    return <div ref={ref}></div>;
+}
+```
+
+The framework keeps diffing the node; the MC reads `this.target` and wires its own
+handlers. Nothing in the framework's virtual DOM sees the `_mc` property.
+
+## Creating elements from the registry
+
+`getCE()` returns the constructor registered by `defineCE()`, so code outside the
+system can instantiate a component:
+
+```ts
+import { getCE } from '@twobirds/microcomponents';
+
+const ShopHeader = getCE('shop-header');
+if (ShopHeader) document.querySelector('header')?.append(new ShopHeader());
+```
+
+`listCE()` lists every tag registered through `defineCE()`. `defineCE()` also accepts a
+class that does **not** extend `McBase` — the class becomes the element itself, with no
+`_mc` registry. That is the escape hatch for interoperating with existing custom
+elements.
+
+## State and forms from plain code
+
+`observe()` wraps an object's properties in Observable wrappers without any MC context;
+`formValues()` binds a named form control to one of them:
+
+```js
+import { observe, formValues } from '@twobirds/microcomponents';
+
+const form = observe({ email: '', qty: 1 });
+form.subscribe('email', (v) => console.log('email is now', v));
+formValues(form, 'email', document.querySelector('input[name=email]'));
+```
+
+## No-build pages
+
+`autoload(true)` makes a page load its own components: an undefined tag in the markup
+resolves to a script URL by the tag-to-path rule (`<shop-header>` → `shop/header.js`)
+and is fetched on demand. A dev page needs only an import map and one call.
+
+## Implementation priority
+
+- **Tier 1 — framework conventions**: auto-attached handlers, lifecycle, statics, plugin
+  methods. Use these first inside a `DC`/`MC`.
+- **Tier 2 — exported functions**: `on`, `trigger`, `observe`, `formValues`, `autoload`
+  — the public API outside a class.
+- **Tier 3 — vanilla JS**: native `addEventListener`, `querySelector`, raw `CustomEvent`
+  — last resort.
+*/
+//# sourceMappingURL=api-external.d.ts.map

package/dist/docs/api-external.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-external.d.ts","sourceRoot":"","sources":["../../src/docs/api-external.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmGE"}

package/dist/docs/cli.d.ts

@@ -0,0 +1,115 @@
+/**
+@page cli CLI
+@order 1
+
+A small command-line tool (`mc`) scaffolds components and runs the dev / build / preview
+chain, with no Vite dependency in the generated project. Nothing has to be installed to
+run it once — `npx` fetches the package into its own cache and runs the bin from there.
+
+```sh
+npx @twobirds/microcomponents --help
+npx @twobirds/microcomponents new my-card --target-html --target-css
+npx -p @twobirds/microcomponents mc new my-card --target-html --target-css
+npx -p @twobirds/microcomponents microcomponents-mcp
+```
+
+Once installed from npm the same tool is available as `mc`. Every command below is one
+line of usage with a worked example.
+
+## mc new
+
+Scaffolds one micro component: the `.ts` file plus the companion assets you flag, wired
+into a `static assets` declaration. The path is derived from the tag (`shop-app` →
+`src/shop/app.ts`).
+
+```sh
+mc new shop-app --target-html --target-css
+# created src/shop/app.ts
+# created src/shop/app.target.html
+# created src/shop/app.target.css
+```
+
+Flags: `--css`, `--html`, `--target-html`, `--shadow-html`, `--target-css`,
+`--shadow-css`, `--js` (plain JavaScript), `--dir <path>` (scaffold root, default `src`),
+`--force` (overwrite), `--dry-run` (print the plan, touch nothing).
+
+## mc create
+
+Scaffolds a complete dev environment for a namespace — package.json, the two shells, the
+starter component, the bundle barrel, and the `opencode.jsonc` that registers the MCP
+server.
+
+```sh
+mc create --namespace shop
+# project "shop" created in shop/ — run: cd shop && pnpm install && pnpm dev
+```
+
+Flags: `--namespace <ns>` (1 to 4 lowercase letters, required), `--dir <path>` (default:
+the namespace), `--force`, `--dry-run`.
+
+## mc dev
+
+Runs `tsc -w` plus a `node:http` server that serves `build/`. The page loads components
+on demand through `autoload()` — nothing is bundled, and a new component is picked up
+without restarting.
+
+```sh
+mc dev            # dev server on port 5173
+mc dev --port 3000
+```
+
+## mc bundle
+
+Assembles the production site in `public/`: one `bundle.js` with every companion asset
+inlined, the concatenated `bundle.css`, and the production shell. A single script tag
+loads it; the autoloader is not needed.
+
+```sh
+mc bundle
+```
+
+## mc preview
+
+Serves the production site in `public/`.
+
+```sh
+mc preview        # preview server on port 5174
+mc preview --port 8080
+```
+
+## mc clean
+
+Removes build artifacts (`dist`, `public`, `build`, `coverage`). A thin wrapper around
+the package.json script of the same name, so the script stays the single source of
+truth; when the project defines no such script, the CLI runs its own implementation.
+
+```sh
+mc clean
+```
+
+## mc check
+
+Type-checks the project. A thin wrapper around the package.json `check` script; with no
+such script, the CLI type-checks the current project with its own `tsconfig.json`.
+
+```sh
+mc check
+```
+
+## mc --version
+
+Reports the version of the installed library, not the version of the project it runs in.
+
+```sh
+mc --version      # 0.10.2
+```
+
+## mc --help
+
+Prints the full usage text, including every flag and companion asset.
+
+```sh
+mc --help
+```
+*/
+//# sourceMappingURL=cli.d.ts.map

package/dist/docs/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/docs/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiHE"}

package/dist/docs/concepts.d.ts

@@ -0,0 +1,42 @@
+/**
+@page concepts Overview
+@order 1
+
+Micro Components (MCs) are function blocks you attach to DOM nodes. The only interference
+with the DOM is a single `_mc` property on a host element, marked with a `data-mc`
+attribute — so any other system can coexist with it. MCs are built on OOP, favour
+composition over inheritance, and work like building blocks.
+
+The library ships helpers for five areas:
+
+- **Web Components** — native custom elements, composed from inner MCs.
+- **State** — observable objects with callbacks, 1-way binding to DOM placeholders.
+- **Form Handling** — 2-way binding between an observable form object and input fields.
+- **Communication** — direct-selected or directional bubbling CustomEvents between MCs.
+- **Autoloading** — build-free pages that load JS requirements into elements on demand.
+
+Prominent features: no-build development, a shallow learning curve, strict web-standards
+compliance, and very little abstraction. It runs Vanilla JS or TypeScript, and works
+alongside React, Angular, Vue, or on its own.
+
+The functional principle — attach an MC to a plain element:
+
+```ts
+class MyMC extends DC {
+    helloWorld() {
+        console.log('Hello World');
+    }
+}
+
+const element = document.querySelector('div');
+DC.add(element, 'myMC', new MyMC(element));
+
+// Hello World
+element._mc.myMC.helloWorld();
+```
+
+The `<div>` gains a `data-mc` attribute; the `_mc` property is the only DOM touch-point.
+Every visible element is a micro component extending `DC`, pure DOM-free logic extends
+`MC`, and additional DOM logic is attached at runtime with `DC.add()`.
+*/
+//# sourceMappingURL=concepts.d.ts.map

package/dist/docs/concepts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concepts.d.ts","sourceRoot":"","sources":["../../src/docs/concepts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwCE"}