@twobirds/microcomponents 0.11.0 → 0.13.0

package/dist/cli/index.js

@@ -3,6 +3,7 @@ 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 { createInterface } from "node:readline/promises";
 import path from "node:path";
 import { createServer } from "node:http";
 //#region src/utils/resolveComponentPath.ts
@@ -168,8 +169,10 @@ runtime autoload loader uses, so the scaffold and the runtime can never disagree
 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
+the home of tags like `<xxx-app>` (tagPath `xxx-app` → `xxx/app`). The project owns its
+namespace, so it can be any length: `isLongNamespace` flags the ones past
+`LONG_NAMESPACE` (5) for the CLI to warn about and confirm before anything is written.
+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
@@ -182,18 +185,36 @@ function starterTag(namespace) {
 	return `${namespace}-app`;
 }
 /**
-Whether a string is a valid project namespace: 1 to 4 lowercase letters.
+Whether a string is a valid project namespace: lowercase letters and digits, starting
+with a letter, any length. The project owns its namespace, so length is the user's
+call — {@link isLongNamespace} flags the ones worth confirming before writing.
 
 @example
 ```ts
 console.log(isValidNamespace('mc'));
-console.log(isValidNamespace('mcxyz'));
-console.log(isValidNamespace('toolong'));
+console.log(isValidNamespace('microcomponents'));
+console.log(isValidNamespace('Shop'));
 ```
 @param ns - Candidate namespace.
 */
 function isValidNamespace(ns) {
-	return /^[a-z]{1,4}$/.test(ns);
+	return /^[a-z][a-z0-9]*$/.test(ns);
+}
+/**
+Whether a namespace is long enough to warn about. The namespace is the project's own
+and the first segment of every component tag, so a long one lands in every tag, every
+folder path, and every bundle import.
+
+@example
+```ts
+console.log(isLongNamespace('mc'));              // false
+console.log(isLongNamespace('shop'));            // false
+console.log(isLongNamespace('microcomponents')); // true
+```
+@param ns - Candidate namespace.
+*/
+function isLongNamespace(ns) {
+	return ns.length > 5;
 }
 /**
 Builds the files of a complete dev environment for a namespace.
@@ -204,17 +225,19 @@ 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.
+@param namespace - lowercase letters and digits, starting with a letter, any length;
+becomes the `src/<namespace>/` folder and the first segment of every component tag.
+@throws If `namespace` is not lowercase letters and digits starting with a letter.
 */
 function scaffoldProject(namespace) {
-	if (!isValidNamespace(namespace)) throw new Error(`invalid namespace "${namespace}": must be 1 to 4 lowercase letters (e.g. "mc")`);
+	if (!isValidNamespace(namespace)) throw new Error(`invalid namespace "${namespace}": must be lowercase letters and digits, starting with a letter (e.g. "mc")`);
 	const tag = starterTag(namespace);
 	const base = tagPath(tag);
 	const files = {};
 	files["package.json"] = packageJson(namespace);
 	files["tsconfig.json"] = tsconfig();
+	files["tsconfig.test.json"] = tsconfigTest();
+	files["vitest.config.ts"] = vitestConfig();
 	files[".gitignore"] = gitignore();
 	files["opencode.jsonc"] = opencodeConfig();
 	files[".opencode/skills/components/SKILL.md"] = componentSkill(namespace, tag);
@@ -226,6 +249,7 @@ function scaffoldProject(namespace) {
 	files[`src/${base}.target.css`] = appCss(tag);
 	files[`src/${namespace}/bundle.ts`] = bundle();
 	files["src/bundle.json"] = bundleConfig(namespace);
+	files[`test/${base}.spec.ts`] = appSpec(tag);
 	return {
 		files,
 		namespace
@@ -240,10 +264,15 @@ function packageJson(namespace) {
 			dev: "mc dev",
 			build: "tsc -p tsconfig.json && mc bundle",
 			preview: "mc preview",
-			typecheck: "tsc --noEmit -p tsconfig.json"
+			typecheck: "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
+			test: "vitest run"
 		},
-		dependencies: { "@twobirds/microcomponents": "^0.11.0" },
-		devDependencies: { typescript: "^6.0.3" }
+		dependencies: { "@twobirds/microcomponents": "^0.13.0" },
+		devDependencies: {
+			typescript: "^6.0.3",
+			vitest: "^4.1.10",
+			jsdom: "^29.1.1"
+		}
 	}, null, "	");
 }
 function tsconfig() {
@@ -267,6 +296,60 @@ function tsconfig() {
 		include: ["src/**/*.ts"]
 	}, null, "	");
 }
