@twobirds/microcomponents 0.12.1 → 0.13.0

package/README.md

@@ -116,9 +116,9 @@ pnpm run cli -- create --namespace mc --dir mc-app
 # project "mc" created in mc-app/ — run: cd mc-app && pnpm install && pnpm dev
 ```
 
-`pnpm dev` runs `mc dev`: `tsc -w` plus a `node:http` server serving `build/`, so a saved component reaches the browser through `autoload()` with nothing bundled; companion assets are mirrored into `build/` next to the compiled component, and the library is resolved through an import map to the served `microcomponents.min.js`. `pnpm build` runs `tsc` then `mc bundle`, which emits one `bundle.js` into `public/` with every companion asset inlined by the CLI bundler, the concatenated `bundle.css`, and the production shell — a single script tag, no autoloader. `pnpm preview` serves `public/`. `pnpm typecheck` checks `src/` and `test/` in two contexts, and `pnpm test` runs the specs under vitest in jsdom, so component class code executes against a real DOM. `opencode.jsonc` registers the MCP server, so opencode picks it up when you open the project.
+`pnpm dev` runs `mc dev`: `tsc -w` plus a `node:http` server serving `build/`, so a saved component reaches the browser through `autoload()` with nothing bundled; companion assets and plain `.js` components are mirrored into `build/` next to the compiled component, and the server rewrites the `@twobirds/microcomponents` specifier in the JS it serves to the `/microcomponents.min.js` it answers, so the page carries no import map. `pnpm build` runs `tsc` then `mc bundle`, which emits one `bundle.js` into `public/` with every companion asset inlined by the CLI bundler, the concatenated `bundle.css`, and the production shell — a single script tag, no autoloader. `pnpm preview` serves `public/`. `pnpm typecheck` checks `src/` and `test/` in two contexts, and `pnpm test` runs the specs under vitest in jsdom, so component class code executes against a real DOM. `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 namespace (lowercase letters and digits, starting with a letter, any length) becomes the `src/<namespace>/` folder and the first segment of every component tag, so `mc` is the home of tags like `<mc-app>`. The project owns its namespace, so length is allowed; past 5 characters `mc create` warns and asks for confirmation, and `--yes` skips the prompt for scripted runs. 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/bundle.d.ts

@@ -4,8 +4,9 @@
 
  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
@@ -28,29 +29,35 @@ export interface BundleConfig {
     outDir?: string;
 }
 /**
- * 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.
  */
-export declare function isCompanion(name: string): boolean;
+export declare function isMirrored(name: string): boolean;
 /**
- * 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`.
  */
-export declare function mirrorCompanions(srcDir: string, buildDir: string, rel?: string): Promise<void>;
+export declare function mirrorSources(srcDir: string, buildDir: string, rel?: string): Promise<void>;
 /**
  * Collect the plain `.css` token presets under `src/`, skipping the companion
  * `.target.css` / `.shadow.css` files, which the bundler inlines into the JS.
@@ -67,14 +74,17 @@ export declare function collectPlainCss(srcDir: string, rel?: string, found?: st
 /**
  * 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.
  */
 export declare function rewriteLibrarySpecifier(code: string, target?: string): string;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/cli/bundle.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;GAeG;AAMH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACpC,MAAM,EAAE,MAAM,EACd,GAAG,SAAK,EACR,KAAK,GAAE,MAAM,EAAO,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAUnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAA6B,GAAG,MAAM,CAEjG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D,OAAO,CAAC,MAAM,EAAE,CAAC,CAkCnB;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC9B,WAAW,GAAE,MAAsB,EACnC,KAAK,GAAE,MAAuE,GAC5E,OAAO,CAAC,MAAM,CAAC,CAIjB"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/cli/bundle.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAY7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACpC,MAAM,EAAE,MAAM,EACd,GAAG,SAAK,EACR,KAAK,GAAE,MAAM,EAAO,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAUnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAA6B,GAAG,MAAM,CAEjG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D,OAAO,CAAC,MAAM,EAAE,CAAC,CAmCnB;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC9B,WAAW,GAAE,MAAsB,EACnC,KAAK,GAAE,MAAuE,GAC5E,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/dist/cli/create.d.ts

