create-zubra 0.0.0-stage → 5.0.1

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/index.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// create-zubra: write a working app that uses zubra components.
+//
+//   npm create zubra                         asks for a directory and a framework
+//   npm create zubra my-app -- --framework react
+//
+// The app has one component (src/components/hello-counter.zb), the plugin wired up, typings,
+// and a browser test (`npm test`). Nothing is installed: the last lines say what to run.
+import { cpSync, existsSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+
+export const FRAMEWORKS = {
+  vanilla: 'No framework (plain HTML and JavaScript)',
+  react: 'React',
+  vue: 'Vue',
+  svelte: 'Svelte',
+  solid: 'Solid',
+  preact: 'Preact',
+  lit: 'Lit',
+  angular: 'Angular',
+  astro: 'Astro (server-rendered pages)',
+};
+
+const templates = fileURLToPath(new URL('./templates/', import.meta.url));
+const { version } = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+
+/** Write the app for `framework` into `dir` (which must be empty or missing); returns the files written. */
+export function create(dir, framework, { name = basename(resolve(dir)) } = {}) {
+  if (!(framework in FRAMEWORKS)) throw new Error(`create-zubra: unknown framework "${framework}"; one of ${Object.keys(FRAMEWORKS).join(', ')}`);
+  const target = resolve(dir);
+  if (existsSync(target) && readdirSync(target).length) throw new Error(`create-zubra: ${dir} isn't empty`);
+  cpSync(join(templates, 'shared'), target, { recursive: true });
+  cpSync(join(templates, framework), target, { recursive: true });
+  // npm drops .gitignore files from packages, so the template's is named _gitignore.
+  renameSync(join(target, '_gitignore'), join(target, '.gitignore'));
+  const files = walk(target);
+  const values = { name: packageName(name), title: name.replace(/[<>{}"'`&\\$]/g, '') || 'Zubra app', version, framework: FRAMEWORKS[framework].replace(/ \(.*/, '') };
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8');
+    const filled = text.replace(/\{\{(name|title|version|framework)\}\}/g, (_, key) => values[key]);
+    if (filled !== text) writeFileSync(file, filled);
+  }
+  return files.map((file) => relative(target, file)).sort();
+}
+
+const walk = (dir) => readdirSync(dir).flatMap((entry) => {
+  const path = join(dir, entry);
+  return statSync(path).isDirectory() ? walk(path) : [path];
+});
+
+const packageName = (name) => name.toLowerCase().replace(/[^a-z0-9._~-]+/g, '-').replace(/^[-._]+|[-._]+$/g, '') || 'zb-app';
+
+/** `[dir] [--framework <name>] [--yes]` → `{ dir, framework, yes, help }`. */
+export function parse(argv) {
+  const options = { dir: null, framework: null, yes: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--framework' || arg === '-f' || arg === '--template' || arg === '-t') options.framework = argv[++i];
+    else if (arg.startsWith('--framework=') || arg.startsWith('--template=')) options.framework = arg.slice(arg.indexOf('=') + 1);
+    else if (arg === '--yes' || arg === '-y') options.yes = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (!arg.startsWith('-') && !options.dir) options.dir = arg;
+    else throw new Error(`create-zubra: unexpected argument ${arg}`);
+  }
+  return options;
+}
+
+async function main(argv) {
+  const options = parse(argv);
+  if (options.help) {
+    console.log(`usage: npm create zubra [directory] -- [--framework ${Object.keys(FRAMEWORKS).join('|')}] [--yes]`);
+    return;
+  }
+  const ask = !options.yes && process.stdin.isTTY;
+  const prompt = ask ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+  try {
+    let { dir, framework } = options;
+    if (!dir) dir = ask ? (await prompt.question('Directory (zb-app): ')).trim() || 'zb-app' : 'zb-app';
+    if (!framework) {
+      const names = Object.keys(FRAMEWORKS);
+      if (ask) {
+        console.log(names.map((key, i) => `  ${i + 1}. ${FRAMEWORKS[key]}`).join('\n'));
+        const answer = (await prompt.question('Framework (1): ')).trim();
+        framework = names[Number(answer || 1) - 1] ?? answer;
+      } else {
+        framework = 'vanilla';
+      }
+    }
+    create(dir, framework);
+    const cd = relative(process.cwd(), resolve(dir)) || '.';
+    console.log(`\nA Zubra app (${FRAMEWORKS[framework]}) is in ${cd}. Next:\n\n${cd === '.' ? '' : `  cd ${cd}\n`}  npm install\n  npm run dev     edit src/components/hello-counter.zb: it updates in place\n  npm test        builds the app and clicks through it in Chromium\n`);
+  } finally {
+    prompt?.close();
+  }
+}
+
+// Run as a command (npm's bin is a link to this file), not imported.
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "create-zubra",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "5.0.1",
+  "description": "Start an app with Zubra web components: `npm create zubra`",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/journey-to-code-org/zubra.git",
+    "directory": "create"
+  },
+  "type": "module",
+  "bin": {
+    "create-zubra": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "templates"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/angular/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <app-root></app-root>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/angular/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@angular/common": "^22.2.5",
+    "@angular/compiler": "^22.2.5",
+    "@angular/core": "^22.2.5",
+    "@angular/platform-browser": "^22.2.5",
+    "@zubra/runtime": "^{{version}}",
+    "rxjs": "^7.8.2",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@analogjs/vite-plugin-angular": "^2.9.6",
+    "@angular/build": "^22.2.6",
+    "@angular/compiler-cli": "^22.2.5",
+    "@zubra/compiler": "^{{version}}",
+    "@zubra/unplugin": "^{{version}}",
+    "playwright": "^1.63.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.6"
+  }
+}

package/templates/angular/src/app.ts

@@ -0,0 +1,19 @@
+import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core';
+import './components/hello-counter.zb';
+
+// Angular uses the element directly: [count] sets the property, (countchange) listens. For
+// forms, ZubraModel from @zubra/runtime/angular makes an element work with ngModel and formControl.
+@Component({
+  selector: 'app-root',
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <main>
+      <h1>{{title}}</h1>
+      <hello-counter [count]="count()" (countchange)="count.set($any($event).detail)" label="Clicks"></hello-counter>
+      <p>Angular sees <span id="seen">{{ count() }}</span></p>
+    </main>
+  `,
+})
+export class App {
+  count = signal(0);
+}

package/templates/angular/src/main.ts

@@ -0,0 +1,5 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideZonelessChangeDetection } from '@angular/core';
+import { App } from './app';
+
+bootstrapApplication(App, { providers: [provideZonelessChangeDetection()] });

package/templates/angular/src/style.css

@@ -0,0 +1,3 @@
+body { margin: 0; min-height: 100vh; display: grid; place-content: center; gap: 1rem; font: 1rem/1.5 system-ui, sans-serif; color: #1d2130; background: #f5f6fa; text-align: center; }
+h1 { margin: 0; font-size: 1.5rem; }
+p { margin: 0; color: #5d6375; }

package/templates/angular/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": [
+      "ES2023",
+      "DOM"
+    ],
+    "strict": true,
+    "experimentalDecorators": true,
+    "skipLibCheck": true,
+    "allowJs": true,
+    "useDefineForClassFields": false
+  },
+  "files": [
+    "src/main.ts"
+  ],
+  "angularCompilerOptions": {
+    "strictTemplates": true
+  }
+}

package/templates/angular/vite.config.js

@@ -0,0 +1,7 @@
+import angular from '@analogjs/vite-plugin-angular';
+import zubra from '@zubra/unplugin/vite';
+
+// Analog's plugin compiles Angular ahead of time inside Vite; .zb imports go through zubra.
+export default {
+  plugins: [zubra(), angular({ tsconfig: new URL('./tsconfig.json', import.meta.url).pathname })],
+};

package/templates/astro/astro.config.mjs

@@ -0,0 +1,5 @@
+import { defineConfig } from 'astro/config';
+import zubra from '@zubra/unplugin/astro';
+
+// Components render to HTML on the server; client:load makes one interactive in the browser.
+export default defineConfig({ integrations: [zubra()] });

package/templates/astro/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@zubra/runtime": "^{{version}}",
+    "astro": "^7.4.7"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "^{{version}}",
+    "@zubra/unplugin": "^{{version}}",
+    "playwright": "^1.63.0"
+  }
+}

package/templates/astro/src/pages/index.astro

@@ -0,0 +1,23 @@
+---
+import HelloCounter from '../components/hello-counter.zb';
+import '../style.css';
+---
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+  </head>
+  <body>
+    <main>
+      <h1>{{title}}</h1>
+      <HelloCounter label="Clicks" client:load />
+      <p>The page sees <span id="seen">0</span></p>
+    </main>
+    <script>
+      document.querySelector('hello-counter').addEventListener('countchange', (event) => {
+        document.querySelector('#seen').textContent = event.detail;
+      });
+    </script>
+  </body>
+</html>

package/templates/astro/src/style.css

@@ -0,0 +1,3 @@
+body { margin: 0; min-height: 100vh; display: grid; place-content: center; gap: 1rem; font: 1rem/1.5 system-ui, sans-serif; color: #1d2130; background: #f5f6fa; text-align: center; }
+h1 { margin: 0; font-size: 1.5rem; }
+p { margin: 0; color: #5d6375; }

package/templates/astro/test/build.js

@@ -0,0 +1,9 @@
+// Builds the site for the browser test; returns the output directory.
+import { join } from 'node:path';
+
+export async function buildApp(root) {
+  const { build } = await import('astro');
+  const outDir = join(root, 'dist');
+  await build({ root, logLevel: 'warn', outDir });
+  return outDir;
+}

package/templates/lit/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <my-app></my-app>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/templates/lit/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@zubra/runtime": "^{{version}}",
+    "lit": "^3.3.3"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "^{{version}}",
+    "@zubra/unplugin": "^{{version}}",
+    "playwright": "^1.63.0",
+    "vite": "^8.3.6"
+  }
+}

package/templates/lit/src/main.js

@@ -0,0 +1,24 @@
+import { LitElement, html, css } from 'lit';
+// In a Lit template, .count sets the property and @countchange listens.
+import './components/hello-counter.zb';
+
+class MyApp extends LitElement {
+  static properties = { count: { state: true } };
+  static styles = css`main { display: grid; gap: 1rem; } p { margin: 0; color: #5d6375; } h1 { margin: 0; font-size: 1.5rem; }`;
+
+  constructor() {
+    super();
+    this.count = 0;
+  }
+
+  render() {
+    return html`
+      <main>
+        <h1>{{title}}</h1>
+        <hello-counter .count=${this.count} @countchange=${(event) => (this.count = event.detail)} label="Clicks"></hello-counter>
+        <p>Lit sees <span id="seen">${this.count}</span></p>
+      </main>
+    `;
+  }
+}
+customElements.define('my-app', MyApp);

package/templates/lit/src/style.css

@@ -0,0 +1,3 @@
+body { margin: 0; min-height: 100vh; display: grid; place-content: center; gap: 1rem; font: 1rem/1.5 system-ui, sans-serif; color: #1d2130; background: #f5f6fa; text-align: center; }
+h1 { margin: 0; font-size: 1.5rem; }
+p { margin: 0; color: #5d6375; }

package/templates/lit/vite.config.js

@@ -0,0 +1,3 @@
+import zubra from '@zubra/unplugin/vite';
+
+export default { plugins: [zubra()] };

package/templates/preact/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/templates/preact/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@zubra/runtime": "^{{version}}",
+    "preact": "^10.29.8"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "^{{version}}",
+    "@zubra/unplugin": "^{{version}}",
+    "@preact/preset-vite": "^2.10.6",
+    "playwright": "^1.63.0",
+    "vite": "^8.3.6"
+  }
+}

package/templates/preact/src/App.jsx

@@ -0,0 +1,14 @@
+import { useState } from 'preact/hooks';
+// Preact uses the element directly: props are set as properties, on<name> listens.
+import './components/hello-counter.zb';
+
+export default function App() {
+  const [count, setCount] = useState(0);
+  return (
+    <main>
+      <h1>{{title}}</h1>
+      <hello-counter count={count} oncountchange={(event) => setCount(event.detail)} label="Clicks" />
+      <p>Preact sees <span id="seen">{count}</span></p>
+    </main>
+  );
+}

package/templates/preact/src/main.jsx

@@ -0,0 +1,4 @@
+import { render } from 'preact';
+import App from './App.jsx';
+
+render(<App />, document.getElementById('app'));

package/templates/preact/src/style.css

@@ -0,0 +1,3 @@
+body { margin: 0; min-height: 100vh; display: grid; place-content: center; gap: 1rem; font: 1rem/1.5 system-ui, sans-serif; color: #1d2130; background: #f5f6fa; text-align: center; }
+h1 { margin: 0; font-size: 1.5rem; }
+p { margin: 0; color: #5d6375; }

package/templates/preact/vite.config.js

@@ -0,0 +1,4 @@
+import preact from '@preact/preset-vite';
+import zubra from '@zubra/unplugin/vite';
+
+export default { plugins: [zubra(), preact()] };

package/templates/react/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/templates/react/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@zubra/runtime": "^{{version}}",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "^{{version}}",
+    "@zubra/unplugin": "^{{version}}",
+    "@vitejs/plugin-react": "^6.2.1",
+    "playwright": "^1.63.0",
+    "vite": "^8.3.6"
+  }
+}

package/templates/react/src/App.jsx

@@ -0,0 +1,14 @@
+import { useState } from 'react';
+// Imported into React, a component is a React component (typed, with onCountChange).
+import HelloCounter from './components/hello-counter.zb';
+
+export default function App() {
+  const [count, setCount] = useState(0);
+  return (
+    <main>
+      <h1>{{title}}</h1>
+      <HelloCounter count={count} onCountChange={(event) => setCount(event.detail)} label="Clicks" />
+      <p>React sees <span id="seen">{count}</span></p>
+    </main>
+  );
+}

package/templates/react/src/main.jsx

@@ -0,0 +1,4 @@
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+
+createRoot(document.getElementById('app')).render(<App />);

package/templates/react/src/style.css

@@ -0,0 +1,3 @@
+body { margin: 0; min-height: 100vh; display: grid; place-content: center; gap: 1rem; font: 1rem/1.5 system-ui, sans-serif; color: #1d2130; background: #f5f6fa; text-align: center; }
+h1 { margin: 0; font-size: 1.5rem; }
+p { margin: 0; color: #5d6375; }

package/templates/react/vite.config.js

@@ -0,0 +1,4 @@
+import react from '@vitejs/plugin-react';
+import zubra from '@zubra/unplugin/vite';
+
+export default { plugins: [zubra(), react()] };

package/templates/shared/AGENTS.md

@@ -0,0 +1,10 @@
+# {{title}}
+
+An app with Zubra components (`src/components/*.zb`): HTML-first web components that work in any framework and render on the server.
+
+| Task | Read |
+|---|---|
+| Write or change a component | `skills/zubra-component/SKILL.md` |
+| Use a component from the app's framework, or plain HTML | `skills/zubra-consume/SKILL.md` |
+
+`npx zubra check src/components/<name>.zb` checks a component; `npm run dev` runs the app with hot reload; `npm test` runs the browser test. The full reference is https://github.com/journey-to-code-org/zubra#readme.

package/templates/shared/README.md

@@ -0,0 +1,17 @@
+# {{title}}
+
+A {{framework}} app using [Zubra](https://github.com/journey-to-code-org/zubra) web components.
+
+```sh
+npm install
+npm run dev     # then edit src/components/hello-counter.zb: it updates in place
+npm run build
+npm test        # builds the app and clicks through it in Chromium (run `npx playwright install chromium` once)
+```
+
+- `src/components/` holds the components: one `.zb` file each, with its script, styles and template.
+- The Zubra plugin (`@zubra/unplugin`) compiles them when they're imported, and writes their typings next to them.
+- The elements are standard custom elements, so they also work in plain HTML, other frameworks and server-rendered pages.
+- `AGENTS.md` and `skills/` tell a coding agent how to write and use the components, so it doesn't have to learn Zubra from the source.
+
+The [tutorial](https://github.com/journey-to-code-org/zubra/blob/main/docs/guide/README.md) goes from here to forms, async data and server rendering.

package/templates/shared/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.astro
+# Typings the zubra plugin writes next to each component (it rewrites them on every build).
+*.d.zb.ts

package/templates/shared/skills/zubra-component/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: zubra-component
+description: Write or change a Zubra component (a `.zb` file, or a `.zb.jsx` function). Use when asked for a web component, a custom element, a form control, or a component that must work in more than one framework or render on the server. Covers the format, state, events, slots, forms, styles, and the boundary between what belongs in the component and what belongs in the app.
+---
+
+A Zubra component is one `.zb` file: a `<script>`, a `<style>`, and a template whose root is the host tag. The compiler turns it into a custom element, its server HTML, its typings and a React or Vue wrapper. You write the HTML; the compiler writes the class.
+
+## Steps
+
+1. **Decide whether it's a leaf.** A component takes data in through props and sends it out through events; it may hold children through slots. If it would need the app's store, router, context or component types, it's a container: write that in the app's framework and put Zubra components inside it. (https://github.com/journey-to-code-org/zubra/blob/main/docs/what-crosses-the-boundary.md has the full list.)
+2. **Name the element with a hyphen** (`star-rating`, not `rating`), and put the file at `src/components/<tag>.zb` unless the project has another convention.
+3. **Write the host tag with every prop**, each with its default, then the script, then the template. Follow the format below.
+4. **Run `zubra check <file>`** (`npx zubra check` without a Rust toolchain). It prints each error with a caret and a suggested fix; `--format json` gives the same as data. Done when it prints `no errors`.
+5. **If the component is server-rendered, run `zubra check --server <file>`** and move anything it names (a `Date`, an `Intl` call, a `window` read) into `onMount` or behind `hydrated()`, so the server HTML is complete.
+6. **Write the test** the project's other components have (a browser test from `npm create zubra`, or `node --test` with the project's harness), covering each prop, each event and keyboard use.
+
+## The format
+
+```html
+<!--
+  A star rating.                               ← the description, for docs and typings
+  @fires valuechange - The value changed; `detail` is the new value.
+-->
+<script>
+  import { onMount } from '@zubra/runtime'
+  let hovered = null                           // state: assigning it updates the DOM
+  const shown = hovered ?? value               // derived: reads state or props, stays in sync
+  const stars = [1, 2, 3, 4, 5].slice(0, max)  // in the server's subset, so the HTML has the stars
+  function rate(stars) { value = stars }       // a prop is a name in the script, readable and writable
+  onMount(() => console.log('in the DOM'))
+</script>
+<style>
+  button { font: inherit; }                    /* scoped to this component, in light DOM too */
+  button.lit { color: gold; }
+</style>
+<star-rating value:model={0} max={5} label="Rate">
+  <zb-each items={stars} as="star" key={star}>
+    <button type="button" aria-label="{star} of {max}" class:lit={star <= shown}
+            onclick={() => rate(star)} onmouseenter={() => (hovered = star)} onmouseleave={() => (hovered = null)}>★</button>
+  </zb-each>
+  <output>{label}: {value}</output>
+</star-rating>
+```
+
+- **Host tag**: `<tag attr={default} …>`. `value={0}` is a number prop, `label="Rate"` a string, `items={[]}` an array, bare `name` a required prop. Kebab-case attributes are camelCase props (`max-value` → `maxValue`). Flags: `shadow` (shadow DOM; light DOM is the default), `form-associated` (a form control), `host-reset` (for other people's pages).
+- **`name:model={default}`** makes a prop two-way: assigning it in the script fires `<name>change` with the new value in `detail`. Frameworks bind it (`v-model`, `bind:value`, React's controlled pattern). Use it for every control's value; never fire the change event by hand.
+- **`{expr}`** in text, inside quoted attributes (`class="card {kind}"`) or as a whole attribute (`items={list}`, any type). Any JavaScript expression; signals and props read as values.
+- **Events on elements**: `onclick={fn}` or `onclick={() => …}`. Modifiers: `onsubmit.prevent`, `.stop`, `.once`, `.self`, `.capture`, `.passive`, `.submit` (submits the form after the handler); key filters `onkeydown.enter`, `.escape`, `.space`, `.up`, `.shift.enter`, `.mod.enter` (⌘ or Ctrl).
+- **`class:name={bool}`**, `class={{ a, b: cond }}`, **`style:prop={value}`**, `style:--var={value}`, `style={{ … }}`. Never build a class or style string by hand.
+- **`{...object}`** spreads attributes, `on<Name>` listeners and properties onto an HTML element (`<input {...api.getInputProps()}>`): use it for a headless library's prop getters. Explicit attributes win; it isn't allowed on the host, directives or Zubra components.
+- **`ref={el}`** assigns an element to a `let` once rendered. **`<zb-window>`/`<zb-document>`** take listeners (`<zb-document onkeydown.escape={close}>`), removed on unmount.
+
+## Directives
+
+| | |
+|---|---|
+| `<p zb-if={…}>`, then `<p zb-else-if={…}>` / `<p zb-else>` on the next siblings | a condition on one element (prefer this for one element) |
+| `<zb-if test={…}>…<zb-else-if test={…}>…</zb-else-if><zb-else>…</zb-else></zb-if>` | a condition over several siblings or text |
+| `<zb-each items={list} as="item" index="i" key={item.id}>` | lists; always give a `key` when rows can reorder or be removed from the middle |
+| `<zb-switch value={x}><zb-case is="a">…</zb-case><zb-case is={["b", "c"]}>…</zb-case><zb-else>…</zb-else></zb-switch>` | one value, several cases (status values, enums) |
+| `let:total={item.price * item.qty}` on `zb-each` / `zb-then` | a derived name for the row or result, instead of repeating the expression |
+| `<zb-slot>` and `<zb-slot name="x">fallback</zb-slot>` | children; `hasSlot('x')` says whether content was given |
+| `<zb-await value={promiseOrResource}><zb-pending>…</zb-pending><zb-then as="data">…</zb-then><zb-catch as="error">… {retry}</zb-catch></zb-await>` | async; `value={[a, b]}` waits for both; `as` may destructure (`as="{ name }"`); `retry()` in zb-catch; `delay={ms}`, `keep` |
+| `<my-child value:bind={state}>` | two-way binding to a child's `:model` prop |
+
+Markup in braces (`{a && <p>…</p>}`, `{a ? <b>…</b> : <i>…</i>}`, `{list.map((x) => <li key={x.id}>…</li>)}`) compiles to the same directives and is accepted, but write the directives: they're the house style. Any other `zb-` attribute is an error.
+
+## Script rules
+
+- **A top-level `let` is state.** Assign it (`count++`, `items = []`) or mutate it (`items.push(x)`, `item.done = !item.done`, `form.email = ""`): both update what read it. Arrays and plain objects in state are reactive proxies; `raw(items)` gives the original for `structuredClone` or `postMessage`.
+- **A top-level `const` that reads props or state is derived**, kept in sync. Other `const`s, functions and imports run once per element.
+- **Props are names.** Read `value`, assign `value = 3`. The script can't declare a name a prop has; a default from the script uses another name (`<x-card title={titleDefault}>`).
+- **`let x = from(prop)`** is state that starts from a prop and resets when the prop changes; `let x = prop` reads it once.
+- **Events**: `emit('name', detail)` from `@zubra/runtime`, name a string literal, all lowercase like the DOM's own (`itemselect`, not `itemSelect` or `item-select`); reuse native names where the meaning matches (`change`, `toggle`, `close`). `before<name>` events are cancelable: `if (!emit('beforeclose')) return`. Document each with `@fires name - text` in the description comment.
+- **Hooks**, plain functions called during the script: `onMount(fn)` (may return a cleanup), `onUnmount(fn)`, `effect(fn)`, `watch(source, (next, prev) => …)`, `computed(fn)`, `state(v)`, `resource(fetcher)`, `id()` (for `id`/`for`/`aria-*`), `host()`, `hasSlot(name)`, `hydrated()`, `createContext`/`provide`/`inject`. Nothing re-renders, so there are no hook rules beyond "call them while the script runs".
+- **Forms**: `form-associated` on the host makes the element a control; a single `:model` prop is its submitted value under its `name`. `validity(() => message)` takes part in validation (`''` is valid). `onFormReset`, `onFormRestore`, `onFormDisabled`.
+- **`<script lang="ts">`** for TypeScript (erasable syntax only). `declare const value: number | null` types a prop whose default doesn't say enough.
+
+## Accessible widgets
+
+There is no Radix here; use, in order: the platform (`<dialog>` with `showModal()`, `popover` + `popovertarget`, CSS anchor positioning, `<details name>`, `<select>`, `<input type=range>`); `rovingFocus(container, { selector, orientation, onMove })` and `typeahead(container, { selector })` from `@zubra/runtime/primitives`, called in `onMount` (each returns its cleanup) for menus, tab lists, toolbars and listboxes; and for combobox, date picker, colour picker or tree view, a Zag.js machine through `@zubra/runtime/zag`: `const machine = useMachine(combobox.machine, () => ({ id: uid, … }))` with `uid = id()` hoisted, `const api = computed(() => combobox.connect(machine.current, normalizeProps))`, then `{...api.getXProps()}` on the elements. Copy the registry's `tab-list`, `dropdown-menu`, `tool-tip`, `accordion-panel` and `combo-box` rather than writing one from scratch.
+
+## JSX form
+
+A `.zb.jsx` / `.zb.tsx` file default-exports a function; same element, same rules: `function StarRating({ value = model(0), max = 5, onValueChange })`, top-level `let` is state, `cond && <X/>` and `list.map(…)` with `key` are the directives, `children` is the default slot, `onValueChange(x)` fires `valuechange`. Prefer `.zb` unless the project is already JSX.
+
+## What the server can't render
+
+The server evaluates the deterministic subset (props, arithmetic, ternaries, template literals, string and array methods, `Math` except `random`, `Object.keys/values/entries`). `Date`, `Intl`, `Math.random`, `toLocaleString`, `window`, `document` and `navigator` are browser-only: put them in `onMount`, in a handler, or in a `let` set from an effect, and show a server-safe fallback. `hydrated()` is `false` on the server and `true` once the element has started, for markup that only works with JavaScript.
+
+## Reference
+
+The Zubra README is the full reference; read a section only when a rule above isn't enough: https://github.com/journey-to-code-org/zubra#writing-a-component, `#directives`, `#classes-styles-events-and-references`, `#script-state-and-hooks`, `#events`, `#slots`, `#forms`, `#styles`, `#async-data`, `#server-rendering-and-hydration`. The registry holds twenty-five tested, accessible components to copy the shape from (`npx zubra add --list`; `registry/components/` in the Zubra repository).

package/templates/shared/skills/zubra-consume/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: zubra-consume
+description: Use a Zubra component (or a library built with `zubra build --lib`) from an app: React, Vue, Svelte, Solid, Angular, Lit, Preact, Astro or plain HTML, with the bundler plugin or without one. Use when wiring a `.zb` import, passing an object prop, listening for a component's event, binding a value two-way, or putting children in a slot.
+---
+
+Every framework uses the element the same way underneath: **properties in, DOM events out, children as slots.** Nothing is written by hand to bridge them; the plugin or the library's wrappers do it.
+
+## Steps
+
+1. **Check how the project builds.** Vite, Rollup, webpack, esbuild or Rspack: `@zubra/unplugin` (`zubra()` in the bundler config; `npm create zubra` wrote it). Next.js: `@zubra/unplugin/loader` in `turbopack.rules`. The Angular CLI: compile with `zubra compile --emit js` and import the `.js`. No bundler: import the compiled module as a `<script type="module">`.
+2. **Import the component** and write the tag. What the import gives depends on the importing file (table below). Typings are written next to the `.zb` file, so props and events are checked.
+3. **Pass objects and arrays as properties, never as attribute strings.** Through the plugin, the wrappers and every framework listed below, a bound value *is* a property. In raw HTML, an attribute is the fallback: JSON for arrays and objects (`data='{"a":1}'`).
+4. **Listen for the DOM event name**: all lowercase (`valuechange`), with the data in `event.detail`. Each framework's spelling is in the table.
+5. **Bind two-way** through the `<prop>` + `<prop>change` pair the component declares with `:model`.
+6. Done when the framework's dev server shows the component, a typo'd prop is a type error, and the event handler receives `detail`.
+
+## Per framework
+
+| Framework | Import gives | Props | Events | Two-way | Children |
+|---|---|---|---|---|---|
+| React 18/19 (`.jsx`/`.tsx`) | A React component (`import Rating from './rating.zb'`) | `<Rating value={3} items={list} />` | `onValueChange={(e) => e.detail}` | `value={v} onValueChange={…}` | JSX children; `slot="name"` on an element for named slots |
+| Vue 3 (`.vue`) | A Vue component | `:items="list"` | `@valuechange="…"` | `v-model:value` (or `v-model` for `value`) | default and `<template #name>` slots |
+| Svelte 5 | The element (typings written) | `<star-rating {value} items={list}>` | `onvaluechange={…}` | `bind:value` | children; `slot="name"` |
+| Solid | The element (typings written) | `prop:items={list}` for objects; plain attributes for primitives | `on:valuechange={…}` | `prop:value` + `on:valuechange` | children; `slot="name"` |
+| Angular | The element; `CUSTOM_ELEMENTS_SCHEMA` on the component | `[items]="list"` | `(valuechange)="…"` | `zubraModel [(ngModel)]="x"` from `@zubra/runtime/angular` | content projection; `slot="name"` |
+| Lit, Preact | The element | `.items=${list}` (Lit), `items={list}` (Preact) | `@valuechange=${…}`, `onvaluechange={…}` | the pair by hand | children |
+| Astro (`@zubra/unplugin/astro`) | A server-rendered component (`<Rating value={3} client:load />`) | props as values in the frontmatter's JSX | a `<script>` on the page: `addEventListener('valuechange', …)` | the pair in a script | children; `slot="name"` |
+| Plain HTML | The element, once its module is loaded | `el.items = list` in a script, or JSON attributes | `el.addEventListener('valuechange', …)` | the pair by hand | children; `slot="name"` |
+
+A library from `zubra build --lib` has the same per element: `@acme/ui/star-rating` (the element), `@acme/ui/react` and `@acme/ui/vue` (wrappers), typings, and `custom-elements.json` for editors and Storybook.
+
+## What crosses, and what doesn't
+
+Props, events, two-way binding, slots, form participation, refs to the host and server rendering cross the element boundary. Render props, the framework's context, Suspense and transitions, and the framework's own components as children-by-name do not: for those, put the Zubra component inside a framework component rather than the other way round. https://github.com/journey-to-code-org/zubra/blob/main/docs/what-crosses-the-boundary.md has the list with the alternatives. React-only widget libraries (Radix, shadcn/ui, React Aria) don't cross either. Inside a Zubra component, use the platform, `@zubra/runtime/primitives` or Zag.js, as in the registry's `tab-list`, `dropdown-menu`, `tool-tip` and `combo-box`. https://github.com/journey-to-code-org/zubra/blob/main/docs/guide/accessible-widgets.md maps Radix to these.
+
+## Server rendering in a framework
+
+Nuxt, SvelteKit, React Router and SolidStart: components must be `shadow` and the page goes through `@zubra/server`'s `injectShadowRoots()` (one hook per framework, in `examples/meta/`). Next.js: the loader's server rule renders shadow-DOM elements without React children. Astro and plain servers render light-DOM components as they are. Details: https://github.com/journey-to-code-org/zubra/blob/main/docs/server-rendering.md.
+
+## Reference
+
+https://github.com/journey-to-code-org/zubra#using-components-in-an-app, `plugin/README.md` in the Zubra repository, and a complete tested app per framework in its `examples/frameworks/` and `examples/meta/`.

package/templates/shared/src/components/hello-counter.zb

@@ -0,0 +1,25 @@
+<!--
+  A counter: your first zubra component. While `npm run dev` runs, edit it here and it updates
+  in place, keeping its count.
+
+  - The host tag (`<hello-counter …>`) declares the props and their defaults.
+  - `count:model` makes `count` two-way: assigning it fires `countchange`, which frameworks
+    bind to (`v-model:count`, `onCountChange`, …).
+  - `let` in the script is state; `const` derived from props or state stays in sync.
+  @fires countchange - The count changed; `detail` is the new count.
+-->
+<script>
+  const atMin = count <= min
+</script>
+<style>
+  :host { display: inline-flex; align-items: center; gap: 0.75rem; font: 1rem system-ui, sans-serif; }
+  button { width: 2.25rem; height: 2.25rem; border: 1px solid #c9cdd6; border-radius: 50%; background: white; font: inherit; font-size: 1.2rem; cursor: pointer; }
+  button:hover { border-color: #5b6cff; }
+  button:disabled { opacity: 0.4; cursor: default; }
+  output { min-width: 6ch; text-align: center; font-variant-numeric: tabular-nums; }
+</style>
+<hello-counter count:model={0} min={0} label="Clicks">
+  <button type="button" class="less" aria-label="Fewer" disabled={atMin} onclick={() => count--}>−</button>
+  <output aria-live="polite">{label}: {count}</output>
+  <button type="button" class="more" aria-label="More" onclick={() => count++}>+</button>
+</hello-counter>

package/templates/shared/test/app.test.js

@@ -0,0 +1,49 @@
+// The app in a real browser: builds it, serves the build and clicks the counter.
+// `npm test` (needs Chromium for Playwright: `npx playwright install chromium`).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright';
+import { buildApp } from './build.js';
+
+const root = fileURLToPath(new URL('..', import.meta.url));
+const TYPES = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.svg': 'image/svg+xml' };
+
+test('the counter counts, and the app sees its count', async () => {
+  const dist = await buildApp(root);
+  const server = createServer((request, response) => {
+    let path = join(dist, decodeURIComponent(new URL(request.url, 'http://x').pathname));
+    if (existsSync(path) && statSync(path).isDirectory()) path = join(path, 'index.html');
+    try {
+      response.writeHead(200, { 'content-type': TYPES[extname(path)] ?? 'text/plain' }).end(readFileSync(path));
+    } catch {
+      response.writeHead(404).end();
+    }
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage();
+    const errors = [];
+    page.on('pageerror', (error) => errors.push(error.message));
+    page.on('console', (message) => message.type() === 'error' && errors.push(message.text()));
+    await page.goto(`http://127.0.0.1:${server.address().port}/`);
+    await page.waitForSelector('hello-counter button.more');
+    assert.equal(await page.textContent('hello-counter output'), 'Clicks: 0');
+    assert.equal(await page.isDisabled('hello-counter button.less'), true);
+
+    await page.click('hello-counter button.more');
+    await page.click('hello-counter button.more');
+    await page.waitForFunction(() => document.querySelector('#seen')?.textContent === '2');
+    assert.equal(await page.textContent('hello-counter output'), 'Clicks: 2');
+    await page.click('hello-counter button.less');
+    await page.waitForFunction(() => document.querySelector('#seen')?.textContent === '1');
+    assert.deepEqual(errors, []);
+  } finally {
+    await browser.close();
+    server.close();
+  }
+});

package/templates/shared/test/build.js

@@ -0,0 +1,9 @@
+// Builds the app for the browser test; returns the output directory.
+import { join } from 'node:path';
+
+export async function buildApp(root) {
+  const { build } = await import('vite');
+  const outDir = join(root, 'dist');
+  await build({ root, configFile: join(root, 'vite.config.js'), configLoader: 'native', logLevel: 'warn', build: { outDir, emptyOutDir: true } });
+  return outDir;
+}

package/templates/solid/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/templates/solid/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@zubra/runtime": "^{{version}}",
+    "solid-js": "^1.9.18"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "^{{version}}",
+    "@zubra/unplugin": "^{{version}}",
+    "playwright": "^1.63.0",
+    "vite": "^8.3.6",
+    "vite-plugin-solid": "^2.11.15"
+  }
+}

package/templates/solid/src/App.jsx

@@ -0,0 +1,14 @@
+import { createSignal } from 'solid-js';
+// Solid uses the element directly: prop:name sets a property, on:name listens.
+import './components/hello-counter.zb';
+
+export default function App() {
+  const [count, setCount] = createSignal(0);
+  return (
+    <main>
+      <h1>{{title}}</h1>
+      <hello-counter prop:count={count()} on:countchange={(event) => setCount(event.detail)} label="Clicks" />
+      <p>Solid sees <span id="seen">{count()}</span></p>
+    </main>
+  );
+}

package/templates/solid/src/main.jsx

@@ -0,0 +1,4 @@
+import { render } from 'solid-js/web';
+import App from './App.jsx';
+
+render(() => <App />, document.getElementById('app'));

package/templates/solid/src/style.css

@@ -0,0 +1,3 @@
+body { margin: 0; min-height: 100vh; display: grid; place-content: center; gap: 1rem; font: 1rem/1.5 system-ui, sans-serif; color: #1d2130; background: #f5f6fa; text-align: center; }
+h1 { margin: 0; font-size: 1.5rem; }
+p { margin: 0; color: #5d6375; }

package/templates/solid/vite.config.js

@@ -0,0 +1,4 @@
+import solid from 'vite-plugin-solid';
+import zubra from '@zubra/unplugin/vite';
+
+export default { plugins: [zubra(), solid()] };

package/templates/svelte/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/templates/svelte/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@zubra/runtime": "^{{version}}",
+    "svelte": "^5.57.3"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "^{{version}}",
+    "@zubra/unplugin": "^{{version}}",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "playwright": "^1.63.0",
+    "vite": "^8.3.6"
+  }
+}

package/templates/svelte/src/App.svelte

@@ -0,0 +1,12 @@
+<script>
+  // Svelte uses the element directly: props are set as properties, on<name> listens.
+  import './components/hello-counter.zb';
+
+  let count = $state(0);
+</script>
+
+<main>
+  <h1>{{title}}</h1>
+  <hello-counter {count} oncountchange={(event) => (count = event.detail)} label="Clicks"></hello-counter>
+  <p>Svelte sees <span id="seen">{count}</span></p>
+</main>

package/templates/svelte/src/main.js

@@ -0,0 +1,4 @@
+import { mount } from 'svelte';
+import App from './App.svelte';
+
+mount(App, { target: document.getElementById('app') });

package/templates/svelte/src/style.css

@@ -0,0 +1,3 @@
+body { margin: 0; min-height: 100vh; display: grid; place-content: center; gap: 1rem; font: 1rem/1.5 system-ui, sans-serif; color: #1d2130; background: #f5f6fa; text-align: center; }
+h1 { margin: 0; font-size: 1.5rem; }
+p { margin: 0; color: #5d6375; }

package/templates/svelte/vite.config.js

@@ -0,0 +1,4 @@
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import zubra from '@zubra/unplugin/vite';
+
+export default { plugins: [zubra(), svelte()] };

package/templates/vanilla/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <main>
+      <h1>{{title}}</h1>
+      <hello-counter label="Clicks"></hello-counter>
+      <p>The page sees <span id="seen">0</span></p>
+    </main>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/templates/vanilla/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@zubra/runtime": "^{{version}}"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "^{{version}}",
+    "@zubra/unplugin": "^{{version}}",
+    "playwright": "^1.63.0",
+    "vite": "^8.3.6"
+  }
+}

package/templates/vanilla/src/main.js

@@ -0,0 +1,7 @@
+import './components/hello-counter.zb';
+
+// The element is a standard custom element: listen for its events like any other.
+const counter = document.querySelector('hello-counter');
+counter.addEventListener('countchange', (event) => {
+  document.querySelector('#seen').textContent = event.detail;
+});

package/templates/vanilla/src/style.css

@@ -0,0 +1,3 @@
+body { margin: 0; min-height: 100vh; display: grid; place-content: center; gap: 1rem; font: 1rem/1.5 system-ui, sans-serif; color: #1d2130; background: #f5f6fa; text-align: center; }
+h1 { margin: 0; font-size: 1.5rem; }
+p { margin: 0; color: #5d6375; }

package/templates/vanilla/vite.config.js

@@ -0,0 +1,3 @@
+import zubra from '@zubra/unplugin/vite';
+
+export default { plugins: [zubra()] };

package/templates/vue/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{title}}</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/templates/vue/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@zubra/runtime": "^{{version}}",
+    "vue": "^3.5.45"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "^{{version}}",
+    "@zubra/unplugin": "^{{version}}",
+    "@vitejs/plugin-vue": "^6.0.10",
+    "playwright": "^1.63.0",
+    "vite": "^8.3.6"
+  }
+}

package/templates/vue/src/App.vue

@@ -0,0 +1,15 @@
+<script setup>
+import { ref } from 'vue';
+// Imported into Vue, a component is a Vue component: v-model:count binds its two-way prop.
+import HelloCounter from './components/hello-counter.zb';
+
+const count = ref(0);
+</script>
+
+<template>
+  <main>
+    <h1>{{title}}</h1>
+    <HelloCounter v-model:count="count" label="Clicks" />
+    <p>Vue sees <span id="seen">{{ count }}</span></p>
+  </main>
+</template>

package/templates/vue/src/main.js

@@ -0,0 +1,4 @@
+import { createApp } from 'vue';
+import App from './App.vue';
+
+createApp(App).mount('#app');

package/templates/vue/src/style.css

@@ -0,0 +1,3 @@
+body { margin: 0; min-height: 100vh; display: grid; place-content: center; gap: 1rem; font: 1rem/1.5 system-ui, sans-serif; color: #1d2130; background: #f5f6fa; text-align: center; }
+h1 { margin: 0; font-size: 1.5rem; }
+p { margin: 0; color: #5d6375; }

package/templates/vue/vite.config.js

@@ -0,0 +1,4 @@
+import vue from '@vitejs/plugin-vue';
+import zubra from '@zubra/unplugin/vite';
+
+export default { plugins: [zubra(), vue()] };

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.