poveste 0.13.0 → 0.14.0

package/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * @deprecated
+ * @deprecated Use {@link logEvent} instead. This forwards to it and warns.
  */
 export function hstEvent(name: string, argument): void
 
@@ -15,5 +15,13 @@ export function logEvent(name: string, argument): void
  */
 export function isCollecting(): boolean
 
+/**
+ * Switches the book between light and dark, or to `value` when one is given.
+ * Returns the mode it ended up in.
+ */
 export function toggleDark(value?: boolean): boolean
+
+/**
+ * Whether the book is currently in dark mode.
+ */
 export function isDark(): boolean

package/dist/node/build-counts.d.ts

@@ -0,0 +1,26 @@
+import type { ServerStoryFile } from '@poveste/shared';
+export interface BuildCounts {
+    /** Story files that produced a story with variants. */
+    stories: number;
+    variants: number;
+    /** Standalone `.story.md` pages, which the book's home page calls Documents. */
+    docs: number;
+    /** Relative paths of the files that produced neither, so the warning can name them. */
+    empty: string[];
+}
+/**
+ * Splits the collected story files three ways, the way the book's own home page
+ * does: stories, documents, and files that produced nothing.
+ *
+ * "No variants" is not the question. A standalone `.story.md` is collected into a
+ * story with `docsOnly: true` and `variants: []` by construction (`markdown.ts`),
+ * so counting empty by variants alone reported every documentation page in the
+ * book as a problem — three of the four `examples/vue3` warned about are
+ * `SHARED_STORY_TITLES` entries that a required spec fails if you delete them,
+ * which left the one real empty file hidden inside them (#670).
+ *
+ * Documents are counted rather than folded in with stories because `HomeView.vue`
+ * already makes exactly this split, and a build that reports 60 stories over a
+ * home page reading 57 Stories and 3 Documents disagrees with itself.
+ */
+export declare function buildCounts(storyFiles: ServerStoryFile[]): BuildCounts;

package/dist/node/build-counts.js

@@ -0,0 +1,31 @@
+/**
+ * Splits the collected story files three ways, the way the book's own home page
+ * does: stories, documents, and files that produced nothing.
+ *
+ * "No variants" is not the question. A standalone `.story.md` is collected into a
+ * story with `docsOnly: true` and `variants: []` by construction (`markdown.ts`),
+ * so counting empty by variants alone reported every documentation page in the
+ * book as a problem — three of the four `examples/vue3` warned about are
+ * `SHARED_STORY_TITLES` entries that a required spec fails if you delete them,
+ * which left the one real empty file hidden inside them (#670).
+ *
+ * Documents are counted rather than folded in with stories because `HomeView.vue`
+ * already makes exactly this split, and a build that reports 60 stories over a
+ * home page reading 57 Stories and 3 Documents disagrees with itself.
+ */
+export function buildCounts(storyFiles) {
+    const counts = { stories: 0, variants: 0, docs: 0, empty: [] };
+    for (const file of storyFiles) {
+        if (file.story?.docsOnly) {
+            counts.docs++;
+        }
+        else if (file.story?.variants.length) {
+            counts.stories++;
+            counts.variants += file.story.variants.length;
+        }
+        else {
+            counts.empty.push(file.relativePath);
+        }
+    }
+    return counts;
+}

package/dist/node/build.js

@@ -5,6 +5,7 @@ import { join } from 'pathe';
 import pc from 'picocolors';
 import { createServer as createViteServer, mergeConfig as mergeViteConfig, build as viteBuild, } from 'vite';
 import { APP_PATH } from './alias.js';
+import { buildCounts } from './build-counts.js';
 import { getSerializedStoryData } from './build-serialize.js';
 import { useCollectStories } from './collect/index.js';
 import { useModuleLoader } from './load.js';
@@ -105,9 +106,7 @@ export async function build(ctx) {
             // Same wrapper the dev path uses for these exact calls (server.ts).
             await wrapLogError('destroyCollectStories', () => destroyCollectStories());
         }
