@twobirds/microcomponents 0.2.5 → 0.4.0

package/README.md

@@ -30,22 +30,84 @@ The distinguishing feature is its **minimalism**, **portability** and **granular
 
 ## Links
 
-[demo shop (on-demand loading)](https://twobirds.gitlab.io/microcomponents/shop/index.html). No build, on-demand loading elements. Check code in debugger.
+[demo shop (on-demand loading)](https://twobirds.gitlab.io/microcomponents/shop/index-dev.html). No build, on-demand loading elements. Check code in debugger.
 
-[demo shop (bundled in one JS file)](https://twobirds.gitlab.io/microcomponents/shop/index-bundled.html). 9 kB including the library.
+[demo shop (bundled in one JS file)](https://twobirds.gitlab.io/microcomponents/shop/index.html). 9 kB including the library.
 
 Check the [typedoc API reference](https://twobirds.gitlab.io/microcomponents/typedoc/index.html) if you want to drill into the source code.
 
 The progress of coding is occasionally being streamed on [twitch](https://twitch.tv/frankieth).
 
+## MCP Server
+
+An MCP (Model Context Protocol) server ships with this repo so AI assistants can look the library up instead of answering from memory: `microcomponents-mcp-server.ts` at the repo root.
+
+```bash
+pnpm run mcp:run   # start the server on stdio
+pnpm run mcp:dev   # restart it whenever src/ changes
+pnpm run mcp:docs  # regenerate docs/api.json and report undocumented exports
+```
+
+Tools: `list-components`, `get-component-docs`, `search-components`, `get-core-concept`, `get-source-file`, `list-undocumented`.
+
+There is no hand-written API list in the server. The whole index is extracted at startup from the JSDoc blocks of the public exports (the names re-exported by each `src/*/index.ts`), so it can never drift away from the code it documents — and `list-undocumented` tells you when a source file still lacks a doc block. Concept essays are hand-authored markdown, one file per concept under `docs/concepts/`, which is also where the tool's list of available concepts comes from.
+
+## CLI
+
+A small command-line tool scaffolds new components so the tag-to-file convention is never hand-written:
+
+```bash
+pnpm run cli -- new my-card --target-html --target-css
+# created my/card.ts
+# created my/card.target.html
+# created my/card.target.css
+```
+
+`--dry-run` prints the plan without touching disk, so you can check the derived paths first:
+
+```bash
+pnpm run cli -- new my-card --target-html --target-css --dry-run
+# would create my/card.ts
+# would create my/card.target.html
+# would create my/card.target.css
+```
+
+`mc create` scaffolds a complete dev environment for a namespace — a Vite dev server serving `src/` straight, a page shell that turns on `autoload(true)`, and a starter component with companion assets:
+
+```bash
+pnpm run cli -- create --namespace mc --dir mc-app
+# created package.json
+# created src/index.html
+# created src/mc/app.ts
+# created src/mc/app.target.html
+# created src/mc/app.target.css
+# ...
+# project "mc" created in mc-app/ — run: cd mc-app && pnpm install && pnpm dev
+```
+
+The namespace (1 to 4 lowercase letters) becomes the `src/<namespace>/` folder and the first segment of every component tag, so `mc` is the home of tags like `<mc-app>`. Because the page shell is the autoload base, `import.meta.url` + the tag-to-path rule resolves `<mc-app>` to `src/mc/app.js` — the compiled starter. `--dir` defaults to the namespace, `--dry-run` prints the plan without touching disk.
+
+Once installed from npm the same command is available as `mc`:
+
+```bash
+mc new my-card [--css] [--html] [--target-html] [--shadow-html] [--target-css] [--shadow-css] [--js] [--dir <path>] [--dry-run]
+mc create --namespace <ns> [--dir <path>] [--dry-run]
+mc clean
+mc check
+```
+
+`clean` and `check` are thin wrappers around the package.json scripts of the same name, so the scripts remain the single source of truth for what they do — `mc check` type-checks every project context (lib, cli, test, demo, node) and exits with the script's exit code.
+
+The scaffold derives the file path from the tag using the same rule the runtime autoload loader uses (`my-card` → `my/card.ts`), names companion assets after the runtime's asset descriptors (`targetHtml` → `card.target.html`), and wires them into a `static assets` declaration. `--js` emits a plain JavaScript file for the rapid-prototyping path.
+
 ## Examples
 
 ### **Functional Principle**
 
-- *This section only shows the priciple: how Micro Components are stored in the DOM*
-- *The section after this shows Web Components / Custom Elements*
-- *All examples on this page are **Javascript**.*
-- *The package has full **Typescript** support*
+- _This section only shows the priciple: how Micro Components are stored in the DOM_
+- _The section after this shows Web Components / Custom Elements_
+- _All examples on this page are **Javascript**._
+- _The package has full **Typescript** support_
 
 html before:
 
@@ -70,10 +132,7 @@ const element = document.querySelector('div');
 DC.add(element, 'myMC', new MyMC(element));
 
 // Hello World
-element
-	._mc
-	.myMC
-	.helloWorld();
+element._mc.myMC.helloWorld();
 ```
 
 html after:
@@ -87,7 +146,7 @@ html after:
 
 ### **Web Components / Custom Elements**
 
-You can define a custom element using a micro component as its primary functional instance.  You are still free to add many more micro components to the custom element at runtime.
+You can define a custom element using a micro component as its primary functional instance. You are still free to add many more micro components to the custom element at runtime.
 
 code:
 
@@ -114,8 +173,8 @@ const body = document.body;
 body.append(new ctor());
 ```
 
-- For more examples regarding web components, go to the [typedocs](https://twobirds.gitlab.io/microcomponents/typedoc/) 
-- Check the sources of the [demo shop](https://twobirds.gitlab.io/microcomponents/shop/index.html) in the browser debugger 
+- For more examples regarding web components, go to the [typedocs](https://twobirds.gitlab.io/microcomponents/typedoc/)
+- Check the sources of the [demo shop](https://twobirds.gitlab.io/microcomponents/shop/index-dev.html) in the browser debugger
 
 ### **State and 1-way-binding**
 
@@ -127,7 +186,6 @@ code:
 observePlugin(DC);
 // create a custom micro component class
 class MyMC extends DC {
-
 	state = { text: 'Hello world!' };
 
 	constructor(target) {
@@ -135,11 +193,11 @@ class MyMC extends DC {
 
 		this.target.innerHTML = '{text}'; // simplicity, there are other methods
 
-		this
-		.bind( 'state', target ) // one way binding
-		.subscribe( 'state', (value) => { // attach your own callbacks
-			console.log(value);
-		});
+		this.bind('state', target) // one way binding
+			.subscribe('state', (value) => {
+				// attach your own callbacks
+				console.log(value);
+			});
 
 		// changing the state will change the DOM
 		this.state.text = 'Hallo Welt'; // also triggers console.log()
@@ -149,38 +207,37 @@ class MyMC extends DC {
 
 ### **Forms and 2-way-binding**
 
-Similar to observables above, you can 2-way-bind an observable object to form input fields. 
+Similar to observables above, you can 2-way-bind an observable object to form input fields.
 
 Changes in the object properties trigger input field changes and vice versa.
 
 code:
 
 ```javascript
-formValuesPlugin(DC);
+formValuePlugin(DC);
 // create a custom micro component class
-targetHtml = /*HTML*/ `
+const targetHtml = `
 <form>
 	<input name="textInput" value="Hallo Welt!"/>
 </form>
 `;
 class MyMC extends DC {
+	formData = { textInput: '' };
+
 	constructor(target) {
 		super(target);
 
 		this.target.innerHTML = targetHtml;
 
-		this.formData = { textInput: '' };
-
-		this
-		.formValues(target, 'formData')// link the form property to the DOM input fields
-		.subscribe( 'formData', (data) => {
-			console.log(data); // the form data object
-		});
+		this.formValues(target, 'formData') // link the form property to the DOM input fields
+			.subscribe('formData', (data) => {
+				console.log(data); // the form data object
+			});
 
 		// now simply changing the form property will change the DOM input fields
-		this.form.textinput = 'Hello World!';
+		this.formData.textInput = 'Hello World!';
 
-		// ... and editing the form input will change the 'form' property
+		// ... and editing the form input will change the 'formData' property
 	}
 }
 ```
@@ -189,7 +246,7 @@ class MyMC extends DC {
 
 #### Native Events
 
-Events and there handlers are defined and triggered inside the system automatically. 
+Events and there handlers are defined and triggered inside the system automatically.
 
 You can use events separately in vanilla JS to communicate with micro components.
 
@@ -232,7 +289,7 @@ class MyMC extends DC {
 	constructor(target) {
 		super(target);
 
-		payload = {
+		const payload = {
 			test: 42,
 		};
 
@@ -243,7 +300,7 @@ class MyMC extends DC {
 
 	// this event handler is attached automatically
 	onCustomEvent(ev) {
-		console.log('onCustomEvent called with', ev.data.test); // "42"
+		console.log('onCustomEvent called with', ev.detail.data.test); // "42"
 	}
 }
 ```

package/dist/MC.min.js

@@ -1 +1 @@
-function e(e,t){let n=t.toLowerCase();return`on`+n in e?n:`_mc`+t[0].toUpperCase()+t.substring(1)}function t(n,r,i){if(n){if(typeof n==`string`){document.querySelectorAll(n).forEach(e=>t(e,r,i));return}n.removeEventListener(e(n,r),i)}}function n(t,r,i,a=!1){if(t){if(typeof t==`string`){document.querySelectorAll(t).forEach(e=>n(e,r,i));return}return t.addEventListener(e(t,r),i,{capture:!1,once:a}),i}}function r(e,t,i){if(e){if(typeof e==`string`){document.querySelectorAll(e).forEach(e=>r(e,t,i));return}return n(e,t,i,!0),i}}var i=class{stopped=!1;constructor(){}stop(){this.stopped=!0}};function a(t,n,r={},o=`l`,s){if(!t)return;if(typeof t==`string`){document.querySelectorAll(t).forEach(e=>a(e,n,r,o));return}let c=/^_mc/.test(n)?n:e(t,n),l=s||new i,u=new CustomEvent(c,{detail:{data:r,control:l},bubbles:!1});l.stopped||/l/.test(o)&&(t.dispatchEvent(u),l.stopped)||/[ud]/.test(o)&&queueMicrotask(()=>{if(o.indexOf(`u`)>-1&&a(t.parentElement,c,r,`lu`,l),o.indexOf(`d`)>-1)for(let e of t.children)a(e,c,r,`ld`)})}var o=new WeakMap;function s(e,t){let n=o.get(e)??new Set;if(n.has(t))return e.adoptedStyleSheets[0];n.add(t),o.set(e,n);let r=new CSSStyleSheet;return r.replaceSync(t),e.adoptedStyleSheets.push(r),r}function c(e,t){let n=e.target,r=n.shadowRoot;!r&&Object.keys(t).some(e=>e.indexOf(`shadow`)===0)&&(r=n.attachShadow({mode:`open`})),Object.keys(t).forEach(i=>{switch(i){case`css`:s(document,t[i]);break;case`targetCss`:s(document,t[i]);break;case`shadowCss`:s(r,t[i]);break;case`shadowHtml`:r.innerHTML=t[i],u(r,e);break;case`targetHtml`:n.innerHTML=t[i],u(n,e);break}})}function l(e,t){let n=t=>{let n=t.match(/^([a-z]+)([A-Z][a-z]*)$/);return n?`./${e.replace(/-/g,`/`)}.${n[1]}.${n[2].toLowerCase()}`:`./${e.replace(/-/g,`/`)}.${t.toLowerCase()}`};return Promise.all(t.map(async e=>{let t=n(e);try{let n=await fetch(t);if(!n.ok)return`file not found: ${t}`;if(t.endsWith(`json`)){let r=await n.text();try{return JSON.parse(r)}catch{return console.error(`could not JSON.parse() asset '${e}' from ${t}:\n`,r),null}}return n.text()}catch{return`file not found: ${t}`}}))}function u(e,t){let r=[...e.querySelectorAll(`*`)];for(let e of r){if(!(e instanceof HTMLElement))continue;let r=[...e.attributes];for(let i of r){let r=i.name.toLowerCase();if(!(`on`+r in e))continue;let o=i.value.trim().split(`|`);if(o.length<2)continue;let[s,c,l]=o;e.removeAttribute(i.name);let u;if(l)try{u=JSON.parse(l)}catch{u=l}s===`this`||s===``?n(e,r,()=>t.trigger(c,u)):n(e,r,()=>a(s,c,u))}}}function d(e,t){return typeof HTMLElement<`u`&&e instanceof HTMLElement&&`_mc`in e&&(t===void 0||t in e._mc)}function f(e,t,n={}){let r=e;`_mc`in e||(r._mc=new b(e));let i=r._mc;return t.length&&!i[t]&&(i[t]=n,e instanceof HTMLElement&&!e.getAttribute(`data-mc`)&&e.setAttribute(`data-mc`,``)),r}function p(e,t){if(!t)return;let n=e._mc;n&&(n[t]&&delete n[t],!Object.keys(n).length&&e instanceof HTMLElement&&e.hasAttribute(`data-mc`)&&e.removeAttribute(`data-mc`))}function m(e){queueMicrotask(()=>{e.trigger(`Init`,null)})}function h(e){let t=e.target,r=Object.getPrototypeOf(e),i=e,a=Object.getOwnPropertyNames(r).filter(e=>/^(on[A-Z]|one[A-Z])/.test(e)&&typeof r[e]==`function`);for(let e of a){let r=/^one/.test(e);n(t,e.replace(/^one?/,``),t=>i[e](t),r)}}function g(e){return Array.from(e.querySelectorAll(`[data-mc]:not(:scope [data-mc] [data-mc])`)).filter(e=>e instanceof HTMLElement&&`_mc`in e).map(e=>e._mc)}function _(e,t){let n=e.parentElement?.closest(`[data-mc]`);for(;n instanceof HTMLElement;){if(`_mc`in n){let e=n._mc;if(t===void 0||t in e)return e}n=n.parentElement?.closest(`[data-mc]`)}return null}var v=class{_target;constructor(e){if(this._target=new WeakRef(e||{}),this instanceof b&&this.constructor!==b){h(this);let e=this.constructor.tag;(e===void 0||e.toUpperCase()===this.target.tagName)&&m(this)}}get target(){return this._target.deref()}},y=class extends v{constructor(e){super(e)}},b=class e extends v{static tag;static _assets={};static assets=[];static attributes={};constructor(t){super(t);let n=this.constructor;if(n===e)return;let r=this.target.tagName.toLowerCase();if(n.tag!==void 0&&r!==n.tag&&n.tag!==``){let t=document.createElement(n.tag);t.classList.add(r),n._originalTag=r,e.add(t,n.name,new n(t)),delete n._originalTag,r.includes(`-`)&&!this.target.isConnected?this.on(`connected`,()=>this.target.replaceWith(t)):this.target.replaceWith(t);return}let i=n.attributes;n.attributes&&Object.keys(n.attributes).forEach(e=>{this.target.setAttribute(e,i[e])});let a=n.assets.filter(e=>!n._assets[e]),o=this;if(n.hasOwnProperty(`_assets`)?c(this,n._assets):n.assets.length&&!n.hasOwnProperty(`_assets`)&&(n._assets={}),a.length?l(n._originalTag||r,a).then(e=>{let t={};a.forEach((n,r)=>{t[n]=e[r]}),c(this,t),n._assets=Object.assign({},n._assets,t);for(let e of[`css`,`targetCss`])t[e]!==void 0&&delete n._assets[e];n.assets=n.assets.filter(e=>e!==`css`&&e!==`targetCss`),o.trigger(`assets`,n._assets)}):[...Object.keys(n._assets)].length&&queueMicrotask(()=>o.trigger(`assets`,n._assets)),n.tag===``){this.target.remove();return}}getAssets(){return this.constructor._assets||{}}static add(e,t,n={}){return f(e,t,n)}static remove(e,t){p(e,t)}static get(e,t,n){if(!d(e))return;let r=e._mc[t];return r instanceof n?r:void 0}off(e,n){t(this.target,e,n)}on(e,t){return n(this.target,e,t)}one(e,t){return r(this.target,e,t)}trigger(e,t={},n=`l`,r){a(this.target,e,t,n,r)}ancestors(e){let t=[],n=_(this.target,e);for(;n;)t.push(n),n=_(n.target,e);return t}closest(e){return _(this.target,e)}children(e){let t=g(this.target);return e===void 0?t:t.filter(t=>e in t)}descendants(e){return Array.from(this.target.querySelectorAll(`[data-mc]`)).filter(e=>e instanceof HTMLElement&&`_mc`in e).map(e=>e._mc).filter(t=>e===void 0||e in t)}};export{b as DC,y as MC,v as McBase,d as isMcHost};
+function e(e,t){let n=t.toLowerCase();return`on`+n in e?n:`_mc`+t[0].toUpperCase()+t.substring(1)}function t(n,r,i){if(n){if(typeof n==`string`){document.querySelectorAll(n).forEach(e=>t(e,r,i));return}n.removeEventListener(e(n,r),i)}}function n(t,r,i,a=!1){if(t){if(typeof t==`string`){document.querySelectorAll(t).forEach(e=>n(e,r,i));return}return t.addEventListener(e(t,r),i,{capture:!1,once:a}),i}}function r(e,t,i){if(e){if(typeof e==`string`){document.querySelectorAll(e).forEach(e=>r(e,t,i));return}return n(e,t,i,!0),i}}var i=class{stopped=!1;constructor(){}stop(){this.stopped=!0}};function a(t,n,r={},o=`l`,s){if(!t)return;if(typeof t==`string`){document.querySelectorAll(t).forEach(e=>a(e,n,r,o));return}let c=/^_mc/.test(n)?n:e(t,n),l=s||new i,u=new CustomEvent(c,{detail:{data:r,control:l},bubbles:!1});l.stopped||/l/.test(o)&&(t.dispatchEvent(u),l.stopped)||/[ud]/.test(o)&&queueMicrotask(()=>{if(o.indexOf(`u`)>-1&&a(t.parentElement,c,r,`lu`,l),o.indexOf(`d`)>-1)for(let e of t.children)a(e,c,r,`ld`)})}var o=new WeakMap;function s(e,t){let n=o.get(e)??new Set;if(n.has(t))return e.adoptedStyleSheets[0];n.add(t),o.set(e,n);let r=new CSSStyleSheet;return r.replaceSync(t),e.adoptedStyleSheets.push(r),r}function c(e,t){let n=e.target,r=n.shadowRoot;!r&&Object.keys(t).some(e=>e.indexOf(`shadow`)===0)&&(r=n.attachShadow({mode:`open`})),Object.keys(t).forEach(i=>{switch(i){case`css`:s(document,t[i]);break;case`targetCss`:s(document,t[i]);break;case`shadowCss`:s(r,t[i]);break;case`shadowHtml`:r.innerHTML=t[i],u(r,e);break;case`targetHtml`:n.innerHTML=t[i],u(n,e);break}})}function l(e,t){let n=t=>{let n=t.match(/^([a-z]+)([A-Z][a-z]*)$/);return n?`./${e.replace(/-/g,`/`)}.${n[1]}.${n[2].toLowerCase()}`:`./${e.replace(/-/g,`/`)}.${t.toLowerCase()}`};return Promise.all(t.map(async e=>{let t=n(e);try{let n=await fetch(t);if(!n.ok)return`file not found: ${t}`;if(t.endsWith(`json`)){let r=await n.text();try{return JSON.parse(r)}catch{return console.error(`could not JSON.parse() asset '${e}' from ${t}:\n`,r),null}}return n.text()}catch{return`file not found: ${t}`}}))}function u(e,t){let r=[...e.querySelectorAll(`*`)];for(let e of r){if(!(e instanceof HTMLElement))continue;let r=[...e.attributes];for(let i of r){let r=i.name.toLowerCase();if(!(`on`+r in e))continue;let o=i.value.trim().split(`|`);if(o.length<2)continue;let[s,c,l]=o;e.removeAttribute(i.name);let u;if(l)try{u=JSON.parse(l)}catch{u=l}s===`this`||s===``?n(e,r,()=>t.trigger(c,u)):n(e,r,()=>a(s,c,u))}}}function d(e,t){return typeof HTMLElement<`u`&&e instanceof HTMLElement&&`_mc`in e&&(t===void 0||t in e._mc)}function f(e,t,n={}){let r=e;`_mc`in e||(r._mc=new b(e));let i=r._mc;return t.length&&!i[t]&&(i[t]=n,e instanceof HTMLElement&&!e.getAttribute(`data-mc`)&&e.setAttribute(`data-mc`,``)),r}function p(e,t){if(!t)return;let n=e._mc;n&&(n[t]&&delete n[t],!Object.keys(n).length&&e instanceof HTMLElement&&e.hasAttribute(`data-mc`)&&e.removeAttribute(`data-mc`))}function m(e){queueMicrotask(()=>{e.trigger(`Init`,null)})}function h(e){let t=e.target,r=Object.getPrototypeOf(e),i=e,a=Object.getOwnPropertyNames(r).filter(e=>/^(on[A-Z]|one[A-Z])/.test(e)&&typeof r[e]==`function`);for(let e of a){let r=/^one/.test(e);n(t,e.replace(/^one?/,``),t=>i[e](t),r)}}function g(e){return Array.from(e.querySelectorAll(`[data-mc]:not(:scope [data-mc] [data-mc])`)).filter(e=>e instanceof HTMLElement&&`_mc`in e).map(e=>e._mc)}function _(e,t){let n=e.parentElement?.closest(`[data-mc]`);for(;n instanceof HTMLElement;){if(`_mc`in n){let e=n._mc;if(t===void 0||t in e)return e}n=n.parentElement?.closest(`[data-mc]`)}return null}var v=class{_target;constructor(e){if(this._target=new WeakRef(e||{}),this instanceof b&&this.constructor!==b){h(this);let e=this.constructor.tag;(e===void 0||e.toUpperCase()===this.target.tagName)&&m(this)}}get target(){return this._target.deref()}},y=class extends v{constructor(e){super(e)}},b=class e extends v{static tag;static _assets={};static assets=[];static _assetsPromise;static attributes={};constructor(t){super(t);let n=this.constructor;if(n===e)return;let r=this.target.tagName.toLowerCase();if(n.tag!==void 0&&r!==n.tag&&n.tag!==``){let t=document.createElement(n.tag);t.classList.add(r),n._originalTag=r,e.add(t,n.name,new n(t)),delete n._originalTag,r.includes(`-`)&&!this.target.isConnected?this.on(`connected`,()=>this.target.replaceWith(t)):this.target.replaceWith(t);return}let i=n.attributes;n.attributes&&Object.keys(n.attributes).forEach(e=>{this.target.setAttribute(e,i[e])});let a=this,o=n.assets.filter(e=>!n._assets[e]);if(Object.keys(n._assets).length&&c(this,n._assets),o.length?(n._assetsPromise||=l(n._originalTag||r,o).then(e=>{let t={};o.forEach((n,r)=>{t[n]=e[r]}),n._assets=Object.assign({},n._assets,t);for(let e of[`css`,`targetCss`])t[e]!==void 0&&delete n._assets[e];return n.assets=n.assets.filter(e=>e!==`css`&&e!==`targetCss`),t}),n._assetsPromise.then(e=>{c(this,e),a.trigger(`assets`,n._assets)})):[...Object.keys(n._assets)].length&&queueMicrotask(()=>a.trigger(`assets`,n._assets)),n.tag===``){this.target.remove();return}}getAssets(){return this.constructor._assets||{}}static add(e,t,n={}){return f(e,t,n)}static remove(e,t){p(e,t)}static get(e,t,n){if(!d(e))return;let r=e._mc[t];return r instanceof n?r:void 0}off(e,n){t(this.target,e,n)}on(e,t){return n(this.target,e,t)}one(e,t){return r(this.target,e,t)}trigger(e,t={},n=`l`,r){a(this.target,e,t,n,r)}ancestors(e){let t=[],n=_(this.target,e);for(;n;)t.push(n),n=_(n.target,e);return t}closest(e){return _(this.target,e)}children(e){let t=g(this.target);return e===void 0?t:t.filter(t=>e in t)}descendants(e){return Array.from(this.target.querySelectorAll(`[data-mc]`)).filter(e=>e instanceof HTMLElement&&`_mc`in e).map(e=>e._mc).filter(t=>e===void 0||e in t)}};export{b as DC,y as MC,v as McBase,d as isMcHost};

package/dist/autoload.min.js

@@ -1 +1 @@
-function e(e,t){let n=t.toLowerCase();return`on`+n in e?n:`_mc`+t[0].toUpperCase()+t.substring(1)}function t(n,r,i){if(n){if(typeof n==`string`){document.querySelectorAll(n).forEach(e=>t(e,r,i));return}n.removeEventListener(e(n,r),i)}}function n(t,r,i,a=!1){if(t){if(typeof t==`string`){document.querySelectorAll(t).forEach(e=>n(e,r,i));return}return t.addEventListener(e(t,r),i,{capture:!1,once:a}),i}}function r(e,t,i){if(e){if(typeof e==`string`){document.querySelectorAll(e).forEach(e=>r(e,t,i));return}return n(e,t,i,!0),i}}var i=class{stopped=!1;constructor(){}stop(){this.stopped=!0}};function a(t,n,r={},o=`l`,s){if(!t)return;if(typeof t==`string`){document.querySelectorAll(t).forEach(e=>a(e,n,r,o));return}let c=/^_mc/.test(n)?n:e(t,n),l=s||new i,u=new CustomEvent(c,{detail:{data:r,control:l},bubbles:!1});l.stopped||/l/.test(o)&&(t.dispatchEvent(u),l.stopped)||/[ud]/.test(o)&&queueMicrotask(()=>{if(o.indexOf(`u`)>-1&&a(t.parentElement,c,r,`lu`,l),o.indexOf(`d`)>-1)for(let e of t.children)a(e,c,r,`ld`)})}var o=new WeakMap;function s(e,t){let n=o.get(e)??new Set;if(n.has(t))return e.adoptedStyleSheets[0];n.add(t),o.set(e,n);let r=new CSSStyleSheet;return r.replaceSync(t),e.adoptedStyleSheets.push(r),r}function c(e,t){let n=e.target,r=n.shadowRoot;!r&&Object.keys(t).some(e=>e.indexOf(`shadow`)===0)&&(r=n.attachShadow({mode:`open`})),Object.keys(t).forEach(i=>{switch(i){case`css`:s(document,t[i]);break;case`targetCss`:s(document,t[i]);break;case`shadowCss`:s(r,t[i]);break;case`shadowHtml`:r.innerHTML=t[i],u(r,e);break;case`targetHtml`:n.innerHTML=t[i],u(n,e);break}})}function l(e,t){let n=t=>{let n=t.match(/^([a-z]+)([A-Z][a-z]*)$/);return n?`./${e.replace(/-/g,`/`)}.${n[1]}.${n[2].toLowerCase()}`:`./${e.replace(/-/g,`/`)}.${t.toLowerCase()}`};return Promise.all(t.map(async e=>{let t=n(e);try{let n=await fetch(t);if(!n.ok)return`file not found: ${t}`;if(t.endsWith(`json`)){let r=await n.text();try{return JSON.parse(r)}catch{return console.error(`could not JSON.parse() asset '${e}' from ${t}:\n`,r),null}}return n.text()}catch{return`file not found: ${t}`}}))}function u(e,t){let r=[...e.querySelectorAll(`*`)];for(let e of r){if(!(e instanceof HTMLElement))continue;let r=[...e.attributes];for(let i of r){let r=i.name.toLowerCase();if(!(`on`+r in e))continue;let o=i.value.trim().split(`|`);if(o.length<2)continue;let[s,c,l]=o;e.removeAttribute(i.name);let u;if(l)try{u=JSON.parse(l)}catch{u=l}s===`this`||s===``?n(e,r,()=>t.trigger(c,u)):n(e,r,()=>a(s,c,u))}}}function d(e,t){return typeof HTMLElement<`u`&&e instanceof HTMLElement&&`_mc`in e&&(t===void 0||t in e._mc)}function f(e,t,n={}){let r=e;`_mc`in e||(r._mc=new y(e));let i=r._mc;return t.length&&!i[t]&&(i[t]=n,e instanceof HTMLElement&&!e.getAttribute(`data-mc`)&&e.setAttribute(`data-mc`,``)),r}function p(e,t){if(!t)return;let n=e._mc;n&&(n[t]&&delete n[t],!Object.keys(n).length&&e instanceof HTMLElement&&e.hasAttribute(`data-mc`)&&e.removeAttribute(`data-mc`))}function m(e){queueMicrotask(()=>{e.trigger(`Init`,null)})}function h(e){let t=e.target,r=Object.getPrototypeOf(e),i=e,a=Object.getOwnPropertyNames(r).filter(e=>/^(on[A-Z]|one[A-Z])/.test(e)&&typeof r[e]==`function`);for(let e of a){let r=/^one/.test(e);n(t,e.replace(/^one?/,``),t=>i[e](t),r)}}function g(e){return Array.from(e.querySelectorAll(`[data-mc]:not(:scope [data-mc] [data-mc])`)).filter(e=>e instanceof HTMLElement&&`_mc`in e).map(e=>e._mc)}function _(e,t){let n=e.parentElement?.closest(`[data-mc]`);for(;n instanceof HTMLElement;){if(`_mc`in n){let e=n._mc;if(t===void 0||t in e)return e}n=n.parentElement?.closest(`[data-mc]`)}return null}var v=class{_target;constructor(e){if(this._target=new WeakRef(e||{}),this instanceof y&&this.constructor!==y){h(this);let e=this.constructor.tag;(e===void 0||e.toUpperCase()===this.target.tagName)&&m(this)}}get target(){return this._target.deref()}},y=class e extends v{static tag;static _assets={};static assets=[];static attributes={};constructor(t){super(t);let n=this.constructor;if(n===e)return;let r=this.target.tagName.toLowerCase();if(n.tag!==void 0&&r!==n.tag&&n.tag!==``){let t=document.createElement(n.tag);t.classList.add(r),n._originalTag=r,e.add(t,n.name,new n(t)),delete n._originalTag,r.includes(`-`)&&!this.target.isConnected?this.on(`connected`,()=>this.target.replaceWith(t)):this.target.replaceWith(t);return}let i=n.attributes;n.attributes&&Object.keys(n.attributes).forEach(e=>{this.target.setAttribute(e,i[e])});let a=n.assets.filter(e=>!n._assets[e]),o=this;if(n.hasOwnProperty(`_assets`)?c(this,n._assets):n.assets.length&&!n.hasOwnProperty(`_assets`)&&(n._assets={}),a.length?l(n._originalTag||r,a).then(e=>{let t={};a.forEach((n,r)=>{t[n]=e[r]}),c(this,t),n._assets=Object.assign({},n._assets,t);for(let e of[`css`,`targetCss`])t[e]!==void 0&&delete n._assets[e];n.assets=n.assets.filter(e=>e!==`css`&&e!==`targetCss`),o.trigger(`assets`,n._assets)}):[...Object.keys(n._assets)].length&&queueMicrotask(()=>o.trigger(`assets`,n._assets)),n.tag===``){this.target.remove();return}}getAssets(){return this.constructor._assets||{}}static add(e,t,n={}){return f(e,t,n)}static remove(e,t){p(e,t)}static get(e,t,n){if(!d(e))return;let r=e._mc[t];return r instanceof n?r:void 0}off(e,n){t(this.target,e,n)}on(e,t){return n(this.target,e,t)}one(e,t){return r(this.target,e,t)}trigger(e,t={},n=`l`,r){a(this.target,e,t,n,r)}ancestors(e){let t=[],n=_(this.target,e);for(;n;)t.push(n),n=_(n.target,e);return t}closest(e){return _(this.target,e)}children(e){let t=g(this.target);return e===void 0?t:t.filter(t=>e in t)}descendants(e){return Array.from(this.target.querySelectorAll(`[data-mc]`)).filter(e=>e instanceof HTMLElement&&`_mc`in e).map(e=>e._mc).filter(t=>e===void 0||e in t)}},b=new Set;function x(e){return()=>{let t=Array.from(document.querySelectorAll(`[data-mc*="${e}"]`)).filter(e=>e instanceof HTMLElement);if(t.length===0)return;let n=customElements.get(e);for(let r of t){try{y.add(r,n.name,new n(r))}catch{if(`create`in n&&typeof n.create==`function`){let e=n.create(r);if(!d(e))throw`create() of Class ${n.name} did not return a McHost.`;e.setAttribute(`data-mc`,r.getAttribute(`data-mc`)??``),r.replaceWith(e),r=e}else throw`Class ${n.name} doesn't have a callable constructor AND class doesn't have a static .create() method.`}let t=r.getAttribute(`data-mc`).split(` `).filter(t=>t!==e&&t!==``).join(` `).trim();r.setAttribute(`data-mc`,t)}}}function S(e){if(b.has(e))return;b.add(e);let t=`./`+e.split(`-`).join(`/`)+`.js`,n=document.createElement(`script`);n.setAttribute(`src`,t),n.setAttribute(`blocking`,`render`),n.async=!0,n.setAttribute(`type`,`module`),n.setAttribute(`data-name`,e),n.setAttribute(`loading`,``),customElements.whenDefined(e).then(x(e)),n.addEventListener(`load`,t=>{b.delete(e),document.head.querySelector(`script[data-name="${e}"]`)?.remove()}),n.addEventListener(`error`,e=>{console.error(`could not load DC code from`,t)}),document.head.append(n)}function C(){[...document.querySelectorAll(`:not(:defined)`)].filter(e=>!!e&&!customElements.get(e.tagName.toLowerCase())&&!b.has(e.tagName.toLowerCase())).forEach(e=>{S(e.tagName.toLowerCase())}),[...document.querySelectorAll(`[data-mc]:not([data-mc=""]`)].filter(e=>!!e).forEach(e=>{(e.getAttribute(`data-mc`)?.split(` `).filter(e=>e!==``))?.forEach(e=>{let t=customElements.get(e);!b.has(e)&&!t?S(e):t&&x(e)()})})}var w=null;function T(e=!0){return e?w?!0:(w=new MutationObserver(C),setTimeout(()=>{w.observe(document.body,{childList:!0,subtree:!0}),C()},5),window.autoload??=T,!0):(w&&=(w.disconnect(),null),!1)}T.state=b;export{T as autoload};
+function e(e,t){let n=t.toLowerCase();return`on`+n in e?n:`_mc`+t[0].toUpperCase()+t.substring(1)}function t(n,r,i){if(n){if(typeof n==`string`){document.querySelectorAll(n).forEach(e=>t(e,r,i));return}n.removeEventListener(e(n,r),i)}}function n(t,r,i,a=!1){if(t){if(typeof t==`string`){document.querySelectorAll(t).forEach(e=>n(e,r,i));return}return t.addEventListener(e(t,r),i,{capture:!1,once:a}),i}}function r(e,t,i){if(e){if(typeof e==`string`){document.querySelectorAll(e).forEach(e=>r(e,t,i));return}return n(e,t,i,!0),i}}var i=class{stopped=!1;constructor(){}stop(){this.stopped=!0}};function a(t,n,r={},o=`l`,s){if(!t)return;if(typeof t==`string`){document.querySelectorAll(t).forEach(e=>a(e,n,r,o));return}let c=/^_mc/.test(n)?n:e(t,n),l=s||new i,u=new CustomEvent(c,{detail:{data:r,control:l},bubbles:!1});l.stopped||/l/.test(o)&&(t.dispatchEvent(u),l.stopped)||/[ud]/.test(o)&&queueMicrotask(()=>{if(o.indexOf(`u`)>-1&&a(t.parentElement,c,r,`lu`,l),o.indexOf(`d`)>-1)for(let e of t.children)a(e,c,r,`ld`)})}var o=new WeakMap;function s(e,t){let n=o.get(e)??new Set;if(n.has(t))return e.adoptedStyleSheets[0];n.add(t),o.set(e,n);let r=new CSSStyleSheet;return r.replaceSync(t),e.adoptedStyleSheets.push(r),r}function c(e,t){let n=e.target,r=n.shadowRoot;!r&&Object.keys(t).some(e=>e.indexOf(`shadow`)===0)&&(r=n.attachShadow({mode:`open`})),Object.keys(t).forEach(i=>{switch(i){case`css`:s(document,t[i]);break;case`targetCss`:s(document,t[i]);break;case`shadowCss`:s(r,t[i]);break;case`shadowHtml`:r.innerHTML=t[i],u(r,e);break;case`targetHtml`:n.innerHTML=t[i],u(n,e);break}})}function l(e,t){let n=t=>{let n=t.match(/^([a-z]+)([A-Z][a-z]*)$/);return n?`./${e.replace(/-/g,`/`)}.${n[1]}.${n[2].toLowerCase()}`:`./${e.replace(/-/g,`/`)}.${t.toLowerCase()}`};return Promise.all(t.map(async e=>{let t=n(e);try{let n=await fetch(t);if(!n.ok)return`file not found: ${t}`;if(t.endsWith(`json`)){let r=await n.text();try{return JSON.parse(r)}catch{return console.error(`could not JSON.parse() asset '${e}' from ${t}:\n`,r),null}}return n.text()}catch{return`file not found: ${t}`}}))}function u(e,t){let r=[...e.querySelectorAll(`*`)];for(let e of r){if(!(e instanceof HTMLElement))continue;let r=[...e.attributes];for(let i of r){let r=i.name.toLowerCase();if(!(`on`+r in e))continue;let o=i.value.trim().split(`|`);if(o.length<2)continue;let[s,c,l]=o;e.removeAttribute(i.name);let u;if(l)try{u=JSON.parse(l)}catch{u=l}s===`this`||s===``?n(e,r,()=>t.trigger(c,u)):n(e,r,()=>a(s,c,u))}}}function d(e,t){return typeof HTMLElement<`u`&&e instanceof HTMLElement&&`_mc`in e&&(t===void 0||t in e._mc)}function f(e,t,n={}){let r=e;`_mc`in e||(r._mc=new y(e));let i=r._mc;return t.length&&!i[t]&&(i[t]=n,e instanceof HTMLElement&&!e.getAttribute(`data-mc`)&&e.setAttribute(`data-mc`,``)),r}function p(e,t){if(!t)return;let n=e._mc;n&&(n[t]&&delete n[t],!Object.keys(n).length&&e instanceof HTMLElement&&e.hasAttribute(`data-mc`)&&e.removeAttribute(`data-mc`))}function m(e){queueMicrotask(()=>{e.trigger(`Init`,null)})}function h(e){let t=e.target,r=Object.getPrototypeOf(e),i=e,a=Object.getOwnPropertyNames(r).filter(e=>/^(on[A-Z]|one[A-Z])/.test(e)&&typeof r[e]==`function`);for(let e of a){let r=/^one/.test(e);n(t,e.replace(/^one?/,``),t=>i[e](t),r)}}function g(e){return Array.from(e.querySelectorAll(`[data-mc]:not(:scope [data-mc] [data-mc])`)).filter(e=>e instanceof HTMLElement&&`_mc`in e).map(e=>e._mc)}function _(e,t){let n=e.parentElement?.closest(`[data-mc]`);for(;n instanceof HTMLElement;){if(`_mc`in n){let e=n._mc;if(t===void 0||t in e)return e}n=n.parentElement?.closest(`[data-mc]`)}return null}var v=class{_target;constructor(e){if(this._target=new WeakRef(e||{}),this instanceof y&&this.constructor!==y){h(this);let e=this.constructor.tag;(e===void 0||e.toUpperCase()===this.target.tagName)&&m(this)}}get target(){return this._target.deref()}},y=class e extends v{static tag;static _assets={};static assets=[];static _assetsPromise;static attributes={};constructor(t){super(t);let n=this.constructor;if(n===e)return;let r=this.target.tagName.toLowerCase();if(n.tag!==void 0&&r!==n.tag&&n.tag!==``){let t=document.createElement(n.tag);t.classList.add(r),n._originalTag=r,e.add(t,n.name,new n(t)),delete n._originalTag,r.includes(`-`)&&!this.target.isConnected?this.on(`connected`,()=>this.target.replaceWith(t)):this.target.replaceWith(t);return}let i=n.attributes;n.attributes&&Object.keys(n.attributes).forEach(e=>{this.target.setAttribute(e,i[e])});let a=this,o=n.assets.filter(e=>!n._assets[e]);if(Object.keys(n._assets).length&&c(this,n._assets),o.length?(n._assetsPromise||=l(n._originalTag||r,o).then(e=>{let t={};o.forEach((n,r)=>{t[n]=e[r]}),n._assets=Object.assign({},n._assets,t);for(let e of[`css`,`targetCss`])t[e]!==void 0&&delete n._assets[e];return n.assets=n.assets.filter(e=>e!==`css`&&e!==`targetCss`),t}),n._assetsPromise.then(e=>{c(this,e),a.trigger(`assets`,n._assets)})):[...Object.keys(n._assets)].length&&queueMicrotask(()=>a.trigger(`assets`,n._assets)),n.tag===``){this.target.remove();return}}getAssets(){return this.constructor._assets||{}}static add(e,t,n={}){return f(e,t,n)}static remove(e,t){p(e,t)}static get(e,t,n){if(!d(e))return;let r=e._mc[t];return r instanceof n?r:void 0}off(e,n){t(this.target,e,n)}on(e,t){return n(this.target,e,t)}one(e,t){return r(this.target,e,t)}trigger(e,t={},n=`l`,r){a(this.target,e,t,n,r)}ancestors(e){let t=[],n=_(this.target,e);for(;n;)t.push(n),n=_(n.target,e);return t}closest(e){return _(this.target,e)}children(e){let t=g(this.target);return e===void 0?t:t.filter(t=>e in t)}descendants(e){return Array.from(this.target.querySelectorAll(`[data-mc]`)).filter(e=>e instanceof HTMLElement&&`_mc`in e).map(e=>e._mc).filter(t=>e===void 0||e in t)}};function b(e){return e.split(`-`).join(`/`)}function x(e){return`./`+b(e)+`.js`}var S=new Set;function C(e){return()=>{let t=Array.from(document.querySelectorAll(`[data-mc*="${e}"]`)).filter(e=>e instanceof HTMLElement);if(t.length===0)return;let n=customElements.get(e);for(let r of t){try{y.add(r,n.name,new n(r))}catch{if(`create`in n&&typeof n.create==`function`){let e=n.create(r);if(!d(e))throw`create() of Class ${n.name} did not return a McHost.`;e.setAttribute(`data-mc`,r.getAttribute(`data-mc`)??``),r.replaceWith(e),r=e}else throw`Class ${n.name} doesn't have a callable constructor AND class doesn't have a static .create() method.`}let t=r.getAttribute(`data-mc`).split(` `).filter(t=>t!==e&&t!==``).join(` `).trim();r.setAttribute(`data-mc`,t)}}}function w(e){if(S.has(e))return;S.add(e);let t=x(e),n=document.createElement(`script`);n.setAttribute(`src`,t),n.setAttribute(`blocking`,`render`),n.async=!0,n.setAttribute(`type`,`module`),n.setAttribute(`data-name`,e),n.setAttribute(`loading`,``),customElements.whenDefined(e).then(C(e)),n.addEventListener(`load`,t=>{S.delete(e),document.head.querySelector(`script[data-name="${e}"]`)?.remove()}),n.addEventListener(`error`,e=>{console.error(`could not load DC code from`,t)}),document.head.append(n)}function T(){[...document.querySelectorAll(`:not(:defined)`)].filter(e=>!!e&&!customElements.get(e.tagName.toLowerCase())&&!S.has(e.tagName.toLowerCase())).forEach(e=>{w(e.tagName.toLowerCase())}),[...document.querySelectorAll(`[data-mc]:not([data-mc=""]`)].filter(e=>!!e).forEach(e=>{(e.getAttribute(`data-mc`)?.split(` `).filter(e=>e!==``))?.forEach(e=>{let t=customElements.get(e);!S.has(e)&&!t?w(e):t&&C(e)()})})}var E=null;function D(e=!0){return e?E?!0:(E=new MutationObserver(T),setTimeout(()=>{E.observe(document.body,{childList:!0,subtree:!0}),T()},5),window.autoload??=D,!0):(E&&=(E.disconnect(),null),!1)}D.state=S;export{D as autoload};

package/dist/cli/create.d.ts

@@ -0,0 +1,53 @@
+/**
+Project scaffolding for `mc create --namespace xxx`.
+
+Pure, filesystem-free logic: given a namespace it returns the files of a complete,
+working Micro Components dev environment and their contents. The starter component's
+path is not re-derived here — it comes from {@link tagPath}, the same primitive the
+runtime autoload loader uses, so the scaffold and the runtime can never disagree about
+where a component lives.
+
+The namespace is the first segment of every component tag, so `xxx` makes `src/xxx/`
+the home of tags like `<xxx-app>` (tagPath `xxx-app` → `xxx/app`). The generated
+environment mirrors the repo's own demos: a Vite dev server serving `src/` straight,
+a page shell at that root that turns on `autoload(true)`, and a starter component with
+companion `targetHtml` / `targetCss` assets. Because the page shell is the autoload
+base, `import.meta.url` + `tagPath('xxx-app')` resolves to `src/xxx/app.js` — the
+compiled starter.
+
+@module CLI/Project
+*/
+/**
+Whether a string is a valid project namespace: 1 to 4 lowercase letters.
+
+@example
+```ts
+console.log(isValidNamespace('mc'));
+console.log(isValidNamespace('mcxyz'));
+console.log(isValidNamespace('toolong'));
+```
+@param ns - Candidate namespace.
+*/
+export declare function isValidNamespace(ns: string): boolean;
+/** Result of {@link scaffoldProject}. */
+export interface ProjectResult {
+    /** Files to write, keyed by path relative to the project root. */
+    files: Record<string, string>;
+    /** The validated namespace. */
+    namespace: string;
+}
+/**
+Builds the files of a complete dev environment for a namespace.
+
+@example
+```ts
+const { namespace, files } = scaffoldProject('mc');
+console.log(namespace);
+console.log(Object.keys(files));
+```
+@param namespace - 1 to 4 lowercase letters; becomes the `src/<namespace>/` folder and
+the first segment of every component tag.
+@throws If `namespace` is not 1 to 4 lowercase letters.
+*/
+export declare function scaffoldProject(namespace: string): ProjectResult;
+//# sourceMappingURL=create.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/cli/create.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;EAkBE;AAUF;;;;;;;;;;EAUE;AACF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC7B,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;EAYE;AACF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAuBhE"}