@twobirds/microcomponents 0.7.0 → 0.9.0

package/README.md

@@ -75,6 +75,20 @@ There is no hand-written API list in the server. The whole index is extracted fr
 
 `get-source-file` reads package-root relative paths (`dist/core/MC.d.ts`, `dist/mcp/concepts/event-system.md`) and refuses any path outside the package sources.
 
+## Vite Plugin
+
+The package ships a Vite plugin as its own entry, `@twobirds/microcomponents/vite`, for the bundled production build:
+
+```ts
+import { loadAssetsPlugin } from '@twobirds/microcomponents/vite';
+
+export default defineConfig({
+	plugins: [loadAssetsPlugin(sourceRoot)],
+});
+```
+
+`loadAssetsPlugin` reads the companion `.css` / `.html` files of every DC class that declares `static assets = [...]` and embeds them as a `static _assets` property inside the class, so `loadAssets()` never fetches them at runtime. `mc create` wires it into the generated `vite.config.ts`, which bundles a single `bundle.js` into `public/`.
+
 ## CLI
 
 A small command-line tool scaffolds new components so the tag-to-file convention is never hand-written:
@@ -95,21 +109,25 @@ pnpm run cli -- new my-card --target-html --target-css --dry-run
 # would create src/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)`, a starter component with companion assets, and an `opencode.jsonc` that registers the MCP server:
+`mc create` scaffolds a complete dev environment for a namespace, following the three-path chain the library's own demos use — `src/` → (tsc) → `build/` → (bundle) → `public/`:
 
 ```bash
 pnpm run cli -- create --namespace mc --dir mc-app
 # created mc-app/package.json
 # created mc-app/opencode.jsonc
 # created mc-app/src/index.html
+# created mc-app/src/index-dev.html
 # created mc-app/src/mc/app.ts
 # created mc-app/src/mc/app.target.html
 # created mc-app/src/mc/app.target.css
+# created mc-app/src/mc/bundle.ts
 # ...
 # 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.
+`pnpm dev` runs `tsc -w` and serves `build/`, so a saved component reaches the browser through `autoload()` with nothing bundled; companion assets are mirrored into `build/` next to the compiled component, which is where the autoloader looks for them. `pnpm build` emits one minified `bundle.js` into `public/` with every companion asset inlined by `loadAssetsPlugin`, the concatenated `bundle.css`, and the production shell — a single script tag, no autoloader. `opencode.jsonc` registers the MCP server, so opencode picks it up when you open the project.
+
+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 dev shell is the autoload base, `import.meta.url` + the tag-to-path rule resolves `<mc-app>` to `build/mc/app.js` — the compiled starter. New components are served automatically by the autoloader, but the bundle walks one entry, so add each one to `src/<namespace>/bundle.ts`. `--dir` defaults to the namespace, `--dry-run` prints the plan without touching disk.
 
 The project is written into a folder of its own, so its files are reported under that folder (`mc-app/src/mc/app.ts`) — the path you can find from the directory you ran the command in, not relative to the project root.
 

package/dist/cli/create.d.ts

@@ -9,11 +9,11 @@ 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.
+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
 */

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

@@ -1 +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,CAwBhE"}
+{"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,CA2BhE"}

package/dist/cli/create.js

@@ -9,11 +9,11 @@ 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.
+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
 */
@@ -63,11 +63,14 @@ export function scaffoldProject(namespace) {
     files['vite.config.ts'] = viteConfig(namespace);
     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'] = shell(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();
     return { files, namespace };
 }
 function packageJson(namespace) {
@@ -78,11 +81,11 @@ function packageJson(namespace) {
         scripts: {
             dev: 'vite',
             build: 'vite build',
-            preview: 'vite preview',
+            preview: 'vite preview --outDir public --port 5174',
             typecheck: 'tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.vc.json',
         },
         dependencies: {
-            '@twobirds/microcomponents': '^0.7.0',
+            '@twobirds/microcomponents': '^0.9.0',
         },
         devDependencies: {
             vite: '^8.1.5',
@@ -101,7 +104,9 @@ function tsconfig() {
             strict: true,
             esModuleInterop: true,
             skipLibCheck: true,
-            noEmit: true,
+            rootDir: 'src',
+            outDir: 'build',
+            removeComments: true,
         },
         include: ['src/**/*.ts'],
     }, null, '\t');
@@ -124,7 +129,8 @@ function tsconfigVc() {
 }
 function gitignore() {
     return `node_modules/
