poveste 0.16.1 → 0.17.0

package/README.md

@@ -47,7 +47,7 @@ Run `npx poveste --help` for the full list of options.
 
 ## Requirements
 
-Node `>=22.22.2` and Vite `^8.0.0`. See
+Node `>=24.15.0` and Vite `^8.0.0`. See
 [supported versions](https://poveste.dev/guide/getting-started#supported-versions) for
 what proves each range.
 

package/dist/node/collect/error.d.ts

@@ -1,2 +1,9 @@
-export declare function serializeError(error: unknown, seen?: WeakSet<Error>): unknown;
+/** What this module needs of a thrown value to be able to describe it. */
+interface ErrorLike {
+    name: string;
+    message: string;
+    stack?: string | undefined;
+}
+export declare function serializeError(error: unknown, seen?: WeakSet<ErrorLike>): unknown;
 export declare function deserializeError(value: unknown): unknown;
+export {};

package/dist/node/collect/error.js

@@ -7,6 +7,27 @@ const MARK = 'pvt:error';
 function isSerialized(value) {
     return typeof value === 'object' && value !== null && value.kind === MARK;
 }
+/*
+ * Not `instanceof Error`, and not `Error.isError` either. A `DOMException` from
+ * jsdom fails both — the first because `runScripts: 'dangerously'` makes jsdom a
+ * separate realm, the second because jsdom's is a webidl2js object rather than a
+ * genuine error — while carrying a name, a message and a stack. It is what a
+ * story's own DOM call throws, and a clone of one retains nothing, so the host
+ * received `{}` (#1097).
+ *
+ * A `stack` is required and not merely read: `{ name, message }` is a shape a
+ * story may legitimately throw, and it should arrive as the data it is.
+ */
+function errorLike(value) {
+    if (Error.isError(value)) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const { name, message, stack } = value;
+    return typeof name === 'string' && typeof message === 'string' && typeof stack === 'string';
+}
 // A property the clone rejects takes the whole message down with it, which is worse
 // than dropping the property.
 function cloneable(value) {
@@ -25,7 +46,7 @@ function cloneable(value) {
  * the error it was called to describe and replace it with its own.
  */
 export function serializeError(error, seen = new WeakSet()) {
-    if (!(error instanceof Error)) {
+    if (!errorLike(error)) {
         return cloneable(error) ? error : String(error);
     }
     if (seen.has(error)) {

package/dist/node/collect/index.js

@@ -1,5 +1,4 @@
 import { cpus } from 'node:os';
-import { escapeRegExp } from '@poveste/shared';
 import path, { relative } from 'pathe';
 import pc from 'picocolors';
 import { TEMP_PATH } from '../alias.js';
@@ -25,7 +24,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(escapeRegExp(path.resolve(TEMP_PATH, 'plugins'))),
+            new RegExp(RegExp.escape(path.resolve(TEMP_PATH, 'plugins'))),
         ],
         transformMode: ctx.config.viteNodeTransformMode,
     });

package/dist/node/dom/env.js

@@ -23,7 +23,10 @@ function createVirtualConsole() {
         if (type === JSDOM_ERROR_CSS_PARSING)
             return;
         if (type === JSDOM_ERROR_UNHANDLED_EXCEPTION) {
-            globalThis.console.error((err.cause instanceof Error ? err.cause.stack : undefined) ?? err.message);
+            // `Error.isError` and not `instanceof`: the cause was constructed inside
+            // jsdom's realm, where `instanceof Error` is false and the stack — the
+            // only part that says which line threw — is discarded (#1093).
+            globalThis.console.error((Error.isError(err.cause) ? err.cause.stack : undefined) ?? err.message);
         }
         else {
             globalThis.console.error(err.message);

package/dist/node/vendors.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Resolves `specifier` as Node would from `from`, to a real path, or `undefined`
+ * when nothing answers.
+ */
+export type Resolver = (specifier: string, from: string) => string | undefined;
+export declare const nodeResolver: Resolver;
+export interface VendoredAlias {
+    /** The bare package the alias points at, `vue`. */
+    name: string;
+    /** The range it is pinned to, `^3.5.26`, or `''` when the spec carries none. */
+    range: string;
+}
+/**
+ * What each vendored dependency aliases, by the name it is installed under:
+ * `{ 'poveste-vue': { name: 'vue', range: '^3.5.26' } }` from
+ * `"poveste-vue": "npm:vue@^3.5.26"`.
+ *
+ * Derived from the manifest rather than listed, because the set is whatever
+ * `@poveste/vendors` declares and a list here would keep working while silently
+ * covering one name fewer. The range comes back with the name because the caller
+ * needs both and this is the only place the spec is parsed.
+ */
+export declare function vendoredAliases(dependencies: Record<string, string> | undefined): Record<string, VendoredAlias>;
+/**
+ * Whether `version` satisfies a caret range, for the caret ranges `@poveste/vendors`
+ * actually declares and **nothing else**.
+ *
+ * A range this cannot read with certainty is refused rather than approximated. That
+ * is the point: `poveste` has no `semver` dependency, a patch release is the wrong
+ * place to add one, and a hand-rolled `satisfies` that silently mis-handles a form it
+ * was never given is the failure this repo keeps producing. So `^X.Y.Z` with a major
+ * of at least 1 is answered, and `^0.x`, a prerelease, a comparator set or anything
+ * else returns false and leaves the chrome on the copy it can certainly run.
+ */
+export declare function satisfiesCaret(version: string | undefined, range: string | undefined): boolean;
+/**
+ * Points the chrome's Vue at the project's, when they are two copies.
+ *
+ * `@poveste/vendors` depends on `poveste-vue`, an npm alias of `vue`. An alias is
+ * a **distinct package name**, so a package manager installs a second physical copy
+ * whatever the project already has — the project's Vue satisfying the aliased range
+ * does not collapse them, and `resolve.dedupe` cannot, because it matches on name.
+ *
+ * Two copies is two reactivity systems. The chrome's components render with the
+ * vendored one while `RouterView` — reached through `poveste-vue-router`, whose own
+ * `vue` import is bare — reacts with the project's, so `RouterView`'s first render
+ * is never invalidated and a Vue consumer's `poveste dev` showed a sidebar, a
+ * breadcrumb and no story at all. Nothing warns: neither copy is wrong, they simply
+ * cannot see each other (#1060).
+ *
+ * Only Vue. The reactivity identity is what breaks, and `@poveste/plugin-vue`
+ * declaring `vue` as a peer is what licenses pointing the chrome at the project's
+ * copy — no peer range licenses the same for pinia, vue-router, VueUse or Iconify,
+ * and making the chrome's pinned copies authoritative for a project's own story code
+ * is a larger change than this defect asks for.
+ *
+ * Empty when the project has no Vue of its own, when the two already resolve to one
+ * file, or when the project's Vue does not satisfy the range vendors pins — in each
+ * case the vendored copy is what the chrome should keep. Refusing on anything it
+ * cannot read with certainty is deliberate: the failure of this function is a chrome
+ * that keeps a Vue it can certainly run, and the failure of guessing is a chrome
+ * handed one it cannot.
+ *
+ * The range is checked rather than assumed from the peer floor. A project only holds
+ * a Vue of its own because a framework plugin's peer range put it there — except that
+ * `--legacy-peer-deps` is exactly how a project ends up holding one the peer range
+ * would have refused (#1062), which leaves a reader on, say, Vue 3.2 with a chrome
+ * collapsed onto a Vue that cannot run it. Such a project is already broken without
+ * this fix, but "already broken" is not a reason to hand it a different break.
+ */
+export declare function collapseVendoredVue(options: {
+    root: string;
+    resolve?: Resolver;
+}): Record<string, string>;

package/dist/node/vendors.js

@@ -0,0 +1,157 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'pathe';
+export const nodeResolver = (specifier, from) => {
+    try {
+        // `createRequire` resolves relative to the *dirname* of what it is given, so a
+        // directory has to be named as a file inside it or every lookup starts one
+        // level too high.
+        return realpathSync(createRequire(join(from, 'noop.js')).resolve(specifier));
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * What each vendored dependency aliases, by the name it is installed under:
+ * `{ 'poveste-vue': { name: 'vue', range: '^3.5.26' } }` from
+ * `"poveste-vue": "npm:vue@^3.5.26"`.
+ *
+ * Derived from the manifest rather than listed, because the set is whatever
+ * `@poveste/vendors` declares and a list here would keep working while silently
+ * covering one name fewer. The range comes back with the name because the caller
+ * needs both and this is the only place the spec is parsed.
+ */
+export function vendoredAliases(dependencies) {
+    const aliases = {};
+    for (const [installedAs, spec] of Object.entries(dependencies ?? {})) {
+        if (!spec.startsWith('npm:')) {
+            continue;
+        }
+        // Split on the last `@` rather than matching a name pattern: a scoped package
+        // opens with one, so the separator is positional and a regex that allows both
+        // is the kind the linter rejects for backtracking.
+        const target = spec.slice('npm:'.length);
+        const at = target.lastIndexOf('@');
+        aliases[installedAs] = at > 0
+            ? { name: target.slice(0, at), range: target.slice(at + 1) }
+            : { name: target, range: '' };
+    }
+    return aliases;
+}
+/**
+ * Whether `version` satisfies a caret range, for the caret ranges `@poveste/vendors`
+ * actually declares and **nothing else**.
+ *
+ * A range this cannot read with certainty is refused rather than approximated. That
+ * is the point: `poveste` has no `semver` dependency, a patch release is the wrong
+ * place to add one, and a hand-rolled `satisfies` that silently mis-handles a form it
+ * was never given is the failure this repo keeps producing. So `^X.Y.Z` with a major
+ * of at least 1 is answered, and `^0.x`, a prerelease, a comparator set or anything
+ * else returns false and leaves the chrome on the copy it can certainly run.
+ */
+export function satisfiesCaret(version, range) {
+    const wanted = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(range ?? '');
+    const have = /^(\d+)\.(\d+)\.(\d+)$/.exec(version ?? '');
+    if (!wanted || !have) {
+        return false;
+    }
+    const [wantedMajor, wantedMinor, wantedPatch] = wanted.slice(1).map(Number);
+    const [major, minor, patch] = have.slice(1).map(Number);
+    // `^0.x` narrows to the minor, and no vendored range uses it. Refuse rather than
+    // implement a rule nothing here exercises.
+    if (wantedMajor === 0 || wantedMajor === undefined || major === undefined) {
+        return false;
+    }
+    if (major !== wantedMajor) {
+        return false;
+    }
+    if (minor !== wantedMinor) {
+        return minor > wantedMinor;
+    }
+    return patch >= wantedPatch;
+}
+/**
+ * Points the chrome's Vue at the project's, when they are two copies.
+ *
+ * `@poveste/vendors` depends on `poveste-vue`, an npm alias of `vue`. An alias is
+ * a **distinct package name**, so a package manager installs a second physical copy
+ * whatever the project already has — the project's Vue satisfying the aliased range
+ * does not collapse them, and `resolve.dedupe` cannot, because it matches on name.
+ *
+ * Two copies is two reactivity systems. The chrome's components render with the
+ * vendored one while `RouterView` — reached through `poveste-vue-router`, whose own
+ * `vue` import is bare — reacts with the project's, so `RouterView`'s first render
+ * is never invalidated and a Vue consumer's `poveste dev` showed a sidebar, a
+ * breadcrumb and no story at all. Nothing warns: neither copy is wrong, they simply
+ * cannot see each other (#1060).
+ *
+ * Only Vue. The reactivity identity is what breaks, and `@poveste/plugin-vue`
+ * declaring `vue` as a peer is what licenses pointing the chrome at the project's
+ * copy — no peer range licenses the same for pinia, vue-router, VueUse or Iconify,
+ * and making the chrome's pinned copies authoritative for a project's own story code
+ * is a larger change than this defect asks for.
+ *
+ * Empty when the project has no Vue of its own, when the two already resolve to one
+ * file, or when the project's Vue does not satisfy the range vendors pins — in each
+ * case the vendored copy is what the chrome should keep. Refusing on anything it
+ * cannot read with certainty is deliberate: the failure of this function is a chrome
+ * that keeps a Vue it can certainly run, and the failure of guessing is a chrome
+ * handed one it cannot.
+ *
+ * The range is checked rather than assumed from the peer floor. A project only holds
+ * a Vue of its own because a framework plugin's peer range put it there — except that
+ * `--legacy-peer-deps` is exactly how a project ends up holding one the peer range
+ * would have refused (#1062), which leaves a reader on, say, Vue 3.2 with a chrome
+ * collapsed onto a Vue that cannot run it. Such a project is already broken without
+ * this fix, but "already broken" is not a reason to hand it a different break.
+ */
+export function collapseVendoredVue(options) {
+    const { root } = options;
+    const resolve = options.resolve ?? nodeResolver;
+    // From the vendors directory, not from the project: that is where the import
+    // happens, and an isolated `node_modules` layout makes `poveste-vue` invisible
+    // from the project root while the chrome resolves it perfectly well.
+    // Through an exported subpath: vendors' `exports` map does not list
+    // `./package.json`, so resolving that name directly fails.
+    const vendorsEntry = resolve('@poveste/vendors/vue', root);
+    const vendorsDir = vendorsEntry ? join(vendorsEntry, '..') : undefined;
+    if (!vendorsDir) {
+        return {};
+    }
+    const vueAlias = Object.entries(vendoredAliases(readJson(join(vendorsDir, 'package.json'))?.dependencies))
+        .find(([, alias]) => alias.name === 'vue');
+    if (!vueAlias) {
+        return {};
+    }
+    const [installedAs, { range }] = vueAlias;
+    const vendored = resolve(installedAs, vendorsDir);
+    const project = resolve('vue', root);
+    if (!vendored || !project || vendored === project) {
+        return {};
+    }
+    if (!satisfiesCaret(versionOf('vue/package.json', resolve, root), range)) {
+        return {};
+    }
+    // To the bare name, not to `project`. A resolved path is whatever the `require`
+    // condition answers — for Vue that is a CJS shim, and handing the chrome that
+    // replaced a split reactivity system with a browser app that does not boot at all.
+    // The name lets Vite resolve its own entry and condition, and `resolve.dedupe`
+    // above then genuinely covers the result.
+    return { [installedAs]: 'vue' };
+}
+function versionOf(specifier, resolve, root) {
+    const manifest = resolve(specifier, root);
+    if (!manifest) {
+        return undefined;
+    }
+    return readJson(manifest)?.version;
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/node/vite.js

@@ -1,6 +1,5 @@
 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';
@@ -11,6 +10,7 @@ import { notifyStoryChange } from './stories.js';
 import { chromeCssScopePlugin, globalStylesPlugin, userCssScopePlugin, } from './style-isolation/index.js';
 import { applyHeadTransform } from './util/head.js';
 import { viteCommand, viteMode } from './util/vite-mode.js';
+import { collapseVendoredVue } from './vendors.js';
 import { createVirtualFilesPlugin } from './virtual/vite-plugin.js';
 const require = createRequire(import.meta.url);
 export async function mergePovesteViteConfig(viteConfig, ctx) {
@@ -153,6 +153,14 @@ export async function getViteConfigWithPlugins(isServer, ctx) {
                     ],
                     alias: {
                         'poveste-style': join(APP_PATH, process.env['POVESTE_DEV'] ? 'app/style/main.pcss' : 'style.css'),
+                        // `dedupe` above cannot reach this one: the chrome's Vue is installed
+                        // under a different name, and dedupe matches on the name (#1060).
+                        //
+                        // Not under `POVESTE_DEV`. That path already aliases bare `vue` to
+                        // `@poveste/vendors/vue`, so sending `poveste-vue` back to `vue` would
+                        // point the vendored entry at itself — the empty re-export its own
+                        // comment warns about.
+                        ...(isServer || process.env['POVESTE_DEV'] ? {} : collapseVendoredVue({ root: ctx.root })),
                     },
                     ...(isServer
                         ? {
@@ -338,7 +346,7 @@ export async function getViteConfigWithPlugins(isServer, ctx) {
             if (/\.(?:vue|js)(?:$|\?)/.test(id)) {
                 const original = code;
                 for (const [flag, value] of Object.entries(flags)) {
-                    code = code.replace(new RegExp(escapeRegExp(flag), 'g'), value);
+                    code = code.replace(new RegExp(RegExp.escape(flag), 'g'), value);
                 }
                 if (original !== code)
                     return code;
@@ -398,11 +406,11 @@ export async function getViteConfigWithPlugins(isServer, ctx) {
                                 ['vue', 'vue'],
                             ].reduce((acc, [name, entry]) => {
                                 acc.push({
-                                    find: new RegExp(`^${escapeRegExp(name)}$`),
+                                    find: new RegExp(`^${RegExp.escape(name)}$`),
                                     replacement: `@poveste/vendors/${entry}`,
                                 });
                                 acc.push({
-                                    find: new RegExp(`^${escapeRegExp(name)}/`),
+                                    find: new RegExp(`^${RegExp.escape(name)}/`),
                                     replacement: `@poveste/vendors/${entry}/`,
                                 });
                                 return acc;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poveste",
   "type": "module",
-  "version": "0.16.1",
+  "version": "0.17.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",
@@ -67,17 +67,17 @@
     "plugin.js"
   ],
   "engines": {
-    "node": ">=22.22.2"
+    "node": ">=24.15.0"
   },
   "peerDependencies": {
     "vite": "^8.0.0"
   },
   "dependencies": {
     "@11ty/gray-matter": "^3.0.0",
-    "@poveste/app": "^0.16.1",
-    "@poveste/controls": "^0.16.1",
-    "@poveste/shared": "^0.16.1",
-    "@poveste/vendors": "^0.16.1",
+    "@poveste/app": "^0.17.0",
+    "@poveste/controls": "^0.17.0",
+    "@poveste/shared": "^0.17.0",
+    "@poveste/vendors": "^0.17.0",
     "change-case": "^5.4.4",
     "chokidar": "^5.0.0",
     "defu": "^6.1.4",