@poveste/shared 0.14.0 → 0.16.0

package/dist/codegen/serialize-js.js

@@ -42,7 +42,7 @@ function objectToSourceLines(object, seen, indentCount = 0) {
         lines.push('{');
         lines.push(...createLines(1, (lines) => {
             for (const key in object) {
-                const value = object[key];
+                const value = Reflect.get(object, key);
                 let printedKey = key;
                 if (KEY_ESCAPE_REG.test(key)) {
                     printedKey = `'${printedKey}'`;
@@ -66,11 +66,11 @@ function arrayToSourceLines(array, seen, indentCount = 0) {
                 addLinesFromValue(lines, value, '', ',', seen);
             }
         });
-        if (contentLines.length === 0) {
+        const [first] = contentLines;
+        if (!first) {
             lines.push('[]');
         }
         else if (contentLines.length <= MAX_SINGLE_LINE_ARRAY_LENGTH && !contentLines.some(line => line.spaces > 1)) {
-            const [first] = contentLines;
             first.line = contentLines.map(({ line }) => line.substring(0, line.length - 1)).join(', ');
             first.line = `[${first.line}]`;
             first.spaces--;
@@ -120,7 +120,11 @@ function addLinesFromValue(lines, value, before, after, seen) {
     lines.push(before + result + after);
 }
 function wrap(lines, before, after) {
-    lines[0].line = before + lines[0].line;
-    lines[lines.length - 1].line += after;
+    const first = lines[0];
+    const last = lines.at(-1);
+    if (first)
+        first.line = before + first.line;
+    if (last)
+        last.line += after;
     return lines;
 }

package/dist/codegen/util.js

@@ -4,7 +4,9 @@ export function indent(lines, count = 1) {
 export function unindent(code) {
     const lines = code.split('\n');
     let indentLevel = -1;
-    let indentText;
+    // Empty until a non-blank line is seen: `replace(undefined, '')` would look for
+    // the literal text "undefined" (TS6 reports it as used before assignment).
+    let indentText = '';
     const linesToAnalyze = lines.filter(line => line.trim().length > 0);
     for (const line of linesToAnalyze) {
         const match = /^\s*/.exec(line);
@@ -51,7 +53,7 @@ export function createAutoBuildingObject(format, specialKeysHandler, key = '', d
             if (!cache[p]) {
                 const childKey = key ? `${key}.${p.toString()}` : p.toString();
                 const child = createAutoBuildingObject(format, specialKeysHandler, childKey, depth + 1);
-                cache[p] = { key: childKey, ...child };
+                cache[p] = child;
             }
             return cache[p].proxy;
         },

package/dist/setup.d.ts

@@ -2,6 +2,11 @@ export type SetupModule = Record<string, unknown> | undefined;
 /**
  * Reads a setup hook (`setupVanilla`, `setupVue3`, ...) out of a setup module.
  *
+ * `retired` names hooks a plugin has stopped accepting. Nothing passes a
+ * non-empty list today; it exists so that removing a name at 1.0 is a string
+ * moving between two arrays rather than a failure mode designed under release
+ * pressure.
+ *
  * Takes the module as an argument instead of letting callers access it inline:
  * the setup modules are namespace imports of virtual or user-provided files that
  * aren't guaranteed to declare every hook, and a static `namespace.setupVue3`
@@ -9,4 +14,4 @@ export type SetupModule = Record<string, unknown> | undefined;
  * consumer build. Passing the namespace through a call forces it to be
  * materialized, so the lookup happens at runtime where it belongs.
  */
-export declare function getSetupHook<T>(mod: SetupModule, name: string | string[]): T | undefined;
+export declare function getSetupHook<T>(mod: SetupModule, name: string | string[], retired?: string[]): T | undefined;

package/dist/setup.js

@@ -1,6 +1,11 @@
 /**
  * Reads a setup hook (`setupVanilla`, `setupVue3`, ...) out of a setup module.
  *
+ * `retired` names hooks a plugin has stopped accepting. Nothing passes a
+ * non-empty list today; it exists so that removing a name at 1.0 is a string
+ * moving between two arrays rather than a failure mode designed under release
+ * pressure.
+ *
  * Takes the module as an argument instead of letting callers access it inline:
  * the setup modules are namespace imports of virtual or user-provided files that
  * aren't guaranteed to declare every hook, and a static `namespace.setupVue3`
@@ -8,9 +13,28 @@
  * consumer build. Passing the namespace through a call forces it to be
  * materialized, so the lookup happens at runtime where it belongs.
  */
-export function getSetupHook(mod, name) {
+export function getSetupHook(mod, name, retired = []) {
     const names = typeof name === 'string' ? [name] : name;
     const present = names.filter(candidate => typeof mod?.[candidate] === 'function');
+    // Dropping a name is otherwise silent: the export stops being looked up, and a
+    // file that has it does nothing at all — no error, no warning, no hook. The
+    // people most likely to hold one are working from an older recipe, which is
+    // the worst audience for a silent failure.
+    //
+    // `retired` is a parameter rather than a constant so the mechanism can be
+    // exercised with a fixture list while every production list is still empty.
+    // An empty detector that has only ever been seen to pass cannot be told apart
+    // from one that does not work (#157).
+    const dropped = retired.filter(candidate => typeof mod?.[candidate] === 'function');
+    if (dropped.length > 0) {
+        // Two different situations, and the message has to say which: with no live
+        // name exported the setup does not run at all, and with one it does — so
+        // "nothing runs" would send someone to debug a setup that is working.
+        const consequence = present.length > 0
+            ? `${present[0]} runs; the old export is ignored.`
+            : `Rename to ${names[names.length - 1]} — nothing runs until you do.`;
+        console.warn(`[poveste] Setup file exports ${dropped.join(', ')}, which ${dropped.length === 1 ? 'is' : 'are'} no longer read. ${consequence}`);
+    }
     // Earlier names win, so a plugin lists its established hook first and a newer
     // alias after it: an existing setup file keeps the exact behaviour it had.
     // Running both instead would apply the same setup twice, which for Vue means
@@ -19,5 +43,6 @@ export function getSetupHook(mod, name) {
         console.warn(`[poveste] Setup file exports ${present.length} interchangeable setup hooks (${present.join(', ')}). `
             + `Only ${present[0]} runs. Keep one — they are aliases, not separate hooks.`);
     }
-    return present.length > 0 ? mod[present[0]] : undefined;
+    const [first] = present;
+    return first ? mod[first] : undefined;
 }

package/dist/state.d.ts

@@ -1,5 +1,32 @@
 export declare function clone(data: any): any;
-export declare function omit(data: any, keys: string[]): {};
+export declare function omit(data: any, keys: string[]): Record<string, any>;
+/**
+ * Whether Vue has marked this value raw, and the walkers must stop here.
+ *
+ * Read as a property rather than through Vue's `isReactive`, because this
+ * package does not depend on Vue — and because the flag is what has to be
+ * asked anyway: `markRaw` defines `__v_skip` **non-enumerable**, so it crosses
+ * neither `structuredClone` nor JSON, and by the time a value has been through
+ * the sandbox bridge the mark is gone (#957).
+ *
+ * A marked value looks plain to every predicate here: a component's exposed
+ * object and `markRaw({ … })` both have `Object.prototype` and own enumerable
+ * keys, so without this the compare and the copy descend into whatever is
+ * behind them.
+ *
+ * The read is guarded because state is user data and may be a proxy with a
+ * throwing trap; an unanswerable value is treated as unmarked, which is the
+ * behaviour this had before.
+ */
+export declare function isMarkedRaw(value: any): boolean;
+/**
+ * Exported because `poveste-app`'s walker has to draw the same line. The two
+ * disagreeing about what a non-plain value is was #977: the walker flattened a
+ * `Date` to `{}` before `isEquivalent` ever saw it, so the defence below —
+ * written for exactly that case — was handed two empty plain objects and
+ * reported them equivalent.
+ */
+export declare function isPlainObject(value: any): boolean;
 /**
  * Structural comparison, deliberately narrow: it recurses into plain objects and
  * arrays and compares everything else by `Object.is`.

package/dist/state.js

@@ -1,3 +1,5 @@
+// `any` in and out, as it has always been published: #709 decides whether this
+// helper stays public, and typing it here would change it for callers first.
 export function clone(data) {
     try {
         return structuredClone(data);
@@ -22,7 +24,43 @@ export function omit(data, keys) {
     }
     return copy;
 }
-function isPlainObject(value) {
+/**
+ * Whether Vue has marked this value raw, and the walkers must stop here.
+ *
+ * Read as a property rather than through Vue's `isReactive`, because this
+ * package does not depend on Vue — and because the flag is what has to be
+ * asked anyway: `markRaw` defines `__v_skip` **non-enumerable**, so it crosses
+ * neither `structuredClone` nor JSON, and by the time a value has been through
+ * the sandbox bridge the mark is gone (#957).
+ *
+ * A marked value looks plain to every predicate here: a component's exposed
+ * object and `markRaw({ … })` both have `Object.prototype` and own enumerable
+ * keys, so without this the compare and the copy descend into whatever is
+ * behind them.
+ *
+ * The read is guarded because state is user data and may be a proxy with a
+ * throwing trap; an unanswerable value is treated as unmarked, which is the
+ * behaviour this had before.
+ */
+export function isMarkedRaw(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    try {
+        return value.__v_skip === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Exported because `poveste-app`'s walker has to draw the same line. The two
+ * disagreeing about what a non-plain value is was #977: the walker flattened a
+ * `Date` to `{}` before `isEquivalent` ever saw it, so the defence below —
+ * written for exactly that case — was handed two empty plain objects and
+ * reported them equivalent.
+ */
+export function isPlainObject(value) {
     if (value === null || typeof value !== 'object') {
         return false;
     }
@@ -47,6 +85,12 @@ export function isEquivalent(a, b, seen) {
     if (Object.is(a, b)) {
         return true;
     }
+    // Same reason as the prototype test below, reached differently: a marked
+    // value is one Vue itself refuses to look inside, and two distinct ones are
+    // not the same value whatever their keys say.
+    if (isMarkedRaw(a) || isMarkedRaw(b)) {
+        return false;
+    }
     const bothArrays = Array.isArray(a) && Array.isArray(b);
     if (!bothArrays && !(isPlainObject(a) && isPlainObject(b))) {
         return false;
@@ -234,7 +278,7 @@ export function diffState(baseline, next) {
  * `Object.is`, so a reference is the identity the comparison is about.
  */
 function copyState(value, seen = new WeakMap()) {
-    if (!Array.isArray(value) && !isPlainObject(value)) {
+    if (isMarkedRaw(value) || (!Array.isArray(value) && !isPlainObject(value))) {
         return value;
     }
     if (seen.has(value)) {

package/dist/story-error.d.ts

@@ -1,13 +1,13 @@
 export declare const SANDBOX_ERROR = "__poveste:sandbox-error";
 export interface StoryError {
     message: string;
-    stack?: string;
+    stack?: string | undefined;
     /**
      * Which occupant threw. A warm realm is retargeted rather than reloaded
      * (#240), so the host has to reject a report from the previous one.
      */
-    storyId?: string;
-    variantId?: string;
+    storyId?: string | undefined;
+    variantId?: string | undefined;
 }
 export declare function toStoryError(error: unknown): Pick<StoryError, 'message' | 'stack'>;
 export declare function reportStoryError(error: unknown, occupant?: Pick<StoryError, 'storyId' | 'variantId'>): void;

package/dist/types/config.d.ts

@@ -1,4 +1,4 @@
-import type MarkdownIt from 'markdown-it';
+import type { MarkdownIt } from 'markdown-it';
 import type { UseHeadInput } from 'unhead/types';
 import type { UserConfig as ViteConfig, ConfigEnv as ViteConfigEnv } from 'vite';
 import type { Plugin } from './plugin.js';

package/dist/types/plugin.d.ts

@@ -40,32 +40,69 @@ export interface ModuleLoader {
     loadModule: (file: string) => Promise<any>;
     destroy: () => void;
 }
+/** What changed under a path passed to `api.watch`. */
+export type WatchEvent = 'add' | 'change' | 'unlink';
+/** Called by `api.watch` with what happened and the absolute path it happened to. */
+export type WatchCallback = (event: WatchEvent, path: string) => Awaitable<unknown>;
 /**
- * What every plugin hook receives. `colors`, `path` and `fs` are Poveste's own
- * picocolors, pathe and fs-extra, handed over so a plugin can use them without
- * adding a second copy to the tree.
+ * What every plugin hook receives.
  *
  * Prefer `log`/`warn`/`error` over `console`: they prefix the plugin's name, so
  * a line in a busy build says what printed it.
  */
 export interface PluginApiBase {
+    /**
+     * Poveste's own picocolors.
+     *
+     * @deprecated Import `picocolors` directly. Works for the rest of 0.x and is removable at 1.0 (#356).
+     */
     colors: typeof pc;
+    /**
+     * Poveste's own pathe.
+     *
+     * @deprecated Import `node:path`, or `pathe` for forward slashes on Windows. Works for the rest of
+     * 0.x and is removable at 1.0 (#356).
+     */
     path: typeof path;
+    /**
+     * Poveste's own fs-extra.
+     *
+     * @deprecated Import `node:fs` or `node:fs/promises` directly. Works for the rest of 0.x and is
+     * removable at 1.0 (#356).
+     */
     fs: typeof fs;
     moduleLoader: ModuleLoader;
     readonly pluginTempDir: string;
-    log: (...msg: any[]) => void;
-    warn: (...msg: any[]) => void;
-    error: (...msg: any[]) => void;
+    log: (...msg: unknown[]) => void;
+    warn: (...msg: unknown[]) => void;
+    error: (...msg: unknown[]) => void;
     getStories: () => ServerStory[];
     addStoryFile: (file: string) => void;
     getConfig: () => PovesteConfig;
+    /**
+     * Calls `callback` when a file under `paths` is added, changed or removed after
+     * the call. What already exists raises nothing.
+     *
+     * Poveste owns the watcher and closes it with the dev server, however the server
+     * ends, so a plugin has nothing to release. The returned function stops watching
+     * sooner. A callback that throws or rejects is logged with the plugin's name.
+     *
+     * Only `poveste dev` watches. In a build this does nothing, because a watcher
+     * opened while a failed build closes its server is what kept that build's
+     * process alive (#434).
+     */
+    watch: (paths: string | string[], callback: WatchCallback) => () => Promise<void>;
 }
 /**
- * {@link PluginApiBase} plus the file watcher, passed to `onDev`. Only the dev
- * server has one — a build never watches.
+ * {@link PluginApiBase} as passed to `onDev`.
  */
 export interface PluginApiDev extends PluginApiBase {
+    /**
+     * Poveste's own chokidar module. A watcher opened from it is the plugin's to close.
+     *
+     * @deprecated Use {@link PluginApiBase.watch}, which Poveste closes with the dev server. Works for
+     * the rest of 0.x and is removable at 1.0 (#356).
+     */
     watcher: typeof chokidar;
 }
 /**

package/dist/types/story.d.ts

@@ -75,26 +75,26 @@ export interface VariantMeta extends CommonMeta {
 export interface Variant {
     id: string;
     title: string;
-    icon?: string;
-    iconColor?: string;
-    setupApp?: (payload: any) => unknown;
-    slots?: () => {
+    icon?: string | undefined;
+    iconColor?: string | undefined;
+    setupApp?: ((payload: any) => unknown) | undefined;
+    slots?: (() => {
         default: any;
         controls: any;
         source: any;
-    };
+    }) | undefined;
     state: any;
-    source?: string;
-    responsiveDisabled?: boolean;
-    autoPropsDisabled?: boolean;
-    configReady?: boolean;
-    previewReady?: boolean;
-    meta?: VariantMeta;
+    source?: string | undefined;
+    responsiveDisabled?: boolean | undefined;
+    autoPropsDisabled?: boolean | undefined;
+    configReady?: boolean | undefined;
+    previewReady?: boolean | undefined;
+    meta?: VariantMeta | undefined;
 }
 export interface PropDefinition {
     name: string;
-    types?: string[];
-    required?: boolean;
+    types?: string[] | undefined;
+    required?: boolean | undefined;
     default?: any;
 }
 export interface AutoPropComponentDefinition {
@@ -123,7 +123,7 @@ export interface ServerStoryFile {
     /**
      * Generated path for tree UI
      */
-    treePath?: string[];
+    treePath?: string[] | undefined;
     /**
      * Use the module id in imports to allow HMR
      */
@@ -131,23 +131,23 @@ export interface ServerStoryFile {
     /**
      * Resolved story data from story file execution
      */
-    story?: ServerStory;
+    story?: ServerStory | undefined;
     /**
      * Data sent to user tree config functions
      */
-    treeFile?: ServerTreeFile;
+    treeFile?: ServerTreeFile | undefined;
     /**
      * Is virtual module
      */
-    virtual?: boolean;
+    virtual?: boolean | undefined;
     /**
      * Virtual module code
      */
-    moduleCode?: string;
+    moduleCode?: string | undefined;
     /**
      * Related markdown docs
      */
-    markdownFile?: ServerMarkdownFile;
+    markdownFile?: ServerMarkdownFile | undefined;
 }
 export interface ServerMarkdownFile {
     id: string;
@@ -155,28 +155,28 @@ export interface ServerMarkdownFile {
     absolutePath: string;
     isRelatedToStory: boolean;
     frontmatter?: any;
-    html?: string;
-    content?: string;
-    storyFile?: ServerStoryFile;
+    html?: string | undefined;
+    content?: string | undefined;
+    storyFile?: ServerStoryFile | undefined;
 }
 export interface ServerStory {
     id: string;
     title: string;
-    group?: string;
+    group?: string | undefined;
     variants: ServerVariant[];
-    layout?: StoryLayout;
-    icon?: string;
-    iconColor?: string;
-    docsOnly?: boolean;
-    docsText?: string;
-    meta?: StoryMeta;
+    layout?: StoryLayout | undefined;
+    icon?: string | undefined;
+    iconColor?: string | undefined;
+    docsOnly?: boolean | undefined;
+    docsText?: string | undefined;
+    meta?: StoryMeta | undefined;
 }
 export interface ServerVariant {
     id: string;
     title: string;
-    icon?: string;
-    iconColor?: string;
-    meta?: VariantMeta;
+    icon?: string | undefined;
+    iconColor?: string | undefined;
+    meta?: VariantMeta | undefined;
 }
 export interface ServerTreeFile {
     title: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/shared",
   "type": "module",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Shared utilities for Poveste",
   "author": {
     "name": "Sorin Gitlan",
@@ -33,24 +33,26 @@
     "dist"
   ],
   "engines": {
-    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+    "node": ">=22.22.2"
   },
   "peerDependencies": {
     "vite": "^8.0.0"
   },
   "dependencies": {
-    "@poveste/vendors": "^0.14.0",
+    "@poveste/vendors": "^0.16.0",
     "@types/fs-extra": "^11.0.4",
-    "@types/markdown-it": "^14.1.2",
-    "chokidar": "^4.0.1",
-    "pathe": "^1.1.2",
+    "chokidar": "^5.0.0",
+    "markdown-it": "^15.0.2",
+    "pathe": "^2.0.3",
     "picocolors": "^1.1.1",
-    "unhead": "^3.1.0"
+    "unhead": "^3.4.1"
   },
   "devDependencies": {
-    "typescript": "5.6.3",
-    "vite": "^8.2.0",
-    "vitest": "^5.0.0"
+    "@types/node": "^26.6.3",
+    "typescript": "6.0.3",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2",
+    "vue-router": "^5.3.1"
   },
   "scripts": {
     "build": "rimraf dist && tsc",