-dist/
+build/
+public/
 `;
 }
 function opencodeConfig() {
@@ -139,6 +145,86 @@ function opencodeConfig() {
         },
     }, null, '\t');
 }
+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';
+\`\`\`
+
+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
 
@@ -156,14 +242,24 @@ pnpm install
 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
 \`\`\`
 
-Components compile to \`dist/\` at their own autoload path, and companion \`.css\`, \`.html\` and
-\`.json\` files are copied next to them, so the built output loads like the dev server.
+\`public/\` is the production site: one minified \`bundle.js\` with every companion asset
+inlined by \`loadAssetsPlugin\`, the concatenated \`bundle.css\`, and the page shell. A
+single script tag loads it, no autoloader needed.
+
+\`\`\`sh
+pnpm preview
+\`\`\`
 
 ## Type-check
 
@@ -171,8 +267,9 @@ Components compile to \`dist/\` at their own autoload path, and companion \`.css
 pnpm typecheck
 \`\`\`
 
-\`tsconfig.json\` checks \`src/\`; \`tsconfig.vc.json\` checks \`vite.config.ts\`, which lives outside
-\`src/\` and needs node types for its \`node:\` imports.
+\`tsconfig.json\` compiles \`src/\` into \`build/\`; \`tsconfig.vc.json\` checks
+\`vite.config.ts\`, which lives outside \`src/\` and needs node types for its \`node:\`
+imports.
 
 ## Components
 
@@ -183,31 +280,40 @@ 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 viteConfig(namespace) {
     return `/**
  * Dev and build config for a Micro Components project.
  *
- * \`src/\` is the Vite root, so the page shell and every component source are
- * served straight from source with no build step. Companion \`.css\`, \`.html\` and
- * \`.json\` files are served as raw text — Vite would otherwise answer a \`.html\`
- * request with its own transformed page (injecting \`/@vite/client\` into the
- * template) and a \`.css\` request with a JS module, neither of which
- * \`loadAssets()\` can consume. \`copyCompanions\` mirrors the same files into
- * \`dist/\` so the built output stays autoload-ready, and every component under
- * \`src/<namespace>/\` is a build entry, emitted at its own autoload path
- * (\`mc/app.ts\` → \`dist/mc/app.js\`).
+ * The chain is \`src/\` → \`build/\` → \`public/\`:
+ *
+ * - \`build/\` is the \`tsc\` output: one \`.js\` per component at its own autoload path,
+ *   plus the copied companion assets and the dev shell. The dev server serves it, so
+ *   the page loads components on demand through \`autoload()\` and nothing is bundled.
+ * - \`public/\` is the production output: one minified \`bundle.js\` with every companion
+ *   asset inlined by \`loadAssetsPlugin\`, the concatenated \`bundle.css\`, and the
+ *   production shell. A single script tag loads it, no autoloader needed.
  *
  * @module ViteConfig
  */
 
 import { defineConfig, type Plugin, type ResolvedConfig } from 'vite';