+function tsconfigTest() {
+	return JSON.stringify({
+		compilerOptions: {
+			target: "ESNext",
+			module: "ESNext",
+			moduleResolution: "Bundler",
+			lib: [
+				"ESNext",
+				"DOM",
+				"DOM.Iterable"
+			],
+			strict: true,
+			esModuleInterop: true,
+			skipLibCheck: true,
+			noEmit: true
+		},
+		include: ["test/**/*.ts"]
+	}, null, "	");
+}
+function vitestConfig() {
+	return `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+	test: {
+		// components need a DOM: jsdom gives \`customElements\`, \`document\`, and the
+		// \`_mc\` contract the library writes, so a spec runs the real class code
+		environment: 'jsdom',
+		include: ['test/**/*.spec.ts'],
+	},
+});
+`;
+}
+function appSpec(tag) {
+	const className = kebabToPascal(tag);
+	return `import { describe, expect, it } from 'vitest';
+import { DC, parse } from '@twobirds/microcomponents';
+import { ${className} } from '../../src/${tagPath(tag)}.js';
+
+describe('${tag}', () => {
+	it('registers the starter tag in the custom element registry', () => {
+		// importing the module runs defineCE, so the tag is in the registry, and the
+		// exported class is the DC subclass behind it
+		expect(customElements.get('${tag}')).toBeDefined();
+		expect(${className}.prototype instanceof DC).toBe(true);
+	});
+
+	it('renders the title from data through parse()', () => {
+		const html = parse('<h1>{title}</h1>', { title: 'Micro Components' });
+
+		expect(html).toContain('<h1>Micro Components</h1>');
+	});
+});
+`;
+}
 function gitignore() {
 	return `node_modules/
 build/
@@ -292,7 +375,7 @@ function opencodeConfig() {
 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/.
+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, binding state or form values in a component, running dev or build, or touching build/ or public/.
 ---
 
 # Micro Components project
@@ -304,11 +387,13 @@ Namespace \`${namespace}\`. Every tag starts with \`${namespace}-\`. Components
 \`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.
+- \`build/\` is the \`tsc\` output plus the files \`tsc\` does not compile — companion assets and plain \`.js\` components — 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.
 
+Never write an import map. \`autoload()\` fetches a component by its tag (\`ns-name\` → \`./ns/name.js\`), and the dev server and \`mc bundle\` resolve the \`@twobirds/microcomponents\` specifier, so the page never lists imports.
+
 ## Add a component
 
 \`\`\`sh
@@ -317,6 +402,8 @@ 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.
 
+\`--js\` writes \`src/ns/name.js\` instead of \`.ts\`. \`tsc\` compiles only \`.ts\`, so the dev server and \`mc bundle\` copy a plain \`.js\` component to \`build/\` verbatim — it autoloads and bundles like a compiled component, with no type checking and no \`.d.ts\`.
+
 Register the component so the production bundle picks it up:
 
 \`\`\`ts
@@ -343,27 +430,38 @@ A camelCase descriptor maps to a dotted filename and is listed in \`static asset
 
 The loader fetches exactly the listed descriptors, so every entry in \`static assets\` needs its file.
 
+## State
+
+Inside a component, use the plugin methods. \`observePlugin(DC)\` adds \`this.notify()\`, \`this.subscribe()\`, \`this.bind()\`; \`formValuePlugin(DC)\` adds \`this.formValues()\` and pulls in the observe methods. Call the plugin once at module level, then chain on \`this\` with the property *name*: \`this.subscribe('data', …)\`.
+
+The pure \`observe()\` and \`formValues()\` functions are for code outside the MC system — vanilla JS, framework lifecycle code, Node. Never call them inside a \`DC\`: the plugin methods create the same wrapper, chain, and keep the \`keyof this & string\` typing contract.
+
 ## 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' } } })
+	new CustomEvent('addToCart', { detail: { data: { id: 'x' } } })
 );
 \`\`\`
 
 Bubble up or down the tree only when the receiver cannot be named.
 
+Event names are plain inside the project — \`add\`, \`toggle\`, \`addToCart\`. Namespace a name (\`${namespace}:addToCart\`) only when a collision is likely: an event entering the project from outside (a framework, a page script, a third-party addon DC), or several DCs attached to one component dispatching the same name. One producer per name means no collision, so no namespace.
+
 ## Verify
 
 \`\`\`sh
 pnpm typecheck
+pnpm test
 pnpm dev
 pnpm build
 pnpm preview
 \`\`\`
 
+Specs live in \`test/\` and run under vitest in jsdom, so component class code executes against a real DOM. Import the component from \`src/\` with a \`.js\` specifier; vitest resolves it to the \`.ts\` source.
+
 \`mc clean\` removes \`build/\`, \`public/\` and \`coverage/\`.
 
 ## API reference
@@ -391,7 +489,8 @@ 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.
+autoloader looks for them. The server binds loopback, so only this machine reaches it;
+\`pnpm dev -- --host 0.0.0.0\` widens it to the LAN.
 
 ## Build
 
@@ -410,13 +509,26 @@ The bundle is driven by \`src/bundle.json\`: \`entry\` names the barrel to bundl
 pnpm preview
 \`\`\`
 
+## Test
+
+\`\`\`sh
+pnpm test
+\`\`\`
+
+Specs live in \`test/\` and run under vitest in jsdom, so component class code executes
+against a real DOM: \`customElements\`, \`document\`, and the \`_mc\` property the library
+writes. \`test/${namespace}/app.spec.ts\` is the starter spec — it asserts the tag is
+registered and that \`parse()\` renders the title from \`data\`.
+
 ## Type-check
 
 \`\`\`sh
 pnpm typecheck
 \`\`\`
 
-\`tsconfig.json\` compiles \`src/\` into \`build/\`.
+\`tsconfig.json\` compiles \`src/\` into \`build/\`; \`tsconfig.test.json\` type-checks
+\`test/\` without emitting, so a spec that imports a component is checked against the
+component's real types.
 
 ## Components
 
@@ -458,11 +570,8 @@ function devShell(namespace, tag) {
 		<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';
+			import * as m from '/microcomponents.min.js';
 			m.autoload(true);
 			Object.assign(window, m);
 		<\/script>
@@ -499,7 +608,7 @@ function appSource(namespace, tag) {
 <${tag}></${tag}>
 \`\`\`
 */
-class ${className} extends DC {
+export class ${className} extends DC {
 	static assets = ['html', 'targetCss'];
 
 	data = { title: 'Micro Components' };
@@ -621,12 +730,12 @@ namespace under a project root, creating nested folders as needed.
 const written = await writeProject('mc', 'mc-app');
 console.log(written);
 ```
-@param namespace - 1 to 4 lowercase letters.
+@param namespace - lowercase letters and digits, starting with a letter, any length.
 @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.
+@throws If `namespace` is not lowercase letters and digits starting with a letter, or
+a target file exists and `force` is false.
 */
 async function writeProject(namespace, root, options = {}) {
 	const { files } = scaffoldProject(namespace);
@@ -1071,8 +1180,9 @@ 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}
+autoload path), then `mc bundle` mirrors the files `tsc` does not compile —
+companion assets and plain `.js` components — 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
@@ -1081,45 +1191,52 @@ copies the production shell. The result is a complete static site: a single
 
 @module CLI/Bundle
 */