@@ -8,8 +8,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
@@ -18,17 +20,35 @@ the dev shell is the autoload base, `import.meta.url` + `tagPath('xxx-app')` res
 @module CLI/Project
 */
 /**
-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.
 */
 export declare function isValidNamespace(ns: string): boolean;
+/** A namespace longer than this is confirmed before the project is written. */
+export declare const LONG_NAMESPACE = 5;
+/**
+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.
+*/
+export declare function isLongNamespace(ns: string): boolean;
 /** Result of {@link scaffoldProject}. */
 export interface ProjectResult {
     /** Files to write, keyed by path relative to the project root. */
@@ -45,9 +65,9 @@ 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.
 */
 export declare function scaffoldProject(namespace: string): ProjectResult;
 //# sourceMappingURL=create.d.ts.map

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,CA6BhE"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/cli/create.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;EAoBE;AAUF;;;;;;;;;;;;EAYE;AACF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,+EAA+E;AAC/E,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;;;;;EAYE;AACF,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEnD;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,CA6BhE"}

package/dist/cli/dev.d.ts

@@ -3,12 +3,14 @@
 
  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.
 
@@ -45,8 +47,9 @@ export declare function mimeFor(name: string): string;
  */
 export declare function resolveTarget(url: string, buildRoot: string, minJs: string): string | undefined;
 /**
- * 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

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

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/cli/dev.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AASjG;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO/F;AA8BD;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACtC,MAAM,CAKR;AAED;;;;;;;;;;GAUG;AAEH,wBAAsB,MAAM,CAC3B,WAAW,GAAE,MAAsB,EACnC,KAAK,GAAE,MAAuE,EAC9E,IAAI,GAAE,MAAa,EACnB,IAAI,GAAE,MAAoB,GACxB,OAAO,CAAC,MAAM,CAAC,CAiCjB"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/cli/dev.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AASjG;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO/F;AAkCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACtC,MAAM,CAKR;AAED;;;;;;;;;;GAUG;AAEH,wBAAsB,MAAM,CAC3B,WAAW,GAAE,MAAsB,EACnC,KAAK,GAAE,MAAuE,EAC9E,IAAI,GAAE,MAAa,EACnB,IAAI,GAAE,MAAoB,GACxB,OAAO,CAAC,MAAM,CAAC,CAiCjB"}

package/dist/cli/dispatch.d.ts

@@ -15,6 +15,8 @@ export type Runner = (script: string, options?: {
     port?: number;
     host?: string;
 }) => Promise<number>;
+/** Asks the user to confirm a namespace long enough to be worth a second look. */
+export type Confirmer = (namespace: string) => Promise<boolean>;
 /**
 Runs a package.json script through pnpm and resolves with its exit code.
 
@@ -35,7 +37,8 @@ export declare function runScript(script: string, options?: {
 /**
 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
@@ -48,6 +51,9 @@ const code = await main(['clean'], async (script) => {
 ```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).
 */
-export declare function main(argv: string[], run?: Runner): Promise<number>;
+export declare function main(argv: string[], run?: Runner, confirm?: Confirmer): Promise<number>;
 //# sourceMappingURL=dispatch.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/cli/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AAsEF,MAAM,MAAM,MAAM,GAAG,CACpB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KACtC,OAAO,CAAC,MAAM,CAAC,CAAC;AAwHrB;;;;;;;;;;;;EAYE;AACF,wBAAsB,SAAS,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;;;;;;;;;;;;;;;EAgBE;AACF,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HnF"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/cli/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AAwEF,MAAM,MAAM,MAAM,GAAG,CACpB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KACtC,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAyIhE;;;;;;;;;;;;EAYE;AACF,wBAAsB,SAAS,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;;;;;;;;;;;;;;;;;;;EAoBE;AACF,wBAAsB,IAAI,CACzB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,GAAE,MAAkB,EACvB,OAAO,GAAE,SAA4B,GACnC,OAAO,CAAC,MAAM,CAAC,CA4IjB"}

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,12 +225,12 @@ 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 = {};
@@ -246,7 +267,7 @@ function packageJson(namespace) {
 			typecheck: "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
 			test: "vitest run"
 		},
