@twobirds/microcomponents 0.9.0 → 0.10.0

package/dist/cli/index.js

@@ -1,4 +1,1810 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { existsSync, watch } from "node:fs";
+import path from "node:path";
+import { createServer } from "node:http";
+//#region src/utils/resolveComponentPath.ts
+/**
+@module Autoload
+
+Single source of truth for the tag-to-file convention: hyphens become path
+separators, so `my-card` resolves to `./my/card.js`. Imported by the runtime
+autoload loader and by build-time tooling so both agree on the path without
+either duplicating the rule.
+*/
+/**
+The tag-to-path primitive: hyphens become path separators, with no prefix or
+extension. `my-card` → `my/card`. The single source of truth for the
+convention; {@link resolveComponentPath} and build-time tooling both derive
+their paths from it so neither duplicates the rule.
+
+@example Returns `'my/card'` for `my-card`, and `'app/header'` for `app-header`.
+```ts
+tagPath('my-card');
+tagPath('app-header');
+```
+@hidden
+@group Autoload
+*/
+function tagPath(tag) {
+	return tag.split("-").join("/");
+}
+//#endregion
+//#region src/cli/scaffold.ts
+/**
+Scaffolding for new micro components.
+
+Pure, filesystem-free logic: given a tag name it returns the files to write and
+their contents. The tag-to-path rule 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.
+
+Companion assets follow the runtime's variant convention (see `loadAssets` /
+`processAssets`): a camelCase descriptor maps to a dotted filename, e.g.
+`'targetHtml'` → `{path}.target.html`, `'shadowCss'` → `{path}.shadow.css`, and
+the unvariant `'css'` → `{path}.css` (the document-level stylesheet where CSS
+custom properties / design tokens live).
+
+@module CLI/Scaffold
+*/
+var TAG_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
+/**
+Whether a string is a valid micro component tag name.
+
+@example
+```ts
+console.log(isValidComponentTag('my-card'));
+console.log(isValidComponentTag('mycard'));
+```
+*/
+function isValidComponentTag(tag) {
+	return TAG_RE.test(tag);
+}
+/**
+Builds the files for a new micro component from its tag name.
+
+@example
+```ts
+const { className, files } = scaffoldComponent('my-card', {
+assets: ['targetHtml', 'targetCss'],
+});
+console.log(className);
+console.log(Object.keys(files));
+```
+@param tag - Kebab-case component tag, e.g. `my-card`.
+@param options - Which companion assets to emit and whether to use `.js`.
+@throws If `tag` is not a valid custom element name.
+*/
+function scaffoldComponent(tag, options = {}) {
+	if (!isValidComponentTag(tag)) throw new Error(`invalid component tag "${tag}": must be kebab-case with at least one hyphen (e.g. "my-card")`);
+	const className = tag.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+	const ext = options.js ? "js" : "ts";
+	const ctorParam = options.js ? "target" : "target: HTMLElement";
+	const base = tagPath(tag);
+	const assets = [...new Set(options.assets ?? [])];
+	const files = {};
+	files[`${base}.${ext}`] = componentSource(tag, ctorParam, assets);
+	for (const kind of assets) files[assetFile(tag, kind)] = assetSource(kind, tag);
+	return {
+		files,
+		className
+	};
+}
+function assetFile(tag, kind) {
+	const m = kind.match(/^([a-z]+)([A-Z][a-z]*)$/);
+	const suffix = m ? `.${m[1]}.${m[2].toLowerCase()}` : `.${kind.toLowerCase()}`;
+	return `${tagPath(tag)}${suffix}`;
+}
+function componentSource(tag, ctorParam, assets) {
+	const lines = [
+		`import { DC, defineCE } from '@twobirds/microcomponents';`,
+		``,
+		`/**`,
+		`\`${tag}\` — describe what this micro component does.`,
+		``,
+		`@example`,
+		"```html",
+		`<${tag}></${tag}>`,
+		"```",
+		`*/`,
+		`defineCE(`,
+		`\t'${tag}',`,
+		`\tclass extends DC {`
+	];
+	if (assets.length) lines.push(`\t\tstatic assets = [${assets.map((a) => `'${a}'`).join(", ")}];`);
+	lines.push(`\t\tconstructor(${ctorParam}) {`, `\t\t\tsuper(target);`, `\t\t}`, `\t}`, `);`, ``);
+	return lines.join("\n");
+}
+function assetSource(kind, tag) {
+	switch (kind) {
+		case "css": return [
+			":root {",
+			"	/* design tokens (CSS custom properties) */",
+			"}",
+			""
+		].join("\n");
+		case "targetCss": return [
+			`${tag} {`,
+			"	display: block;",
+			"}",
+			""
+		].join("\n");
+		case "shadowCss": return [
+			":host {",
+			"	display: block;",
+			"}",
+			""
+		].join("\n");
+		default: return "<slot></slot>\n";
+	}
+}
+//#endregion
+//#region src/utils/helpers.ts
+/**
+* Converts a kebab-case string to PascalCase.
+* Example: 'my-component-name' -> 'MyComponentName'
+* @param str - The kebab-case string to convert.
+* @returns The converted PascalCase string.
+*
+* @example
+* ```ts
+* console.log(kebabToPascal('my-element'));
+* ```
+*/
+function kebabToPascal(str) {
+	return str.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+//#endregion
+//#region src/cli/create.ts
+/**
+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 follows the three-path chain the library's own demos use: `src/` holds the
+authored sources, `build/` receives the per-file `tsc` output that the dev server
+serves through `autoload()`, and `public/` receives the bundled production site. Because
+the dev shell is the autoload base, `import.meta.url` + `tagPath('xxx-app')` resolves to
+`build/xxx/app.js` — the compiled starter.
+
+@module CLI/Project
+*/
+/** The starter component tag for a namespace: `xxx` → `xxx-app`. */
+function starterTag(namespace) {
+	return `${namespace}-app`;
+}
+/**
+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.
+*/
+function isValidNamespace(ns) {
+	return /^[a-z]{1,4}$/.test(ns);
+}
+/**
+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.
+*/
+function scaffoldProject(namespace) {
+	if (!isValidNamespace(namespace)) throw new Error(`invalid namespace "${namespace}": must be 1 to 4 lowercase letters (e.g. "mc")`);
+	const tag = starterTag(namespace);
+	const base = tagPath(tag);
+	const files = {};
+	files["package.json"] = packageJson(namespace);
+	files["tsconfig.json"] = tsconfig();
+	files[".gitignore"] = gitignore();
+	files["opencode.jsonc"] = opencodeConfig();
+	files[".opencode/skills/components/SKILL.md"] = componentSkill(namespace, tag);
+	files["README.md"] = readme(namespace, tag);
+	files["src/index.html"] = prodShell(tag);
+	files["src/index-dev.html"] = devShell(namespace, tag);
+	files[`src/${base}.ts`] = appSource(namespace, tag);
+	files[`src/${base}.target.html`] = appHtml(namespace);
+	files[`src/${base}.target.css`] = appCss(tag);
+	files[`src/${namespace}/bundle.ts`] = bundle();
+	files["src/bundle.json"] = bundleConfig(namespace);
+	return {
+		files,
+		namespace
+	};
+}
+function packageJson(namespace) {
+	return JSON.stringify({
+		name: `${namespace}-app`,
+		private: true,
+		type: "module",
+		scripts: {
+			dev: "mc dev",
+			build: "tsc -p tsconfig.json && mc bundle",
+			preview: "mc preview",
+			typecheck: "tsc --noEmit -p tsconfig.json"
+		},
+		dependencies: { "@twobirds/microcomponents": "^0.10.0" },
+		devDependencies: { typescript: "^6.0.3" }
+	}, null, "	");
+}
+function tsconfig() {
+	return JSON.stringify({
+		compilerOptions: {
+			target: "ESNext",
+			module: "ESNext",
+			moduleResolution: "Bundler",
+			lib: [
+				"ESNext",
+				"DOM",
+				"DOM.Iterable"
+			],
+			strict: true,
+			esModuleInterop: true,
+			skipLibCheck: true,
+			rootDir: "src",
+			outDir: "build",
+			removeComments: true
+		},
+		include: ["src/**/*.ts"]
+	}, null, "	");
+}
+function gitignore() {
+	return `node_modules/
+build/
+public/
+`;
+}
+function opencodeConfig() {
+	return JSON.stringify({
+		$schema: "https://opencode.ai/config.json",
+		lsp: true,
+		mcp: { microcomponents: {
+			type: "local",
+			command: [
+				"npx",
+				"-p",
+				"@twobirds/microcomponents",
+				"microcomponents-mcp"
+			],
+			enabled: true
+		} }
+	}, null, "	");
+}
+function componentSkill(namespace, tag) {
+	return `---
+name: components
+description: Use when adding, editing, naming, or wiring a micro component in this project, registering a component in the bundle, choosing an event dispatch target, running dev or build, or touching build/ or public/.
+---
+
+# Micro Components project
+
+Namespace \`${namespace}\`. Every tag starts with \`${namespace}-\`. Components live in \`src/${namespace}/\` and the starter is \`<${tag}>\`.
+
+## The chain
+
+\`src/\` → \`build/\` → \`public/\`
+
+- \`src/\` is the only folder to edit.
+- \`build/\` is the \`tsc\` output plus mirrored companion assets, served by the dev server. Generated.
+- \`public/\` is the production site: \`bundle.js\` with companion assets inlined, \`bundle.css\`, \`index.html\`. Generated.
+
+Never edit, rename, or delete anything under \`build/\` or \`public/\`. Change \`src/\` and rebuild.
+
+## Add a component
+
+\`\`\`sh
+npx mc new ${namespace}-name --target-html --target-css
+\`\`\`
+
+The tag must be kebab-case with at least one hyphen. \`ns-name\` becomes \`src/ns/name.ts\`: the first hyphen becomes the folder, which is the same rule the autoloader uses.
+
+Register the component so the production bundle picks it up:
+
+\`\`\`ts
+// src/${namespace}/bundle.ts
+import './name.js';
+\`\`\`
+
+The bundler reads \`src/bundle.json\`; its \`entry\` points at this barrel, so the barrel is what \`public/bundle.js\` is built from.
+
+A component missing from the barrel loads in dev through \`autoload()\` but is absent from \`public/bundle.js\`.
+
+## Companion assets
+
+A camelCase descriptor maps to a dotted filename and is listed in \`static assets\`:
+
+| descriptor | file | role |
+| --- | --- | --- |
+| \`css\` | \`name.css\` | document-level tokens under \`:root\` |
+| \`targetCss\` | \`name.target.css\` | styles scoped to the host tag |
+| \`shadowCss\` | \`name.shadow.css\` | styles inside the shadow root |
+| \`html\` | \`name.html\` | light-DOM template |
+| \`targetHtml\` | \`name.target.html\` | template for \`target.innerHTML\`, \`{key}\` tokens filled by \`parse()\` |
+| \`shadowHtml\` | \`name.shadow.html\` | template for \`shadowRoot.innerHTML\` |
+
+The loader fetches exactly the listed descriptors, so every entry in \`static assets\` needs its file.
+
+## Events
+
+Prefer a direct target with the default local dispatch and a typed payload:
+
+\`\`\`ts
+target.dispatchEvent(
+	new CustomEvent('${namespace}:action', { detail: { data: { id: 'x' } } })
+);
+\`\`\`
+
+Bubble up or down the tree only when the receiver cannot be named.
+
+## Verify
+
+\`\`\`sh
+pnpm typecheck
+pnpm dev
+pnpm build
+pnpm preview
+\`\`\`
+
+\`mc clean\` removes \`build/\`, \`public/\` and \`coverage/\`.
+
+## API reference
+
+The \`microcomponents\` MCP server registered in \`opencode.jsonc\` documents every export, the event system, and the concept essays. Query it instead of guessing an API.
+`;
+}
+function readme(namespace, tag) {
+	return `# ${namespace} App
+
+A Micro Components project scaffolded by \`mc create --namespace ${namespace}\`.
+
+## Install
+
+\`\`\`sh
+pnpm install
+\`\`\`
+
+## Dev
+
+\`\`\`sh
+pnpm dev
+\`\`\`
+
+The dev server runs \`tsc -w\` and serves \`build/\`, so a saved component reaches the
+browser through \`autoload()\` with no bundling. Companion \`.css\`, \`.html\` and \`.json\`
+files are mirrored into \`build/\` next to the compiled component, which is where the
+autoloader looks for them.
+
+## Build
+
+\`\`\`sh
+pnpm build
+\`\`\`
+
+\`public/\` is the production site: one \`bundle.js\` with every companion asset
+inlined by \`mc bundle\`, the concatenated \`bundle.css\`, and the page shell. A
+single script tag loads it, no autoloader needed.
+
+The bundle is driven by \`src/bundle.json\`: \`entry\` names the barrel to bundle,
+\`fileName\` the output, and \`outDir\` the folder.
+
+\`\`\`sh
+pnpm preview
+\`\`\`
+
+## Type-check
+
+\`\`\`sh
+pnpm typecheck
+\`\`\`
+
+\`tsconfig.json\` compiles \`src/\` into \`build/\`.
+
+## Components
+
+Components live in \`src/${namespace}/\`. The starter is \`<${tag}>\` (\`src/${namespace}/app.ts\`).
+
+Add a component with:
+
+\`\`\`sh
+npx mc new ${namespace}-name --target-html --target-css
+\`\`\`
+
+Then add its import to \`src/${namespace}/bundle.ts\` so the production bundle picks it up.
+
+\`.opencode/skills/components/SKILL.md\` carries the same rules for opencode: the
+\`src/\` → \`build/\` → \`public/\` chain, the asset descriptors, the bundle registration,
+and the event dispatch preference.
+`;
+}
+function prodShell(tag) {
+	return `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>${tag.replace("-app", " App")}</title>
+		<script type="module" src="bundle.js"><\/script>
+		<link rel="stylesheet" href="./bundle.css" />
+	</head>
+	<body>
+		<${tag}></${tag}>
+	</body>
+</html>
+`;
+}
+function devShell(namespace, tag) {
+	return `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>${namespace} App</title>
+		<script type="importmap">
+			{ "imports": { "@twobirds/microcomponents": "/microcomponents.min.js" } }
+		<\/script>
+		<script type="module">
+			import * as m from '@twobirds/microcomponents';
+			m.autoload(true);
+			Object.assign(window, m);
+		<\/script>
+	</head>
+	<body>
+		<${tag}></${tag}>
+	</body>
+</html>
+`;
+}
+function bundle() {
+	return `// Barrel entry for the production bundle: imports every component so the bundler
+// registers them all in one file. Add a line here when a component is created.
+
+import './app.js';
+`;
+}
+function bundleConfig(namespace) {
+	return JSON.stringify({
+		entry: `${namespace}/bundle.ts`,
+		fileName: "bundle.js",
+		outDir: "public"
+	}, null, "	");
+}
+function appSource(namespace, tag) {
+	const className = kebabToPascal(tag);
+	return `import { DC, defineCE, parse, processAssets, type McEvent } from '@twobirds/microcomponents';
+
+/**
+\`${tag}\` — the starter micro component.
+
+@example
+\`\`\`html
+<${tag}></${tag}>
+\`\`\`
+*/
+class ${className} extends DC {
+	static assets = ['targetHtml', 'targetCss'];
+
+	data = { title: 'Micro Components' };
+
+	// Fill the template \`{key}\` tokens once, instead of binding reactive state.
+	oneAssets(ev: McEvent<Record<string, string>>): void {
+		processAssets(this, {
+			targetHtml: parse(ev.detail.data.targetHtml, this.data),
+		});
+	}
+}
+
+defineCE('${tag}', ${className});
+`;
+}
+function appHtml(namespace) {
+	return `<div class="app">
+	<h1>{title}</h1>
+	<p>Namespace scaffold ready. Edit <code>src/${namespace}/app.ts</code>.</p>
+</div>
+`;
+}
+function appCss(tag) {
+	return `${tag} {
+	display: block;
+	padding: 2rem;
+	font-family: system-ui, sans-serif;
+}
+`;
+}
+//#endregion
+//#region src/cli/writeScaffold.ts
+/**
+Filesystem side of {@link scaffoldComponent} and {@link scaffoldProject}: writes the
+generated files under a root directory, creating nested folders as needed.
+
+Existing files are never overwritten silently: every target is checked before the
+first write, so a rerun in a populated directory reports the conflicts and touches
+nothing. `force` opts into overwriting.
+
+@module CLI/Scaffold
+*/
+/**
+The path of a target file as it appears from the current working directory.
+`mc create` writes a project into a folder of its own, so a path relative to the
+project root cannot be found from the directory the command ran in: this turns
+`src/mc/app.ts` under `mc-app/` into `mc-app/src/mc/app.ts`. Falls back to the
+absolute path when the target lies outside the current directory, so the log never
+prints `../../..` chains.
+
+@example
+```ts
+// in a directory containing mc-app/src/mc/app.ts
+displayPath(path.resolve('mc-app', 'src/mc/app.ts'));
+displayPath('/tmp/mc-app/package.json');
+```
+@param abs - Absolute path of the target file.
+@group CLI
+*/
+function displayPath(abs) {
+	const rel = path.relative(process.cwd(), abs);
+	return rel.startsWith("..") ? abs : rel;
+}
+/**
+Writes generated files under `root`, creating nested folders as needed, and reports
+the written paths relative to `root`.
+
+@example
+```ts
+const written = await writeGenerated({ 'my/card.ts': 'source' }, 'src', false);
+console.log(written);
+```
+@param files - Files to write, keyed by path relative to `root`.
+@param root - Directory to write under (`src` for a component, `mc-app` for a project).
+@param force - Overwrite files that already exist.
+@returns The written file paths, relative to `root`.
+@throws If any target file exists and `force` is false. Nothing is written in that case.
+*/
+async function writeGenerated(files, root, force) {
+	const targets = Object.entries(files).map(([rel, contents]) => ({
+		rel,
+		abs: path.resolve(root, rel),
+		contents
+	}));
+	if (!force) {
+		const conflicts = targets.filter((target) => existsSync(target.abs)).map((t) => displayPath(t.abs));
+		if (conflicts.length) throw new Error(`refusing to overwrite ${conflicts.length} existing file(s):\n${conflicts.map((file) => `\t${file}`).join("\n")}\n\nrerun with --force to overwrite`);
+	}
+	const written = [];
+	for (const { rel, abs, contents } of targets) {
+		await mkdir(path.dirname(abs), { recursive: true });
+		await writeFile(abs, contents, "utf8");
+		written.push(rel);
+	}
+	return written;
+}
+/**
+Scaffolds a component onto disk under `root`.
+
+@example
+```ts
+const written = await writeScaffold('my-card', 'src', { assets: ['css'] });
+console.log(written);
+```
+@param tag - Kebab-case component tag.
+@param root - Directory to scaffold under (e.g. `src`).
+@param options - Which companion files to emit, and whether to overwrite existing ones.
+@returns The written file paths, relative to `root`.
+@throws If a target file exists and `force` is false.
+*/
+async function writeScaffold(tag, root, options = {}) {
+	const { files } = scaffoldComponent(tag, options);
+	return writeGenerated(files, root, options.force ?? false);
+}
+/**
+Filesystem side of {@link scaffoldProject}: writes a complete dev environment for a
+namespace under a project root, creating nested folders as needed.
+
+@example
+```ts
+const written = await writeProject('mc', 'mc-app');
+console.log(written);
+```
+@param namespace - 1 to 4 lowercase letters.
+@param root - Directory to create the project in (e.g. `mc-app`).
+@param options - Whether to overwrite existing files.
+@returns The written file paths, relative to `root`.
+@throws If `namespace` is not 1 to 4 lowercase letters, or a target file exists and
+`force` is false.
+*/
+async function writeProject(namespace, root, options = {}) {
+	const { files } = scaffoldProject(namespace);
+	return writeGenerated(files, root, options.force ?? false);
+}
+//#endregion
+//#region src/cli/inliner.ts
+/**
+Asset inlining for the vite-free CLI bundler.
+
+Companion `.css` / `.html` files declared by a DC class through
+`static assets = [...]` are read at build time and embedded as a
+`static _assets = { ... }` property inserted as the first line inside the
+class body, so `loadAssets()` never fetches them at runtime. The original
+`static assets` line is preserved for debugging purposes.
+
+This is the inlining the shipped Vite plugin used, ported to run inside
+{@link bundleEntry} without Vite: the bundler calls {@link inlineAssets} on
+each module body before wrapping it, reading the companion files from the
+same folder as the compiled `.js` (the mirrored `build/` tree).
+
+@module CLI/Inliner
+*/
+/**
+* Escape a raw string so it can be safely embedded inside a JS template literal.
+* Backticks and `${` sequences are escaped to prevent breaking the enclosing literal.
+*
+* @example Returns the input with backticks and `${` sequences escaped.
+* ```ts
+* escapeTemplateLiteral('price is ${cost}`done`');
+* ```
+*/
+function escapeTemplateLiteral(raw) {
+	return raw.replace(/\\/g, "\\\\").replace(/\$/g, "\\$").replace(/`/g, "\\`");
+}
+/**
+* Resolve the relative file path for a given asset descriptor and component tag.
+* Only the last segment of the tag is used as the basename since the `.js` source
+* already lives in the correct directory (e.g. `cart-container-checkout.js` is
+* inside `cart/container/`, so we just need `checkout.target.html`).
+*
+* @example Returns `./header.shadow.css`, `./card.target.html` and `./summary.css` for the calls below.
+* ```ts
+* resolveAssetPath('shop-header', 'shadowCss');
+* resolveAssetPath('product-card', 'targetHtml');
+* resolveAssetPath('cart-summary', 'css');
+* ```
+*/
+function resolveAssetPath(tagName, asset) {
+	const basename = tagName.split("-").pop() ?? tagName;
+	const m = asset.match(/^([a-z]+)([A-Z][a-z]*)$/);
+	if (m) return `./${basename}.${m[1]}.${m[2].toLowerCase()}`;
+	return `./${basename}.${asset.toLowerCase()}`;
+}
+/**
+* Extract the tag name from a `defineCE('tag-name', ...)` call in source code.
+* Returns the first found tag or undefined.
+*
+* @example Returns `'shop-header'` for the code below.
+* ```ts
+* extractDefineCETag("defineCE('shop-header', ShopHeader);");
+* ```
+*/
+function extractDefineCETag(code) {
+	const m = code.match(/defineCE\s*\(\s*['"]([^'"]+)['"]/);
+	return m ? m[1] : void 0;
+}
+/**
+* Strip all line and block comments from source code, replacing
+* their content with equivalent whitespace so character positions stay valid for
+* later string slicing.
+*
+* @example Blanks out the `// note` segment while keeping every character
+* position and line break, so later string slicing stays aligned.
+* ```ts
+* stripComments('const a = 1; // note\nconst b = 2;');
+* ```
+*/
+function stripComments(code) {
+	let result = "";
+	let i = 0;
+	while (i < code.length) if (code[i] === "/" && code[i + 1] === "/") {
+		const end = code.indexOf("\n", i);
+		if (end === -1) {
+			result += " ".repeat(code.length - i);
+			break;
+		}
+		result += " ".repeat(end - i) + "\n";
+		i = end + 1;
+	} else if (code[i] === "/" && code[i + 1] === "*") {
+		const end = code.indexOf("*/", i + 2);
+		if (end === -1) {
+			result += " ".repeat(code.length - i);
+			break;
+		}
+		let j = i;
+		while (j <= end + 1) {
+			result += code[j] === "\n" ? "\n" : " ";
+			j++;
+		}
+		i = end + 2;
+	} else {
+		result += code[i];
+		i++;
+	}
+	return result;
+}
+/**
+* Read and inline all assets for a given tag, returning an array of
+* `{ key, literal }` entries suitable for building object literals.
+* Plain `.css` files hold CSS custom-property presets and are inlined with
+* their real content so the component injects the default variables at
+* runtime. They are never left empty — an empty string would make the
+* runtime treat the asset as not-yet-loaded and re-fetch it.
+*
+* @example Returns one escaped template literal per descriptor, ready to be joined into an object.
+* ```ts
+* readAssetsInline('/build/shop/header', 'shop-header', ['shadowCss', 'targetHtml']);
+* ```
+* @throws If a companion file for a descriptor does not exist.
+*/
+async function readAssetsInline(dir, tagName, assets) {
+	const entries = [];
+	for (const asset of assets) {
+		const relPath = resolveAssetPath(tagName, asset);
+		const filePath = path.resolve(dir, relPath);
+		try {
+			const content = await readFile(filePath, "utf8");
+			entries.push({
+				key: asset,
+				literal: "`" + escapeTemplateLiteral(content).replace(/[\n\t\r]/g, " ").replace(/\s\s/g, " ") + "`"
+			});
+		} catch (_err) {
+			throw new Error(`[load-assets] Cannot resolve asset "${asset}" for component "${tagName}": file not found at ${filePath}`, { cause: _err });
+		}
+	}
+	return entries;
+}
+/**
+* Inline every `static assets = [...]` declaration in a module body as a
+* `static _assets` property, reading the companion files from `dir`.
+*
+* @example Returns the class with `static _assets` injected after its opening brace.
+* ```ts
+* await inlineAssets("class A extends DC { static assets = ['targetHtml']; }", '/build/mc');
+* ```
+* @param code Module source (the compiled `.js`).
+* @param dir Folder holding the companion files next to the module.
+* @returns The transformed code, or the original when there is nothing to inline.
+*/
+async function inlineAssets(code, dir) {
+	if (!code.includes("static assets")) return code;
+	const stripped = stripComments(code);
+	const tagName = extractDefineCETag(stripped);
+	if (!tagName) return code;
+	const saMatches = [...stripped.matchAll(/static\s+assets\s*=\s*\[(.*?)\]\s*;?/gs)];
+	if (saMatches.length === 0) return code;
+	let transformed = code;
+	for (let i = saMatches.length - 1; i >= 0; i--) {
+		const match = saMatches[i];
+		const assets = match[1].split(",").map((a) => a.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+		if (assets.length === 0) continue;
+		const assetsObj = `{ ${(await readAssetsInline(dir, tagName, assets)).map((e) => `${e.key}: ${e.literal}`).join(", ")} }`;
+		const beforeMatch = stripped.substring(0, match.index);
+		const classOpenMatch = /class\s+\w+[^{]*\{/.exec(beforeMatch);
+		if (!classOpenMatch) continue;
+		const classBraceIndex = classOpenMatch.index + classOpenMatch[0].length - 1;
+		const injectCode = `\n    static _assets = ${assetsObj};\n`;
+		transformed = transformed.substring(0, classBraceIndex + 1) + injectCode + transformed.substring(classBraceIndex + 1);
+	}
+	return transformed;
+}
+//#endregion
+//#region src/cli/bundler.ts
+/**
+Pure-TypeScript global bundler — no Vite, no Rolldown, no oxc.
+
+Reads the `tsc`-emitted ESM files in a project's `build/` and flattens the
+barrel entry's dependency graph into one self-contained ES module. Each source
+module is wrapped in a function scope keyed by its path (relative to the root),
+its `import`/`export` statements are rewritten to a tiny `require` registry,
+and the entry's re-exported names are emitted as the bundle's public exports.
+
+When `inline` is set, every module body is first run through
+{@link inlineAssets}, so a DC class declaring `static assets = [...]` gets its
+companion `.css` / `.html` embedded as `static _assets` and `loadAssets()`
+never fetches them at runtime.
+
+The rewrite is comment-aware: `import`/`export` lines inside JSDoc `@example`
+blocks are left untouched, so the self-referential `@twobirds/microcomponents`
+specifiers in documentation never break resolution.
+
+@module CLI/Bundler
+*/
+/**
+* Resolve a relative specifier to a module id (path relative to `root`),
+* given the id of the importing module. Bare specifiers (`node:`, `@twobirds/`)
+* are external and return `undefined`.
+*
+* @example Resolves a sibling and a parent-relative import.
+* ```ts
+* resolveId('./events.js', 'utils/helpers.js');   // 'utils/events.js'
+* resolveId('../utils/helpers.js', 'core/MC.js');  // 'utils/helpers.js'
+* ```
+*/
+function resolveId(spec, currentId) {
+	if (!spec.startsWith(".")) return void 0;
+	return path.posix.normalize(path.posix.join(path.posix.dirname(currentId), spec));
+}
+/** Parse the binding list inside `{ a, b as c }` into local/exported pairs. */
+function parseBindings(inner) {
+	return inner.split(",").map((b) => b.trim()).filter(Boolean).map((b) => {
+		const m = b.match(/^(\w+)(?:\s+as\s+(\w+))?$/);
+		if (!m) return {
+			local: b,
+			exported: b
+		};
+		return {
+			local: m[1],
+			exported: m[2] ?? m[1]
+		};
+	});
+}
+/**
+* Rewrite a single top-level `import` line into a `require` destructure.
+* Returns the replacement line and the resolved dependency id.
+*
+* @example Turns a named import into a registry lookup.
+* ```ts
+* rewriteImport("import { on, trigger } from './events.js'", 'utils/helpers.js');
+* ```
+*/
+function rewriteImport(line, currentId) {
+	const sideEffect = line.match(/^import\s*['"]([^'"]+)['"];?\s*$/);
+	if (sideEffect) {
+		const id = resolveId(sideEffect[1], currentId);
+		return {
+			line: id ? `__r(${JSON.stringify(id)});` : line,
+			spec: id,
+			names: [],
+			pairs: []
+		};
+	}
+	const m = line.match(/^import\s+(?:\*\s+as\s+(\w+)|\{([^}]*)\}|(\w+))\s*from\s*['"]([^'"]+)['"];?\s*$/);
+	if (!m) return {
+		line,
+		names: [],
+		pairs: []
+	};
+	const id = resolveId(m[4], currentId);
+	if (!id) return {
+		line,
+		names: [],
+		pairs: []
+	};
+	const lookup = `__r(${JSON.stringify(id)})`;
+	if (m[1]) return {
+		line: `const ${m[1]} = ${lookup};`,
+		spec: id,
+		names: [],
+		pairs: []
+	};
+	if (m[2]) return {
+		line: `const { ${parseBindings(m[2]).map((b) => b.local === b.exported ? b.local : `${b.local}: ${b.exported}`).join(", ")} } = ${lookup};`,
+		spec: id,
+		names: [],
+		pairs: []
+	};
+	return {
+		line: `const ${m[3]} = ${lookup}.default;`,
+		spec: id,
+		names: [],
+		pairs: []
+	};
+}
+/**
+* Rewrite a single top-level `export` line. `export *` / `export { } from`
+* become registry merges; declarations and bare `export { }` record the local
+* bindings that get assigned to `exports` at the end of the module body.
+*
+* @example Turns a star re-export into an Object.assign merge.
+* ```ts
+* rewriteExport("export * from './helpers.js'", 'microcomponents.js');
+* ```
+*/
+function rewriteExport(line, currentId) {
+	const star = line.match(/^export\s+\*\s+from\s*['"]([^'"]+)['"];?\s*$/);
+	if (star) {
+		const id = resolveId(star[1], currentId);
+		return {
+			line: id ? `Object.assign(exports, ${`__r(${JSON.stringify(id)})`});` : line,
+			spec: id,
+			star: true,
+			names: [],
+			pairs: []
+		};
+	}
+	const namedFrom = line.match(/^export\s+\{([^}]*)\}\s*from\s*['"]([^'"]+)['"];?\s*$/);
+	if (namedFrom) {
+		const id = resolveId(namedFrom[2], currentId);
+		const bindings = parseBindings(namedFrom[1]);
+		const destructure = bindings.map((b) => `${b.local}: __x_${b.exported}`).join(", ");
+		const assigns = bindings.map((b) => `exports.${b.exported} = __x_${b.exported};`).join(" ");
+		return {
+			line: id ? `const { ${destructure} } = __r(${JSON.stringify(id)}); ${assigns}` : line,
+			spec: id,
+			names: bindings.map((b) => b.exported),
+			pairs: []
+		};
+	}
+	const named = line.match(/^export\s+\{([^}]*)\};?\s*$/);
+	if (named) {
+		const bindings = parseBindings(named[1]);
+		return {
+			line: "",
+			names: bindings.map((b) => b.exported),
+			pairs: bindings
+		};
+	}
+	const decl = line.match(/^export\s+(function|class|const|let|var)\s+(\w+)/);
+	if (decl) return {
+		line: line.replace(/^export\s+/, ""),
+		names: [decl[2]],
+		pairs: [{
+			local: decl[2],
+			exported: decl[2]
+		}]
+	};
+	if (line.match(/^export\s+default\s+/)) return {
+		line: "const __default = " + line.replace(/^export\s+default\s+/, ""),
+		names: ["default"],
+		pairs: [{
+			local: "__default",
+			exported: "default"
+		}]
+	};
+	return {
+		line,
+		names: [],
+		pairs: []
+	};
+}
+/**
+* Depth-first, post-order walk of one entry's dependency graph. Each visited
+* module is rewritten once; `export *` merges the dependency's export names
+* into the current module's public set.
+*
+* @example Walks the whole barrel graph from the entry.
+* ```ts
+* const mods = await collectModules('mc/bundle.js', 'build');
+* ```
+*/
+async function collectModules(entryId, root, inline) {
+	const modules = /* @__PURE__ */ new Map();
+	/** Modules currently being processed. Real cycles exist in the graph
+	*  (e.g. `state/observables.js` <-> `state/placeholders.js`), so a
+	*  re-entrant visit must return early instead of recursing forever. The
+	*  `__r` registry mirrors ESM live-binding semantics, so the cycle resolves
+	*  at runtime once both modules have run. */
+	const visiting = /* @__PURE__ */ new Set();
+	async function visit(id) {
+		if (modules.has(id) || visiting.has(id)) return;
+		visiting.add(id);
+		let code = await readFile(path.join(root, id), "utf8");
+		if (inline) code = await inlineAssets(code, path.join(root, path.dirname(id)));
+		const stripped = stripComments(code);
+		const lines = code.split("\n");
+		const strippedLines = stripped.split("\n");
+		const exportNames = /* @__PURE__ */ new Set();
+		const pairs = [];
+		const out = [];
+		const deps = [];
+		const starSpecs = [];
+		for (let i = 0; i < lines.length; i++) {
+			const t = strippedLines[i].trim();
+			if (t.startsWith("import ")) {
+				const r = rewriteImport(lines[i], id);
+				out.push(r.line);
+				if (r.spec) deps.push(r.spec);
+			} else if (t.startsWith("export ")) {
+				const r = rewriteExport(lines[i], id);
+				out.push(r.line);
+				if (r.spec) deps.push(r.spec);
+				if (r.star && r.spec) starSpecs.push(r.spec);
+				for (const n of r.names) exportNames.add(n);
+				for (const p of r.pairs) pairs.push(p);
+			} else out.push(lines[i]);
+		}
+		for (const d of deps) await visit(d);
+		for (const s of starSpecs) for (const n of modules.get(s).exportNames) exportNames.add(n);
+		visiting.delete(id);
+		modules.set(id, {
+			id,
+			body: out.join("\n"),
+			exportNames,
+			pairs
+		});
+	}
+	await visit(entryId);
+	return modules;
+}
+/**
+* Assemble one entry's flattened ES module string from its collected graph.
+*
+* @example Produces a self-contained bundle for the barrel entry.
+* ```ts
+* const code = await bundleEntry('mc/bundle.js', 'build', true);
+* ```
+* @param entryId Entry module id, relative to `root` (e.g. `mc/bundle.js`).
+* @param root Folder holding the compiled `.js` files.
+* @param inline Inline companion assets into DC classes before wrapping.
+*/
+async function bundleEntry(entryId, root, inline = true) {
+	const modules = await collectModules(entryId, root, inline);
+	const wrappers = [];
+	for (const m of modules.values()) {
+		const assigns = m.pairs.map((p) => `exports.${p.exported} = ${p.local};`).join("\n");
+		wrappers.push(`__m[${JSON.stringify(m.id)}] = function (exports, __r) {\n${m.body}\n${assigns}\n};`);
+	}
+	const names = [...modules.get(entryId).exportNames];
+	const bindings = names.map((n, i) => `const __ex${i} = __e[${JSON.stringify(n)}];`).join("\n");
+	const publicExports = names.map((n, i) => `__ex${i} as ${n}`).join(", ");
+	return [
+		"const __m = {};",
+		"const __c = {};",
+		"function __r(id) {",
+		"    if (__c[id]) return __c[id];",
+		"    const exp = {};",
+		"    __c[id] = exp;",
+		"    __m[id](exp, __r);",
+		"    return exp;",
+		"}",
+		wrappers.join("\n"),
+		`const __e = __r(${JSON.stringify(entryId)});`,
+		bindings,
+		`export { ${publicExports} };`
+	].join("\n");
+}
+//#endregion
+//#region src/cli/bundle.ts
+/**
+Filesystem side of `mc bundle`: assembles the production site in `public/` from
+the `tsc`-emitted `build/` tree, with no Vite.
+
+The chain is `src/` → `build/` → `public/`. The scaffolded `build` script runs
+`tsc -p tsconfig.json` (so `build/` holds one `.js` per component at its
+autoload path), then `mc bundle` mirrors the companion assets into `build/`,
+walks the barrel entry named by `src/bundle.json` through {@link bundleEntry}
+(inlining every `static assets`), rewrites the `@twobirds/microcomponents`
+specifier to the self-contained `microcomponents.min.js` shipped next to the
+bundle, concatenates the plain `.css` token presets into `bundle.css`, and
+copies the production shell. The result is a complete static site: a single
+`bundle.js` loads every component, no autoloader needed.
+
+@module CLI/Bundle
+*/
+/** Companion asset extensions copied verbatim next to their compiled `.js`. */
+var COMPANION_EXTENSIONS = [
+	".css",
+	".html",
+	".json"
+];
+/**
+* Whether a file is a companion asset to mirror into `build/`.
+*
+* @example
+* ```ts
+* isCompanion('app.target.html');  // true
+* isCompanion('index.html');       // false
+* ```
+* @param name Basename of the file.
+*/
+function isCompanion(name) {
+	if (name === "index.html" || name === "index-dev.html") return false;
+	return COMPANION_EXTENSIONS.some((ext) => name.endsWith(ext));
+}
+/**
+* Mirror companion assets (`.css`, `.html`, `.json`) from `src/` into `build/`,
+* preserving the tree, so the bundler reads each asset next to its compiled `.js`.
+*
+* @example
+* ```ts
+* await mirrorCompanions('<root>/src', '<root>/build');
+* ```
+* @param srcDir Source root to walk.
+* @param buildDir Folder to write into.
+* @param rel Path of the walked directory relative to `srcDir`.
+*/
+async function mirrorCompanions(srcDir, buildDir, rel = "") {
+	for (const entry of await readdir(path.join(srcDir, rel), { withFileTypes: true })) {
+		const next = rel ? path.join(rel, entry.name) : entry.name;
+		if (entry.isDirectory()) {
+			if (entry.name === "node_modules") continue;
+			await mirrorCompanions(srcDir, buildDir, next);
+		} else if (isCompanion(entry.name)) {
+			const dst = path.join(buildDir, next);
+			await mkdir(path.dirname(dst), { recursive: true });
+			await cp(path.join(srcDir, next), dst);
+		}
+	}
+}
+/**
+* Collect the plain `.css` token presets under `src/`, skipping the companion
+* `.target.css` / `.shadow.css` files, which the bundler inlines into the JS.
+*
+* @example
+* ```ts
+* const css = await collectPlainCss('<root>/src');
+* ```
+* @param srcDir Source root to walk.
+* @param rel Path of the walked directory relative to `srcDir`.
+* @param found Accumulated absolute paths.
+*/
+async function collectPlainCss(srcDir, rel = "", found = []) {
+	for (const entry of await readdir(path.join(srcDir, rel), { withFileTypes: true })) {
+		const next = rel ? path.join(rel, entry.name) : entry.name;
+		if (entry.isDirectory()) {
+			if (entry.name !== "node_modules") await collectPlainCss(srcDir, next, found);
+		} else if (entry.name.endsWith(".css") && !/\.(target|shadow)\.css$/.test(entry.name)) found.push(path.join(srcDir, next));
+	}
+	return found;
+}
+/**
+* Rewrite the library specifier in a bundled module to the self-contained bundle
+* shipped next to it, so the browser can resolve `@twobirds/microcomponents`
+* without a bare-specifier import map.
+*
+* @example Turns the package specifier into a relative path.
+* ```ts
+* rewriteLibrarySpecifier("import { DC } from '@twobirds/microcomponents';");
+* ```
+* @param code Bundled module source.
+* @param target Relative specifier to point the import at.
+*/
+function rewriteLibrarySpecifier(code, target = "./microcomponents.min.js") {
+	return code.replace(/from\s*['"]@twobirds\/microcomponents['"]/g, `from '${target}'`);
+}
+/**
+* Assemble the production site in `public/` from the compiled `build/` tree.
+*
+* @example
+* ```ts
+* await bundleProject('<root>', { minJs: '<pkg>/dist/microcomponents.min.js' });
+* ```
+* @param projectRoot Project root (the folder holding `src/`, `build/`, `public/`).
+* @param options.minJs Absolute path of the self-contained `microcomponents.min.js` to ship next to the bundle.
+* @param options.bundleEntry Optional override of the barrel entry (defaults to `src/bundle.json`).
+* @returns The names of the files written into `public/`.
+*/
+async function bundleProject(projectRoot, options) {
+	const sourceRoot = path.join(projectRoot, "src");
+	const buildRoot = path.join(projectRoot, "build");
+	const config = JSON.parse(await readFile(path.join(sourceRoot, "bundle.json"), "utf8"));
+	const publicRoot = path.join(projectRoot, options.outDir ?? config.outDir ?? "public");
+	const fileName = config.fileName ?? "bundle.js";
+	await mirrorCompanions(sourceRoot, buildRoot);
+	const rewritten = rewriteLibrarySpecifier(await bundleEntry((options.bundleEntry ?? config.entry).replace(/\.ts$/, ".js"), buildRoot, true));
+	await mkdir(publicRoot, { recursive: true });
+	await writeFile(path.join(publicRoot, fileName), rewritten, "utf8");
+	await cp(options.minJs, path.join(publicRoot, "microcomponents.min.js"));
+	const cssFiles = await collectPlainCss(sourceRoot);
+	const parts = await Promise.all(cssFiles.map((f) => readFile(f, "utf8")));
+	await writeFile(path.join(publicRoot, "bundle.css"), parts.join("\n"), "utf8");
+	await cp(path.join(sourceRoot, "index.html"), path.join(publicRoot, "index.html"));
+	return [
+		fileName,
+		"microcomponents.min.js",
+		"bundle.css",
+		"index.html"
+	];
+}
+/**
+* CLI entry for `mc bundle`: runs {@link bundleProject} against the current
+* project, reading the self-contained library from this package's own `dist/`.
+*
+* @param projectRoot Project root (defaults to the current directory).
+* @param minJs Path of `microcomponents.min.js` (defaults to this package's `dist/`).
+* @returns The process exit code.
+*/
+async function runBundle(projectRoot = process.cwd(), minJs = path.join(import.meta.dirname, "..", "microcomponents.min.js")) {
+	const written = await bundleProject(projectRoot, { minJs });
+	console.log(`bundled ${written.join(", ")} into public/`);
+	return 0;
+}
+//#endregion
+//#region src/cli/dev.ts
+/**
+Vite-free dev server for `mc dev`.
+
+A minimal `node:http` static server rooted at the project's `build/` folder, so
+a saved component reaches the browser through `autoload()` with no bundling. It
+mirrors companion assets from `src/` into `build/` (on startup and on every
+change), runs `tsc -w` for the lifetime of the server, serves companion
+`.css` / `.html` / `.json` as raw text (so `loadAssets()` receives markup it
+can use), redirects `/` to the autoload shell (`index-dev.html`), and serves
+the self-contained library at `/microcomponents.min.js` — the target of the
+import map in the dev shell.
+
+There is no HMR: a page reload picks up the recompiled component.
+
+@module CLI/Dev
+*/
+/** Page shells Vite/the server serves as HTML; everything else stays raw text. */
+var SHELLS = /* @__PURE__ */ new Set(["index.html", "index-dev.html"]);
+/**
+* Content type for a served file. Companion `.html` / `.json` stay raw text so
+* `loadAssets()` gets usable markup; the page shells are HTML.
+*
+* @example
+* ```ts
+* mimeFor('app.target.html');  // 'text/plain'
+* mimeFor('index-dev.html');   // 'text/html'
+* mimeFor('app.js');           // 'text/javascript'
+* ```
+* @param name Basename of the file.
+*/
+function mimeFor(name) {
+	if (name.endsWith(".js")) return "text/javascript";
+	if (name.endsWith(".css")) return "text/css";
+	if (name.endsWith(".svg")) return "image/svg+xml";
+	if (name.endsWith(".html")) return SHELLS.has(name) ? "text/html" : "text/plain";
+	if (name.endsWith(".json")) return "text/plain";
+	return "application/octet-stream";
+}
+/**
+* Resolve a request URL to a file to serve, given the served `build/` root and
+* the library bundle. `/` and `/index.html` map to the autoload shell;
+* `/microcomponents.min.js` maps to the library; everything else to `build/`.
+*
+* @example
+* ```ts
+* resolveTarget('/mc/app.target.html', buildRoot, minJs);
+* resolveTarget('/', buildRoot, minJs);
+* ```
+* @param url Request URL (path only, no query).
+* @param buildRoot Served folder.
+* @param minJs Absolute path of the self-contained library.
+* @returns Absolute file path, or `undefined` when nothing matches.
+*/
+function resolveTarget(url, buildRoot, minJs) {
+	const file = decodeURIComponent(url.split("?")[0]);
+	if (url === "/" || url === "/index.html") return path.join(buildRoot, "index-dev.html");
+	if (url === "/microcomponents.min.js") return minJs;
+	const abs = path.join(buildRoot, file);
+	return abs.startsWith(buildRoot) && existsSync(abs) ? abs : void 0;
+}
+/**
+* Serve one request from the `build/` tree.
+*/
+async function serve(req, res, buildRoot, minJs) {
+	const abs = resolveTarget(req.url?.split("?")[0] ?? "/", buildRoot, minJs);
+	if (!abs) {
+		res.statusCode = 404;
+		res.end("not found");
+		return;
+	}
+	try {
+		const text = await readFile(abs, "utf-8");
+		res.setHeader("Content-Type", mimeFor(path.basename(abs)));
+		res.end(text);
+	} catch {
+		/* v8 ignore start — resolveTarget already checked existence; a read failure is a race */
+		res.statusCode = 404;
+		res.end("not found");
+	}
+}
+/**
+* Mirror companion assets from `src/` into `build/`, preserving the tree, so the
+* served folder stays autoload-ready.
+*
+* @example
+* ```ts
+* await mirrorInto(sourceRoot, buildRoot);
+* ```
+* @param sourceRoot Source root to walk.
+* @param buildRoot Folder to write into.
+* @param rel Path of the walked directory relative to `sourceRoot`.
+*/
+async function mirrorInto(sourceRoot, buildRoot, rel = "") {
+	for (const entry of await readdir(path.join(sourceRoot, rel), { withFileTypes: true })) {
+		const next = rel ? path.join(rel, entry.name) : entry.name;
+		if (entry.isDirectory()) {
+			if (entry.name !== "node_modules") await mirrorInto(sourceRoot, buildRoot, next);
+		} else if (isCompanion(entry.name) || entry.name === "index-dev.html") {
+			const dst = path.join(buildRoot, next);
+			await mkdir(path.dirname(dst), { recursive: true });
+			await cp(path.join(sourceRoot, next), dst);
+		}
+	}
+}
+/**
+* Build the dev server for a project: an `node:http` server rooted at `build/`.
+*
+* @example
+* ```ts
+* const server = createDevServer('<root>', { minJs: '<pkg>/dist/microcomponents.min.js', port: 5173 });
+* server.listen(port);
+* ```
+* @param projectRoot Project root (the folder holding `src/`, `build/`).
+* @param options.minJs Absolute path of the self-contained library.
+* @param options.port Dev-server port.
+* @returns The HTTP server (not yet listening).
+*/
+function createDevServer(projectRoot, options) {
+	const buildRoot = path.join(projectRoot, "build");
+	return createServer((req, res) => {
+		serve(req, res, buildRoot, options.minJs);
+	});
+}
+/**
+* CLI entry for `mc dev`: mirror companions, start the server, and run `tsc -w`
+* for the lifetime of the process.
+*
+* @param projectRoot Project root (defaults to the current directory).
+* @param minJs Path of `microcomponents.min.js` (defaults to this package's `dist/`).
+* @param port Dev-server port.
+* @returns The process exit code (the server keeps running until killed).
+*/
+/* v8 ignore start — the long-running server + tsc watch is exercised by hand, not in the suite */
+async function runDev(projectRoot = process.cwd(), minJs = path.join(import.meta.dirname, "..", "microcomponents.min.js"), port = 5173) {
+	const sourceRoot = path.join(projectRoot, "src");
+	const buildRoot = path.join(projectRoot, "build");
+	await mirrorInto(sourceRoot, buildRoot);
+	const tsc = spawn("npx", [
+		"tsc",
+		"-w",
+		"-p",
+		"tsconfig.json"
+	], {
+		cwd: projectRoot,
+		stdio: "inherit"
+	});
+	watch(sourceRoot, { recursive: true }, (_event, file) => {
+		if (!file || file.endsWith(".ts")) return;
+		const abs = path.join(sourceRoot, file);
+		if (isCompanion(path.basename(file)) || file.endsWith("index-dev.html")) {
+			const dst = path.join(buildRoot, file);
+			mkdir(path.dirname(dst), { recursive: true }).then(() => cp(abs, dst));
+		}
+	});
+	const server = createDevServer(projectRoot, {
+		minJs,
+		port
+	});
+	server.listen(port);
+	console.log(`dev server on http://localhost:${port}/ (serving build/, tsc -w running)`);
+	return new Promise((resolve) => {
+		tsc.on("exit", () => {
+			server.close();
+			resolve(0);
+		});
+	});
+}
+/* v8 ignore end */
+//#endregion
+//#region src/cli/preview.ts
+/**
+Vite-free preview server for `mc preview`.
+
+A minimal `node:http` static server rooted at the project's `public/` folder —
+the production site assembled by `mc bundle` (one `bundle.js`, the
+`microcomponents.min.js` it imports, `bundle.css`, and the page shell). `/`
+serves `index.html`; every file is served raw with its content type.
+
+@module CLI/Preview
+*/
+/**
+* Resolve a request URL to a file in `public/`. `/` and `/index.html` map to the
+* production shell; everything else to `public/<path>`.
+*
+* @example
+* ```ts
+* resolvePublicTarget('/bundle.js', publicRoot);
+* resolvePublicTarget('/', publicRoot);
+* ```
+* @param url Request URL (path only, no query).
+* @param publicRoot Served folder.
+* @returns Absolute file path, or `undefined` when nothing matches.
+*/
+function resolvePublicTarget(url, publicRoot) {
+	const file = decodeURIComponent(url.split("?")[0]);
+	if (url === "/" || url === "/index.html") return path.join(publicRoot, "index.html");
+	const abs = path.join(publicRoot, file);
+	return abs.startsWith(publicRoot) && existsSync(abs) ? abs : void 0;
+}
+/**
+* Serve one request from the `public/` tree.
+*/
+async function servePublic(req, res, publicRoot) {
+	const abs = resolvePublicTarget(req.url?.split("?")[0] ?? "/", publicRoot);
+	if (!abs) {
+		res.statusCode = 404;
+		res.end("not found");
+		return;
+	}
+	try {
+		const text = await readFile(abs, "utf-8");
+		res.setHeader("Content-Type", mimeFor(path.basename(abs)));
+		res.end(text);
+	} catch {
+		/* v8 ignore start — resolvePublicTarget already checked existence; a read failure is a race */
+		res.statusCode = 404;
+		res.end("not found");
+	}
+}
+/**
+* Build the preview server for a project: an `node:http` server rooted at `public/`.
+*
+* @example
+* ```ts
+* const server = createPreviewServer('<root>', 5174);
+* server.listen(5174);
+* ```
+* @param projectRoot Project root (the folder holding `public/`).
+* @param port Preview-server port.
+* @param outDir Output folder relative to the root (default `public`).
+* @returns The HTTP server (not yet listening).
+*/
+function createPreviewServer(projectRoot, port, outDir = "public") {
+	const publicRoot = path.join(projectRoot, outDir);
+	return createServer((req, res) => {
+		servePublic(req, res, publicRoot);
+	});
+}
+/**
+* CLI entry for `mc preview`: serve the production site in `public/`.
+*
+* @param projectRoot Project root (defaults to the current directory).
+* @param port Preview-server port.
+* @returns The process exit code (the server keeps running until killed).
+*/
+/* v8 ignore start — the long-running server is exercised by hand, not in the suite */
+async function runPreview(projectRoot = process.cwd(), port = 5174) {
+	const server = createPreviewServer(projectRoot, port);
+	server.listen(port);
+	console.log(`preview server on http://localhost:${port}/ (serving public/)`);
+	return new Promise((resolve) => {
+		server.on("close", () => resolve(0));
+	});
+}
+/* v8 ignore end */
+//#endregion
+//#region src/cli/dispatch.ts
+/**
+Command dispatcher for the `mc` CLI.
+
+Kept free of any top-level side effects so the routing can be unit-tested:
+`index.ts` is the thin executable entry that calls {@link main}, while this
+module only exports the logic. Commands that wrap a package.json script
+(`clean`, `check`) are deliberately thin — they delegate to the script so the
+script stays the single source of truth. When the current project defines no
+such script, the CLI runs its own implementation against the current project,
+so the command works in any consumer project.
+
+@module CLI/Dispatch
+*/
+var USAGE = `mc — Micro Components build tools
+
+Usage:
+  mc new <tag> [--css] [--html] [--target-html] [--shadow-html] [--target-css] [--shadow-css] [--js] [--dir <path>] [--force] [--dry-run]
+  mc create --namespace <ns> [--dir <path>] [--force] [--dry-run]
+  mc dev [--port <n>]
+  mc bundle
+  mc preview [--port <n>]
+  mc clean
+  mc check
+  mc --version
+  mc --help
+
+Commands:
+  new <tag>   Scaffold a micro component (e.g. mc new my-card --target-html --target-css)
+  create      Create a dev environment (e.g. mc create --namespace mc --dir mc-app)
+  dev         Serve build/ through autoload() with tsc -w (no bundling)
+  bundle      Assemble public/ from build/: bundle.js with assets inlined, bundle.css, shell
+  preview     Serve the production site in public/
+  clean       Remove build artifacts (dist, public, build, coverage)
+  check       Type-check every project (lib, cli, test, demo, node)
+
+Companion assets:
+  --css           document-level stylesheet (CSS custom properties / design tokens)
+  --html          unvariant light-DOM template
+  --target-html   template applied to target.innerHTML
+  --shadow-html   template applied to shadowRoot.innerHTML
+  --target-css    document-level styles scoped to the host tag
+  --shadow-css    styles injected into the shadow root
+
+Other options:
+  --js         emit plain JavaScript instead of TypeScript
+  --dir <path> scaffold root (default: src)
+  --port <n>   dev / preview server port (default: 5173 / 5174)
+  --force      overwrite files that already exist
+  --dry-run    print what would be written; touch nothing on disk
+  --version    print the version of the package the CLI ships in (-v)
+  --help       print this text (-h)
+
+Created paths are printed as they appear from the current directory. mc create writes
+a whole project into a folder of its own (default: the namespace), so its files show
+up under that folder, e.g. mc-app/src/mc/app.ts.
+`;
+var ASSET_FLAGS = {
+	css: "css",
+	html: "html",
+	"target-html": "targetHtml",
+	"shadow-html": "shadowHtml",
+	"target-css": "targetCss",
+	"shadow-css": "shadowCss"
+};
+/**
+A scaffolded file as it appears from the current directory: the file `rel` under
+`root`, resolved and made readable. `mc create` writes a project into a folder of
+its own, so `src/mc/app.ts` under `mc-app` prints as `mc-app/src/mc/app.ts` — the
+path the user can find with `ls`.
+
+@example
+```ts
+createdPath('mc-app', 'src/mc/app.ts');
+createdPath('src', 'my/card.ts');
+```
+@param root - Scaffold root the file is written under.
+@param rel - Path of the file relative to `root`.
+*/
+function createdPath(root, rel) {
+	return displayPath(path.resolve(root, rel));
+}
+/**
+Spawns a command and resolves with its exit code.
+
+@example
+```ts
+const code = await spawnProcess('pnpm', ['run', 'clean']);
+```
+@param command - Executable to spawn.
+@param args - Arguments to pass.
+@param cwd - Working directory (defaults to the current one).
+*/
+function spawnProcess(command, args, cwd) {
+	return new Promise((resolve) => {
+		spawn(command, args, {
+			stdio: "inherit",
+			cwd
+		}).on("exit", (code) => resolve(code ?? 1));
+	});
+}
+/**
+Whether the package.json in the current directory declares `script` in its
+"scripts". Consumers get this check so `mc clean`/`mc check` can fall back to
+the CLI's own implementation when the project defines no such script.
+
+@example
+```ts
+const ok = await hasScript('clean');
+```
+@param script - Script name to look up.
+*/
+async function hasScript(script) {
+	try {
+		return typeof JSON.parse(await readFile(path.join(process.cwd(), "package.json"), "utf8"))?.scripts?.[script] === "string";
+	} catch {
+		return false;
+	}
+}
+/** Build artifacts to remove, relative to the project root. */
+var CLEAN_DIRS = [
+	"dist",
+	"public",
+	"build",
+	"coverage"
+];
+/**
+Removes build artifacts in the current project.
+
+@example
+```ts
+const code = await cleanSelf();
+```
+@param cwd - Project root (defaults to the current directory).
+*/
+async function cleanSelf(cwd = process.cwd()) {
+	await Promise.all(CLEAN_DIRS.map(async (dir) => {
+		const abs = path.join(cwd, dir);
+		if (existsSync(abs)) {
+			await rm(abs, {
+				recursive: true,
+				force: true
+			});
+			console.log(`removed ${dir}/`);
+		}
+	}));
+	return 0;
+}
+/**
+Type-checks the current project with its own `tsconfig.json`.
+
+@example
+```ts
+const code = await checkSelf();
+```
+@param cwd - Project root (defaults to the current directory).
+*/
+async function checkSelf(cwd = process.cwd()) {
+	if (!existsSync(path.join(cwd, "tsconfig.json"))) {
+		console.error("mc check: no tsconfig.json in the current project");
+		return 1;
+	}
+	return spawnProcess("pnpm", [
+		"exec",
+		"tsc",
+		"--noEmit",
+		"-p",
+		"tsconfig.json"
+	], cwd);
+}
+/**
+The version of the package the CLI ships in, read from its package.json. Two
+levels above `dist/cli` (and above `src/cli` when tsx runs the source) is the
+package root, so the CLI reports the version it was installed with, not the
+version of the project it is run in.
+
+@example
+```ts
+const version = await readVersion();
+```
+@param pkgPath - package.json to read (defaults to the package root of this CLI).
+*/
+async function readVersion(pkgPath = path.join(import.meta.dirname, "..", "..", "package.json")) {
+	const { version } = JSON.parse(await readFile(pkgPath, "utf8"));
+	return version;
+}
+/**
+Runs a package.json script through pnpm and resolves with its exit code.
+
+Thin wrappers like `clean` and `check` delegate here so the script — not the
+CLI — remains the single source of truth for what each command does. If the
+current project defines no such script, the CLI runs its own implementation
+against the current project, so the command works in any consumer project.
+
+@example
+```ts
+const code = await runScript('check');
+```
+*/
+async function runScript(script, options) {
+	if (await hasScript(script)) return spawnProcess("pnpm", ["run", script]);
+	if (script === "clean") return cleanSelf();
+	if (script === "check") return checkSelf();
+	if (script === "dev") return runDev(process.cwd(), void 0, options?.port ?? 5173);
+	if (script === "bundle") return runBundle();
+	if (script === "preview") return runPreview(process.cwd(), options?.port ?? 5174);
+	console.error(`mc: no "${script}" script in the current project`);
+	return 1;
+}
+/**
+Parses `argv` and routes it to the matching command, returning a process exit
+code. `run` is injectable so the script-wrapping commands can be tested without
+spawning anything.
+
+@example
+```ts
+const code = await main(['clean'], async (script) => {
+console.log(`would run ${script}`);
+return 0;
+});
+```
+@example
+```ts
+const code = await main(['--version']);
+```
+*/
+async function main(argv, run = runScript) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: {
+			css: { type: "boolean" },
+			html: { type: "boolean" },
+			"target-html": { type: "boolean" },
+			"shadow-html": { type: "boolean" },
+			"target-css": { type: "boolean" },
+			"shadow-css": { type: "boolean" },
+			js: { type: "boolean" },
+			dir: { type: "string" },
+			namespace: { type: "string" },
+			port: { type: "string" },
+			force: { type: "boolean" },
+			"dry-run": { type: "boolean" },
+			help: {
+				type: "boolean",
+				short: "h"
+			},
+			version: {
+				type: "boolean",
+				short: "v"
+			}
+		}
+	});
+	const command = positionals[0];
+	if (values.version) {
+		console.log(await readVersion());
+		return 0;
+	}
+	if (values.help || !command) {
+		console.log(USAGE);
+		return 0;
+	}
+	if (command === "new") {
+		const tag = positionals[1];
+		if (!tag) {
+			console.error("mc new: missing component tag (e.g. mc new my-card)");
+			return 1;
+		}
+		const assets = [];
+		const flags = values;
+		for (const [flag, kind] of Object.entries(ASSET_FLAGS)) if (flags[flag]) assets.push(kind);
+		if (values["dry-run"]) {
+			const { files } = scaffoldComponent(tag, {
+				assets,
+				js: values.js
+			});
+			const root = values.dir ?? "src";
+			for (const rel of Object.keys(files).sort()) console.log(`would create ${createdPath(root, rel)}`);
+			return 0;
+		}
+		const root = values.dir ?? "src";
+		let written;
+		try {
+			written = await writeScaffold(tag, root, {
+				assets,
+				js: values.js,
+				force: values.force
+			});
+		} catch (e) {
+			console.error(e.message);
+			return 1;
+		}
+		for (const rel of written) console.log(`created ${createdPath(root, rel)}`);
+		return 0;
+	}
+	if (command === "create") {
+		const namespace = values.namespace;
+		if (!namespace) {
+			console.error("mc create: missing --namespace (e.g. mc create --namespace mc)");
+			return 1;
+		}
+		const root = values.dir ?? namespace;
+		let files;
+		try {
+			({files} = scaffoldProject(namespace));
+		} catch (e) {
+			console.error(e.message);
+			return 1;
+		}
+		if (values["dry-run"]) {
+			for (const rel of Object.keys(files).sort()) console.log(`would create ${createdPath(root, rel)}`);
+			return 0;
+		}
+		let written;
+		try {
+			written = await writeProject(namespace, root, { force: values.force });
+		} catch (e) {
+			console.error(e.message);
+			return 1;
+		}
+		for (const rel of written) console.log(`created ${createdPath(root, rel)}`);
+		console.log(`\nproject "${namespace}" created in ${root}/ — run: cd ${root} && pnpm install && pnpm dev`);
+		return 0;
+	}
+	if (command === "dev") return run("dev", { port: values.port ? Number(values.port) : 5173 });
+	if (command === "bundle") return run("bundle");
+	if (command === "preview") return run("preview", { port: values.port ? Number(values.port) : 5174 });
+	if (command === "clean") return run("clean");
+	if (command === "check") return run("check");
+	console.error(`mc: unknown command "${command}"\n\n${USAGE}`);
+	return 1;
+}
+//#endregion
+//#region src/cli/index.ts
 /**
 Executable entry point of the `mc` CLI (package.json "bin").
 
@@ -8,5 +1814,5 @@ in and pushes the resulting exit code out.
 
 @module CLI/Index
 */
-import { main } from './dispatch.js';
 process.exitCode = await main(process.argv.slice(2));
+//#endregion