@twobirds/microcomponents 0.13.0 → 0.13.2

package/README.md

@@ -138,7 +138,7 @@ Once installed from npm the same command is available as `mc` (and as `microcomp
 
 ```bash
 mc new my-card [--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>]
@@ -165,7 +165,7 @@ npx -p @twobirds/microcomponents mc new my-card --target-html --target-css
 npx -p @twobirds/microcomponents microcomponents-mcp
 ```
 
-The scaffold derives the file path from the tag using the same rule the runtime autoload loader uses (`my-card` → `my/card.ts`), names companion assets after the runtime's asset descriptors (`targetHtml` → `card.target.html`), and wires them into a `static assets` declaration. `--js` emits a plain JavaScript file for the rapid-prototyping path.
+The scaffold derives the file path from the tag using the same rule the runtime autoload loader uses (`my-card` → `my/card.ts`), names companion assets after the runtime's asset descriptors (`targetHtml` → `card.target.html`), and wires them into a `static assets` declaration. Every hyphen becomes a folder, so the tag's segments are the DOM containment chain — `<cart-container-articles>` sits inside `<cart-container>`, so it is `src/cart/container/articles.ts` — and the last segment names what the component does, not what shape it is: `panel`, `box`, `wrapper` are superfluous, because a folder level costs a segment that has to say something. `--js` emits a plain JavaScript file for the rapid-prototyping path.
 
 ## Examples
 
@@ -414,7 +414,7 @@ Feel free to contact me for any questions or inquiries:
 
 email [Frank Thürigen](mailto:fthuerigen@gmail.com?subject=Micro%20Components)
 
-You can [fund this](https://www.gofundme.com/f/nachhaltige-programmierung).
+You can [fund this](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=fthuerigen@gmail.com&item_name=Micro+Components&currency_code=EUR).
 
 ## Disclaimer
 

package/dist/cli/dispatch.d.ts

@@ -18,12 +18,38 @@ export type Runner = (script: string, options?: {
 /** Asks the user to confirm a namespace long enough to be worth a second look. */
 export type Confirmer = (namespace: string) => Promise<boolean>;
 /**
+Whether `mc <command>` runs the project's package.json script or the CLI's own
+implementation.
+
+A script that is a thin wrapper around the same command must not be delegated:
+`mc dev` would spawn `pnpm run dev`, which runs `mc dev`, which spawns
+`pnpm run dev`, forever. The scaffold writes exactly that shape (`"dev": "mc dev"`,
+`"preview": "mc preview"`), so this guard is what keeps `pnpm dev` in a scaffolded
+project from looping.
+
+@example
+```ts
+scriptTarget('mc dev', 'dev');                               // 'self'
+scriptTarget('mc dev --port 5173', 'dev');                   // 'self'
+scriptTarget('npx mc preview', 'preview');                   // 'self'
+scriptTarget('vite preview --outDir build', 'dev');          // 'delegate'
+scriptTarget('tsc -p tsconfig.json && mc bundle', 'bundle'); // 'delegate'
+scriptTarget(undefined, 'clean');                            // 'self'
+```
+@param body - The script body, or `undefined` when the project declares no such script.
+@param command - The `mc` command being run.
+@returns `'delegate'` to run the project script, `'self'` to run the CLI's implementation.
+*/
+export declare function scriptTarget(body: string | undefined, command: string): 'delegate' | 'self';
+/**
 Runs a package.json script through pnpm and resolves with its exit code.
 
 Thin wrappers like `clean` and `check` delegate here so the script — not the
 CLI — remains the single source of truth for what each command does. If the
 current project defines no such script, the CLI runs its own implementation
-against the current project, so the command works in any consumer project.
+against the current project, so the command works in any consumer project. A script
+that is a thin wrapper around the command itself is not delegated, because
+delegating makes the CLI run itself forever — see {@link scriptTarget}.
 
 @example
 ```ts

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;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"}
+{"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;AAgFhE;;;;;;;;;;;;;;;;;;;;;;EAsBE;AACF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAQ3F;AAgED;;;;;;;;;;;;;;EAcE;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

@@ -267,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.13.0" },
+		dependencies: { "@twobirds/microcomponents": "^0.13.2" },
 		devDependencies: {
 			typescript: "^6.0.3",
 			vitest: "^4.1.10",
@@ -400,7 +400,9 @@ Never write an import map. \`autoload()\` fetches a component by its tag (\`ns-n
 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.
+The tag must be kebab-case with at least one hyphen. Every hyphen becomes a folder, so \`ns-parent-name\` becomes \`src/ns/parent/name.ts\` — the same rule the autoloader uses, so the tag is the file path.
+
+The segments are the DOM containment chain: the namespace, then the components the element sits inside, then the component's own name. \`<cart-container-articles>\` sits inside \`<cart-container>\`, so it is \`src/cart/container/articles.ts\`. The last segment names what the component does, not what shape it is: \`<${namespace}-header-search>\` → \`src/${namespace}/header/search.ts\`. Generic structural words (\`panel\`, \`box\`, \`wrapper\`, \`widget\`, \`view\`) are superfluous — \`<${namespace}-header-panel>\` → \`src/${namespace}/header/panel.js\` buys a folder level that says nothing.
 
 \`--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\`.
 
@@ -1719,23 +1721,56 @@ function spawnProcess(command, args, cwd) {
 	});
 }
 /**
-Whether the package.json in the current directory declares `script` in its
-"scripts". Consumers get this check so `mc clean`/`mc check` can fall back to
-the CLI's own implementation when the project defines no such script.
+The body of a package.json script in the current directory, or `undefined` when the
+project declares no such script. Consumers get this check so `mc clean`/`mc check`
+can fall back to the CLI's own implementation when the project defines no such script.
 
 @example
 ```ts
-const ok = await hasScript('clean');
+await scriptBody('clean');  // 'rm -rf dist'
+await scriptBody('nope');   // undefined
 ```
 @param script - Script name to look up.
 */
-async function hasScript(script) {
+async function scriptBody(script) {
 	try {
-		return typeof JSON.parse(await readFile(path.join(process.cwd(), "package.json"), "utf8"))?.scripts?.[script] === "string";
+		const body = JSON.parse(await readFile(path.join(process.cwd(), "package.json"), "utf8"))?.scripts?.[script];
+		return typeof body === "string" ? body : void 0;
 	} catch {
-		return false;
+		return;
 	}
 }
+/** The CLI's own bin names, so a script that wraps this command is recognized. */
+var SELF_BINS = /* @__PURE__ */ new Set(["mc", "microcomponents"]);
+/**
+Whether `mc <command>` runs the project's package.json script or the CLI's own
+implementation.
+
+A script that is a thin wrapper around the same command must not be delegated:
+`mc dev` would spawn `pnpm run dev`, which runs `mc dev`, which spawns
+`pnpm run dev`, forever. The scaffold writes exactly that shape (`"dev": "mc dev"`,
+`"preview": "mc preview"`), so this guard is what keeps `pnpm dev` in a scaffolded
+project from looping.
+
+@example
+```ts
+scriptTarget('mc dev', 'dev');                               // 'self'
+scriptTarget('mc dev --port 5173', 'dev');                   // 'self'
+scriptTarget('npx mc preview', 'preview');                   // 'self'
+scriptTarget('vite preview --outDir build', 'dev');          // 'delegate'
+scriptTarget('tsc -p tsconfig.json && mc bundle', 'bundle'); // 'delegate'
+scriptTarget(undefined, 'clean');                            // 'self'
+```
+@param body - The script body, or `undefined` when the project declares no such script.
+@param command - The `mc` command being run.
+@returns `'delegate'` to run the project script, `'self'` to run the CLI's implementation.
+*/
+function scriptTarget(body, command) {
+	if (!body) return "self";
+	const tokens = body.trim().split(/\s+/);
+	while (tokens[0] === "npx" || tokens[0] === "pnpm" && tokens[1] === "exec") tokens.splice(0, tokens[0] === "npx" ? 1 : 2);
+	return SELF_BINS.has(tokens[0]) && tokens[1] === command ? "self" : "delegate";
+}
 /** Build artifacts to remove, relative to the project root. */
 var CLEAN_DIRS = [
 	"dist",
@@ -1809,7 +1844,9 @@ Runs a package.json script through pnpm and resolves with its exit code.
 Thin wrappers like `clean` and `check` delegate here so the script — not the
 CLI — remains the single source of truth for what each command does. If the
 current project defines no such script, the CLI runs its own implementation
-against the current project, so the command works in any consumer project.
+against the current project, so the command works in any consumer project. A script
+that is a thin wrapper around the command itself is not delegated, because
+delegating makes the CLI run itself forever — see {@link scriptTarget}.
 
 @example
 ```ts
@@ -1817,7 +1854,7 @@ const code = await runScript('check');
 ```
 */
 async function runScript(script, options) {
-	if (await hasScript(script)) return spawnProcess("pnpm", ["run", script]);
+	if (scriptTarget(await scriptBody(script), script) === "delegate") 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, options?.host ?? "127.0.0.1");

package/dist/docs/cli.d.ts

@@ -44,18 +44,25 @@ mc create --namespace shop
 # project "shop" created in shop/ — run: cd shop && pnpm install && pnpm dev
 ```
 
-Flags: `--namespace <ns>` (1 to 4 lowercase letters, required), `--dir <path>` (default:
-the namespace), `--force`, `--dry-run`.
+Flags: `--namespace <ns>` (lowercase letters and digits, starting with a letter, any
+length, required), `--dir <path>` (default: the namespace), `--force`, `--yes` (`-y`,
+skip the confirmation), `--dry-run`. The project owns its namespace, so length is the
+user's call; past 5 characters `mc create` warns and asks the terminal to confirm before
+anything is written, and `--dry-run` warns without prompting.
 
 ## mc dev
 
 Runs `tsc -w` plus a `node:http` server that serves `build/`. The page loads components
 on demand through `autoload()` — nothing is bundled, and a new component is picked up
-without restarting.
+without restarting. 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, and it mirrors the files `tsc` does not compile — companion assets and plain `.js`
+components — into `build/` next to the compiled component.
 
 ```sh
-mc dev            # dev server on port 5173
+mc dev                 # dev server on port 5173, bound to 127.0.0.1
 mc dev --port 3000
+mc dev --host 0.0.0.0  # widen the bind to the LAN
 ```
 
 ## mc bundle
@@ -70,11 +77,13 @@ mc bundle
 
 ## mc preview
 
-Serves the production site in `public/`.
+Serves the production site in `public/`. Like `mc dev`, it binds to `127.0.0.1` by
+default, so the served files are not reachable off the machine; `--host` widens the bind.
 
 ```sh
-mc preview        # preview server on port 5174
+mc preview                 # preview server on port 5174, bound to 127.0.0.1
 mc preview --port 8080
+mc preview --host 0.0.0.0  # widen the bind to the LAN
 ```
 
 ## mc clean
@@ -101,7 +110,7 @@ mc check
 Reports the version of the installed library, not the version of the project it runs in.
 
 ```sh
-mc --version      # 0.13.0
+mc --version      # 0.13.2
 ```
 
 ## mc --help

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/docs/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiHE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/docs/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0HE"}

package/dist/docs/installation.d.ts

@@ -14,10 +14,11 @@ the prompt).
 npx @twobirds/microcomponents create --namespace shop
 # created shop/package.json
 # created shop/opencode.jsonc
+# created shop/src/bundle.json
 # created shop/src/index.html
 # created shop/src/index-dev.html
 # created shop/src/shop/app.ts
-# created shop/src/shop/app.target.html
+# created shop/src/shop/app.html
 # created shop/src/shop/app.target.css
 # created shop/src/shop/bundle.ts
 # ...
@@ -36,7 +37,11 @@ the project.
 `mc new` derives the file path from the tag using the same rule the runtime autoloader
 uses (`shop-app` → `shop/app.ts`), names companion assets after the runtime's asset
 descriptors (`targetHtml` → `app.target.html`), and wires them into a `static assets`
-declaration.
+declaration. Every hyphen becomes a folder, so the segments are the DOM containment
+chain: a child of `<cart-container>` is `<cart-container-articles>` →
+`src/cart/container/articles.ts`. The last segment names what the component does, not
+what shape it is — `panel`, `box`, `wrapper` are superfluous, because a folder level
+costs a segment that has to say something.
 
 ```sh
 mc new shop-app --target-html --target-css

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

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

package/dist/mcp/api.json

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

package/dist/mcp/concepts/custom-element-registry.md

@@ -47,6 +47,14 @@ src/
 
 The DOM hierarchy is therefore immediately visible in the file system.
 
+The name is the shortest one that says what the component does. The leaf segment is the
+component's function, not its shape: `<shop-header-search>` → `src/shop/header/search.js`
+says what the child of the header does. `<shop-header-panel>` → `src/shop/header/panel.js`
+is wrong — `panel` describes a shape, so the file carries no information about the
+component, and the folder level the tag creates is paid for by a word that says nothing.
+Generic structural words (`panel`, `box`, `wrapper`, `widget`, `view`) are superfluous:
+the nesting a tag encodes costs a directory, so the segment must be worth it.
+
 ---
 
 ## General-Purpose Components in Side Folders

package/dist/mcp/concepts/mc-types.md

@@ -111,6 +111,11 @@ External design of the composed unit is driven by namespaced CSS custom properti
 </cart-container>
 ```
 
+A child's tag carries its parent's prefix, so its file lands in the parent's folder
+(`<cart-container-articles>` → `src/cart/container/articles.ts`), and the last segment
+names what the child does — `articles`, `checkout`, `pay`. A generic structural word
+(`panel`, `box`, `wrapper`) makes the folder level it creates say nothing.
+
 ### 1d. Leaf Components
 
 Self-contained visual units that project no child custom elements — a button, a badge,

package/dist/mcp/concepts/microcomponent-architecture.md

@@ -16,7 +16,7 @@ Every `.ts` or `.js` file contains exactly **one class**, regardless of which ty
 visual, logic-only, style-only, or pure logic. This applies to `DC` subclasses, `MC`
 subclasses, and any other class defined in `src/`.
 
-Why:
+For the classes the toolchain registers, three mechanisms make the rule loadable:
 
 - **Autoload resolution** — `autoload()` maps a tag name to a single script path
   (`<shop-header>` → `./shop/header.js`). One class per file keeps that mapping
@@ -27,5 +27,25 @@ Why:
 - **Registry clarity** — `defineCE()` is called once per file, so file, class, and
   registered tag stay in a 1:1 relationship.
 
+The three logic types are where the rule is easiest to lose, because none of those three
+mechanisms can catch a violation:
+
+- **Logic-only `DC`** (`static tag = ''`) — the class is registered, so the 1:1 contract
+  holds, and the asset name is the host's tag name, which for a removed host is the
+  registered tag (`app-router` → `./app/router.css`). The class runs setup logic on a
+  host it is attached to with `DC.add(host, key, instance)`: one instance under one key,
+  so a second class in the file is a second attachable unit with no key of its own. Its
+  companions are `.css` and `.json` — the constructor removes the host after the assets
+  are applied, so a markup companion has nothing to inject into.
+- **Style-only `DC`** (`static tag = ''`, `static assets = ['css']`) — the class is a
+  delivery vehicle for one stylesheet. File, class, registered tag, and the `.css`
+  companion are one thing under four names: `page-cockpit` in `src/page/cockpit.ts`
+  fetches `./page/cockpit.css`. A second class in the file would ship a second
+  stylesheet under a basename the first one owns.
+- **Pure logic `MC`** — no tag, no `defineCE`, no autoload path, so nothing in the
+  toolchain sees the file at all. The rule holds for the reason a reusable unit gets its
+  own file: the import is by path, so one file is one capability and the file name is
+  the capability. A helper that is not a class is a utility function, not an `MC`.
+
 Non-class entities that belong to the class — interfaces, types, constants, plain
 functions — may live alongside it. A class that is reusable on its own gets its own file.

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

@@ -4,9 +4,11 @@ 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`).
+- `src/` holds the authored sources: component `.ts` files, plain `.js` components
+  written with `mc new --js`, the companion `.target.html` / `.target.css` /
+  `.shadow.css` assets, the bundle barrel `src/<namespace>/bundle.ts` with the
+  `src/bundle.json` that names it, 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 files `tsc` does not compile — mirrored companion assets, plain `.js`
   components, and the dev shell. `mc dev` serves it, so the page loads components
@@ -23,7 +25,8 @@ 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`.
+entry, the one `src/bundle.json` names, so every component must be imported by the barrel
+`src/<namespace>/bundle.ts` that file points at.
 
 ## Shells
 

package/package.json

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