@zubra/unplugin 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/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @zubra/unplugin
 
-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.
+Compile `.zb` components in Vite (and Rollup, webpack, esbuild and Rspack, through [unplugin](https://github.com/unjs/unplugin)). Importing a component gives each file what its framework expects, so nobody writes integration code.
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import zubra from '@zubra/unplugin/vite';
+
+export default defineConfig({ plugins: [zubra(), react()] });
+```
+
+```tsx
+// App.tsx
+import Rating from './rating.zb';
+
+export function App() {
+  const [stars, setStars] = useState(1);
+  return <Rating value={stars} onValueChange={(event) => setStars(event.detail)} />;
+}
+```
+
+```vue
+<!-- App.vue -->
+<script setup>
+import Rating from './rating.zb';
+const stars = ref(1);
+</script>
+<template><Rating v-model="stars" /></template>
+```
+
+## JSX components
+
+`.zb.jsx` and `.zb.tsx` files are components too (see the main README), resolved and wrapped like `.zb` files: `import Rating from './rating.zb.tsx'` in a React file is a React component, and `?element` gives the element. TypeScript reads the component's own source for its types, so no typings file is written for it.
+
+## What an import gives
+
+| Imported from | Default export |
+|---|---|
+| a `.jsx` / `.tsx` file | a React component (`@zubra/runtime/react`, React 18 and 19) |
+| a `.vue` file | a Vue 3 component (`@zubra/runtime/vue`) |
+| another `.zb` component | the custom element class |
+| any other file | the project's framework (detected from the React or Vue Vite plugin), or the element class when there is none |
+
+Every variant defines the custom element, so `<zb-rating>` also works in plain HTML. Add `?element`, `?react` or `?vue` to an import to choose explicitly. `tag` is also exported.
+
+- **React**: props are set as properties; `on<Event>` in any casing listens for the component's events (`onValueChange` for `valuechange`); `value` + `onValueChange` is the controlled pattern. Children go into the component's slots (`slot="name"` for named slots) and stay live as React updates them.
+- **Vue**: props are set as DOM properties before the element starts; events are Vue events (`@valuechange`); every `<prop>` + `<prop>change` pair supports `v-model:<prop>`, and `v-model` binds `value`. Named slots (`<template #title>`) become `slot="title"` content.
+- **Anything else** (Svelte, Solid, Preact, Lit, Angular, plain DOM) uses the element directly: properties in, DOM events out, as with built-in elements. In Svelte, Solid and Preact projects (detected from their Vite plugins) every file gets the element, and the typings are written for that framework.
+
+## Server builds and Astro
+
+In a server build (Vite's SSR), each component module also registers its server renderer, which renders with `@zubra/compiler` from the component's sources embedded in the bundle. `renderToString(Element, { props, attributes, slots })` from `@zubra/runtime/server` uses it. Install `@zubra/compiler` in apps that render on the server, or pass `ssr: false` to leave it out.
+
+For Astro, add the integration (it adds this plugin to Astro's Vite config):
+
+```js
+// astro.config.mjs
+import zubra from '@zubra/unplugin/astro'
+export default { integrations: [zubra()] }
+```
+
+```astro
+---
+import Rating from '../components/rating.zb'
+---
+<Rating value={3} class="big" />          <!-- server-rendered HTML, no JavaScript -->
+<Rating value={3} client:load />          <!-- server-rendered, then hydrated -->
+```
+
+Props go to the component, other attributes to its host, children to its slots (`slot="name"` for a named one).
+
+## Styles
+
+With Vite, a component's `<style>` is a CSS module in Vite's pipeline, so PostCSS, Tailwind (`@reference "tailwindcss"`, `@apply`) and preprocessors (`<style lang="scss">`) process it. Light-DOM components' CSS lands in the page's CSS bundle; shadow components get theirs as a string (`?inline`) for their shadow roots. With other bundlers, plain CSS is inlined in the module. See the main README's Styles section.
+
+## Options
+
+```js
+zubra({
+  compiler: '/path/to/zubra',    // default: $ZUBRA_COMPILER, then @zubra/compiler, then `zubra` on PATH
+  framework: 'auto',           // or 'react' | 'vue' | 'element': the default for plain files
+  dts: true,                   // write typings next to each component
+  runtime: '@zubra/runtime',     // the runtime module compiled code imports
+  ssr: true,                   // server builds register a renderer (needs @zubra/compiler at run time)
+})
+```
+
+## Types
+
+Next to each component the plugin writes `rating.d.zb.ts`, typed for the project's framework: the React component's props and handlers, or the Vue component's props, events and `v-model`. TypeScript uses these files when `allowArbitraryExtensions` is on:
+
+```json
+{ "compilerOptions": { "allowArbitraryExtensions": true, "types": ["@zubra/unplugin/client"] } }
+```
+
+`@zubra/unplugin/client` covers `.zb` imports that don't have typings yet (before the first build) and the `?element` form. The generated files can be committed or ignored (`*.d.zb.ts`).
+
+## Development
+
+In Vite's dev server, editing a component **updates it in place**: the elements on the page get the new template, script and styles, and keep their props, state (by the order of the script's `let`s, as long as a value's kind doesn't change) and slotted content. A change to the element's interface (its props, events, `shadow` or `form-associated`) reloads the page instead. A compile error appears in Vite's overlay with the line, a code frame and the compiler's suggestion.
+
+Components that import the edited one are recompiled too. Other bundlers' watch modes (Rollup, webpack) recompile on change.
+
+## Tests
+
+`npm test` builds real React, Vue and plain Vite apps, runs them in Chromium, type-checks the generated typings with TypeScript, and checks the dev server, `build --watch` and error reporting. It needs a Rust toolchain (the compiler is built from this repository) and Playwright with Chromium.

package/client.d.ts

@@ -0,0 +1,32 @@
+// Fallback typings for `.zb` imports, for files the plugin hasn't written typings next to yet.
+// Add "@zubra/unplugin/client" to `types` in tsconfig.json; with `allowArbitraryExtensions`, the
+// generated `x.d.zb.ts` files next to each component give exact types.
+declare module '*.zb' {
+  const component: any;
+  export const tag: string;
+  export default component;
+}
+
+// An explicit variant: `import Card from './card.zb?element'` is always the element class.
+declare module '*.zb?element' {
+  const element: CustomElementConstructor & {
+    readonly zubra: {
+      readonly tag: string;
+      readonly props: Readonly<Record<string, { readonly attribute: string; readonly default: unknown; readonly required: boolean }>>;
+      readonly events: readonly string[];
+      readonly slots: readonly string[];
+      readonly shadow: boolean;
+      readonly form: boolean;
+    };
+  };
+  export const tag: string;
+  export default element;
+}
+declare module '*.zb?react' {
+  const component: any;
+  export default component;
+}
+declare module '*.zb?vue' {
+  const component: any;
+  export default component;
+}

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@zubra/unplugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "5.0.3",
+  "description": "Compile .zb components in Vite, Rollup, webpack, esbuild and Rspack, with React and Vue wrappers picked automatically",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/journey-to-code-org/zubra.git",
+    "directory": "plugin"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./vite": "./src/vite.js",
+    "./rollup": "./src/rollup.js",
+    "./webpack": "./src/webpack.js",
+    "./esbuild": "./src/esbuild.js",
+    "./loader": "./src/loader.cjs",
+    "./rspack": "./src/rspack.js",
+    "./astro": "./src/astro.js",
+    "./astro/server": "./src/astro-server.js",
+    "./astro/client": "./src/astro-client.js",
+    "./client": {
+      "types": "./client.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "unplugin": "3.7.0"
+  },
+  "peerDependencies": {
+    "@zubra/compiler": "^5.0.0",
+    "@zubra/runtime": "^5.0.0"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "file:../compiler",
+    "@zubra/runtime": "file:../runtime",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@sveltejs/vite-plugin-svelte": "7.3.1",
+    "@tailwindcss/vite": "4.3.5",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.2.1",
+    "@vitejs/plugin-vue": "6.0.10",
+    "astro": "7.4.7",
+    "esbuild": "0.28.2",
+    "lit": "3.3.3",
+    "playwright": "1.63.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "rollup": "4.68.0",
+    "sass": "1.108.1",
+    "solid-js": "1.9.18",
+    "svelte": "5.57.3",
+    "tailwindcss": "4.3.5",
+    "typescript": "7.0.2",
+    "vite": "8.3.6",
+    "vite-plugin-solid": "2.11.15",
+    "vue": "3.5.45",
+    "webpack": "5.112.2"
+  },
+  "files": [
+    "src",
+    "client.d.ts"
+  ],
+  "peerDependenciesMeta": {
+    "@zubra/compiler": {
+      "optional": true
+    }
+  }
+}

package/src/astro-client.js

@@ -0,0 +1,3 @@
+// The Astro renderer's client side. Loading the component's module defines its element, which
+// hydrates the server-rendered markup by itself, so there's nothing to do here.
+export default () => async () => {};

package/src/astro-server.js

@@ -0,0 +1,35 @@
+// The Astro renderer's server side: renders a zubra element with @zubra/runtime/server.
+import { canRender, renderToString } from '@zubra/runtime/server';
+
+// Astro passes named slots camelCased (`slot="side-note"` → `sideNote`).
+const kebab = (name) => name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+function slotName(meta, name) {
+  if (name === 'default' || meta.slots.includes(name)) return name;
+  if (meta.slots.includes(kebab(name))) return kebab(name);
+  throw new Error(`zubra: <${meta.tag}> has no slot \`${name}\``);
+}
+
+export default {
+  name: '@zubra/astro',
+  check(Component) {
+    return canRender(Component);
+  },
+  async renderToStaticMarkup(Component, given, slotted) {
+    const meta = Component.zubra;
+    const props = {};
+    const attributes = {};
+    for (const [name, value] of Object.entries(given ?? {})) {
+      if (value === undefined || typeof value === 'function') continue;
+      if (Object.hasOwn(meta.props, name)) props[name] = value;
+      else attributes[name] = value;
+    }
+    const slots = {};
+    for (const [name, html] of Object.entries(slotted ?? {})) {
+      const content = String(html ?? '');
+      if (content.trim()) slots[slotName(meta, name)] = content;
+    }
+    return { html: renderToString(Component, { props, attributes, slots }) };
+  },
+  supportsAstroStaticSlot: false,
+};

package/src/astro.js

@@ -0,0 +1,42 @@
+// Astro integration: `.zb` components in Astro pages, server-rendered, hydrated with a client
+// directive.
+//
+//   // astro.config.mjs
+//   import zubra from '@zubra/unplugin/astro'
+//   export default { integrations: [zubra()] }
+//
+//   ---
+//   import Rating from '../components/rating.zb'
+//   ---
+//   <Rating value={3} client:load />      <!-- server-rendered, then hydrated in the browser -->
+//   <Rating value={3} />                  <!-- server-rendered HTML only -->
+//
+// Props go to the component; other attributes (`class`, `id`, `data-*`) to its host element.
+// Children are slot content (`slot="name"` for a named slot). Options are the plugin's.
+import vite from './vite.js';
+
+export default function zubra(options = {}) {
+  return {
+    name: '@zubra/astro',
+    hooks: {
+      'astro:config:setup': ({ addRenderer, updateConfig }) => {
+        addRenderer({
+          name: '@zubra/astro',
+          serverEntrypoint: '@zubra/unplugin/astro/server',
+          clientEntrypoint: '@zubra/unplugin/astro/client',
+        });
+        updateConfig({
+          vite: {
+            plugins: [vite({ framework: 'element', ...options })],
+            // The server build renders with @zubra/compiler, which loads zubra.wasm from beside
+            // itself: bundled into Astro's prerender chunks, it would look for it there. (From
+            // npm it's external anyway; linked or in a workspace, Vite would bundle it.)
+            // Astro prerenders in its own Vite environment, so this is `resolve.external` (every
+            // server environment), not `ssr.external`.
+            resolve: { external: [options.compilerModule ?? '@zubra/compiler'] },
+          },
+        });
+      },
+    },
+  };
+}

package/src/esbuild.js

@@ -0,0 +1,3 @@
+import { unplugin } from './index.js';
+
+export default unplugin.esbuild;

package/src/index.js

@@ -0,0 +1,372 @@
+// @zubra/unplugin: `.zb` components in any bundler unplugin supports (Vite first).
+//
+//   // vite.config.js
+//   import zubra from '@zubra/unplugin/vite'
+//   export default { plugins: [zubra(), react()] }
+//
+//   // App.tsx — a React component, because this is a React file
+//   import Rating from './rating.zb'
+//   <Rating value={stars} onValueChange={(event) => setStars(event.detail)} />
+//
+// What an import of a `.zb` file gives depends on who imports it, so nobody writes glue code:
+//
+// - from a `.jsx`/`.tsx` file: a React component (`@zubra/runtime/react`);
+// - from a `.vue` file: a Vue component (`@zubra/runtime/vue`);
+// - from anything else (plain JS/TS, another `.zb`): the custom element class. In a project
+//   using React or Vue, plain `.js`/`.ts` files get that framework's component.
+//
+// Every variant defines the element, so `<zb-rating>` also works in HTML and in templates.
+// `?element`, `?react` or `?vue` on the import picks one explicitly. Compile errors show the
+// source line (in Vite's overlay, too); editing a `.zb` file reloads the page, because the
+// platform can't redefine a custom element. Next to each component the plugin writes typings
+// (`rating.d.zb.ts`, used by TypeScript with `allowArbitraryExtensions`) for the project's
+// framework.
+import { createUnplugin } from 'unplugin';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { addProps, zubraImports } from './props.js';
+import { basename, dirname, extname, relative, resolve, sep } from 'node:path';
+
+const VARIANTS = ['element', 'react', 'vue'];
+/** A component file: `.zb`, or a JSX component (`.zb.jsx` / `.zb.tsx`). */
+const COMPONENT = /\.zb(?:\.[jt]sx)?$/;
+const QUERY = '?zubra=';
+
+const split = (id) => {
+  const at = id.indexOf('?');
+  return at < 0 ? [id, ''] : [id.slice(0, at), id.slice(at + 1)];
+};
+
+/** The variant an importer gets: by explicit query, by the importer's kind, or the project's. */
+export function variantFor(query, importer, project) {
+  const asked = VARIANTS.find((variant) => new URLSearchParams(query).has(variant));
+  if (asked) return asked;
+  if (!importer) return project;
+  const [file] = split(importer);
+  if (COMPONENT.test(file)) return 'element'; // a component, or a wrapper (`x.zb?zubra=react`)
+  if (file.endsWith('.vue')) return 'vue';
+  // JSX is React's, or Vue's in a Vue project (vue-jsx); Solid and Preact use custom elements
+  // directly.
+  if (/\.[jt]sx$/.test(file)) return project === 'vue' ? 'vue' : project === 'react' || project === 'element' ? 'react' : 'element';
+  return project === 'react' || project === 'vue' ? project : 'element';
+}
+
+/** `.zb` files a component imports, recursively, so changing one recompiles its importers. */
+function dependencies(path, seen = new Set()) {
+  if (seen.has(path)) return seen;
+  seen.add(path);
+  let source = '';
+  try { source = readFileSync(path, 'utf8'); } catch { return seen; }
+  // A JSX component's imports are the whole file's; an .zb file's are its <script>'s.
+  const script = /\.[jt]sx$/.test(path) ? 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('.')) dependencies(resolve(dirname(path), specifier), seen);
+  }
+  return seen;
+}
+
+/**
+ * A component module in Vite's dev server: it accepts its own updates, which the runtime swaps
+ * into the live elements (keeping their state). An update that changes the element's interface
+ * (its props, events, shadow or form setting) reloads the page instead.
+ */
+function hot(code) {
+  // On the first line, so line numbers in errors stay the compiler's.
+  return `globalThis.__ZUBRA_HOT__ = true; ${code}
+if (import.meta.hot) {
+  import.meta.hot.accept((next) => {
+    // (A reload, not invalidate(): a framework wrapper above accepts its own updates.)
+    if (!next || next.default?.hotReloaded === false) location.reload();
+  });
+}
+`;
+}
+
+/**
+ * What a server build appends to a component: its renderer, registered by tag. It renders with
+ * @zubra/compiler from the component's sources, embedded (keyed by path below their common
+ * directory), so the server bundle needs nothing from the build machine.
+ */
+function serverRenderer(path, compilerModule, runtime) {
+  const paths = [...dependencies(path)].filter((file) => existsSync(file));
+  let common = dirname(path);
+  while (!paths.every((file) => file.startsWith(common + sep))) common = dirname(common);
+  // Imports may go up (`../x/y.zb`) before coming back down: keep the directories they pass.
+  let up = 0;
+  for (const file of paths) {
+    for (const [, specifier] of readFileSync(file, 'utf8').matchAll(/import\s+(?:[^'"]*?from\s+)?['"]((?:\.\.\/)+)[^'"]*\.zb(?:\.[jt]sx)?['"]/g)) {
+      up = Math.max(up, specifier.length / 3);
+    }
+  }
+  for (let i = 0; i < up && dirname(common) !== common; i++) common = dirname(common);
+  const key = (file) => `/${relative(common, file).split(sep).join('/')}`;
+  const files = Object.fromEntries(paths.map((file) => [key(file), readFileSync(file, 'utf8')]));
+  return `
+import { registerRenderer as $zubraRegister } from ${JSON.stringify(`${runtime}/server`)};
+import { request as $zubraRequest } from ${JSON.stringify(compilerModule)};
+const $zubraFiles = ${JSON.stringify(files)};
+$zubraRegister(tag, (props, slots) => {
+  const response = $zubraRequest({ emit: 'html', path: ${JSON.stringify(key(path))}, files: $zubraFiles, props, slots, slotSource: 'html', partial: true });
+  if (!response.ok) throw new Error(response.error);
+  return response.output;
+});
+`;
+}
+
+export const unplugin = createUnplugin((options = {}, meta = {}) => {
+  // The compiler: a CLI when one is given (option or $ZUBRA_COMPILER); otherwise the WebAssembly
+  // build (@zubra/compiler) if it's installed, so no Rust toolchain is needed; else `zubra` on PATH.
+  const explicit = options.compiler ?? process.env.ZUBRA_COMPILER;
+  const compiler = explicit ?? 'zubra';
+  let wasm = null;
+  async function chooseBackend() {
+    if (explicit || wasm) return;
+    try {
+      const module = await import('@zubra/compiler');
+      if (module.available()) wasm = module;
+    } catch {
+      // Not installed: use the CLI.
+    }
+  }
+  const runtime = options.runtime ?? '@zubra/runtime';
+  let project = options.framework && options.framework !== 'auto' ? options.framework : null;
+  const typings = options.dts ?? true;
+  // Server builds render components with @zubra/compiler at request time (`ssr: false` leaves
+  // that out: the elements then render on the client only).
+  const serverRendering = options.ssr ?? true;
+  let ssrFramework = null; // React Router, SvelteKit or Nuxt (Vite): see the light-DOM warning
+  const warnedLight = new Set();
+  const relativePath = (path) => path.startsWith(process.cwd()) ? path.slice(process.cwd().length + 1) : path;
+  const compilerModule = options.compilerModule ?? '@zubra/compiler';
+  let dev = false; // Vite's dev server: components hot-reload
+
+  /** CLI flags → a request for the WebAssembly compiler. */
+  function asRequest(args) {
+    const request = { emit: 'html' };
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i];
+      if (flag === '--keep-imports') request.keepImports = true;
+      else if (flag === '--no-imports') request.noImports = true;
+      else {
+        const key = { '--emit': 'emit', '--framework': 'framework', '--runtime': 'runtime', '--css-import': 'cssImport', '--css-import-inline': 'cssImportInline' }[flag];
+        if (!key) throw new Error(`zubra: unexpected compiler flag ${flag}`);
+        request[key] = args[++i];
+      }
+    }
+    return request;
+  }
+
+  function compile(path, ...args) {
+    if (wasm) {
+      const response = wasm.compileFile(path, asRequest(args));
+      if (!response.ok) throw new Error(response.error);
+      return { code: response.output, warnings: response.warnings.join('').trim() };
+    }
+    const result = spawnSync(compiler, ['compile', path, ...args], { encoding: 'utf8' });
+    if (result.error) {
+      throw new Error(`zubra: couldn't run the compiler \`${compiler}\` (${result.error.code ?? result.error.message}). `
+        + 'Install @zubra/compiler (the WebAssembly build), install the CLI, or pass { compiler: "/path/to/zubra" }.');
+    }
+    if (result.status !== 0) throw new Error(result.stderr.trim() || `zubra: the compiler exited with ${result.status}`);
+    return { code: result.stdout, warnings: result.stderr.trim() };
+  }
+
+  /**
+   * A compile error for the bundler: with Vite, `loc` and `frame` put it in the dev overlay with
+   * the source line and the compiler's help. Always throws: Rollup's and Vite's `error()` throw,
+   * but esbuild's and Bun's (through unplugin) only record the error, and drop it when the hook
+   * returns nothing.
+   */
+  function fail(context, error, id) {
+    const text = String(error.message ?? error);
+    const at = text.match(/-->\s+(.+?):(\d+):(\d+)/);
+    const message = text.split('\n')[0].replace(/^error:\s*/, '');
+    if (!at) context.error(text);
+    else {
+      context.error({
+        message: `${message}\n\n${text}`,
+        id,
+        loc: { file: at[1], line: Number(at[2]), column: Number(at[3]) },
+        frame: text.split('\n').slice(1).join('\n'),
+        plugin: 'zubra',
+      });
+    }
+    throw new Error(text);
+  }
+
+  // Each component's tag and prop names, for `zb-props` (by path, while its file is unchanged).
+  const interfaces = new Map();
+  function interfaceOf(path) {
+    const stamp = statSync(path).mtimeMs;
+    const known = interfaces.get(path);
+    if (known?.stamp === stamp) return known.value;
+    const description = JSON.parse(compile(path, '--emit', 'interface').code);
+    const value = { tag: description.tag, props: new Set(description.props.map((prop) => prop.name)) };
+    interfaces.set(path, { stamp, value });
+    return value;
+  }
+
+  function writeTypings(path) {
+    const framework = ['react', 'vue', 'svelte', 'solid'].includes(project) ? project : 'none';
+    const target = resolve(dirname(path), `${basename(path, '.zb')}.d.zb.ts`);
+    const contents = compile(path, '--emit', 'dts', '--framework', framework).code;
+    // Only when changed, so watchers don't loop.
+    if (!existsSync(target) || readFileSync(target, 'utf8') !== contents) writeFileSync(target, contents);
+  }
+
+  return {
+    name: 'zubra',
+    enforce: 'pre',
+
+    async buildStart() {
+      await chooseBackend();
+    },
+
+    async resolveId(source, importer) {
+      const [specifier, query] = split(source);
+      if (!COMPONENT.test(specifier)) return null;
+      let path;
+      if (specifier.startsWith('/') && existsSync(specifier)) path = specifier;
+      else if (importer && specifier.startsWith('.')) path = resolve(dirname(split(importer)[0]), specifier);
+      else {
+        const resolved = await this.resolve?.(specifier, importer, { skipSelf: true });
+        if (!resolved) return null;
+        path = split(resolved.id)[0];
+      }
+      // A component's stylesheet keeps its whole query: Vite (and Tailwind) recognize CSS by its
+      // `&lang.css` suffix, and inline CSS by `&inline`.
+      if (new URLSearchParams(query).get('zubra') === 'style') return `${path}?${query}`;
+      // A variant already chosen (a wrapper's import of its element, a dev server URL) stays.
+      const variant = new URLSearchParams(query).get('zubra') ?? variantFor(query, importer, project ?? 'element');
+      return `${path}${QUERY}${variant}`;
+    },
+
+    loadInclude(id) {
+      return /\.zb(?:\.[jt]sx)?\?zubra=/.test(id);
+    },
+
+    load(id, loadOptions) {
+      // A server build (Vite's SSR, or its server environments): the module also registers its
+      // server renderer.
+      const server = loadOptions?.ssr === true || this?.environment?.config?.consumer === 'server';
+      const [path, query] = split(id);
+      const variant = new URLSearchParams(query).get('zubra');
+      if (variant === 'style') {
+        // This component's stylesheet, for the bundler's CSS pipeline (PostCSS, Tailwind,
+        // preprocessors) to process.
+        try {
+          return compile(path, '--emit', 'css', '--no-imports').code;
+        } catch (error) {
+          return fail(this, error, path);
+        }
+      }
+      if (variant === 'react' || variant === 'vue') {
+        const element = JSON.stringify(`${path}${QUERY}element`);
+        // In development the wrapper accepts its updates: the element it wraps hot-reloads itself.
+        return `import Element from ${element};\nimport { wrap } from ${JSON.stringify(`${runtime}/${variant}`)};\n`
+          + `export { tag } from ${element};\nexport default wrap(Element);\n`
+          + (dev && meta.framework === 'vite' ? 'if (import.meta.hot) import.meta.hot.accept(() => {});\n' : '');
+      }
+      for (const dependency of dependencies(path)) this.addWatchFile?.(dependency);
+      if (server && ssrFramework && path.endsWith('.zb') && !warnedLight.has(path) && isLightDom(readFileSync(path, 'utf8'))) {
+        warnedLight.add(path);
+        // Since 3.3 the React and Vue wrappers server-render a light-DOM element's content and
+        // keep the framework out of the host while hydrating, so light DOM works there when the
+        // element is given no framework children. Svelte uses the element directly, claims every
+        // node, and fails on the element's own.
+        if (ssrFramework === 'SvelteKit') {
+          this.warn(`${relativePath(path)} is a light-DOM component, and SvelteKit hydrates the server's HTML: when the element renders into its host first, Svelte fails to hydrate the page. `
+            + 'Add `shadow` to its host tag (see examples/meta/README.md).');
+        } else {
+          this.warn(`${relativePath(path)} is a light-DOM component: in ${ssrFramework}, that works when the element is given no children from ${ssrFramework === 'Nuxt' ? 'Vue' : 'React'} (its content is server-rendered and hydrated in place); `
+            + `an element given children must be \`shadow\`, or ${ssrFramework === 'Nuxt' ? 'Vue removes what it finds there' : 'React re-renders the page'} (see examples/meta/README.md).`);
+        }
+      }
+      // (A JSX component is typed by its own source: TypeScript reads the function.)
+      if (typings && path.endsWith('.zb')) writeTypings(path);
+      // With Vite, a <style> goes through Vite's CSS pipeline; elsewhere it's inlined as written.
+      const styles = [];
+      if (meta.framework === 'vite' && path.endsWith('.zb') && /<style[\s>]/i.test(readFileSync(path, 'utf8'))) {
+        const lang = readFileSync(path, 'utf8').match(/<style[^>]*\slang=["']([a-z0-9]+)["']/i)?.[1] ?? 'css';
+        styles.push('--css-import', `${path}?zubra=style&lang.${lang}`, '--css-import-inline', `${path}?zubra=style&inline&lang.${lang}`);
+      }
+      let output;
+      try {
+        output = compile(path, '--emit', 'js', '--keep-imports', '--runtime', runtime, ...styles);
+      } catch (error) {
+        return fail(this, error, path);
+      }
+      if (output.warnings) this.warn(output.warnings);
+      if (server) return serverRendering ? output.code + serverRenderer(path, compilerModule, runtime) : output.code;
+      return dev && meta.framework === 'vite' ? hot(output.code) : output.code;
+    },
+
+    rollup: {
+      // The runtime loads remark.js (stripped markup) with a dynamic import, which is a second
+      // chunk; a single-file build (`output.file`) inlines it instead of failing.
+      outputOptions(outputOptions) {
+        if (outputOptions.file && !outputOptions.dir && outputOptions.inlineDynamicImports === undefined) {
+          return { ...outputOptions, inlineDynamicImports: true };
+        }
+        return null;
+      },
+    },
+
+    vite: {
+      config() {
+        // One copy of each framework, even when @zubra/runtime is linked from elsewhere.
+        return { resolve: { dedupe: ['react', 'react-dom', 'vue', '@angular/core', '@angular/common', '@angular/forms'] } };
+      },
+      configResolved(config) {
+        const names = config.plugins.map((plugin) => plugin.name);
+        // Frameworks that hydrate the server's HTML around elements (Solid doesn't mind).
+        ssrFramework = names.includes('react-router') ? 'React Router'
+          : names.some((name) => name.startsWith('vite-plugin-sveltekit')) ? 'SvelteKit'
+            : names.some((name) => name.startsWith('nuxt:')) ? 'Nuxt' : null;
+        if (project) return;
+        if (names.some((name) => /^vite:react/.test(name) || name === 'react-router')) project = 'react';
+        else if (names.includes('vite:vue')) project = 'vue';
+        else if (names.includes('solid')) project = 'solid';
+        else if (names.some((name) => name.startsWith('preact'))) project = 'preact';
+        else if (names.some((name) => name.startsWith('vite-plugin-svelte'))) project = 'svelte';
+        else project = 'element';
+      },
+      configureServer() {
+        dev = true;
+      },
+      // Svelte and Solid use the elements directly: in their server builds, the hosts get
+      // `zb-props` (see props.js), for @zubra/server's injectShadowRoots().
+      async transform(code, id, transformOptions) {
+        const dialect = project === 'svelte' ? 'svelte' : project === 'solid' ? 'solid' : null;
+        if (!dialect) return null;
+        const server = transformOptions?.ssr === true || this?.environment?.config?.consumer === 'server';
+        const [path] = split(id);
+        if (!server || path.includes('/node_modules/') || COMPONENT.test(path)) return null;
+        if (dialect === 'svelte' ? !path.endsWith('.svelte') : !/\.[jt]sx$/.test(path)) return null;
+        const tags = new Map();
+        for (const specifier of zubraImports(code)) {
+          const resolved = specifier.startsWith('.') ? resolve(dirname(path), specifier) : (await this.resolve(specifier, id, { skipSelf: true }))?.id;
+          const file = resolved && split(resolved)[0];
+          if (!file || !existsSync(file)) continue;
+          try {
+            const { tag, props } = interfaceOf(file);
+            tags.set(tag, props);
+          } catch {
+            // A compile error shows when the component itself loads.
+          }
+        }
+        const code2 = addProps(code, tags, dialect);
+        return code2 == null ? null : { code: code2, map: null };
+      },
+    },
+  };
+});
+
+/** Whether a `.zb` component renders into light DOM (no `shadow` on its host tag). */
+export function isLightDom(source) {
+  const markup = source.replace(/<!--[^]*?-->/g, '').replace(/<(script|style)\b[^]*?<\/\1>/gi, '');
+  const host = markup.match(/<([a-z][a-z0-9]*-[a-z0-9-]*)\b([^>]*)>/i);
+  return !!host && !/(^|\s)shadow(\s|=|$|\/)/.test(host[2]);
+}
+
+export default unplugin;

package/src/loader.cjs

@@ -0,0 +1,83 @@
+// A webpack-style loader for `.zb` files, for bundlers that take loaders but not plugins:
+// Next.js's Turbopack (`turbopack.rules`), and webpack itself.
+//
+//   // next.config.js
+//   export default {
+//     turbopack: { rules: { '*.zb': { loaders: ['@zubra/unplugin/loader'], as: '*.js' } } },
+//   };
+//
+// The module defines the element (importing a component's own `.zb` imports, which go through
+// the loader too) and, as its default export, the element as a React component (a client
+// component). `?element` imports the element itself instead. Options: `{ runtime, react: false,
+// server: true }`.
+//
+// `server: true`, for the server's build, also registers how to render the component there
+// (with @zubra/compiler, from its sources embedded in the module). Then the React wrapper renders
+// a shadow-DOM component's declarative shadow root into the server's HTML, so it shows before
+// JavaScript (Next.js, which has no HTML hook for @zubra/server's injectShadowRoots):
+//
+//   '*.zb': [
+//     { condition: 'browser', loaders: ['@zubra/unplugin/loader'], as: '*.js' },
+//     { condition: { not: 'browser' }, loaders: [{ loader: '@zubra/unplugin/loader', options: { server: true } }], as: '*.js' },
+//   ],
+'use strict';
+
+const { existsSync } = require('node:fs');
+const { dirname, join, relative, sep } = require('node:path');
+
+// Inside the zubra repository, the CLI from `cargo build` stands in for @zubra/compiler's
+// WebAssembly build (as in the plugin).
+function findCli(from) {
+  for (let dir = from, up = 0; up < 10; up++, dir = dirname(dir)) {
+    for (const profile of ['debug', 'release']) {
+      const cli = join(dir, 'target', profile, `zubra${process.platform === 'win32' ? '.exe' : ''}`);
+      if (existsSync(cli)) return cli;
+    }
+  }
+  return null;
+}
+
+/** The module's server renderer: @zubra/compiler, from the component's sources (by relative path). */
+function serverRenderer(path, files, runtime, compilerModule) {
+  const paths = Object.keys(files);
+  let common = dirname(path);
+  while (!paths.every((file) => file.startsWith(common + sep))) common = dirname(common);
+  const key = (file) => `/${relative(common, file).split(sep).join('/')}`;
+  const embedded = Object.fromEntries(paths.map((file) => [key(file), files[file]]));
+  return `
+import { registerRenderer as $zubraRegister } from ${JSON.stringify(`${runtime}/server`)};
+import { request as $zubraRequest } from ${JSON.stringify(compilerModule)};
+$zubraRegister(tag, (props, slots) => {
+  const response = $zubraRequest({ emit: 'html', path: ${JSON.stringify(key(path))}, files: ${JSON.stringify(embedded)}, props, slots, slotSource: 'html', partial: true });
+  if (!response.ok) throw new Error(response.error);
+  return response.output;
+});
+`;
+}
+
+module.exports = function zubraLoader() {
+  const callback = this.async();
+  const options = (typeof this.getOptions === 'function' ? this.getOptions() : this.query) || {};
+  const runtime = options.runtime || '@zubra/runtime';
+  const path = this.resourcePath;
+  const element = /(^|[?&])element\b/.test(this.resourceQuery || '');
+  import('@zubra/compiler')
+    .then((compiler) => {
+      if (!compiler.available() && !process.env.ZUBRA_COMPILER) {
+        const cli = findCli(this.rootContext || process.cwd()) || findCli(__dirname);
+        if (cli) process.env.ZUBRA_COMPILER = cli;
+      }
+      const files = compiler.sources(path);
+      for (const file of Object.keys(files)) if (file !== path) this.addDependency(file);
+      const response = compiler.compileFile(path, { emit: 'js', runtime, keepImports: true });
+      if (!response.ok) throw new Error(response.error);
+      for (const warning of response.warnings) this.emitWarning(new Error(warning));
+      let code = response.output;
+      if (options.server) code += serverRenderer(path, files, runtime, options.compilerModule || '@zubra/compiler');
+      if (element || options.react === false) return callback(null, code);
+      // The element, and the element as a React component (React's hooks: a client component).
+      code = code.replace(/^export default \$define\(/m, 'const $element = $define(');
+      callback(null, `'use client';\n${code}\nimport { wrap as $wrap } from ${JSON.stringify(`${runtime}/react`)};\nexport { $element as Element };\nexport default $wrap($element);\n`);
+    })
+    .catch((error) => callback(error));
+};

package/src/props.js

@@ -0,0 +1,128 @@
+// `zb-props` for Svelte and Solid. React's and Vue's adapters write it themselves; Svelte and Solid
+// use the elements directly, and their server HTML has no object props (Svelte writes
+// "[object Object]", Solid's `prop:` values are properties). So in their server builds, each zubra
+// host in a component's markup gets `zb-props={JSON.stringify({ … })}` from the attributes that
+// set its props, and `@zubra/server`'s injectShadowRoots() renders it complete.
+
+/**
+ * `code` with `zb-props` added to the hosts of `tags` (tag → its prop names). `dialect` is
+ * `svelte` (`log={…}`, `{log}`, `bind:value={…}`) or `solid` (`prop:items={…}`, `items={…}`).
+ */
+export function addProps(code, tags, dialect) {
+  if (!tags.size) return null;
+  const names = [...tags.keys()].map((tag) => tag.replace(/[-]/g, '\\-')).join('|');
+  const opening = new RegExp(`<(${names})(?=[\\s/>])`, 'g');
+  const edits = [];
+  for (let match; (match = opening.exec(code)); ) {
+    const props = tags.get(match[1]);
+    const attributes = readAttributes(code, match.index + match[0].length);
+    if (!attributes) continue;
+    opening.lastIndex = attributes.end;
+    if (attributes.list.some((attribute) => attribute.name === 'zb-props')) continue;
+    const entries = [];
+    for (const { name, expression, shorthand } of attributes.list) {
+      if (expression == null) continue;
+      const prop = dialect === 'solid' ? name.replace(/^prop:/, '') : name.replace(/^bind:/, '');
+      if (!props.has(prop)) continue;
+      if (shorthand) entries.push(prop);
+      else entries.push(`${JSON.stringify(prop)}: (${expression})`);
+    }
+    if (!entries.length) continue;
+    edits.push({ at: match.index + match[0].length, text: ` zb-props={JSON.stringify({ ${entries.join(', ')} })}` });
+  }
+  if (!edits.length) return null;
+  let out = code;
+  for (const { at, text } of edits.reverse()) out = out.slice(0, at) + text + out.slice(at);
+  return out;
+}
+
+/** The attributes of a tag whose name ends at `start`, up to its `>`: `{ list, end }`, or null. */
+export function readAttributes(code, start) {
+  const list = [];
+  let i = start;
+  while (i < code.length) {
+    while (/\s/.test(code[i])) i++;
+    if (code[i] === '>') return { list, end: i + 1 };
+    if (code[i] === '/' && code[i + 1] === '>') return { list, end: i + 2 };
+    if (code[i] === '{') {
+      // Svelte's shorthand (`{log}`) or a spread (`{...rest}`).
+      const end = closeBrace(code, i);
+      if (end < 0) return null;
+      const inner = code.slice(i + 1, end).trim();
+      if (/^[A-Za-z_$][\w$]*$/.test(inner)) list.push({ name: inner, expression: inner, shorthand: true });
+      i = end + 1;
+      continue;
+    }
+    const name = /^[^\s=/>{"']+/.exec(code.slice(i))?.[0];
+    if (!name) return null;
+    i += name.length;
+    while (/\s/.test(code[i])) i++;
+    if (code[i] !== '=') {
+      list.push({ name, expression: null });
+      continue;
+    }
+    i++;
+    while (/\s/.test(code[i])) i++;
+    if (code[i] === '"' || code[i] === "'") {
+      const end = code.indexOf(code[i], i + 1);
+      if (end < 0) return null;
+      list.push({ name, expression: null, text: code.slice(i + 1, end) });
+      i = end + 1;
+    } else if (code[i] === '{') {
+      const end = closeBrace(code, i);
+      if (end < 0) return null;
+      list.push({ name, expression: code.slice(i + 1, end).trim() });
+      i = end + 1;
+    } else {
+      const value = /^[^\s>]+/.exec(code.slice(i))?.[0] ?? '';
+      list.push({ name, expression: null, text: value });
+      i += value.length;
+    }
+  }
+  return null;
+}
+
+/** The index of the `}` closing the `{` at `start` (strings and template literals skipped), or -1. */
+function closeBrace(code, start) {
+  let depth = 0;
+  for (let i = start; i < code.length; i++) {
+    const c = code[i];
+    if (c === '"' || c === "'") {
+      i = skipString(code, i);
+      if (i < 0) return -1;
+    } else if (c === '`') {
+      i = skipTemplate(code, i);
+      if (i < 0) return -1;
+    } else if (c === '{') depth++;
+    else if (c === '}' && --depth === 0) return i;
+  }
+  return -1;
+}
+
+function skipString(code, start) {
+  for (let i = start + 1; i < code.length; i++) {
+    if (code[i] === '\\') i++;
+    else if (code[i] === code[start]) return i;
+  }
+  return -1;
+}
+
+function skipTemplate(code, start) {
+  for (let i = start + 1; i < code.length; i++) {
+    if (code[i] === '\\') i++;
+    else if (code[i] === '`') return i;
+    else if (code[i] === '$' && code[i + 1] === '{') {
+      i = closeBrace(code, i + 1);
+      if (i < 0) return -1;
+    }
+  }
+  return -1;
+}
+
+/** The `.zb` files a module imports (specifiers, as written). */
+export function zubraImports(code) {
+  const found = [];
+  const pattern = /\bimport\s+(?:[^'"]*?\sfrom\s+)?['"]([^'"]+\.zb(?:\.[jt]sx)?)(?:\?[^'"]*)?['"]/g;
+  for (let match; (match = pattern.exec(code)); ) found.push(match[1]);
+  return found;
+}

package/src/rollup.js

@@ -0,0 +1,3 @@
+import { unplugin } from './index.js';
+
+export default unplugin.rollup;

package/src/rspack.js

@@ -0,0 +1,3 @@
+import { unplugin } from './index.js';
+
+export default unplugin.rspack;

package/src/vite.js

@@ -0,0 +1,3 @@
+import { unplugin } from './index.js';
+
+export default unplugin.vite;

package/src/webpack.js

@@ -0,0 +1,3 @@
+import { unplugin } from './index.js';
+
+export default unplugin.webpack;