@twobirds/microcomponents 0.9.0 → 0.10.0

package/README.md

@@ -75,23 +75,9 @@ There is no hand-written API list in the server. The whole index is extracted fr
 
 `get-source-file` reads package-root relative paths (`dist/core/MC.d.ts`, `dist/mcp/concepts/event-system.md`) and refuses any path outside the package sources.
 
-## Vite Plugin
-
-The package ships a Vite plugin as its own entry, `@twobirds/microcomponents/vite`, for the bundled production build:
-
-```ts
-import { loadAssetsPlugin } from '@twobirds/microcomponents/vite';
-
-export default defineConfig({
-	plugins: [loadAssetsPlugin(sourceRoot)],
-});
-```
-
-`loadAssetsPlugin` reads the companion `.css` / `.html` files of every DC class that declares `static assets = [...]` and embeds them as a `static _assets` property inside the class, so `loadAssets()` never fetches them at runtime. `mc create` wires it into the generated `vite.config.ts`, which bundles a single `bundle.js` into `public/`.
-
 ## CLI
 
-A small command-line tool scaffolds new components so the tag-to-file convention is never hand-written:
+A small command-line tool scaffolds new components and runs the dev/build/preview chain, with no Vite dependency in the generated project:
 
 ```bash
 pnpm run cli -- new my-card --target-html --target-css
@@ -125,7 +111,7 @@ 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 `tsc -w` and serves `build/`, so a saved component reaches the browser through `autoload()` with nothing bundled; companion assets are mirrored into `build/` next to the compiled component, which is where the autoloader looks for them. `pnpm build` emits one minified `bundle.js` into `public/` with every companion asset inlined by `loadAssetsPlugin`, the concatenated `bundle.css`, and the production shell — a single script tag, no autoloader. `opencode.jsonc` registers the MCP server, so opencode picks it up when you open the project.
+`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/`. `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.
 

package/dist/cli/bundle.d.ts