-		dependencies: { "@twobirds/microcomponents": "^0.12.1" },
+		dependencies: { "@twobirds/microcomponents": "^0.13.0" },
 		devDependencies: {
 			typescript: "^6.0.3",
 			vitest: "^4.1.10",
@@ -354,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
@@ -366,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
@@ -379,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
@@ -405,18 +430,26 @@ 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
@@ -537,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>
@@ -700,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);
@@ -1150,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
@@ -1160,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);
@@ -1229,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.
@@ -1259,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");
@@ -1295,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.
 
@@ -1362,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;
@@ -1371,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
@@ -1387,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);
@@ -1441,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));
 		}
@@ -1568,7 +1613,7 @@ 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 create --namespace <ns> [--dir <path>] [--force] [--yes] [--dry-run]
   mc dev [--port <n>] [--host <addr>]
   mc bundle
   mc preview [--port <n>] [--host <addr>]
@@ -1601,6 +1646,7 @@ Other options:
   --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)
@@ -1618,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
@@ -1764,7 +1829,8 @@ async function runScript(script, options) {
 /**
 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
@@ -1777,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,
@@ -1795,6 +1864,10 @@ async function main(argv, run = runScript) {
 			port: { type: "string" },
 			host: { type: "string" },
 			force: { type: "boolean" },
+			yes: {
+				type: "boolean",
+				short: "y"
+			},
 			"dry-run": { type: "boolean" },
 			help: {
 				type: "boolean",
@@ -1854,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 {

package/dist/cli/writeScaffold.d.ts

@@ -55,12 +55,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.
 */
 export declare function writeProject(namespace: string, root: string, options?: WriteOptions): Promise<string[]>;
 //# sourceMappingURL=writeScaffold.d.ts.map

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

@@ -14,7 +14,9 @@ event delegation is untouched by that.
 ## Talking to micro components from vanilla JS
 
 `on()` and `trigger()` are the two ends of the wire. A custom event name is prefixed
-with `_mc` automatically, so the same name works on both sides:
+with `_mc` automatically, so the same name works on both sides. A project-level prefix
+(`shop:CartUpdate`) is optional here, and worth adding when the dispatching code is not
+yours — it keeps an unrelated `CartUpdate` from the page from reaching your handler:
 
 ```js
 import { on, trigger } from '@twobirds/microcomponents';
@@ -83,11 +85,18 @@ form.subscribe('email', (v) => console.log('email is now', v));
 formValues(form, 'email', document.querySelector('input[name=email]'));
 ```
 
+These are the standalone APIs, for code with no `this` to attach to. Inside a `DC` the
+plugin methods are the API: `observePlugin(DC)` gives `this.subscribe()` / `this.bind()` /
+`this.notify()`, and `formValuePlugin(DC)` gives `this.formValues()` — never call the pure
+functions inside a component.
+
 ## No-build pages
 
 `autoload(true)` makes a page load its own components: an undefined tag in the markup
 resolves to a script URL by the tag-to-path rule (`<shop-header>` → `shop/header.js`)
-and is fetched on demand. A dev page needs only an import map and one call.
+and is fetched on demand. A dev page needs one call and one import of the library URL
+the dev server serves — no import map, because the toolchain resolves the
+`@twobirds/microcomponents` specifier for it.
 
 ## Implementation priority
 

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

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

package/dist/docs/cli.d.ts

@@ -101,7 +101,7 @@ mc check
 Reports the version of the installed library, not the version of the project it runs in.
 
 ```sh
-mc --version      # 0.12.1
+mc --version      # 0.13.0
 ```
 
 ## mc --help

package/dist/docs/installation.d.ts

@@ -4,8 +4,11 @@
 
 `mc create` scaffolds a complete dev environment for a namespace, following the
 three-path chain the library's own demos use. Run it straight with `npx` — no install.
-The namespace (1 to 4 lowercase letters) becomes the `src/<ns>/` folder and the first
-segment of every component tag, so `shop` is the home of tags like `<shop-app>`.
+The namespace (lowercase letters and digits, starting with a letter, any length)
+becomes the `src/<ns>/` folder and the first segment of every component tag, so `shop`
+is the home of tags like `<shop-app>`. The project owns its namespace, so length is
+allowed; past 5 characters `mc create` warns and asks for confirmation (`--yes` skips
+the prompt).
 
 ```sh
 npx @twobirds/microcomponents create --namespace shop
@@ -69,6 +72,8 @@ Companion asset flags:
 | `--html` | html | unvariant light-DOM template |
 
 `--js` emits plain JavaScript for rapid prototyping; `--dry-run` prints the plan without
-touching disk; `--force` overwrites existing files.
+touching disk; `--force` overwrites existing files. A plain `.js` component is copied to
+`build/` verbatim by `mc dev` and `mc bundle` — `tsc` compiles only `.ts`, so it gets no
+type checking and no `.d.ts`, and it autoloads and bundles like a compiled component.
 */
 //# sourceMappingURL=installation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"installation.d.ts","sourceRoot":"","sources":["../../src/docs/installation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BE;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4CE"}
+{"version":3,"file":"installation.d.ts","sourceRoot":"","sources":["../../src/docs/installation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8BE;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8CE"}

package/dist/mcp/api.json

@@ -1,5 +1,5 @@
 {
-  "libraryVersion": "0.12.1",
+  "libraryVersion": "0.13.0",
   "exportedCount": 59,
   "entries": {
     "MC": {

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

@@ -45,6 +45,26 @@ Pass an object, not a bare string, so the receiver reads named fields (`ev.detai
 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.
 
+## Naming events
+
+Inside a project, event names are plain: `add`, `toggle`, `addToCart`. Nothing else in
+the project dispatches them, so there is nothing to collide with and a namespace buys
+nothing. The runtime's own `_mc` prefix (`getMcEventName`, `trueEventName`) is applied
+for you — it marks the events the library dispatches (`_mcConnected`, `_mcFormReset`) so
+they cannot collide with native names. It is not a project convention.
+
+Namespace a name when a collision is likely:
+
+- **From outside the project** — a framework, a page script, or a third-party addon DC
+  dispatching into your components. `shop:addToCart` keeps an unrelated `addToCart` from
+  landing on the wrong handler.
+- **Several DCs in one component** — two DCs attached to the same host dispatching the
+  same name for different purposes. The namespace is the tie-breaker.
+
+The decision is collision likelihood, not style. An i18n (DOM translation) addon DC in a
+component is almost certainly the only translator there, so `translate` needs no
+namespace; a generic `update` shared by three addons does.
+
 ## 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/no-importmap.md

@@ -0,0 +1,48 @@
+Never write an import map in a Micro Components project. An import map is a table of
+bare specifiers a page has to hand-list. In this library the system resolves imports
+itself, in both delivery modes, so a page carrying an import map is doing the
+system's job by hand.
+
+## Autoload mode
+
+`autoload()` watches the DOM and fetches a component by its tag name. An undefined tag
+in the markup becomes a script request: `<shop-header>` → `./shop/header.js`
+(`resolveComponentPath`, the same rule `mc new` uses to place the file — see
+[custom-element-registry](custom-element-registry.md) §Tag Name to File Path Mapping).
+The page never imports a component, so an import map has nothing to describe: the tag
+in the markup _is_ the import.
+
+The library specifier is resolved by the toolchain, not by the page:
+
+| Context                     | How `@twobirds/microcomponents` resolves                                                               |
+| --------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Vite dev server (the demos) | `resolve.alias` to the library source, set in `demo/dev-server.ts`                                     |
+| `mc dev`                    | the server rewrites the specifier in the JS it serves to `/microcomponents.min.js`                     |
+| `mc bundle`                 | `rewriteLibrarySpecifier` points the import at the `microcomponents.min.js` shipped next to the bundle |
+
+The dev shell imports the library by URL (`/microcomponents.min.js`), so the page needs
+no table of its own. `rewriteLibrarySpecifier` is the single source of truth for the
+rewrite: the bundler passes the relative target, the dev server passes its served URL.
+
+## Bundled mode
+
+`bundle.js` contains every component the barrel registers, with companion assets
+inlined by `mc bundle`. Every tag is in the custom element registry before the page
+renders, so a tag that appears in the DOM is upgraded immediately: its constructor
+runs, its assets are already readable through `this.assets`, and `oneInit()` fires
+synchronously. Nothing is fetched, so nothing is mapped.
+
+A component missing from the barrel `src/<namespace>/bundle.ts` is the one gap: it
+loads in dev through `autoload()` and is absent from `public/bundle.js`. Fix the
+barrel, not the HTML.
+
+## The rule
+
+- A component import is never written by hand. Autoload mode fetches it per tag;
+  bundled mode already contains it.
+- The library specifier is resolved by the toolchain — Vite alias, dev-server rewrite,
+  bundler rewrite — never by an import map in the page.
+- If a page needs an import map, a resolution step is missing. Fix the server, the
+  alias, or the bundle. Do not add a `<script type="importmap">`.
+
+See [project-layout](project-layout.md) for the two shells that carry these modes.

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

@@ -8,8 +8,9 @@ src/  →  (tsc)  →  build/  →  (bundle)  →  public/
   `.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. `mc dev` serves it, so
-  the page loads components on demand through `autoload()` and nothing is bundled.
+  plus the files `tsc` does not compile — mirrored companion assets, plain `.js`
+  components, and the dev shell. `mc dev` serves it, so the page loads components
+  on demand through `autoload()` and nothing is bundled.
 - `public/` is the production site: one `bundle.js` with every companion asset
   inlined by `mc bundle`, the concatenated `bundle.css`, and the production
   shell. A single script tag loads it; the autoloader is not needed.
@@ -28,9 +29,12 @@ entry, so every component must be imported by the barrel `src/<namespace>/bundle
 
 The two shells are deliberately different:
 
-- `index-dev.html` imports the library through an import map (to the served
-  `microcomponents.min.js`) and calls `autoload(true)`, so a tag in the markup
-  pulls its own `.js` from `build/`.
+- `index-dev.html` imports the library from the served `/microcomponents.min.js` and
+  calls `autoload(true)`, so a tag in the markup pulls its own `.js` from `build/`.
+  The page writes no import map: the dev server rewrites the
+  `@twobirds/microcomponents` specifier in the JS it serves to that URL, so a
+  compiled component resolves the library without the page listing any imports.
+  See [no-importmap](no-importmap.md).
 - `index.html` loads `bundle.js` and `bundle.css`, which only exist in `public/`.
 
 `mc dev` redirects `/` to `index-dev.html`; `mc bundle` copies `index.html` next to

package/dist/mcp/concepts/state-management.md

@@ -1,14 +1,20 @@
-State management uses observable objects with reactive binding. Two usage patterns exist:
+State management uses observable objects with reactive binding. Which API you use is
+decided by where the code lives, and that is a rule, not a preference:
 
-**Standalone functions** (outside MC ecosystem):
+**Inside a `DC`** — always the plugin equivalents:
 
-- observe(obj) — wraps properties in Observable wrappers; you manage subscribe/bind/notify manually
-- formValues(obj, prop, dom) — binds form controls to an observable property on the object
+- `observePlugin(DC)` — adds `.notify()`, `.subscribe()`, `.bind()` instance methods that implicitly create observables on demand
+- `formValuePlugin(DC)` — adds `.formValues()` instance method; also pulls in all `observePlugin` methods
 
-**Plugins** (inside DC custom elements):
+**Outside the MC system** — the pure functions, for code with no `this` to attach to
+(vanilla JS, framework lifecycle code, Node):
 
-- observePlugin(DC) — adds .notify(), .subscribe(), .bind() instance methods that implicitly create observables on demand
-- formValuePlugin(DC) — adds .formValues() instance method; also pulls in all observePlugin methods
+- `observe(obj)` — wraps properties in Observable wrappers; you manage subscribe/bind/notify manually
+- `formValues(obj, prop, dom)` — binds form controls to an observable property on the object
+
+Never call `observe()` or `formValues()` inside a `DC`. The plugin methods create the same
+wrapper, chain, and keep the `keyof this & string` typing contract; a pure call inside a
+component puts the observable outside the class's typed surface.
 
 Key behaviors:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twobirds/microcomponents",
-	"version": "0.12.1",
+	"version": "0.13.0",
 	"description": "Micro Components",
 	"keywords": [
 		"PWA",