-import { cp, mkdir, readdir, readFile } from 'node:fs/promises';
+import { loadAssetsPlugin } from '@twobirds/microcomponents/vite';
+import { spawn } from 'node:child_process';
+import { cp, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 const projectRoot = import.meta.dirname;
 const sourceRoot = path.join(projectRoot, 'src');
+const buildRoot = path.join(projectRoot, 'build');
+const publicRoot = path.join(projectRoot, 'public');
 const namespace = '${namespace}';
 
 const pageShells = new Set(['index.html', 'index-dev.html']);
@@ -229,6 +335,84 @@ function isCompanionAsset(name: string): boolean {
 	return name.endsWith('.css') || name.endsWith('.json') || name.endsWith('.html');
 }
 
+/**
+ * Mirrors companion assets and the dev shell from \`src/\` into the served folder,
+ * preserving the tree. Autoload resolves \`<ns-app>\` to \`<ns>/app.js\` relative to the
+ * page shell, so the served folder needs the compiled component *and* its companion
+ * files at the same relative path.
+ *
+ * @example
+ * \`\`\`ts
+ * await mirrorAssets(sourceRoot, buildRoot);
+ * \`\`\`
+ *
+ * @param root Source root to walk.
+ * @param out Folder to write into.
+ * @param rel Path of the walked directory relative to \`root\`.
+ */
+async function mirrorAssets(root: string, out: string, rel = ''): Promise<void> {
+	for (const entry of await readdir(path.join(root, rel), { withFileTypes: true })) {
+		const next = rel ? path.join(rel, entry.name) : entry.name;
+		if (entry.isDirectory()) {
+			await mirrorAssets(root, out, next);
+		} else if (isCompanionAsset(entry.name) || entry.name === 'index-dev.html') {
+			const dst = path.join(out, next);
+			await mkdir(path.dirname(dst), { recursive: true });
+			await cp(path.join(root, next), dst);
+		}
+	}
+}
+
+/**
+ * Runs \`tsc -w\` for the lifetime of the dev server, so a saved component reaches
+ * \`build/\` without a second command.
+ *
+ * @example
+ * \`\`\`ts
+ * plugins: [tscWatch()],
+ * \`\`\`
+ */
+function tscWatch(): Plugin {
+	let child: ReturnType<typeof spawn> | undefined;
+	return {
+		name: 'tsc-watch',
+		configResolved() {
+			child = spawn('npx', ['tsc', '-w', '-p', 'tsconfig.json'], { cwd: projectRoot, stdio: 'inherit' });
+		},
+		closeServer() {
+			child?.kill();
+		},
+	};
+}
+
+/**
+ * Mirrors companion assets into \`build/\` before the dev server starts, and again on
+ * every change, so the served folder stays autoload-ready.
+ *
+ * @example
+ * \`\`\`ts
+ * plugins: [syncBuild()],
+ * \`\`\`
+ */
+function syncBuild(): Plugin {
+	return {
+		name: 'sync-build',
+		enforce: 'pre',
+		async configureServer(server) {
+			await mirrorAssets(sourceRoot, buildRoot);
+			server.watcher.on('all', async (event, file) => {
+				if (!file.startsWith(sourceRoot) || file.endsWith('.ts')) return;
+				const rel = path.relative(sourceRoot, file);
+				if (isCompanionAsset(path.basename(file)) || file.endsWith('index-dev.html')) {
+					const dst = path.join(buildRoot, rel);
+					await mkdir(path.dirname(dst), { recursive: true });
+					await cp(file, dst);
+				}
+			});
+		},
+	};
+}
+
 /**
  * Serves companion \`.css\`, \`.html\` and \`.json\` files as raw text, ahead of the
  * Vite transform middleware. Without it a \`.html\` request returns the transformed
@@ -237,10 +421,10 @@ function isCompanionAsset(name: string): boolean {
  *
  * @example
  * \`\`\`ts
- * plugins: [rawAssets(sourceRoot)],
+ * plugins: [rawAssets(buildRoot)],
  * \`\`\`
  *
- * @param root Source root that mirrors the \`src/\` tree.
+ * @param root Source root that mirrors the served tree.
  */
 function rawAssets(root: string): Plugin {
 	return {
@@ -266,109 +450,139 @@ function rawAssets(root: string): Plugin {
 }
 
 /**
- * Copies every companion asset from \`src/\` into the build output, preserving the
- * directory tree. Autoload resolves \`<ns-app>\` to \`<ns>/app.js\` relative to the
- * page shell, so \`dist/\` needs the compiled component *and* its companion files
- * at the same relative path.
+ * Serves the autoload shell (\`index-dev.html\`) at \`/\`. Vite answers \`/\` with
+ * \`index.html\`, which is the production shell referencing \`bundle.js\` — that file
+ * only exists in \`public/\`, so the dev server has to redirect to the dev shell.
  *
  * @example
  * \`\`\`ts
- * plugins: [copyCompanions(sourceRoot)],
+ * plugins: [devShell()],
  * \`\`\`
+ */
+function devShell(): Plugin {
+	return {
+		name: 'dev-shell',
+		enforce: 'pre',
+		configureServer(server) {
+			server.middlewares.use((req, res, next) => {
+				const url = req.url?.split('?')[0];
+				if (url !== '/' && url !== '/index.html') return next();
+				req.url = '/index-dev.html';
+				next();
+			});
+		},
+	};
+}
+
+/**
+ * Concatenates the plain \`.css\` token presets under \`src/\` into \`bundle.css\`,
+ * skipping the companion \`.target.css\` and \`.shadow.css\` files, which
+ * \`loadAssetsPlugin\` inlines into the JS bundle.
  *
- * @param root Source root to walk.
+ * @example
+ * \`\`\`ts
+ * plugins: [bundleCss()],
+ * \`\`\`
  */
-function copyCompanions(root: string): Plugin {
+function bundleCss(): Plugin {
 	let outDir = '';
 	return {
-		name: 'copy-companions',
+		name: 'bundle-css',
 		apply: 'build',
 		configResolved(config: ResolvedConfig) {
 			outDir = path.resolve(config.root, config.build.outDir);
 		},
 		async closeBundle() {
-			async function walk(dir: string, rel: string): Promise<void> {
-				for (const entry of await readdir(dir, { withFileTypes: true })) {
-					const src = path.join(dir, entry.name);
+			async function collect(dir: string, rel: string, found: string[]): Promise<void> {
+				for (const entry of await readdir(path.join(dir, rel), { withFileTypes: true })) {
+					const next = rel ? path.join(rel, entry.name) : entry.name;
 					if (entry.isDirectory()) {
-						await walk(src, path.join(rel, entry.name));
-					} else if (isCompanionAsset(entry.name)) {
-						const dst = path.join(outDir, rel, entry.name);
-						await mkdir(path.dirname(dst), { recursive: true });
-						await cp(src, dst);
+						await collect(path.join(dir, rel), next, found);
+					} else if (entry.name.endsWith('.css') && !/\\.(target|shadow)\\.css$/.test(entry.name)) {
+						found.push(path.join(dir, next));
 					}
 				}
 			}
-			await walk(root, '');
+			const files: string[] = [];
+			await collect(sourceRoot, '', files);
+			const parts = await Promise.all(files.map((f) => readFile(f, 'utf-8')));
+			await mkdir(outDir, { recursive: true });
+			await writeFile(path.join(outDir, 'bundle.css'), parts.join('\\n'), 'utf-8');
 		},
 	};
 }
 
 /**
- * Names a build chunk after its source path, so a component lands at the autoload
- * path (\`src/mc/app.ts\` → \`dist/mc/app.js\`). Rollup truncates chunk names at the
- * last \`/\`, so \`info.name\` alone cannot carry a folder — the facade module id is
- * the reliable source.
+ * Copies the production shell into \`public/\` next to the bundle, so the served
+ * folder is a complete static site.
  *
  * @example
  * \`\`\`ts
- * entryName({ name: 'mc/app', facadeModuleId: '/project/src/mc/app.ts' });
- * entryName({ name: 'index', facadeModuleId: '/project/src/index.html' });
+ * plugins: [copyShell()],
  * \`\`\`
- *
- * @param info Rollup chunk info.
  */
-function entryName(info: { name: string; facadeModuleId: string | null }): string {
-	const facade = info.facadeModuleId;
-	if (!facade || facade.endsWith('.html')) return \`\${info.name}.js\`;
-	return path.relative(sourceRoot, facade).replace(/\\\\/g, '/').replace(/\\.(ts|js)$/, '.js');
+function copyShell(): Plugin {
+	let outDir = '';
+	return {
+		name: 'copy-shell',
+		apply: 'build',
+		configResolved(config: ResolvedConfig) {
+			outDir = path.resolve(config.root, config.build.outDir);
+		},
+		async closeBundle() {
+			await cp(path.join(sourceRoot, 'index.html'), path.join(outDir, 'index.html'));
+		},
+	};
 }
 
-/**
- * Collects every component source as a build entry, keyed by its path relative to
- * \`src/\`. Plain \`.js\` files count too, so the rapid-prototyping path stays
- * buildable. New components are picked up automatically — no config edit needed.
- *
- * @example
- * \`\`\`ts
- * const entries: Record<string, string> = {};
- * await collectEntries(path.join(sourceRoot, 'mc'), 'mc', entries);
- * \`\`\`
- *
- * @param dir Directory to walk.
- * @param rel Path of that directory relative to \`src/\`.
- * @param entries Accumulated entries, mutated in place.
- */
-async function collectEntries(dir: string, rel: string, entries: Record<string, string>): Promise<void> {
-	for (const entry of await readdir(dir, { withFileTypes: true })) {
-		const full = path.join(dir, entry.name);
-		if (entry.isDirectory()) {
-			await collectEntries(full, path.join(rel, entry.name), entries);
-		} else if (entry.name.endsWith('.ts') || entry.name.endsWith('.js')) {
-			entries[path.join(rel, entry.name).replace(/\\.(ts|js)$/, '')] = full;
-		}
+export default defineConfig(({ command }) => {
+	if (command === 'serve') {
+		return {
+			root: buildRoot,
+			server: { port: 5173, open: false },
+			plugins: [syncBuild(), tscWatch(), rawAssets(buildRoot), devShell()],
+		};
 	}
-}
-
-export default defineConfig(async () => {
-	const entries: Record<string, string> = {};
-	await collectEntries(path.join(sourceRoot, namespace), namespace, entries);
 	return {
 		root: sourceRoot,
 		build: {
-			outDir: path.join(projectRoot, 'dist'),
+			outDir: publicRoot,
 			emptyOutDir: true,
+			minify: true,
+			target: 'esnext',
+			sourcemap: false,
+			lib: {
+				entry: path.join(sourceRoot, namespace, 'bundle.ts'),
+				formats: ['es'],
+				fileName: () => 'bundle.js',
+			},
 			rollupOptions: {
-				input: { index: path.join(sourceRoot, 'index.html'), ...entries },
-				output: { entryFileNames: (info: { name: string; facadeModuleId: string | null }) => entryName(info) },
+				treeshake: false,
+				output: { comments: false, keepNames: true },
 			},
 		},
-		plugins: [rawAssets(sourceRoot), copyCompanions(sourceRoot)],
+		plugins: [loadAssetsPlugin(sourceRoot), bundleCss(), copyShell()],
 	};
 });
 `;
 }
-function shell(namespace, tag) {
+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>
@@ -387,6 +601,13 @@ function shell(namespace, tag) {
 </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 appSource(namespace, tag) {
     const className = kebabToPascal(tag);
     return `import { DC, defineCE, parse, processAssets, type McEvent } from '@twobirds/microcomponents';

package/dist/mcp/api.json

@@ -1,6 +1,6 @@
 {
-  "libraryVersion": "0.7.0",
-  "exportedCount": 41,
+  "libraryVersion": "0.9.0",
+  "exportedCount": 42,
   "entries": {
     "MC": {
       "name": "MC",
@@ -429,7 +429,7 @@
       "signatures": [
         "export function trigger<D = unknown>( target: HTMLElement | string | undefined | null, event: string, data: D = {} as D, bubble: BubbleDirections = 'l', // direction of bubbling controller?: BubbleController ) {"
       ],
-      "description": "Creates and dispatches a custom event on the specified DOM node.\n\nThe event is namespaced with an `_mc` prefix by default, unless already prefixed.\nSupports bidirectional bubbling (up/down the DOM tree) based on the `bubble` parameter:\n- 'l': local dispatch only\n- 'u': bubble up towards ancestors\n- 'd': bubble down to descendants\n\nThe dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload\nunder `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.\n\nThe first dispatch fires locally only; the second bubbles upward to ancestor components.",
+      "description": "Creates and dispatches a custom event on the specified DOM node.\n\nThe event is namespaced with an `_mc` prefix by default, unless already prefixed.\nSupports bidirectional bubbling (up/down the DOM tree) based on the `bubble` parameter:\n- 'l': local dispatch only\n- 'u': bubble up towards ancestors\n- 'd': bubble down to descendants\n\nThe dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload\nunder `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.\n\nPrefer a direct target over bubbling: name the receiving element in `target` and keep the\ndefault `'l'`, so one `querySelectorAll` reaches it in a single step. Reserve `'u'`/`'d'`\nfor receivers that cannot be named in advance, since they walk the tree and re-dispatch the\nevent at every level. Pass a typed object as `data` rather than a bare string, so the\nhandler reads named fields from `ev.detail.data` and the flow stays readable as it grows.\n\nThe first dispatch fires locally only; the second bubbles upward to ancestor components.",
       "examples": [
         {
           "title": "",
@@ -595,6 +595,21 @@
         "export type McRemoved<T extends HTMLElement, K extends string> = T extends { _mc: McController } ? { _mc: Record<K, never> } : unknown;"
       ],
       "description": "The type `remove()` asserts onto the caller's reference: on an enhanced target the\nremoved key is poisoned to `never` (member access becomes a compile error); a\nplain target is left untouched. A later `add()` re-registers the key cleanly."
+    },
+    "loadAssetsPlugin": {
+      "name": "loadAssetsPlugin",
+      "kind": "function",
+      "file": "src/vite/loadAssets.ts",
+      "signatures": [
+        "export function loadAssetsPlugin(rootDir: string): PluginOption {"
+      ],
+      "description": "Vite plugin factory that inlines companion `.css` / `.html` assets into the\nDC classes declaring them through `static assets = [...]`.",
+      "examples": [
+        {
+          "title": "Register the plugin in a Vite config, pointing at the source root.",
+          "code": "import { loadAssetsPlugin } from './vite-plugin-load-assets';\nexport default defineConfig({ plugins: [loadAssetsPlugin(__dirname)] });"
+        }
+      ]
     }
   },
   "undocumented": []

package/dist/mcp/concepts/event-system.md

@@ -22,6 +22,29 @@ Bubble directions in trigger():
 
 Only use bubbling when there is a specific reason for it. Usually directly addressing the target is better, because of the speed advantage using querySelectorAll().
 
+## Choosing the target
+
+Name the receiving element in the trigger call and keep the default `'l'`, so a single
+`querySelectorAll` reaches it in one step. `'u'` and `'d'` walk the tree and re-dispatch the
+event at every level, so reserve them for receivers you cannot name in advance — a plugin
+listening to unknown descendants, or a widget whose host markup is not yours.
+
+The template declares the handler, the handler builds the payload, the trigger carries it:
+
+```html
+<button class="remove" click="|remove">✕</button>
+```
+
+```ts
+onRemove(): void {
+	trigger('todo-list', 'remove', { id: this.data.id });
+}
+```
+
+Pass an object, not a bare string, so the receiver reads named fields (`ev.detail.data.id`)
+and the flow stays readable as the payload grows. Declare the events on the component's event
+map (`EM` on `DC`) so the payload type is inferred at both ends.
+
 ## Payload & propagation
 
 MC-triggered custom events and lifecycle events are `McEvent<D>` — a `CustomEvent` whose `detail` is `{ data, control }`. The payload is always read from `ev.detail.data`, never `ev.data`.

package/dist/mcp/concepts/project-layout.md

@@ -0,0 +1,37 @@
+A Micro Components project keeps one folder per stage of the chain:
+
+```
+src/  →  (tsc)  →  build/  →  (bundle)  →  public/
+```
+
+- `src/` holds the authored sources: component `.ts` files, the companion
+  `.target.html` / `.target.css` / `.shadow.css` assets, the dev shell
+  (`index-dev.html`) and the production shell (`index.html`).
+- `build/` is the `tsc` output: one `.js` per component at its own autoload path,
+  plus the mirrored companion assets and the dev shell. The dev server serves it, so
+  the page loads components on demand through `autoload()` and nothing is bundled.
+- `public/` is the production site: one minified `bundle.js` with every companion
+  asset inlined by `loadAssetsPlugin`, the concatenated `bundle.css`, and the
+  production shell. A single script tag loads it; the autoloader is not needed.
+
+`build/` and `public/` are generated, so they stay out of git.
+
+A website that ships with the project — a playground, a component browser, a docs page —
+lives in `src/` like any other page, is served from `build/` while developing, and is
+served from `public/` in production. Do not add a fourth tree for it.
+
+A new component is picked up by the dev server automatically, because `autoload()`
+resolves its tag to a file under `build/`. The bundle is not: the bundler walks a single
+entry, so every component must be imported by the barrel `src/<namespace>/bundle.ts`.
+
+## Shells
+
+The two shells are deliberately different:
+
+- `index-dev.html` imports the library and calls `autoload(true)`, so a tag in the markup
+  pulls its own `.js` from `build/`.
+- `index.html` loads `bundle.js` and `bundle.css`, which only exist in `public/`.
+
+The dev server redirects `/` to `index-dev.html`; the production build copies
+`index.html` next to the bundle. Serving the production shell in dev would request a
+`bundle.js` that was never built.

package/dist/utils/events.d.ts

@@ -170,6 +170,12 @@ export declare class BubbleController implements McBubbleController {
  * The dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload
  * under `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.
  *
+ * Prefer a direct target over bubbling: name the receiving element in `target` and keep the
+ * default `'l'`, so one `querySelectorAll` reaches it in a single step. Reserve `'u'`/`'d'`
+ * for receivers that cannot be named in advance, since they walk the tree and re-dispatch the
+ * event at every level. Pass a typed object as `data` rather than a bare string, so the
+ * handler reads named fields from `ev.detail.data` and the flow stays readable as it grows.
+ *
  * @param target - The DOM element on which to trigger the event, or a querySelectorAll(selector) selector string.
  * @param event - The name of the event (will be prefixed if needed).
  * @param data - Additional data payload attached to `event.detail.data`.

package/dist/utils/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDE;AAIF,OAAO,KAAK,EACX,gBAAgB,EAChB,kBAAkB,EAElB,cAAc,EACd,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;;;;;EAQE;AACF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;;;;EAaE;AACF,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,mBAAmB,GAAG,SAAS,GAAG,IAAI,CAAC;AAEhF,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,IAAI,CAAC;AACR,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,IAAI,CAAC;AA4CR,wBAAgB,EAAE,CAAC,CAAC,GAAG,OAAO,EAC7B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,IAAI,CAAC,EAAE,OAAO,GACZ,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,EAAE,CACjB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,EAC3C,IAAI,CAAC,EAAE,OAAO,GACZ,kCAAkC,CAAC;AAsDtC,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,kCAAkC,CAAC;AA2CtC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAiB,YAAW,kBAAkB;IAC1D,OAAO,UAAS;;IAEhB;;;;;;;;;;;;;;OAcG;IACH,IAAI;CAGJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EAClC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,EAC/C,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,CAAW,EACjB,MAAM,GAAE,gBAAsB,EAAE,wBAAwB;AACxD,UAAU,CAAC,EAAE,gBAAgB,QA+C7B"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDE;AAIF,OAAO,KAAK,EACX,gBAAgB,EAChB,kBAAkB,EAElB,cAAc,EACd,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;;;;;EAQE;AACF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;;;;EAaE;AACF,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,mBAAmB,GAAG,SAAS,GAAG,IAAI,CAAC;AAEhF,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,IAAI,CAAC;AACR,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,IAAI,CAAC;AA4CR,wBAAgB,EAAE,CAAC,CAAC,GAAG,OAAO,EAC7B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,IAAI,CAAC,EAAE,OAAO,GACZ,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,EAAE,CACjB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,EAC3C,IAAI,CAAC,EAAE,OAAO,GACZ,kCAAkC,CAAC;AAsDtC,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,kCAAkC,CAAC;AA2CtC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAiB,YAAW,kBAAkB;IAC1D,OAAO,UAAS;;IAEhB;;;;;;;;;;;;;;OAcG;IACH,IAAI;CAGJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EAClC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,EAC/C,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,CAAW,EACjB,MAAM,GAAE,gBAAsB,EAAE,wBAAwB;AACxD,UAAU,CAAC,EAAE,gBAAgB,QA+C7B"}

package/dist/utils/events.js

@@ -253,6 +253,12 @@ export class BubbleController {
  * The dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload
  * under `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.
  *
+ * Prefer a direct target over bubbling: name the receiving element in `target` and keep the
+ * default `'l'`, so one `querySelectorAll` reaches it in a single step. Reserve `'u'`/`'d'`
+ * for receivers that cannot be named in advance, since they walk the tree and re-dispatch the
+ * event at every level. Pass a typed object as `data` rather than a bare string, so the
+ * handler reads named fields from `ev.detail.data` and the flow stays readable as it grows.
+ *
  * @param target - The DOM element on which to trigger the event, or a querySelectorAll(selector) selector string.
  * @param event - The name of the event (will be prefixed if needed).
  * @param data - Additional data payload attached to `event.detail.data`.

package/dist/vite/index.d.ts

@@ -0,0 +1,7 @@
+/**
+Vite module — build-time plugins for a bundled Micro Components project.
+
+@module Vite
+*/
+export { loadAssetsPlugin } from './loadAssets.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA;;;;EAIE;AAEF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/vite/index.js

@@ -0,0 +1,6 @@
+/**
+Vite module — build-time plugins for a bundled Micro Components project.
+
+@module Vite
+*/
+export { loadAssetsPlugin } from './loadAssets.js';

package/dist/vite/loadAssets.d.ts

@@ -0,0 +1,36 @@
+/**
+Inlines `static assets = [...]` declarations on DC classes for a bundled build: companion
+`.css` / `.html` files 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.
+
+The plugin ships as its own entry, `@twobirds/microcomponents/vite`, so a project that
+bundles to `public/` imports it without copying the source.
+
+@example
+```ts
+import { loadAssetsPlugin } from '@twobirds/microcomponents/vite';
+
+export default defineConfig({
+    plugins: [loadAssetsPlugin(sourceRoot)],
+});
+```
+
+@module Vite
+*/
+import type { PluginOption } from 'vite';
+/**
+ * Vite plugin factory that inlines companion `.css` / `.html` assets into the
+ * DC classes declaring them through `static assets = [...]`.
+ *
+ * @example Register the plugin in a Vite config, pointing at the source root.
+ * ```ts
+ * import { loadAssetsPlugin } from './vite-plugin-load-assets';
+ * export default defineConfig({ plugins: [loadAssetsPlugin(__dirname)] });
+ * ```
+ *
+ * @param rootDir Directory holding the component source files.
+ * @returns A Vite plugin option.
+ */
+export declare function loadAssetsPlugin(rootDir: string): PluginOption;
+//# sourceMappingURL=loadAssets.d.ts.map

package/dist/vite/loadAssets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadAssets.d.ts","sourceRoot":"","sources":["../../src/vite/loadAssets.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;EAmBE;AAIF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAgJzC;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAiE9D"}

package/dist/vite/loadAssets.js

@@ -0,0 +1,221 @@
+// oxlint-disable no-await-in-loop
+/**
+Inlines `static assets = [...]` declarations on DC classes for a bundled build: companion
+`.css` / `.html` files 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.
+
+The plugin ships as its own entry, `@twobirds/microcomponents/vite`, so a project that
+bundles to `public/` imports it without copying the source.
+
+@example
+```ts
+import { loadAssetsPlugin } from '@twobirds/microcomponents/vite';
+
+export default defineConfig({
+    plugins: [loadAssetsPlugin(sourceRoot)],
+});
+```
+
+@module Vite
+*/
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * 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 .ts source
+ * already lives in the correct directory (e.g. `cart-container-checkout.ts` 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] : undefined;
+}
+/**
+ * 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) {
+        // Line comment
+        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;
+            }
+            // Preserve newlines inside block comments to keep line positions valid
+            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; the same files are also merged into bundle.css as the override
+ * placeholder. 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('/src/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;
+}
+/**
+ * Vite plugin factory that inlines companion `.css` / `.html` assets into the
+ * DC classes declaring them through `static assets = [...]`.
+ *
+ * @example Register the plugin in a Vite config, pointing at the source root.
+ * ```ts
+ * import { loadAssetsPlugin } from './vite-plugin-load-assets';
+ * export default defineConfig({ plugins: [loadAssetsPlugin(__dirname)] });
+ * ```
+ *
+ * @param rootDir Directory holding the component source files.
+ * @returns A Vite plugin option.
+ */
+export function loadAssetsPlugin(rootDir) {
+    return {
+        name: 'load-assets-inline',
+        async transform(code, id) {
+            if (!code.includes('static assets'))
+                return null;
+            const dir = path.dirname(id);
+            // Strip comments so JSDoc examples don't trigger false matches.
+            // Whitespace-preserving replacement keeps character indices valid.
+            const stripped = stripComments(code);
+            // Resolve the component tag name from defineCE(...) call
+            const tagName = extractDefineCETag(stripped);
+            if (!tagName)
+                return null;
+            // Match: static assets = [ 'asset1' , 'asset2' ];
+            const saRegex = /static\s+assets\s*=\s*\[(.*?)\]\s*;?/gs;
+            const saMatches = [...stripped.matchAll(saRegex)];
+            if (saMatches.length === 0)
+                return null;
+            let transformed = code;
+            // There should be exactly one per file, but handle all in reverse
+            for (let i = saMatches.length - 1; i >= 0; i--) {
+                const match = saMatches[i];
+                const assetListRaw = match[1];
+                const assets = assetListRaw
+                    .split(',')
+                    .map((a) => a.trim().replace(/^['"]|['"]$/g, ''))
+                    .filter(Boolean);
+                if (assets.length === 0)
+                    continue;
+                // Read and inline all asset contents
+                const entries = await readAssetsInline(dir, tagName, assets);
+                // Build the static _assets property to inject as first line in class body
+                const objEntries = entries.map((e) => `${e.key}: ${e.literal}`);
+                const assetsObj = `{ ${objEntries.join(', ')} }`;
+                // Find the opening brace of the class that owns this `static assets` declaration.
+                // Search backwards from the match position to locate "class ... {" — we need the
+                // index of the opening brace so we can insert right after it.
+                const beforeMatch = stripped.substring(0, match.index);
+                const classOpenMatch = /class\s+\w+[^{]*\{/.exec(beforeMatch);
+                if (!classOpenMatch)
+                    continue;
+                // Absolute position of the opening brace in `transformed` (= same as in `stripped`)
+                const classBraceIndex = classOpenMatch.index + classOpenMatch[0].length - 1;
+                // Build injection code — static _assets as first line inside the class body
+                const injectCode = `\n    static _assets = ${assetsObj};\n`;
+                transformed =
+                    transformed.substring(0, classBraceIndex + 1) +
+                        injectCode +
+                        transformed.substring(classBraceIndex + 1);
+            }
+            return transformed;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"description": "Micro Components",
 	"keywords": [
 		"PWA",
@@ -73,6 +73,10 @@
 			"types": "./dist/mcp/index.d.ts",
 			"import": "./dist/mcp/index.js"
 		},
+		"./vite": {
+			"types": "./dist/vite/index.d.ts",
+			"import": "./dist/vite/index.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"scripts": {