@@ -0,0 +1,106 @@
+/**
+ Filesystem side of `mc bundle`: assembles the production site in `public/` from
+ the `tsc`-emitted `build/` tree, with no Vite.
+
+ The chain is `src/` → `build/` → `public/`. The scaffolded `build` script runs
+ `tsc -p tsconfig.json` (so `build/` holds one `.js` per component at its
+ autoload path), then `mc bundle` mirrors the companion assets into `build/`,
+ walks the barrel entry named by `src/bundle.json` through {@link bundleEntry}
+ (inlining every `static assets`), rewrites the `@twobirds/microcomponents`
+ specifier to the self-contained `microcomponents.min.js` shipped next to the
+ bundle, concatenates the plain `.css` token presets into `bundle.css`, and
+ copies the production shell. The result is a complete static site: a single
+ `bundle.js` loads every component, no autoloader needed.
+
+ @module CLI/Bundle
+ */
+/**
+ * Shape of `src/bundle.json`: the single source of truth for the production bundle.
+ * The bundler reads it, so changing the entry, the output name, or the output folder
+ * is a config edit in `src/` — not an edit of the CLI.
+ */
+export interface BundleConfig {
+    /** Barrel entry to bundle, relative to `src/` (e.g. `mc/bundle.ts`). */
+    entry: string;
+    /** Output file name (default `bundle.js`). */
+    fileName?: string;
+    /** Output folder, relative to the project root (default `public`). */
+    outDir?: string;
+}
+/**
+ * Whether a file is a companion asset to mirror into `build/`.
+ *
+ * @example
+ * ```ts
+ * isCompanion('app.target.html');  // true
+ * isCompanion('index.html');       // false
+ * ```
+ * @param name Basename of the file.
+ */
+export declare function isCompanion(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`.
+ *
+ * @example
+ * ```ts
+ * await mirrorCompanions('<root>/src', '<root>/build');
+ * ```
+ * @param srcDir Source root to walk.
+ * @param buildDir Folder to write into.
+ * @param rel Path of the walked directory relative to `srcDir`.
+ */
+export declare function mirrorCompanions(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.
+ *
+ * @example
+ * ```ts
+ * const css = await collectPlainCss('<root>/src');
+ * ```
+ * @param srcDir Source root to walk.
+ * @param rel Path of the walked directory relative to `srcDir`.
+ * @param found Accumulated absolute paths.
+ */
+export declare function collectPlainCss(srcDir: string, rel?: string, found?: string[]): Promise<string[]>;
+/**
+ * Rewrite the library specifier in a bundled module to the self-contained bundle
+ * shipped next to it, so the browser can resolve `@twobirds/microcomponents`
+ * without a bare-specifier import map.
+ *
+ * @example Turns the package specifier into a relative path.
+ * ```ts
+ * rewriteLibrarySpecifier("import { DC } from '@twobirds/microcomponents';");
+ * ```
+ * @param code Bundled module source.
+ * @param target Relative specifier to point the import at.
+ */
+export declare function rewriteLibrarySpecifier(code: string, target?: string): string;
+/**
+ * Assemble the production site in `public/` from the compiled `build/` tree.
+ *
+ * @example
+ * ```ts
+ * await bundleProject('<root>', { minJs: '<pkg>/dist/microcomponents.min.js' });
+ * ```
+ * @param projectRoot Project root (the folder holding `src/`, `build/`, `public/`).
+ * @param options.minJs Absolute path of the self-contained `microcomponents.min.js` to ship next to the bundle.
+ * @param options.bundleEntry Optional override of the barrel entry (defaults to `src/bundle.json`).
+ * @returns The names of the files written into `public/`.
+ */
+export declare function bundleProject(projectRoot: string, options: {
+    minJs: string;
+    bundleEntry?: string;
+    outDir?: string;
+}): Promise<string[]>;
+/**
+ * CLI entry for `mc bundle`: runs {@link bundleProject} against the current
+ * project, reading the self-contained library from this package's own `dist/`.
+ *
+ * @param projectRoot Project root (defaults to the current directory).
+ * @param minJs Path of `microcomponents.min.js` (defaults to this package's `dist/`).
+ * @returns The process exit code.
+ */
+export declare function runBundle(projectRoot?: string, minJs?: string): Promise<number>;
+//# sourceMappingURL=bundle.d.ts.map

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

@@ -0,0 +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"}

package/dist/cli/bundler.d.ts

@@ -0,0 +1,44 @@
+/**
+ Pure-TypeScript global bundler — no Vite, no Rolldown, no oxc.
+
+ Reads the `tsc`-emitted ESM files in a project's `build/` and flattens the
+ barrel entry's dependency graph into one self-contained ES module. Each source
+ module is wrapped in a function scope keyed by its path (relative to the root),
+ its `import`/`export` statements are rewritten to a tiny `require` registry,
+ and the entry's re-exported names are emitted as the bundle's public exports.
+
+ When `inline` is set, every module body is first run through
+ {@link inlineAssets}, so a DC class declaring `static assets = [...]` gets its
+ companion `.css` / `.html` embedded as `static _assets` and `loadAssets()`
+ never fetches them at runtime.
+
+ The rewrite is comment-aware: `import`/`export` lines inside JSDoc `@example`
+ blocks are left untouched, so the self-referential `@twobirds/microcomponents`
+ specifiers in documentation never break resolution.
+
+ @module CLI/Bundler
+ */
+/**
+ * Assemble one entry's flattened ES module string from its collected graph.
+ *
+ * @example Produces a self-contained bundle for the barrel entry.
+ * ```ts
+ * const code = await bundleEntry('mc/bundle.js', 'build', true);
+ * ```
+ * @param entryId Entry module id, relative to `root` (e.g. `mc/bundle.js`).
+ * @param root Folder holding the compiled `.js` files.
+ * @param inline Inline companion assets into DC classes before wrapping.
+ */
+export declare function bundleEntry(entryId: string, root: string, inline?: boolean): Promise<string>;
+/**
+ * Token-aware minifier: strips comments and collapses indentation/blank lines.
+ * Identifier mangling is intentionally omitted — the registry form is small
+ * enough and mangling a hand-rolled tokenizer risks breaking regex literals.
+ *
+ * @example Collapses a module to comment-free, single-line-per-statement code.
+ * ```ts
+ * minify('  // note\n  export function a() { return 1; }\n');
+ * ```
+ */
+export declare function minify(code: string): string;
+//# sourceMappingURL=bundler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bundler.d.ts","sourceRoot":"","sources":["../../src/cli/bundler.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;GAmBG;AA2NH;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,UAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC/F;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM3C"}

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,CA2BhE"}
+{"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,CA0BhE"}

package/dist/cli/dev.d.ts

@@ -0,0 +1,87 @@
+/**
+ Vite-free dev server for `mc dev`.
+
+ A minimal `node:http` static server rooted at the project's `build/` folder, so
+ a saved component reaches the browser through `autoload()` with no bundling. It
+ mirrors companion assets from `src/` into `build/` (on startup and on every
+ change), runs `tsc -w` for the lifetime of the server, serves companion
+ `.css` / `.html` / `.json` as raw text (so `loadAssets()` receives markup it
+ can use), redirects `/` to the autoload shell (`index-dev.html`), and serves
+ the self-contained library at `/microcomponents.min.js` — the target of the
+ import map in the dev shell.
+
+ There is no HMR: a page reload picks up the recompiled component.
+
+ @module CLI/Dev
+ */
+import { type Server } from 'node:http';
+/**
+ * Content type for a served file. Companion `.html` / `.json` stay raw text so
+ * `loadAssets()` gets usable markup; the page shells are HTML.
+ *
+ * @example
+ * ```ts
+ * mimeFor('app.target.html');  // 'text/plain'
+ * mimeFor('index-dev.html');   // 'text/html'
+ * mimeFor('app.js');           // 'text/javascript'
+ * ```
+ * @param name Basename of the file.
+ */
+export declare function mimeFor(name: string): string;
+/**
+ * Resolve a request URL to a file to serve, given the served `build/` root and
+ * the library bundle. `/` and `/index.html` map to the autoload shell;
+ * `/microcomponents.min.js` maps to the library; everything else to `build/`.
+ *
+ * @example
+ * ```ts
+ * resolveTarget('/mc/app.target.html', buildRoot, minJs);
+ * resolveTarget('/', buildRoot, minJs);
+ * ```
+ * @param url Request URL (path only, no query).
+ * @param buildRoot Served folder.
+ * @param minJs Absolute path of the self-contained library.
+ * @returns Absolute file path, or `undefined` when nothing matches.
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * await mirrorInto(sourceRoot, buildRoot);
+ * ```
+ * @param sourceRoot Source root to walk.
+ * @param buildRoot Folder to write into.
+ * @param rel Path of the walked directory relative to `sourceRoot`.
+ */
+export declare function mirrorInto(sourceRoot: string, buildRoot: string, rel?: string): Promise<void>;
+/**
+ * Build the dev server for a project: an `node:http` server rooted at `build/`.
+ *
+ * @example
+ * ```ts
+ * const server = createDevServer('<root>', { minJs: '<pkg>/dist/microcomponents.min.js', port: 5173 });
+ * server.listen(port);
+ * ```
+ * @param projectRoot Project root (the folder holding `src/`, `build/`).
+ * @param options.minJs Absolute path of the self-contained library.
+ * @param options.port Dev-server port.
+ * @returns The HTTP server (not yet listening).
+ */
+export declare function createDevServer(projectRoot: string, options: {
+    minJs: string;
+    port: number;
+}): Server;
+/**
+ * CLI entry for `mc dev`: mirror companions, start the server, and run `tsc -w`
+ * for the lifetime of the process.
+ *
+ * @param projectRoot Project root (defaults to the current directory).
+ * @param minJs Path of `microcomponents.min.js` (defaults to this package's `dist/`).
+ * @param port Dev-server port.
+ * @returns The process exit code (the server keeps running until killed).
+ */
+export declare function runDev(projectRoot?: string, minJs?: string, port?: number): Promise<number>;
+//# sourceMappingURL=dev.d.ts.map

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

@@ -0,0 +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;;;;;;;;GAQG;AAEH,wBAAsB,MAAM,CAC3B,WAAW,GAAE,MAAsB,EACnC,KAAK,GAAE,MAAuE,EAC9E,IAAI,GAAE,MAAa,GACjB,OAAO,CAAC,MAAM,CAAC,CA8BjB"}

package/dist/cli/dispatch.d.ts

@@ -11,7 +11,9 @@ so the command works in any consumer project.
 
 @module CLI/Dispatch
 */
-export type Runner = (script: string) => Promise<number>;
+export type Runner = (script: string, options?: {
+    port?: number;
+}) => Promise<number>;
 /**
 Runs a package.json script through pnpm and resolves with its exit code.
 
@@ -25,7 +27,9 @@ against the current project, so the command works in any consumer project.
 const code = await runScript('check');
 ```
 */
-export declare function runScript(script: string): Promise<number>;
+export declare function runScript(script: string, options?: {
+    port?: number;
+}): Promise<number>;
 /**
 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

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;AA0DF,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAwHzD;;;;;;;;;;;;EAYE;AACF,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ/D;AAED;;;;;;;;;;;;;;;;EAgBE;AACF,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8GnF"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/cli/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;EAYE;AAoEF,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAwHtF;;;;;;;;;;;;EAYE;AACF,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAW5F;AAED;;;;;;;;;;;;;;;;EAgBE;AACF,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsHnF"}