-        const storyCount = ctx.storyFiles.reduce((sum, file) => sum + (file.story?.variants.length ? 1 : 0), 0);
-        const variantCount = ctx.storyFiles.reduce((sum, file) => sum + (file.story?.variants.length ?? 0), 0);
-        const emptyStoryCount = ctx.storyFiles.length - storyCount;
+        const { stories: storyCount, variants: variantCount, docs: docsCount, empty } = buildCounts(ctx.storyFiles);
         const { viteConfig: buildViteConfigRaw } = await getViteConfigWithPlugins(false, ctx);
         const buildViteConfig = mergeViteConfig(buildViteConfigRaw, {
             // Vite picks the `.env` file from `mode`, not from NODE_ENV — this said
@@ -261,10 +260,11 @@ export async function build(ctx) {
         await writeFile('__sandbox.html', sandboxHtml, ctx);
         await writeFile('poveste.json', JSON.stringify(getSerializedStoryData(ctx), null, 2), ctx);
         const duration = performance.now() - startTime;
-        if (emptyStoryCount) {
-            console.warn(pc.yellow(`⚠️  ${emptyStoryCount} empty story file${emptyStoryCount === 1 ? '' : 's'}`));
+        if (empty.length) {
+            console.warn(pc.yellow(`⚠️  ${empty.length} empty story file${empty.length === 1 ? '' : 's'}: ${empty.join(', ')}`));
         }
-        console.log(pc.green(`✅ Built ${storyCount} stor${storyCount === 1 ? 'y' : 'ies'} (${variantCount} variant${variantCount === 1 ? '' : 's'}) in ${Math.round(duration / 1000 * 100) / 100}s`));
+        const docsNote = docsCount ? ` and ${docsCount} document${docsCount === 1 ? '' : 's'}` : '';
+        console.log(pc.green(`✅ Built ${storyCount} stor${storyCount === 1 ? 'y' : 'ies'} (${variantCount} variant${variantCount === 1 ? '' : 's'})${docsNote} in ${Math.round(duration / 1000 * 100) / 100}s`));
         // Render
         if (previewStoryCallbacks.length) {
             const { baseUrl, close } = await startPreview({}, ctx);

package/dist/node/collect/index.js

@@ -1,6 +1,7 @@
 import { cpus } from 'node:os';
 import { MessageChannel } from 'node:worker_threads';
 import Tinypool from '@akryum/tinypool';
+import { escapeRegExp } from '@poveste/shared';
 import { createBirpc } from 'birpc';
 import path, { relative } from 'pathe';
 import pc from 'picocolors';
@@ -29,7 +30,7 @@ export function useCollectStories(options, ctx) {
                 // @TODO temporary fix for https://github.com/histoire-dev/histoire/issues/409
                 /vite\w*\/dist\/client\/(client|env).mjs/,
                 ...ctx.config.viteNodeInlineDeps ?? [],
-                new RegExp(path.resolve(TEMP_PATH, 'plugins')),
+                new RegExp(escapeRegExp(path.resolve(TEMP_PATH, 'plugins'))),
             ],
             fallbackCJS: true,
         },

package/dist/node/virtual/codegen.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Emitting values into generated modules.
+ *
+ * Every generator in this directory builds JavaScript source by interpolation,
+ * and most of the values come from somewhere the author of that source did not
+ * control — a plugin's id, a user's config key, the project's own path. Getting
+ * it wrong produces a syntax error inside a module nobody wrote and nobody can
+ * open, which is the symptom rather than a crash at the input (#609).
+ *
+ * There are two positions and they need different things.
+ */
+/** A value in a string or key position. Valid JSON is valid JavaScript here. */
+export declare function jsString(value: string): string;
+/**
+ * A value in an *identifier* position — a binding name, an import name.
+ *
+ * Quoting cannot help here, so the only honest options are to reject the value
+ * or to rename it. These names are read back by consumers (`logos.square`,
+ * `generatedSetup.setupVue3`), so renaming would move the problem to whoever
+ * looks them up. It rejects, naming the value and where it came from.
+ */
+export declare function jsIdentifier(value: string, what: string): string;

package/dist/node/virtual/codegen.js

@@ -0,0 +1,30 @@
+/**
+ * Emitting values into generated modules.
+ *
+ * Every generator in this directory builds JavaScript source by interpolation,
+ * and most of the values come from somewhere the author of that source did not
+ * control — a plugin's id, a user's config key, the project's own path. Getting
+ * it wrong produces a syntax error inside a module nobody wrote and nobody can
+ * open, which is the symptom rather than a crash at the input (#609).
+ *
+ * There are two positions and they need different things.
+ */
+/** A value in a string or key position. Valid JSON is valid JavaScript here. */
+export function jsString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * A value in an *identifier* position — a binding name, an import name.
+ *
+ * Quoting cannot help here, so the only honest options are to reject the value
+ * or to rename it. These names are read back by consumers (`logos.square`,
+ * `generatedSetup.setupVue3`), so renaming would move the problem to whoever
+ * looks them up. It rejects, naming the value and where it came from.
+ */
+export function jsIdentifier(value, what) {
+    if (!/^[A-Z_$][\w$]*$/i.test(value)) {
+        throw new Error(`${what} must be usable as a JavaScript identifier, and ${JSON.stringify(value)} is not. `
+            + 'It is emitted into a generated module as a binding name, where quoting cannot rescue it.');
+    }
+    return value;
+}

package/dist/node/virtual/resolved-commands.js

@@ -1,3 +1,4 @@
+import { jsIdentifier, jsString } from './codegen.js';
 const serializedFields = ['id', 'label', 'prompts', 'icon', 'searchText'];
 export function resolvedCommands(ctx) {
     const imports = [];
@@ -21,10 +22,10 @@ function getCommandFields(command, imports) {
     if (command.clientSetupFile) {
         const importedVar = `__setup${imports.length}__`;
         if (typeof command.clientSetupFile === 'string') {
-            imports.push(`import ${importedVar} from '${command.clientSetupFile}'`);
+            imports.push(`import ${importedVar} from ${jsString(command.clientSetupFile)}`);
         }
         else {
-            imports.push(`import { ${command.clientSetupFile.importName} as ${importedVar} } from '${command.clientSetupFile.file}'`);
+            imports.push(`import { ${jsIdentifier(command.clientSetupFile.importName, `clientSetupFile.importName '${command.clientSetupFile.importName}'`)} as ${importedVar} } from ${jsString(command.clientSetupFile.file)}`);
         }
         fields.push(`...${importedVar}`);
     }

package/dist/node/virtual/resolved-config.js

@@ -1,10 +1,11 @@
+import { jsIdentifier, jsString } from './codegen.js';
 export function resolvedConfig(ctx) {
     let js = `export const config = ${JSON.stringify(ctx.config)}\n`;
     if (ctx.config.theme?.logo) {
         for (const key in ctx.config.theme.logo) {
-            js += `import Logo_${key} from '${ctx.config.theme.logo[key]}'\n`;
+            js += `import Logo_${jsIdentifier(key, `theme.logo key '${key}'`)} from ${jsString(ctx.config.theme.logo[key])}\n`;
         }
     }
-    js += `export const logos = {${Object.keys(ctx.config.theme?.logo ?? {}).map(key => `${key}: Logo_${key}`).join(', ')}}\n`;
+    js += `export const logos = {${Object.keys(ctx.config.theme?.logo ?? {}).map(key => `${jsString(key)}: Logo_${key}`).join(', ')}}\n`;
     return js;
 }

package/dist/node/virtual/resolved-stories.js

@@ -1,4 +1,5 @@
 import { makeTree } from '../tree.js';
+import { jsString } from './codegen.js';
 export function resolvedStories(ctx) {
     const resolvedStories = ctx.storyFiles.filter(s => !!s.story);
     const files = resolvedStories.map((file, index) => {
@@ -23,7 +24,7 @@ ${resolvedStories.map((file, index) => {
         }
         return supportPlugin.importStoryComponent(file, index);
     }).filter(Boolean).join('\n')}
-export let files = [${files.map(file => `{${JSON.stringify(file).slice(1, -1)}, component: Comp${file.index}, source: () => import('virtual:story-source:${file.story.id}')}`).join(',\n')}]
+export let files = [${files.map(file => `{${JSON.stringify(file).slice(1, -1)}, component: Comp${file.index}, source: () => import(${jsString(`virtual:story-source:${file.story.id}`)})}`).join(',\n')}]
 export let tree = ${JSON.stringify(makeTree(ctx.config, resolvedStories))}
 const handlers = []
 export function onUpdate (cb) {

package/dist/node/virtual/resolved-support-plugins-client.js

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
+import { jsString } from './codegen.js';
 import { PLUGINS_HAVE_DEV } from './util.js';
 const require = createRequire(import.meta.url);
 export function resolvedSupportPluginsClient(ctx) {
-    const plugins = ctx.supportPlugins.map(p => `'${p.id}': () => import(${JSON.stringify(require.resolve(`${p.moduleName}/client${process.env.POVESTE_DEV && PLUGINS_HAVE_DEV.includes(p.moduleName) ? '-dev' : ''}`, {
+    const plugins = ctx.supportPlugins.map(p => `${jsString(p.id)}: () => import(${JSON.stringify(require.resolve(`${p.moduleName}/client${process.env.POVESTE_DEV && PLUGINS_HAVE_DEV.includes(p.moduleName) ? '-dev' : ''}`, {
         paths: [ctx.root, import.meta.url],
     }))})`);
     return `export const clientSupportPlugins = {

package/dist/node/virtual/resolved-support-plugins-collect.js

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
+import { jsString } from './codegen.js';
 import { PLUGINS_HAVE_DEV } from './util.js';
 const require = createRequire(import.meta.url);
 export function resolvedSupportPluginsCollect(ctx) {
-    const plugins = ctx.supportPlugins.map(p => `'${p.id}': () => import(${JSON.stringify(require.resolve(`${p.moduleName}/collect${process.env.POVESTE_DEV && PLUGINS_HAVE_DEV.includes(p.moduleName) ? '-dev' : ''}`, {
+    const plugins = ctx.supportPlugins.map(p => `${jsString(p.id)}: () => import(${JSON.stringify(require.resolve(`${p.moduleName}/collect${process.env.POVESTE_DEV && PLUGINS_HAVE_DEV.includes(p.moduleName) ? '-dev' : ''}`, {
         paths: [ctx.root, import.meta.url],
     }))})`);
     return `export const collectSupportPlugins = {

package/dist/node/virtual/util.js

@@ -1,3 +1,4 @@
+import { jsIdentifier } from './codegen.js';
 export const ID_SEPARATOR = '__-__';
 /**
  * Names of every setup hook contributed by the enabled support plugins, e.g.
@@ -28,7 +29,7 @@ export function getSetupFnGroups(ctx) {
  * in every consumer build.
  */
 export function declareEmptySetupFns(ctx) {
-    return getSetupFnNames(ctx).map(fnName => `export const ${fnName} = undefined`).join('\n');
+    return getSetupFnNames(ctx).map(fnName => `export const ${jsIdentifier(fnName, `support plugin setupFn '${fnName}'`)} = undefined`).join('\n');
 }
 export const PLUGINS_HAVE_DEV = [
     '@poveste/plugin-vue',

package/dist/node/vite.js

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { escapeRegExp } from '@poveste/shared';
 import { lookup as lookupMime } from 'mrmime';
 import { dirname, join, relative } from 'pathe';
 import { loadConfigFromFile as loadViteConfigFromFile, mergeConfig as mergeViteConfig, searchForWorkspaceRoot, } from 'vite';
@@ -299,7 +300,7 @@ export async function getViteConfigWithPlugins(isServer, ctx) {
             if (/\.(?:vue|js)(?:$|\?)/.test(id)) {
                 const original = code;
                 for (const flag in flags) {
-                    code = code.replace(new RegExp(flag, 'g'), flags[flag]);
+                    code = code.replace(new RegExp(escapeRegExp(flag), 'g'), flags[flag]);
                 }
                 if (original !== code)
                     return code;
@@ -360,11 +361,11 @@ export async function getViteConfigWithPlugins(isServer, ctx) {
                                 ['vue', 'vue'],
                             ].reduce((acc, [name, entry]) => {
                                 acc.push({
-                                    find: new RegExp(`^${name.replace(/\//g, '\\/')}$`),
+                                    find: new RegExp(`^${escapeRegExp(name)}$`),
                                     replacement: `@poveste/vendors/${entry}`,
                                 });
                                 acc.push({
-                                    find: new RegExp(`^${name.replace(/\//g, '\\/')}\\/`),
+                                    find: new RegExp(`^${escapeRegExp(name)}/`),
                                     replacement: `@poveste/vendors/${entry}/`,
                                 });
                                 return acc;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poveste",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Interactive component playgrounds for Vue, Nuxt, Svelte, SvelteKit and Quasar — a drop-in fork of histoire, with Quasar support histoire does not ship.",
   "author": {
     "name": "Sorin Gitlan",
@@ -73,10 +73,10 @@
   },
   "dependencies": {
     "@akryum/tinypool": "^0.3.1",
-    "@poveste/app": "^0.13.0",
-    "@poveste/controls": "^0.13.0",
-    "@poveste/shared": "^0.13.0",
-    "@poveste/vendors": "^0.13.0",
+    "@poveste/app": "^0.14.0",
+    "@poveste/controls": "^0.14.0",
+    "@poveste/shared": "^0.14.0",
+    "@poveste/vendors": "^0.14.0",
     "@types/markdown-it": "^14.1.2",
     "birpc": "^0.2.19",
     "change-case": "^5.4.4",
@@ -109,7 +109,7 @@
     "@types/node": "^22.10.1",
     "typescript": "5.6.3",
     "vite": "^8.2.0",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "rimraf dist && tsc",

package/plugin.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Sends a custom event from the book UI to the plugin's `onDevEvent` hook, and
+ * resolves with whatever that hook returns.
+ *
+ * Development only: the API it calls is installed by the dev server, so in a
+ * built book this resolves to `undefined` without erroring.
+ */
 export function sendEvent(event: string, payload?: any): Promise<any>
 
+/**
+ * Navigates the book to a story by its `id` — the same field `getStories()`
+ * returns on the plugin API. Development only, and a no-op in a built book.
+ */
 export function openStory(storyId: string): void

package/plugin.js

@@ -2,6 +2,11 @@ export function sendEvent(event, payload) {
   if (window.__HST_PLUGIN_API__) {
     return window.__HST_PLUGIN_API__.sendEvent(event, payload)
   }
+  // The dev server installs that API and a built book has no plugin host, so
+  // this is the ordinary path there. Resolve rather than fall off the end: the
+  // signature promises a `Promise`, and returning `undefined` meant
+  // `sendEvent(...).then(...)` threw in a built book while `await` was fine.
+  return Promise.resolve(undefined)
 }
 
 export function openStory(storyId) {

package/dist/node/builtin-plugins/pinceau-tokens-style.d.ts

@@ -1 +0,0 @@
-export declare const css = ".__pvt-shade {\n  height: 80px;\n  border-radius: 4px;\n}\n\n.__pvt-text {\n  font-size: 4rem;\n  display: flex;\n  align-items: flex-end;\n}\n\n.__pvt-border {\n  border-style: solid;\n  border-width: 2px;\n}\n\n.__pvt-spaces {\n  background-color: rgb(113 113 122 / 0.1);\n  width: min-content;\n}\n\n.__pvt-margin {\n  border: dashed 1px rgb(113 113 122 / 0.5);\n  width: min-content;\n}\n\n.__pvt-spaces-box,\n.__pvt-margin-box {\n  width: 5rem;\n  height: 5rem;\n  background-color: rgb(113 113 122 / 0.5);\n}\n\n.__pvt-spaces,\n.__pvt-spaces-box,\n.__pvt-margin,\n.__pvt-margin-box,\n.__pvt-drop-shadow {\n  border-radius: 4px;\n}\n\n.__pvt-truncate {\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n\n.__pvt-drop-shadow {\n  width: 8rem;\n  height: 8rem;\n  background: white;\n  margin-bottom: 0.5rem;\n}\n\n.__pvt-drop-shadow {\n  background: #4e4e57;\n}\n\n.__pvt-border-radius {\n  width: 8rem;\n  height: 8rem;\n  background-color: rgb(113 113 122 / 0.5);\n}\n\n.__pvt-border-width {\n  width: 8rem;\n  height: 8rem;\n  border-color: rgb(113 113 122 / 0.5);\n  background-color: rgb(113 113 122 / 0.1);\n}\n\n.__pvt-width {\n  background-color: rgb(113 113 122 / 0.1);\n}\n\n.__pvt-width-box,\n.__pvt-height {\n  background-color: rgb(113 113 122 / 0.5);\n}\n\n.__pvt-width-box {\n  height: 5rem;\n}";

package/dist/node/builtin-plugins/pinceau-tokens-style.js

@@ -1,85 +0,0 @@
-// Injected as `style.css` next to the generated story file, so it styles
-// the Pinceau token stories without reaching the book's own stylesheet.
-export const css = `.__pvt-shade {
-  height: 80px;
-  border-radius: 4px;
-}
-
-.__pvt-text {
-  font-size: 4rem;
-  display: flex;
-  align-items: flex-end;
-}
-
-.__pvt-border {
-  border-style: solid;
-  border-width: 2px;
-}
-
-.__pvt-spaces {
-  background-color: rgb(113 113 122 / 0.1);
-  width: min-content;
-}
-
-.__pvt-margin {
-  border: dashed 1px rgb(113 113 122 / 0.5);
-  width: min-content;
-}
-
-.__pvt-spaces-box,
-.__pvt-margin-box {
-  width: 5rem;
-  height: 5rem;
-  background-color: rgb(113 113 122 / 0.5);
-}
-
-.__pvt-spaces,
-.__pvt-spaces-box,
-.__pvt-margin,
-.__pvt-margin-box,
-.__pvt-drop-shadow {
-  border-radius: 4px;
-}
-
-.__pvt-truncate {
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.__pvt-drop-shadow {
-  width: 8rem;
-  height: 8rem;
-  background: white;
-  margin-bottom: 0.5rem;
-}
-
-.__pvt-drop-shadow {
-  background: #4e4e57;
-}
-
-.__pvt-border-radius {
-  width: 8rem;
-  height: 8rem;
-  background-color: rgb(113 113 122 / 0.5);
-}
-
-.__pvt-border-width {
-  width: 8rem;
-  height: 8rem;
-  border-color: rgb(113 113 122 / 0.5);
-  background-color: rgb(113 113 122 / 0.1);
-}
-
-.__pvt-width {
-  background-color: rgb(113 113 122 / 0.1);
-}
-
-.__pvt-width-box,
-.__pvt-height {
-  background-color: rgb(113 113 122 / 0.5);
-}
-
-.__pvt-width-box {
-  height: 5rem;
-}`;

package/dist/node/builtin-plugins/pinceau-tokens.d.ts

@@ -1,6 +0,0 @@
-import type { Plugin } from '@poveste/shared';
-export interface PinceauTokensOptions {
-    configOrPaths?: string | string[];
-    configFileName?: string;
-}
-export declare function pinceauTokens(_options?: PinceauTokensOptions): Plugin;

package/dist/node/builtin-plugins/pinceau-tokens.js

@@ -1,424 +0,0 @@
-import { join } from 'pathe';
-import { getInjectedImport } from '../util/vendors.js';
-import { css } from './pinceau-tokens-style.js';
-export function pinceauTokens(_options = {}) {
-    const themePath = join(process.cwd(), 'node_modules/.vite/pinceau/index.js');
-    async function generate(api) {
-        try {
-            await api.fs.ensureDir(api.pluginTempDir);
-            await api.fs.emptyDir(api.pluginTempDir);
-            api.moduleLoader.clearCache();
-            await api.fs.writeFile(api.path.resolve(api.pluginTempDir, 'style.css'), css);
-            const theme = await api.moduleLoader.loadModule(themePath);
-            const storyFile = api.path.resolve(api.pluginTempDir, 'Pinceau.story.js');
-            await api.fs.writeFile(storyFile, storyTemplate(theme));
-            api.addStoryFile(storyFile);
-        }
-        catch (e) {
-            api.error(e.stack ?? e.message);
-        }
-    }
-    return {
-        name: 'builtin:pinceau-tokens',
-        config(config) {
-            // Add 'design-system' group
-            if (!config.tree) {
-                config.tree = {};
-            }
-            if (!config.tree.groups) {
-                config.tree.groups = [];
-            }
-            if (!config.tree.groups.some(g => g.id === 'design-system')) {
-                let index = 0;
-                // After 'top' group
-                const topIndex = config.tree.groups.findIndex(g => g.id === 'top');
-                if (topIndex > -1) {
-                    index = topIndex + 1;
-                }
-                // Insert group
-                config.tree.groups.splice(index, 0, {
-                    id: 'design-system',
-                    title: 'Design System',
-                });
-            }
-        },
-        async onDev(api, onCleanup) {
-            await generate(api);
-            const watcher = api.watcher.watch(themePath)
-                .on('change', () => generate(api))
-                .on('add', () => generate(api));
-            onCleanup(() => {
-                watcher.close();
-            });
-        },
-        async onBuild(api) {
-            await generate(api);
-        },
-    };
-}
-function storyTemplate(pinceauConfig) {
-    pinceauConfig = pinceauConfig?.theme || pinceauConfig?.default?.theme || {};
-    // No `import 'poveste-style'` — see the tailwind plugin's template (#219).
-    return `import './style.css'
-import { createApp, h, markRaw, ref } from ${getInjectedImport('@poveste/vendors/vue')}
-import {
-  HstColorShades,
-  HstTokenList,
-  HstTokenGrid,
-  HstText,
-  HstTextarea,
-  HstNumber,
-} from ${getInjectedImport('@poveste/controls')}
-
-const config = markRaw(${JSON.stringify(pinceauConfig, null, 2)})
-const search = ref('')
-const sampleText = ref('Cat sit like bread eat prawns daintily with a claw then lick paws clean wash down prawns with a lap of carnation milk then retire to the warmest spot on the couch to claw at the fabric before taking a catnap mrow cat cat moo moo lick ears lick paws')
-const fontSize = ref(16)
-const flattenTokens = (data, transformValue = (value) => (value?.value || value)) => {
-  const output = {}
-  function step(obj, prev) {
-    Object.keys(obj).forEach((key) => {
-      const value = obj[key]
-      const isarray = Array.isArray(value)
-      const type = Object.prototype.toString.call(value)
-      const isobject
-        = type === '[object Object]'
-        || type === '[object Array]'
-
-      const newKey = prev ? prev + '.' + key : key
-
-      if (value.value && !output[newKey]) {
-        output[newKey] = transformValue(value)
-      }
-
-      if (!isarray && isobject && Object.keys(value).length) { return step(value, newKey) }
-    })
-  }
-  step(data)
-  return output
-}
-
-function mountApp ({ el, state, onUnmount }, render) {
-  Object.assign(state, {
-    search,
-    sampleText,
-    fontSize,
-  })
-
-  const app = createApp({
-    render,
-  })
-  app.mount(el)
-
-  onUnmount(() => {
-    app.unmount()
-  })
-}
-
-/*
-  media?: PinceauTokens
-  colors?: ScaleTokens
-  fonts?: PinceauTokens
-  fontWeights?: FontWeightTokens
-  fontSizes?: BreakpointsTokens
-  size?: BreakpointsTokens
-  space?: BreakpointsTokens
-  radii?: BreakpointsTokens
-  borders?: BreakpointsTokens
-  borderWidths?: BreakpointsTokens
-  borderStyles?: BreakpointsTokens
-  shadows?: BreakpointsTokens
-  opacity?: BreakpointsTokens
-  leads?: BreakpointsTokens
-  letterSpacings?: BreakpointsTokens
-  transitions?: PinceauTokens
-  zIndices?: PinceauTokens
-*/
-
-export default {
-  id: 'pinceau',
-  title: 'Pinceau',
-  group: 'design-system',
-  icon: 'noto:paintbrush',
-  responsiveDisabled: true,
-  layout: { type: 'single', iframe: false },
-  variants: [
-    {
-      id: 'media-queries',
-      title: 'Media Queries',
-      icon: 'carbon:screen',
-      onMount: (api) => mountApp(api, () => h(HstTokenGrid, {
-        tokens: flattenTokens(config.media),
-        getName: key => '@mq.' + key,
-        colSize: 180,
-      }, ({ token }) => h('div', {
-        class: '__pvt-drop-shadow',
-      }))),
-    },
-    {
-      id: 'colors',
-      title: 'Colors',
-      icon: 'carbon:color-palette',
-      onMount: (api) => mountApp(api, () => Object.entries(config.colors).map(([key, shades]) => h(HstColorShades, {
-        key,
-        shades: shades.value ? { DEFAULT: shades.value } : flattenTokens(shades),
-        getName: shade => '{colors.' + key + '.' + shade + '}',
-        search: search.value,
-      }, ({ color}) => h('div', {
-        class: '__pvt-shade',
-        style: {
-          backgroundColor: color,
-        },
-      })))),
-      onMountControls: (api) => mountApp(api, () => [
-        h(HstText, {
-          title: 'Filter...',
-          modelValue: search.value,
-          'onUpdate:modelValue': value => { search.value = value },
-        }),
-      ]),
-    },
-    // SPACES
-    {
-      id: 'Spaces',
-      title: 'Spaces',
-      icon: 'carbon:area',
-      onMount: (api) => mountApp(api, () => h(HstTokenList, {
-        tokens: flattenTokens(config.space),
-        getName: key => '{space.' + key + '}',
-      }, ({ token }) => h('div', {
-        class: '__pvt-spaces',
-        style: {
-          padding: token.value,
-        },
-      }, [
-        h('div', {
-          class: '__pvt-spaces-box',
-        }),
-      ]))),
-    },
-    // SIZES
-    {
-      id: 'sizes',
-      title: 'Sizes',
-      icon: 'carbon:pan-horizontal',
-      onMount: (api) => mountApp(api, () => h(HstTokenList, {
-        tokens: flattenTokens(config.size),
-        getName: key => '{size.' + key + '}',
-      }, ({ token }) => h('div', {
-        class: '__pvt-width',
-      }, [
-        h('div', {
-          class: '__pvt-width-box',
-          style: {
-            width: token.value,
-          },
-        }),
-      ]))),
-    },
-    // FONTSIZES
-    {
-      id: 'font-size',
-      title: 'Font Size',
-      icon: 'carbon:text-font',
-      onMount: (api) => mountApp(api, () => h(HstTokenList, {
-        tokens: flattenTokens(config.fontSizes),
-        getName: key => '{fontSizes.' + key + '}',
-      }, ({ token }) => h('div', {
-        class: '__pvt-truncate',
-        style: {
-          fontSize: token.value,
-        },
-      }, sampleText.value))),
-      onMountControls: (api) => mountApp(api, () => [
-        h(HstTextarea, {
-          title: 'Sample text',
-          modelValue: sampleText.value,
-          'onUpdate:modelValue': value => { sampleText.value = value },
-          rows: 5,
-        }),
-      ]),
-    },
-    // FONTWEIGHTS
-    {
-      id: 'font-weight',
-      title: 'Font Weight',
-      icon: 'carbon:text-font',
-      onMount: (api) => mountApp(api, () => h(HstTokenList, {
-        tokens: flattenTokens(config.fontWeights),
-        getName: key => '{fontWeights.' + key + '}',
-      }, ({ token }) => h('div', {
-        class: '__pvt-truncate',
-        style: {
-          fontWeight: token.value,
-          fontSize: \`\${fontSize.value}px\`,
-        },
-      }, sampleText.value))),
-      onMountControls: (api) => mountApp(api, () => [
-        h(HstTextarea, {
-          title: 'Sample text',
-          modelValue: sampleText.value,
-          'onUpdate:modelValue': value => { sampleText.value = value },
-          rows: 5,
-        }),
-        h(HstNumber, {
-          title: 'Font size',
-          modelValue: fontSize.value,
-          'onUpdate:modelValue': value => { fontSize.value = value },
-          min: 1,
-        }),
-      ]),
-    },
-    // FONTS
-    {
-      id: 'fonts',
-      title: 'Fonts',
-      icon: 'carbon:text-font',
-      onMount: (api) => mountApp(api, () => h(HstTokenList, {
-        tokens: flattenTokens(config.fonts),
-        getName: key => '{fonts.' + key + '}',
-      }, ({ token }) => h('div', {
-        class: '__pvt-truncate',
-        style: {
-          fontFamily: token.value,
-          fontSize: \`\${fontSize.value}px\`,
-        },
-      }, sampleText.value))),
-      onMountControls: (api) => mountApp(api, () => [
-        h(HstTextarea, {
-          title: 'Sample text',
-          modelValue: sampleText.value,
-          'onUpdate:modelValue': value => { sampleText.value = value },
-          rows: 5,
-        }),
-        h(HstNumber, {
-          title: 'Font size',
-          modelValue: fontSize.value,
-          'onUpdate:modelValue': value => { fontSize.value = value },
-          min: 1,
-        }),
-      ]),
-    },
-    // LETTERSPACINGS
-    {
-      id: 'letter-spacing',
-      title: 'Letter Spacing',
-      icon: 'carbon:text-font',
-      onMount: (api) => mountApp(api, () => h(HstTokenList, {
-        tokens: flattenTokens(config.letterSpacings),
-        getName: key => '{letterSpacings.' + key + '}',
-      }, ({ token }) => h('div', {
-        class: '__pvt-truncate',
-        style: {
-          letterSpacing: token.value,
-          fontSize: \`\${fontSize.value}px\`,
-        },
-      }, sampleText.value))),
-      onMountControls: (api) => mountApp(api, () => [
-        h(HstTextarea, {
-          title: 'Sample text',
-          modelValue: sampleText.value,
-          'onUpdate:modelValue': value => { sampleText.value = value },
-          rows: 5,
-        }),
-        h(HstNumber, {
-          title: 'Font size',
-          modelValue: fontSize.value,
-          'onUpdate:modelValue': value => { fontSize.value = value },
-          min: 1,
-        }),
-      ]),
-    },
-    // LEADS
-    {
-      id: 'leads',
-      title: 'Leads',
-      icon: 'carbon:text-font',
-      onMount: (api) => mountApp(api, () => h(HstTokenList, {
-        tokens: flattenTokens(config.leads),
-        getName: key => '{leads.' + key + '}',
-      }, ({ token }) => h('div', {
-        style: {
-          lineHeight: token.value,
-        },
-      }, sampleText.value))),
-      onMountControls: (api) => mountApp(api, () => [
-        h(HstTextarea, {
-          title: 'Sample text',
-          modelValue: sampleText.value,
-          'onUpdate:modelValue': value => { sampleText.value = value },
-          rows: 5,
-        }),
-        // @TODO select font size
-      ]),
-    },
-    // SHADOWS
-    {
-      id: 'shadows',
-      title: 'Shadows',
-      icon: 'carbon:shape-except',
-      onMount: (api) => mountApp(api, () => h(HstTokenGrid, {
-        tokens: flattenTokens(config.shadows),
-        getName: key => '{shadows.' + key + '}',
-        colSize: 180,
-      }, ({ token }) => h('div', {
-        class: '__pvt-drop-shadow',
-        style: 'box-shadow:' + token.value,
-      }))),
-    },
-    // OPACITIES
-    {
-      id: 'opacities',
-      title: 'Opacities',
-      icon: 'carbon:bring-forward',
-      onMount: (api) => mountApp(api, () => h(HstTokenGrid, {
-        tokens: flattenTokens(config.opacity),
-        getName: key => '{opacity.' + key + '}',
-        colSize: 180,
-      }, ({ token }) => h('div', {
-        class: '__pvt-drop-shadow',
-        style: 'opacity:' + token.value,
-      }))),
-    },
-    // RADII
-    {
-      id: 'border-radius',
-      title: 'Border Radius',
-      icon: 'carbon:condition-wait-point',
-      onMount: (api) => mountApp(api, () => h(HstTokenGrid, {
-        tokens: flattenTokens(config.radii),
-        getName: key => '{radii.' + key + '}',
-        colSize: 180,
-      }, ({ token }) => h('div', {
-        class: '__pvt-border-radius',
-        style: {
-          borderRadius: token.value,
-        },
-      }))),
-    },
-    // BORDERWIDTHS
-    {
-      id: 'border-width',
-      title: 'Border Width',
-      icon: 'carbon:checkbox',
-      onMount: (api) => mountApp(api, () => h(HstTokenGrid, {
-        tokens: flattenTokens(config.borderWidths),
-        getName: key => '{borderWidths.' + key + '}',
-        colSize: 180,
-      }, ({ token }) => h('div', {
-        class: '__pvt-border-width',
-        style: {
-          borderWidth: token.value,
-        },
-      }))),
-    },
-    // FULL CONFIG
-    {
-      id: 'full-config',
-      title: 'Full Config',
-      icon: 'carbon:code',
-      onMount: (api) => mountApp(api, () => h('pre', JSON.stringify(config, null, 2))),
-    },
-  ],
-}`;
-}