-/** Companion asset extensions copied verbatim next to their compiled `.js`. */
-var COMPANION_EXTENSIONS = [
+/** Files `tsc` does not compile, copied verbatim next to the compiled components. */
+var MIRROR_EXTENSIONS = [
 	".css",
 	".html",
-	".json"
+	".json",
+	".js"
 ];
 /**
-* Whether a file is a companion asset to mirror into `build/`.
+* Whether a file in `src/` is copied verbatim into `build/`. Companion assets
+* (`.css`, `.html`, `.json`) sit next to their compiled `.js`, and a plain `.js`
+* component (`mc new --js`) is copied as it is: `tsc` compiles only `.ts`, so plain
+* JS reaches the autoloader by copying, not by compiling. The page shells are not
+* mirrored by this rule — `mc dev` copies the dev shell itself.
 *
 * @example
 * ```ts
-* isCompanion('app.target.html');  // true
-* isCompanion('index.html');       // false
+* isMirrored('app.target.html');  // true
+* isMirrored('app.js');           // true — a plain JS component
+* isMirrored('index.html');       // false
 * ```
 * @param name Basename of the file.
 */
-function isCompanion(name) {
+function isMirrored(name) {
 	if (name === "index.html" || name === "index-dev.html") return false;
-	return COMPANION_EXTENSIONS.some((ext) => name.endsWith(ext));
+	return MIRROR_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`.
+* Mirror the files `tsc` does not compile (`.css`, `.html`, `.json`, `.js`) from
+* `src/` into `build/`, preserving the tree, so the bundler reads each asset and
+* each plain JS component next to its compiled `.js`.
 *
 * @example
 * ```ts
-* await mirrorCompanions('<root>/src', '<root>/build');
+* await mirrorSources('<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 = "") {
+async function mirrorSources(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)) {
+			await mirrorSources(srcDir, buildDir, next);
+		} else if (isMirrored(entry.name)) {
 			const dst = path.join(buildDir, next);
 			await mkdir(path.dirname(dst), { recursive: true });
 			await cp(path.join(srcDir, next), dst);
@@ -1150,17 +1267,20 @@ async function collectPlainCss(srcDir, rel = "", 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.
+* without a bare-specifier import map. Subpath imports resolve to the same module,
+* so the library stays one instance. This is the single source of truth for the
+* rule: the bundler uses the relative target, the dev server passes its served URL.
 *
-* @example Turns the package specifier into a relative path.
+* @example Turns the package specifier into a relative path, leaves others alone.
 * ```ts
 * rewriteLibrarySpecifier("import { DC } from '@twobirds/microcomponents';");
+* rewriteLibrarySpecifier("import { z } from 'zod';"); // unchanged
 * ```
 * @param code Bundled module source.
-* @param target Relative specifier to point the import at.
+* @param target Specifier to point the import at.
 */
 function rewriteLibrarySpecifier(code, target = "./microcomponents.min.js") {
-	return code.replace(/from\s*['"]@twobirds\/microcomponents['"]/g, `from '${target}'`);
+	return code.replace(/(['"])@twobirds\/microcomponents(?:\/[^'"]*)?\1/g, `$1${target}$1`);
 }
 /**
 * Assemble the production site in `public/` from the compiled `build/` tree.
@@ -1180,7 +1300,7 @@ async function bundleProject(projectRoot, options) {
 	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);
+	await mirrorSources(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");
@@ -1216,12 +1336,14 @@ 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
+mirrors the files `tsc` does not compile — companion assets and plain `.js`
+components — 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.
+can use), redirects `/` to the autoload shell (`index-dev.html`), serves the
+self-contained library at `/microcomponents.min.js`, and rewrites the
+`@twobirds/microcomponents` specifier in served JS to that URL, so a compiled
+component resolves the library with no import map in the page.
 
 There is no HMR: a page reload picks up the recompiled component.
 
@@ -1283,8 +1405,9 @@ async function serve(req, res, buildRoot, minJs) {
 	}
 	try {
 		const text = await readFile(abs, "utf-8");
+		const body = abs.endsWith(".js") ? rewriteLibrarySpecifier(text, "/microcomponents.min.js") : text;
 		res.setHeader("Content-Type", mimeFor(path.basename(abs)));
-		res.end(text);
+		res.end(body);
 	} catch {
 		/* v8 ignore start — resolveTarget already checked existence; a read failure is a race */
 		res.statusCode = 404;
@@ -1292,8 +1415,9 @@ async function serve(req, res, buildRoot, minJs) {
 	}
 }
 /**
-* Mirror companion assets from `src/` into `build/`, preserving the tree, so the
-* served folder stays autoload-ready.
+* Mirror the files `tsc` does not compile — companion assets and plain `.js`
+* components — from `src/` into `build/`, preserving the tree, so the served
+* folder stays autoload-ready.
 *
 * @example
 * ```ts
@@ -1308,7 +1432,7 @@ async function mirrorInto(sourceRoot, buildRoot, rel = "") {
 		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") {
+		} else if (isMirrored(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);
@@ -1341,10 +1465,12 @@ function createDevServer(projectRoot, options) {
 * @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.
+* @param host Bind address. Defaults to loopback, so a dev server serving source files is
+*   not reachable off the machine. Pass an interface address to serve the LAN.
 * @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) {
+async function runDev(projectRoot = process.cwd(), minJs = path.join(import.meta.dirname, "..", "microcomponents.min.js"), port = 5173, host = "127.0.0.1") {
 	const sourceRoot = path.join(projectRoot, "src");
 	const buildRoot = path.join(projectRoot, "build");
 	await mirrorInto(sourceRoot, buildRoot);
@@ -1360,7 +1486,7 @@ async function runDev(projectRoot = process.cwd(), minJs = path.join(import.meta
 	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")) {
+		if (isMirrored(path.basename(file)) || file.endsWith("index-dev.html")) {
 			const dst = path.join(buildRoot, file);
 			mkdir(path.dirname(dst), { recursive: true }).then(() => cp(abs, dst));
 		}
@@ -1369,8 +1495,8 @@ async function runDev(projectRoot = process.cwd(), minJs = path.join(import.meta
 		minJs,
 		port
 	});
-	server.listen(port);
-	console.log(`dev server on http://localhost:${port}/ (serving build/, tsc -w running)`);
+	server.listen(port, host);
+	console.log(`dev server on http://${host === "0.0.0.0" ? "localhost" : host}:${port}/ (serving build/, tsc -w running)`);
 	return new Promise((resolve) => {
 		tsc.on("exit", () => {
 			server.close();
@@ -1454,13 +1580,15 @@ function createPreviewServer(projectRoot, port, outDir = "public") {
 *
 * @param projectRoot Project root (defaults to the current directory).
 * @param port Preview-server port.
+* @param host Bind address. Defaults to loopback, so a preview server is not reachable off
+*   the machine. Pass an interface address to serve the LAN.
 * @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) {
+async function runPreview(projectRoot = process.cwd(), port = 5174, host = "127.0.0.1") {
 	const server = createPreviewServer(projectRoot, port);
-	server.listen(port);
-	console.log(`preview server on http://localhost:${port}/ (serving public/)`);
+	server.listen(port, host);
+	console.log(`preview server on http://${host === "0.0.0.0" ? "localhost" : host}:${port}/ (serving public/)`);
 	return new Promise((resolve) => {
 		server.on("close", () => resolve(0));
 	});
@@ -1485,10 +1613,10 @@ 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 create --namespace <ns> [--dir <path>] [--force] [--yes] [--dry-run]
+  mc dev [--port <n>] [--host <addr>]
   mc bundle
-  mc preview [--port <n>]
+  mc preview [--port <n>] [--host <addr>]
   mc clean
   mc check
   mc --version
@@ -1515,7 +1643,10 @@ Other options:
   --js         emit plain JavaScript instead of TypeScript
   --dir <path> scaffold root (default: src)
   --port <n>   dev / preview server port (default: 5173 / 5174)
+  --host <addr> dev / preview bind address (default: 127.0.0.1 — loopback only; pass
+                0.0.0.0 or a interface address to serve the LAN)
   --force      overwrite files that already exist
+  --yes        skip the confirmation when a namespace is longer than 5 characters (-y)
   --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)
@@ -1533,6 +1664,25 @@ var ASSET_FLAGS = {
 	"shadow-css": "shadowCss"
 };
 /**
+Asks on the terminal whether to continue with a long namespace. `y`/`yes`
+(case-insensitive) continue; anything else, including an unreadable stdin, aborts.
+
+@example
+```ts
+const ok = await confirmNamespace('microcomponents');
+```
+@param namespace - The namespace to confirm.
+*/
+async function confirmNamespace(namespace) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	const answer = await rl.question(`continue with "${namespace}"? [y/N] `);
+	rl.close();
+	return /^y(es)?$/i.test(answer.trim());
+}
+/**
 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
@@ -1670,16 +1820,17 @@ 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 === "dev") return runDev(process.cwd(), void 0, options?.port ?? 5173, options?.host ?? "127.0.0.1");
 	if (script === "bundle") return runBundle();
-	if (script === "preview") return runPreview(process.cwd(), options?.port ?? 5174);
+	if (script === "preview") return runPreview(process.cwd(), options?.port ?? 5174, options?.host ?? "127.0.0.1");
 	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.
+spawning anything, and `confirm` is injectable so the long-namespace prompt can be
+tested without a terminal.
 
 @example
 ```ts
@@ -1692,8 +1843,11 @@ return 0;
 ```ts
 const code = await main(['--version']);
 ```
+@param argv - Arguments to route (usually `process.argv.slice(2)`).
+@param run - Runs a package.json script (defaults to {@link runScript}).
+@param confirm - Confirms a long namespace (defaults to the terminal prompt).
 */
-async function main(argv, run = runScript) {
+async function main(argv, run = runScript, confirm = confirmNamespace) {
 	const { values, positionals } = parseArgs({
 		args: argv,
 		allowPositionals: true,
@@ -1708,7 +1862,12 @@ async function main(argv, run = runScript) {
 			dir: { type: "string" },
 			namespace: { type: "string" },
 			port: { type: "string" },
+			host: { type: "string" },
 			force: { type: "boolean" },
+			yes: {
+				type: "boolean",
+				short: "y"
+			},
 			"dry-run": { type: "boolean" },
 			help: {
 				type: "boolean",
@@ -1768,6 +1927,13 @@ async function main(argv, run = runScript) {
 			console.error("mc create: missing --namespace (e.g. mc create --namespace mc)");
 			return 1;
 		}
+		if (isLongNamespace(namespace)) {
+			console.warn(`mc create: namespace "${namespace}" is ${namespace.length} characters — every component tag in the project starts with it.`);
+			if (!values["dry-run"] && !values.yes && !await confirm(namespace)) {
+				console.error("mc create: aborted");
+				return 1;
+			}
+		}
 		const root = values.dir ?? namespace;
 		let files;
 		try {
@@ -1791,9 +1957,15 @@ async function main(argv, run = runScript) {
 		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 === "dev") return run("dev", {
+		port: values.port ? Number(values.port) : 5173,
+		host: values.host
+	});
 	if (command === "bundle") return run("bundle");
-	if (command === "preview") return run("preview", { port: values.port ? Number(values.port) : 5174 });
+	if (command === "preview") return run("preview", {
+		port: values.port ? Number(values.port) : 5174,
+		host: values.host
+	});
 	if (command === "clean") return run("clean");
 	if (command === "check") return run("check");
 	console.error(`mc: unknown command "${command}"\n\n${USAGE}`);