@zubra/compiler 0.0.0-stage → 5.0.3

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Mikey Nichols
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/cli.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// `zubra` from npm (@zubra/compiler): the WebAssembly compiler on the command line, with no Rust.
+//
+//   zubra build --lib <dir> [--out dist] [--name <package>] [--version <x.y.z>] [--watch]
+//   zubra add <component>... [--dir src/components] [--force]     copy registry components in
+//   zubra add --list
+//   zubra compile <file> [--emit js|html|css|dts|manifest] [--framework react|vue|svelte|solid] [--partial]
+//   zubra check <file>... [--server]          --server: what a server without JavaScript leaves out
+//   zubra convert <Component.jsx> [--prefix <word>] [--as jsx|zubra] [--out <file> | --stdout]   React → zubra JSX, or .zb
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, watch, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { compileFile, request } from './index.js';
+import { buildLibrary } from './library.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** The component registry: shipped in the package, or the repository's when run from a checkout. */
+export function registryDir() {
+  for (const dir of [join(here, 'registry'), join(here, '../registry')]) {
+    if (existsSync(join(dir, 'index.json'))) return dir;
+  }
+  throw new Error('zubra add: the component registry is missing from this install');
+}
+
+export function readRegistry(dir = registryDir()) {
+  return JSON.parse(readFileSync(join(dir, 'index.json'), 'utf8'));
+}
+
+/**
+ * Copy registry components (and those they use) into `target`. Returns the files written.
+ * An existing file is an error unless `force`, so your edits are never overwritten.
+ */
+export function add(names, { target = 'src/components', force = false, registry = registryDir() } = {}) {
+  const { components } = readRegistry(registry);
+  const byName = new Map(components.map((component) => [component.name, component]));
+  const wanted = new Set();
+  const visit = (name) => {
+    const component = byName.get(name);
+    if (!component) {
+      const near = [...byName.keys()].filter((candidate) => candidate.startsWith(name.slice(0, 3)) || distance(candidate, name) <= 2);
+      throw new Error(`zubra add: no component "${name}" in the registry${near.length ? `; did you mean ${near.join(', ')}?` : ''} (zubra add --list)`);
+    }
+    if (wanted.has(name)) return;
+    wanted.add(name);
+    for (const dependency of component.dependencies ?? []) visit(dependency);
+  };
+  for (const name of names) visit(name);
+  const files = [...wanted].flatMap((name) => byName.get(name).files);
+  mkdirSync(target, { recursive: true });
+  const clashes = files.filter((file) => existsSync(join(target, file)));
+  if (clashes.length && !force) throw new Error(`zubra add: ${clashes.map((file) => join(target, file)).join(', ')} already exists (--force replaces it)`);
+  for (const file of files) copyFileSync(join(registry, 'components', file), join(target, file));
+  return files.map((file) => join(target, file));
+}
+
+/** The npm packages the added files import (beyond the runtime), from the registry's index. */
+export function packagesFor(files, registry = registryDir()) {
+  const added = new Set(files.map((file) => basename(file)));
+  const { components } = readRegistry(registry);
+  return [...new Set(components.filter((component) => component.files.some((file) => added.has(file))).flatMap((component) => component.packages ?? []))];
+}
+
+/** Edit distance, for "did you mean". */
+function distance(a, b) {
+  let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i];
+    for (let j = 1; j <= b.length; j++) next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    row = next;
+  }
+  return row[b.length];
+}
+
+function options(args) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) rest.push(arg);
+    else if (['--lib', '--force', '--list', '--partial', '--stdout', '--server', '--watch'].includes(arg)) flags[arg.slice(2)] = true;
+    else flags[arg.slice(2)] = args[++i];
+  }
+  return { flags, rest };
+}
+
+function main(argv) {
+  const [command, ...args] = argv;
+  const { flags, rest } = options(args);
+  if (command === 'build') {
+    if (!flags.lib || rest.length !== 1) throw new Error('usage: zubra build --lib <components dir> [--out dist] [--name <package>] [--version <x.y.z>] [--watch]');
+    const out = flags.out ?? 'dist';
+    const build = () => {
+      const { components, warnings } = buildLibrary(rest[0], { out, name: flags.name, version: flags.version });
+      for (const warning of warnings) process.stderr.write(warning);
+      console.log(`zubra: built ${components.length} component${components.length === 1 ? '' : 's'} into ${relative(process.cwd(), resolve(out)) || '.'}: ${components.map(({ tag }) => `<${tag}>`).join(' ')}`);
+    };
+    if (!flags.watch) return build();
+    // --watch: build, then again after each change to the components (a compile error is
+    // reported and the last good build stays).
+    const attempt = () => {
+      try {
+        build();
+      } catch (error) {
+        console.error(error.message);
+      }
+    };
+    attempt();
+    let timer = null;
+    watch(rest[0], { recursive: true }, (_event, file) => {
+      if (file && !/\.zb(\.[jt]sx)?$/.test(file)) return;
+      clearTimeout(timer);
+      timer = setTimeout(attempt, 50);
+    });
+    console.log(`zubra: watching ${rest[0]} (Ctrl+C to stop)`);
+  } else if (command === 'add') {
+    if (flags.list) {
+      for (const component of readRegistry().components) console.log(`${component.name.padEnd(20)} ${component.description}`);
+      return;
+    }
+    if (!rest.length) throw new Error('usage: zubra add <component>... [--dir src/components] [--force]   (zubra add --list)');
+    const files = add(rest, { target: flags.dir ?? 'src/components', force: flags.force });
+    console.log(`zubra: added ${files.join(', ')}. They're yours now: edit them as you like.`);
+    const packages = packagesFor(files);
+    if (packages.length) console.log(`zubra: they import ${packages.join(', ')}: npm install ${packages.join(' ')}`);
+  } else if (command === 'convert') {
+    if (rest.length !== 1) throw new Error('usage: zubra convert <Component.jsx> [--prefix <word>] [--as jsx|zubra] [--out <file> | --stdout]');
+    const path = resolve(rest[0]);
+    const response = request({ command: 'convert', path, files: { [path]: readFileSync(path, 'utf8') }, prefix: flags.prefix, as: flags.as });
+    if (!response.ok) throw new Error(response.error);
+    for (const change of response.changes) process.stderr.write(`${rest[0]}: ${change}\n`);
+    if (flags.stdout) process.stdout.write(response.output);
+    else {
+      const target = flags.out ?? relative(process.cwd(), response.file);
+      writeFileSync(target, response.output);
+      process.stderr.write(`${rest[0]}: wrote ${target} (<${response.tag}>)\n`);
+    }
+    for (const warning of response.warnings) process.stderr.write(warning);
+    if (!response.complete) {
+      process.stderr.write(`${response.diagnostics.length} thing${response.diagnostics.length === 1 ? '' : 's'} to finish by hand (above)\n`);
+      process.exitCode = 1;
+    }
+  } else if (command === 'compile' || command === 'check') {
+    if (!rest.length) throw new Error(`usage: zubra ${command} <file>${command === 'check' ? '...' : ''}`);
+    let failed = false;
+    for (const file of command === 'check' ? rest : rest.slice(0, 1)) {
+      const response = compileFile(file, {
+        command, emit: flags.emit ?? 'html', framework: flags.framework, runtime: flags.runtime, partial: flags.partial, server: flags.server,
+        props: flags.props ? JSON.parse(readFileSync(flags.props, 'utf8')) : undefined,
+      });
+      for (const warning of response.warnings) process.stderr.write(warning);
+      if (!response.ok) {
+        process.stderr.write(response.error);
+        failed = true;
+      } else if (command === 'compile') {
+        if (flags.output) writeFileSync(flags.output, response.output);
+        else process.stdout.write(response.output);
+      }
+    }
+    if (command === 'check' && !failed) console.log(`checked ${rest.length} file${rest.length === 1 ? '' : 's'}: no errors`);
+    if (failed) process.exitCode = 1;
+  } else {
+    console.log(readFileSync(fileURLToPath(import.meta.url), 'utf8').split('\n').slice(2, 9).map((line) => line.replace(/^\/\/ ?/, '')).join('\n'));
+    if (command && command !== 'help' && command !== '--help') process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/index.d.ts

@@ -0,0 +1,81 @@
+export interface Diagnostic {
+  file: string;
+  line: number;
+  column: number;
+  severity: 'error' | 'warning';
+  message: string;
+  help: string | null;
+}
+
+export interface Response {
+  ok: boolean;
+  /** The compiled text (null for `command: 'check'` or on error). */
+  output: string | null;
+  /** The error, rendered for a terminal. */
+  error: string | null;
+  /** Warnings, rendered for a terminal. */
+  warnings: string[];
+  /** Every error and warning, for editors. */
+  diagnostics: Diagnostic[];
+}
+
+export interface Options {
+  command?: 'compile' | 'check';
+  emit?: 'html' | 'js' | 'css' | 'dts' | 'manifest' | 'html-data' | 'interface';
+  runtime?: string;
+  keepImports?: boolean;
+  noImports?: boolean;
+  cssImport?: string;
+  cssImportInline?: string;
+  framework?: 'react' | 'vue' | 'svelte' | 'solid' | 'none';
+  modulePath?: string;
+  props?: Record<string, unknown>;
+  slots?: Record<string, string>;
+  /** What `slots` is written in: zubra template syntax (the default here) or rendered HTML. */
+  slotSource?: 'template' | 'html';
+  /** For `emit: 'html'`: leave what only the browser can compute for the element. */
+  partial?: boolean;
+}
+
+export interface Request extends Options {
+  path: string;
+  /** Every source the compilation needs, by absolute path. */
+  files: Record<string, string>;
+}
+
+/** The text of a 4.x server's hydration-marker comments, for tools that remove comments: keep these. (5.0 writes processing instructions, which they keep.) */
+export declare const ZUBRA_MARKER_COMMENT: RegExp;
+export declare function available(): boolean;
+export declare function request(request: Request): Response;
+export declare function sources(path: string, files?: Record<string, string>): Record<string, string>;
+export declare function compileFile(path: string, options?: Options): Response;
+
+export interface RenderOptions {
+  /** The host's prop values. */
+  props?: Record<string, unknown>;
+  /** Supplied content by slot name (`default` for unnamed content). */
+  slots?: Record<string, string>;
+  /** What `slots` is written in: rendered HTML, kept as written (the default), or zubra template syntax. */
+  slotSource?: 'html' | 'template';
+  /** Leave what only the browser can compute for the element (the default), instead of an error. */
+  partial?: boolean;
+  /** The sources, by absolute path, instead of reading them from disk. */
+  files?: Record<string, string>;
+}
+
+export interface Rendered {
+  /** The server-rendered markup, which the element hydrates. */
+  html: string;
+  /** The scoped stylesheets of the component and the components it uses. */
+  css: string;
+  warnings: string[];
+}
+
+export declare class CompileError extends Error {
+  diagnostics: Diagnostic[];
+}
+
+/** Server-render a component. Throws a `CompileError` on errors. */
+export declare function render(path: string, options?: RenderOptions): Rendered;
+/** A component's server-rendered HTML. Throws a `CompileError` on errors. */
+export declare function renderToString(path: string, options?: RenderOptions): string;

package/index.js

@@ -0,0 +1,123 @@
+// @zubra/compiler: the zubra compiler as WebAssembly, for Node (and bundler plugins) without a
+// Rust toolchain. Same compiler, same output, same errors as the `zubra` CLI.
+//
+//   import { compileFile, renderToString } from '@zubra/compiler';
+//   const { ok, output, error, warnings } = compileFile('src/inbox.zb', { emit: 'js' });
+//   const html = renderToString('src/inbox.zb', { props: { heading: 'Mail' } });
+//
+// `request()` is the raw interface: one JSON-shaped request in, one response out (see the
+// compiler's `request` module). `compileFile()` reads the file and every `.zb` file it
+// imports, and makes that request.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+/**
+ * The text of the hydration-marker comments a 4.x server writes (`<!--[-->`, `<!--]-->`, `<!---->`,
+ * `<!--[?-->`, `<!--[!-->`), for tools that remove comments: keep the ones matching this. For example
+ * html-minifier-terser's `ignoreCustomComments: [ZUBRA_MARKER_COMMENT]`. Since 5.0 the markers are
+ * processing instructions (`<?zb [?>`), which minifiers keep without it.
+ */
+export const ZUBRA_MARKER_COMMENT = /^[[\]?!]*$/;
+
+const wasmUrl = new URL('./zubra.wasm', import.meta.url);
+let exports = null;
+
+/** Whether the WebAssembly module is present (it's built by `npm run build`, or ships in the package). */
+export function available() {
+  return existsSync(wasmUrl);
+}
+
+function wasm() {
+  if (!exports) {
+    if (!available()) throw new Error('@zubra/compiler: zubra.wasm is missing; run `npm run build` in its package (needs Rust with the wasm32-unknown-unknown target)');
+    exports = new WebAssembly.Instance(new WebAssembly.Module(readFileSync(wasmUrl)), {}).exports;
+  }
+  return exports;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/**
+ * One request to the compiler; returns `{ ok, output, error, warnings, diagnostics }`. Without
+ * zubra.wasm, a native `zubra` named by $ZUBRA_COMPILER answers it instead (`zubra request`).
+ */
+export function request(body) {
+  if (!available() && process.env.ZUBRA_COMPILER) return native(process.env.ZUBRA_COMPILER, body);
+  const { memory, zubra_alloc, zubra_request, zubra_free } = wasm();
+  const bytes = encoder.encode(JSON.stringify(body));
+  const pointer = zubra_alloc(bytes.length);
+  new Uint8Array(memory.buffer, pointer, bytes.length).set(bytes);
+  const packed = BigInt.asUintN(64, zubra_request(pointer, bytes.length));
+  const at = Number(packed >> 32n);
+  const length = Number(packed & 0xffffffffn);
+  // The memory may have grown during the request; read through the current buffer.
+  const text = decoder.decode(new Uint8Array(memory.buffer, at, length).slice());
+  zubra_free(at, length);
+  return JSON.parse(text);
+}
+
+function native(compiler, body) {
+  const result = spawnSync(compiler, ['request'], { input: JSON.stringify(body), encoding: 'utf8', maxBuffer: 1 << 30 });
+  if (result.error || result.status !== 0) throw new Error(`@zubra/compiler: ${compiler} request failed: ${result.error?.message ?? result.stderr}`);
+  return JSON.parse(result.stdout);
+}
+
+/** The components (`.zb`, `.zb.jsx`, `.zb.tsx`) `path` imports, recursively, with their sources (the path itself included). */
+export function sources(path, files = {}) {
+  const absolute = resolve(path);
+  if (absolute in files) return files;
+  let source;
+  try { source = readFileSync(absolute, 'utf8'); } catch { return files; }
+  files[absolute] = source;
+  // A JSX component's imports are the whole file's; an .zb file's are its <script>'s.
+  const script = /\.[jt]sx$/.test(absolute) ? source : source.match(/<script[^>]*>([\s\S]*?)<\/script>/i)?.[1] ?? '';
+  for (const [, specifier] of script.matchAll(/import\s+(?:[^'"]*?from\s+)?['"]([^'"]+\.zb(?:\.[jt]sx)?)['"]/g)) {
+    if (specifier.startsWith('.')) sources(resolve(dirname(absolute), specifier), files);
+  }
+  return files;
+}
+
+/**
+ * Compile the component at `path`. Options mirror the CLI's: `emit` (`html` | `js` | `css` |
+ * `dts` | `manifest`), `command: 'check'`, `runtime`, `keepImports`, `noImports`, `cssImport` +
+ * `cssImportInline`, `framework`, `modulePath`, `props`, `slots`.
+ */
+export function compileFile(path, options = {}) {
+  const absolute = resolve(path);
+  return request({ ...options, path: absolute, files: sources(absolute) });
+}
+
+/** A compile error, with the rendered message and the diagnostics. */
+export class CompileError extends Error {
+  constructor(response) {
+    super(response.error);
+    this.name = 'CompileError';
+    this.diagnostics = response.diagnostics;
+  }
+}
+
+/**
+ * Server-render the component at `path`: its HTML (which the element hydrates in the browser)
+ * and the scoped stylesheets of it and the components it uses. `props` are the host's values
+ * (JSON), `slots` the supplied content by slot name (`default` for unnamed content): HTML,
+ * kept as written (`slotSource: 'template'` reads it as zubra template syntax instead). `files`
+ * supplies the sources instead of reading them from disk (see `sources`). What only the browser
+ * can compute (JavaScript expressions, runtime-only values) is left for the element to fill in
+ * when it starts; `partial: false` makes that an error instead. Throws a `CompileError` on errors.
+ */
+export function render(path, { props = {}, slots = {}, slotSource = 'html', partial = true, files } = {}) {
+  const absolute = resolve(path);
+  const all = files ?? sources(absolute);
+  const html = request({ emit: 'html', path: absolute, files: all, props, slots, slotSource, partial });
+  if (!html.ok) throw new CompileError(html);
+  const css = request({ emit: 'css', path: absolute, files: all });
+  if (!css.ok) throw new CompileError(css);
+  return { html: html.output, css: css.output, warnings: html.warnings };
+}
+
+/** The component's server-rendered HTML (see `render`). */
+export function renderToString(path, options) {
+  return render(path, options).html;
+}

package/library.d.ts

@@ -0,0 +1,20 @@
+export interface LibraryOptions {
+  /** The output directory (replaced). Default: `dist`. */
+  out?: string;
+  /** The package's name and version; default: the current directory's package.json. */
+  name?: string;
+  version?: string;
+  /** The runtime module the elements import. Default: `@zubra/runtime`. */
+  runtime?: string;
+}
+
+export interface LibraryComponent {
+  tag: string;
+  /** The element's class name, as exported from the package's index. */
+  name: string;
+  /** The module path, without extension, relative to the output directory. */
+  module: string;
+}
+
+/** Compile every component under `dir` into a publishable package (see library.js). */
+export declare function buildLibrary(dir: string, options?: LibraryOptions): { components: LibraryComponent[]; warnings: string[] };

package/library.js

@@ -0,0 +1,224 @@
+// Library mode: compile a folder of components into a package anyone can install and use, with
+// no bundler or zubra tooling on their side.
+//
+//   import { buildLibrary } from '@zubra/compiler/library';
+//   buildLibrary('src/components', { out: 'dist', name: '@acme/ui', version: '1.0.0' });
+//
+// (or `npx zubra build --lib src/components`). The output:
+//
+//   <name>.js, <name>.d.ts        each element: an ES module importing @zubra/runtime
+//   index.js, index.d.ts          every element, by its class name
+//   react/…, vue/…                each element as a React or Vue component, typed
+//   custom-elements.json          the Custom Elements Manifest (Storybook, IDEs, docs tools)
+//   skills/using-<name>/SKILL.md  how to use the components, for coding agents, from the manifest
+//   package.json                  exports for all of the above
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { compileFile } from './index.js';
+
+const SOURCE = /\.zb(?:\.[jt]sx)?$/;
+const { version: compilerVersion } = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+
+const walk = (dir) => readdirSync(dir).sort().flatMap((entry) => {
+  const path = join(dir, entry);
+  if (statSync(path).isDirectory()) return entry === 'node_modules' || entry.startsWith('.') ? [] : walk(path);
+  return SOURCE.test(entry) ? [path] : [];
+});
+
+const pascal = (tag) => tag.split('-').map((part) => part[0].toUpperCase() + part.slice(1)).join('');
+const posix = (path) => path.split(sep).join('/');
+
+/**
+ * Compile every component under `dir` into a package in `out`. Returns
+ * `{ components: [{ tag, name, module }], warnings }`; throws on the first compile error.
+ */
+export function buildLibrary(dir, options = {}) {
+  const root = resolve(dir);
+  const target = resolve(options.out ?? 'dist');
+  // Built next to the target and swapped in at the end, so a compile error leaves the last good
+  // build in place (`--watch`).
+  const out = `${target}.building`;
+  const runtime = options.runtime ?? '@zubra/runtime';
+  const sources = walk(root);
+  if (!sources.length) throw new Error(`zubra build --lib: no components (.zb, .zb.jsx, .zb.tsx) in ${dir}`);
+  if (target === root || root.startsWith(target + sep)) throw new Error('zubra build --lib: the output directory must not contain the components');
+  rmSync(out, { recursive: true, force: true });
+  try {
+    return finish(build());
+  } catch (error) {
+    rmSync(out, { recursive: true, force: true });
+    throw error;
+  }
+  function finish(result) {
+    rmSync(target, { recursive: true, force: true });
+    renameSync(out, target);
+    return result;
+  }
+  function build() {
+
+  const write = (path, text) => {
+    mkdirSync(dirname(join(out, path)), { recursive: true });
+    writeFileSync(join(out, path), text);
+  };
+  const compile = (path, options) => {
+    const response = compileFile(path, { runtime, ...options });
+    if (!response.ok) throw new Error(response.error);
+    return response;
+  };
+
+  const components = [];
+  const warnings = [];
+  const modules = [];
+  for (const path of sources) {
+    const module = posix(relative(root, path)).replace(SOURCE, '');
+    const js = compile(path, { emit: 'js' });
+    warnings.push(...js.warnings);
+    const manifest = JSON.parse(compile(path, { emit: 'manifest', modulePath: `${module}.js` }).output);
+    const declaration = manifest.modules[0].declarations.find((item) => item.customElement);
+    const tag = declaration.tagName;
+    const name = declaration.name ?? pascal(tag);
+    modules.push(...manifest.modules);
+    const face = JSON.parse(compile(path, { emit: 'interface' }).output);
+    components.push({ tag, name, module, declaration, interface: face });
+
+    // The element, also exported by its class name (as its typings declare).
+    write(`${module}.js`, `${js.output.replace(/^export default \$define\(/m, 'const $element = $define(')}
+export default $element;
+export { $element as ${name} };
+`);
+    write(`${module}.d.ts`, compile(path, { emit: 'dts', framework: 'none' }).output);
+    const up = '../'.repeat(module.split('/').length);
+    for (const framework of ['react', 'vue']) {
+      // React's entries are client components (they use hooks): React Server Components need
+      // the directive to import them from a server component.
+      const directive = framework === 'react' ? "'use client';\n" : '';
+      write(`${framework}/${module}.js`, `${directive}import Element from ${JSON.stringify(`${up}${module}.js`)};
+import { wrap } from ${JSON.stringify(`${runtime}/${framework}`)};
+
+export * from ${JSON.stringify(`${up}${module}.js`)};
+export default wrap(Element);
+`);
+      write(`${framework}/${module}.d.ts`, compile(path, { emit: 'dts', framework }).output);
+    }
+  }
+  const tags = new Map();
+  for (const component of components) {
+    if (tags.has(component.tag)) throw new Error(`zubra build --lib: <${component.tag}> is defined by both ${tags.get(component.tag)} and ${component.module}`);
+    tags.set(component.tag, component.module);
+  }
+
+  const index = () => components.map(({ name, module }) => `export { default as ${name} } from ${JSON.stringify(`./${module}.js`)};`).join('\n') + '\n';
+  write('index.js', index());
+  write('index.d.ts', index());
+  for (const framework of ['react', 'vue']) {
+    write(`${framework}/index.js`, (framework === 'react' ? "'use client';\n" : '') + index());
+    write(`${framework}/index.d.ts`, index());
+  }
+  write('custom-elements.json', JSON.stringify({ schemaVersion: '2.1.0', readme: '', modules }, null, 2) + '\n');
+
+  // package.json: what's given, then the project's own package.json, then defaults.
+  const project = existsSync('package.json') ? JSON.parse(readFileSync('package.json', 'utf8')) : {};
+  const runtimeRange = `^${compilerVersion.replace(/^(\d+\.\d+)\..*/, '$1.0')}`;
+  // npm packages the components import (a Zag machine, say), as peers: the app installs them
+  // once. The range is the project's own, where it lists the package.
+  const ranges = { ...project.peerDependencies, ...project.devDependencies, ...project.dependencies };
+  const imported = [...new Set(readdirSync(out, { recursive: true }).filter((file) => file.endsWith('.js') && !/^(react|vue)[\\/]/.test(file)).flatMap((file) =>
+    [...readFileSync(join(out, file), 'utf8').matchAll(/(?:^|\n)\s*(?:import|export)\b[^'"]*?\bfrom\s*['"]((?:@[\w.-]+\/)?[\w.-]+)[^'"]*['"]/g)].map((match) => match[1])))]
+    .filter((name) => name !== runtime && !name.startsWith('.')).sort();
+  if (imported.some((name) => name.startsWith('@zag-js/')) && !imported.includes('@zag-js/vanilla')) imported.push('@zag-js/vanilla');
+  const pkg = {
+    name: options.name ?? project.name ?? 'zubra-components',
+    version: options.version ?? project.version ?? '0.1.0',
+    ...(project.description ? { description: project.description } : {}),
+    ...(project.license ? { license: project.license } : {}),
+    type: 'module',
+    main: './index.js',
+    types: './index.d.ts',
+    customElements: './custom-elements.json',
+    // Importing a module defines its element.
+    sideEffects: ['./*.js', './**/*.js'],
+    exports: {
+      '.': { types: './index.d.ts', default: './index.js' },
+      './react': { types: './react/index.d.ts', default: './react/index.js' },
+      './vue': { types: './vue/index.d.ts', default: './vue/index.js' },
+      './custom-elements.json': './custom-elements.json',
+      './package.json': './package.json',
+      ...Object.fromEntries(components.flatMap(({ module }) => [
+        [`./${module}`, { types: `./${module}.d.ts`, default: `./${module}.js` }],
+        [`./react/${module}`, { types: `./react/${module}.d.ts`, default: `./react/${module}.js` }],
+        [`./vue/${module}`, { types: `./vue/${module}.d.ts`, default: `./vue/${module}.js` }],
+      ])),
+    },
+    peerDependencies: { [runtime]: runtimeRange, ...Object.fromEntries(imported.map((name) => [name, ranges[name] ?? '*'])), react: '>=18', vue: '>=3.3' },
+    peerDependenciesMeta: { react: { optional: true }, vue: { optional: true } },
+  };
+  write('package.json', JSON.stringify(pkg, null, 2) + '\n');
+  // A skill for coding agents: how to use this library's components, from the manifest, so an
+  // agent needn't read the modules to learn the props, events and slots.
+  write(`skills/${skillName(pkg.name)}/SKILL.md`, skill(pkg.name, components));
+  return { components: components.map(({ tag, name, module }) => ({ tag, name, module })), warnings };
+  }
+}
+
+const skillName = (name) => `using-${name.replace(/^@/, '').replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').toLowerCase()}`;
+
+/** The library's skill: one section per component, from its manifest declaration and interface. */
+function skill(name, components) {
+  const code = (text) => `\`${text}\``;
+  const sections = components.map(({ tag, name: className, module, declaration, interface: face }) => {
+    const props = face.props ?? [];
+    const events = declaration.events ?? [];
+    const slots = (declaration.slots ?? []).map((slot) => slot.name || 'default');
+    const model = props.filter((prop) => prop.model).map((prop) => prop.name);
+    const lines = [`### ${code(`<${tag}>`)}`, ''];
+    if (declaration.description) lines.push(declaration.description.replace(/\s*\n\s*/g, ' '), '');
+    lines.push(`Import ${code(`${name}/${module}`)} (the element, also exported as ${code(className)}), ${code(`${name}/react/${module}`)} (a React component) or ${code(`${name}/vue/${module}`)} (a Vue component).`, '');
+    if (props.length) {
+      lines.push('| Prop | Type | Default | |', '|---|---|---|---|');
+      for (const prop of props) {
+        const note = [prop.required ? 'required' : '', prop.model ? `two-way: fires ${code(`${prop.name}change`)}` : ''].filter(Boolean).join('; ');
+        lines.push(`| ${code(prop.name)} | ${code(prop.type ?? 'unknown')} | ${prop.required ? '' : code(JSON.stringify(prop.default))} | ${note} |`);
+      }
+      lines.push('');
+    }
+    if (events.length) {
+      lines.push('Events (bubbling `CustomEvent`s, data in `detail`):', '');
+      for (const event of events) lines.push(`- ${code(event.name)} (${code(event.type?.text ?? 'CustomEvent')})${event.description ? `: ${event.description.replace(/\s*\n\s*/g, ' ')}` : ''}`);
+      lines.push('');
+    }
+    if (slots.length) lines.push(`Slots: ${slots.map((slot) => code(slot)).join(', ')}.`, '');
+    if (face.form) lines.push('A form control: give it a `name` and it submits with the form, validates, and resets.', '');
+    if (model.length) lines.push(`Two-way binding: ${model.map((prop) => `${code(prop)} with ${code(`${prop}change`)}`).join(', ')} (Vue ${code('v-model')}, Svelte ${code('bind:')}, React controlled, Angular ${code('zubraModel')}).`, '');
+    return lines.join('\n');
+  });
+  return `---
+name: ${skillName(name)}
+description: Use the ${name} web components (${components.map((c) => `<${c.tag}>`).join(', ')}) from React, Vue, Svelte, Solid, Angular, plain HTML or a server-rendered page. Covers each component's props, events, slots and two-way binding.
+---
+
+${name} is a library of zubra web components. Each is a standard custom element: **properties in, DOM events out, children as slots.** It works in every framework without integration code, and ${code(`${name}/react`)} and ${code(`${name}/vue`)} export ready-made wrappers.
+
+## Steps
+
+1. Import the component the way the app's framework reads imports: React and Vue apps import from ${code(`${name}/react`)} or ${code(`${name}/vue`)} (or the per-component path); everything else imports ${code(`${name}/<component>`)}, which defines the element, and writes the tag.
+2. Pass objects and arrays as properties (every framework binding does; in raw HTML, JSON in the attribute). Listen for the event names below, lowercase, with ${code('event.detail')}.
+3. Done when the component renders, a typo'd prop is a type error (typings ship with the package), and the handler receives ${code('detail')}.
+
+| Framework | Props | Events | Two-way |
+|---|---|---|---|
+| React | ${code('<Tag value={v} items={list} />')} | ${code('onValueChange={(e) => e.detail}')} | ${code('value')} + ${code('onValueChange')} |
+| Vue | ${code(':items="list"')} | ${code('@valuechange="…"')} | ${code('v-model')} / ${code('v-model:prop')} |
+| Svelte | ${code('{value} items={list}')} | ${code('onvaluechange={…}')} | ${code('bind:value')} |
+| Solid | ${code('prop:items={list}')} | ${code('on:valuechange={…}')} | ${code('prop:value')} + ${code('on:valuechange')} |
+| Angular (${code('CUSTOM_ELEMENTS_SCHEMA')}) | ${code('[items]="list"')} | ${code('(valuechange)="…"')} | ${code('zubraModel [(ngModel)]')} from ${code('@zubra/runtime/angular')} |
+| Plain HTML | ${code('el.items = list')} or a JSON attribute | ${code("addEventListener('valuechange', …)")} | the pair by hand |
+
+Server rendering: the elements hydrate server HTML in place; inside Nuxt, SvelteKit, React Router, SolidStart or Next.js, use ${code('@zubra/server')}'s ${code('injectShadowRoots()')} (see https://github.com/journey-to-code-org/zubra/blob/main/docs/server-rendering.md).
+
+## Components
+
+${sections.join('\n\n')}
+
+The full manifest is ${code('custom-elements.json')} in this package.
+`;
+}