@poveste/plugin-vue 0.15.0 → 0.16.0

package/dist/bundled/client/server/run.js

@@ -1,44 +1,44 @@
 import { VUE_SETUP_HOOK_NAMES as e } from "../../setup-hooks.js";
-import t from "./Story.js";
-import n from "./Variant.js";
-import { createApp as r, h as i } from "vue";
-import { getSetupHook as a } from "@poveste/shared";
-import * as o from "virtual:$poveste-generated-global-setup";
-import * as s from "virtual:$poveste-setup";
+import { addStoryContext as t, storyFileContext as n } from "./context.js";
+import r from "./Story.js";
+import i from "./Variant.js";
+import { createApp as a, h as o } from "vue";
+import { getSetupHook as s } from "@poveste/shared";
+import * as c from "virtual:$poveste-generated-global-setup";
+import * as l from "virtual:$poveste-setup";
 //#region src/client/server/run.ts
-async function c({ file: c, storyData: l, el: u }) {
-	let { default: d } = await import(/* @vite-ignore */
+async function u({ file: u, storyData: d, el: f }) {
+	let { default: p } = await import(/* @vite-ignore */
 		/* @vite-ignore */
-		c.moduleId
-	), f = r({
-		provide: {
-			addStory(e) {
-				l.push(e);
-			},
-			hstStoryFile: c
+		u.moduleId
+	), m = a({
+		setup() {
+			t.provide((e) => {
+				d.push(e);
+			}), n.provide(u);
 		},
 		render() {
-			return i(d);
+			return o(p);
 		}
 	});
-	f.component("Story", t), f.component("Variant", n);
-	let p = {
-		app: f,
+	m.component("Story", r), m.component("Variant", i);
+	let h = {
+		app: m,
 		story: void 0,
 		variant: void 0,
 		addWrapper: () => {}
-	}, m = a(o, e);
-	m && await m(p);
-	let h = a(s, e);
-	if (h && await h(p), f.mount(u), d.doc) {
+	}, g = s(c, e);
+	g && await g(h);
+	let _ = s(l, e);
+	if (_ && await _(h), m.mount(f), p.doc) {
 		let e = document.createElement("div");
-		e.innerHTML = d.doc;
+		e.innerHTML = p.doc;
 		let t = e.textContent;
-		l.forEach((e) => {
+		d.forEach((e) => {
 			e.docsText = t;
 		});
 	}
-	f.unmount();
+	m.unmount();
 }
 //#endregion
-export { c as run };
+export { u as run };

package/dist/client/app/MountStory.d.ts

@@ -9,6 +9,10 @@ declare const _default: import("vue").DefineComponent<import("vue").ExtractPropT
         type: StringConstructor;
         default: null;
     };
+    syncState: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
 }>, {
     el: import("vue").Ref<HTMLDivElement | undefined, HTMLDivElement | undefined>;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
@@ -20,7 +24,12 @@ declare const _default: import("vue").DefineComponent<import("vue").ExtractPropT
         type: StringConstructor;
         default: null;
     };
+    syncState: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
 }>> & Readonly<{}>, {
+    syncState: boolean;
     targetVariantId: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 export default _default;

package/dist/client/app/context.d.ts

@@ -0,0 +1,9 @@
+import type { ComputedRef } from 'vue';
+/** The story a variant belongs to. Read with `?.` throughout. */
+export declare const storyContext: import("../context.js").Context<ComputedRef<any>>;
+/**
+ * The story's implicit state, absent when the story has none. A variant skips
+ * its state sync rather than failing, which is behaviour rather than an
+ * oversight — this is the type saying so.
+ */
+export declare const implicitStateContext: import("../context.js").Context<() => any>;

package/dist/client/app/render-context.d.ts

@@ -9,10 +9,25 @@ export interface PreviewRenderContext {
      * app realm, where the story view needs all of them mounted.
      */
     targetVariantId?: string | null;
+    /**
+     * Whether this mount pass owns the live state sync for its variants.
+     *
+     * False in a sandbox realm, where the render tree beside it already syncs the
+     * same `variant.state` against the same story's bindings. Two syncs over one
+     * state is two deep watchers walking the whole graph on every edit, and a
+     * story holding a large one pays for both: #964 measured the sandbox running
+     * three syncs where the app realm runs one.
+     *
+     * The app realm keeps it. Its mount pass is the only thing that fills
+     * `variant.state` there — with no controls slot nothing renders, so nothing
+     * else would — and that is what the controls panel builds from.
+     */
+    syncState?: boolean;
     externalState: Variant['state'] | null;
     nextVariantIndex: {
         value: number;
     };
 }
 export declare function provideRenderContext(value: PreviewRenderContext): void;
+/** Null outside a preview, which several call sites read with `?.`. */
 export declare function useRenderContext(): PreviewRenderContext | null;

package/dist/client/app/util.d.ts

@@ -1,4 +1,17 @@
 import type { ComponentInternalInstance } from 'vue';
+/**
+ * A value Vue has marked raw is carried by reference rather than rebuilt.
+ *
+ * Both sides of this bridge live in one realm, so the reference is the useful
+ * thing to hand over: the baseline then holds the same identity the next pass
+ * reads, `isEquivalent` settles it by `Object.is`, and nothing walks whatever
+ * is behind it. Rebuilding it was ten of the twenty traversals a keystroke
+ * cost (#957).
+ *
+ * The bridge that leaves this realm cannot do the same — see `toRawDeep` in
+ * `poveste-app`, where the mark does not survive the crossing and the key is
+ * dropped instead.
+ */
 /**
  * Using external/user Vue
  */
@@ -17,4 +30,23 @@ export declare function syncStateBundledAndExternal(bundledState: Record<string,
     stop(): void;
 };
 /** The component being set up. Throws outside `setup`, where Vue returns null. */
+/**
+ * Whether a `<script setup>` binding can be story state a control drives.
+ *
+ * A readonly ref cannot: the write-back is refused, so the two sides of the
+ * bridge never agree on it and the sync re-walks forever (#959). `useTemplateRef`
+ * returns one — in dev builds only, which is why a built book is quiet and the
+ * mode story authors work in is not.
+ *
+ * It has to be asked of the ref rather than of what the ref holds. The guard
+ * beside this one tests the value, and a value test cannot classify a template
+ * ref at all: at setup time it holds `null`, and what it will hold later is not
+ * knowable from here. Readonly-ness is a property of the ref itself and is
+ * settled by the time the binding is registered.
+ *
+ * A `computed` is caught by the same rule and for the same reason — it is a
+ * derived value, and a control that cannot write is not a control. Before this
+ * it appeared in the panel and warned when written.
+ */
+export declare function isWritableBinding(value: unknown): boolean;
 export declare function useInstance(name: string): ComponentInternalInstance;

package/dist/client/context.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A context keyed by a symbol, with its provide and its inject in one place.
+ *
+ * Six of these used to be string keys carrying `any`, and two of the six were
+ * the same string meaning two different things in two realms (#981). A symbol
+ * cannot collide and the type travels with it.
+ *
+ * `inject` and `injectOptional` are separate functions rather than one call with a
+ * default, because "nobody provided this" and "this is allowed to be absent"
+ * are different questions that used to arrive as the same `undefined` — and the
+ * first one is what an author hits when they nest a component wrongly.
+ *
+ * Reka's `createContext` is this shape and is already a dependency of the
+ * controls package. It is not one of this package's, and this is fifteen lines,
+ * so it is written here rather than taking a dependency for it.
+ */
+export interface Context<T> {
+    provide: (value: T) => void;
+    /** Throws, naming the provider, when nothing provided it. */
+    inject: (consumer: string) => T;
+    /** `null` when nothing provided it, which the caller is expected to handle. */
+    injectOptional: () => T | null;
+}
+/**
+ * `description` is what a symbol shows in a stack; `provider` is the component
+ * a reader has to go and add, and is the only part of the error they can act on.
+ *
+ * The key comes from the global registry rather than being minted here, because
+ * this module is evaluated more than once. A collection worker's module graph is
+ * invalidated while a story is mid-run, so `provide` and `inject` can each hold
+ * their own instance of this file — a plain `Symbol()` then differs between them
+ * and the injection misses, which reads as a `<Variant>` outside its `<Story>`.
+ * Every description here is already unique, so the registry cannot re-collide
+ * the way the string keys in #981 did.
+ *
+ * Absence is read as `null` rather than `undefined` so that a provider passing
+ * `undefined` on purpose is still a provider. None does today, and this is the
+ * cheaper of the two mistakes to have made.
+ */
+export declare function createContext<T>(description: string, provider: string): Context<T>;

package/dist/client/server/context.d.ts

@@ -0,0 +1,7 @@
+import type { ServerStory, ServerStoryFile, ServerVariant } from '@poveste/shared';
+/** The file being collected, provided by `run.ts` rather than by a component. */
+export declare const storyFileContext: import("../context.js").Context<ServerStoryFile>;
+/** Optional: a `<Story>` collected outside a run has nowhere to report to. */
+export declare const addStoryContext: import("../context.js").Context<(story: ServerStory) => void>;
+export declare const serverStoryContext: import("../context.js").Context<ServerStory>;
+export declare const addVariantContext: import("../context.js").Context<(variant: ServerVariant) => void>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/plugin-vue",
   "type": "module",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Poveste plugin for Vue.js support",
   "author": {
     "name": "Sorin Gitlan",
@@ -67,30 +67,30 @@
     "src"
   ],
   "engines": {
-    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+    "node": ">=22.22.2"
   },
   "peerDependencies": {
-    "poveste": "^0.15.0",
-    "vue": "^3.5.26"
+    "poveste": "^0.16.0",
+    "vue": "^3.5.43"
   },
   "dependencies": {
-    "@poveste/controls": "^0.15.0",
-    "@poveste/shared": "^0.15.0",
-    "@poveste/vendors": "^0.15.0",
+    "@poveste/controls": "^0.16.0",
+    "@poveste/shared": "^0.16.0",
+    "@poveste/vendors": "^0.16.0",
     "change-case": "^5.4.4",
-    "ignore": "^7.0.6",
+    "ignore": "^7.0.10",
     "launch-editor": "^2.9.1",
     "pathe": "^2.0.3",
     "tinyglobby": "^0.2.17"
   },
   "devDependencies": {
-    "@types/node": "^22.10.1",
+    "@types/node": "^26.6.3",
     "concurrently": "^10.0.5",
-    "poveste": "0.15.0",
+    "poveste": "0.16.0",
     "typescript": "6.0.3",
-    "vite": "^8.2.0",
-    "vitest": "^5.0.0",
-    "vue": "^3.5.26"
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2",
+    "vue": "^3.5.43"
   },
   "scripts": {
     "build": "rimraf dist && vite build && tsc -d -P tsconfig.build.json && pnpm run build:types",

package/src/client/__tests__/context.spec.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vitest'
+
+/*
+ * A collection worker evaluates the context modules more than once — its graph is
+ * invalidated while a story is mid-run — so the provider and the consumer can each
+ * hold their own instance of one file. The key is what has to survive that: minted
+ * per instance it differs between them, the injection misses, and the reader is
+ * told their `<Variant>` is outside a `<Story>`.
+ *
+ * Vue's own `provide`/`inject` are stubbed because they need a mounted component
+ * and this package's tests have no DOM; the key they are handed is the subject.
+ */
+const provided: unknown[] = []
+const injected: unknown[] = []
+
+vi.mock('vue', () => ({
+  provide: (key: unknown) => {
+    provided.push(key)
+  },
+  inject: (key: unknown) => {
+    injected.push(key)
+    return null
+  },
+}))
+
+const { createContext } = await import('../context.js')
+
+function keyOf(description: string) {
+  createContext(description, '<Story>').provide('anything')
+  return provided.at(-1)
+}
+
+describe('createContext', () => {
+  it('gives two instances of the same context one key', () => {
+    expect(keyOf('poveste-test-context')).toBe(keyOf('poveste-test-context'))
+  })
+
+  it('keeps two contexts apart when their descriptions differ', () => {
+    // What #981 was: one key meaning two things.
+    expect(keyOf('poveste-test-one')).not.toBe(keyOf('poveste-test-two'))
+  })
+
+  it('injects under the key it provides under', () => {
+    const context = createContext<string>('poveste-test-round-trip', '<Story>')
+    context.provide('the story file')
+    context.injectOptional()
+
+    expect(injected.at(-1)).toBe(provided.at(-1))
+  })
+})

package/src/client/app/MountStory.ts

@@ -26,6 +26,11 @@ export default _defineComponent({
       type: String,
       default: null,
     },
+
+    syncState: {
+      type: Boolean,
+      default: true,
+    },
   },
 
   setup(props) {
@@ -35,6 +40,7 @@ export default _defineComponent({
       slotName: 'default',
       currentVariant: null,
       targetVariantId: props.targetVariantId,
+      syncState: props.syncState,
       externalState: null,
       nextVariantIndex: {
         value: 0,

package/src/client/app/Story.ts

@@ -2,9 +2,10 @@ import type { Story } from '@poveste/shared'
 import type { PropType, VNode } from 'vue'
 import type { PreviewRenderContext } from './render-context.js'
 import { omitInheritStoryProps } from '@poveste/shared'
-import { cloneVNode, computed, defineComponent, h, isRef, provide, reactive, useAttrs } from 'vue'
+import { cloneVNode, computed, defineComponent, h, isRef, reactive, useAttrs } from 'vue'
+import { implicitStateContext, storyContext } from './context.js'
 import { useRenderContext } from './render-context.js'
-import { useInstance } from './util.js'
+import { isWritableBinding, useInstance } from './util.js'
 import Variant from './Variant.js'
 
 export default defineComponent({
@@ -35,7 +36,7 @@ export default defineComponent({
 
     const renderContext = useRenderContext()
     const story = computed(() => attrs.story)
-    provide('story', story)
+    storyContext.provide(story)
 
     const storyComponent: any = vm.parent
     const implicitState = reactive<Record<string, any>>({})
@@ -56,6 +57,10 @@ export default defineComponent({
         return
       }
 
+      if (!isWritableBinding(value)) {
+        return
+      }
+
       Object.defineProperty(implicitState, key, {
         enumerable: true,
         configurable: true,
@@ -90,7 +95,7 @@ export default defineComponent({
     for (const key in storyComponent.data) {
       addImplicitState(storyComponent.data, key)
     }
-    provide('implicitState', () => implicitState)
+    implicitStateContext.provide(() => implicitState)
 
     function updateStory() {
       if (props.meta) {

package/src/client/app/Variant.ts

@@ -1,9 +1,10 @@
 import type { Variant } from '@poveste/shared'
-import type { ComputedRef, PropType } from 'vue'
+import type { PropType } from 'vue'
 import type { PreviewRenderContext } from './render-context.js'
 import { applyState, autoPropsStateKeys } from '@poveste/shared'
-import { computed, defineComponent, inject, onBeforeUnmount, useAttrs } from 'vue'
+import { computed, defineComponent, onBeforeUnmount, useAttrs } from 'vue'
 import { syncVariantAutoProps } from './auto-props.js'
+import { implicitStateContext, storyContext } from './context.js'
 import { useRenderContext } from './render-context.js'
 import { syncStateBundledAndExternal, toRawDeep, useInstance } from './util.js'
 
@@ -56,8 +57,8 @@ export default defineComponent({
       variant?: Variant
     }
     const vm = useInstance('Variant')
-    const story = inject<ComputedRef<any>>('story')
-    const implicitState = inject<() => any>('implicitState')
+    const story = storyContext.injectOptional()
+    const implicitState = implicitStateContext.injectOptional()
     const renderContext = useRenderContext()
     let lastPropsTypesSnapshot: string
     let renderVariant: Variant | undefined
@@ -84,7 +85,11 @@ export default defineComponent({
       applyState(mountVariant.value.state, toRawDeep(state))
     }
 
-    if (renderContext?.mode !== 'render' && mountVariant.value && implicitState) {
+    // `syncState` is false in a sandbox realm, where the render tree beside this
+    // one already syncs the same `variant.state` against the same story's
+    // bindings. Both were live, so an edit walked the graph twice over for one
+    // copy of it (#964).
+    if (renderContext?.mode !== 'render' && renderContext?.syncState !== false && mountVariant.value && implicitState) {
       mountStateSync = syncStateBundledAndExternal(mountVariant.value.state, implicitState(), autoPropsStateKeys)
     }
 

package/src/client/app/__tests__/state-sync.spec.ts

@@ -1,7 +1,7 @@
 import { autoPropsStateKeys } from '@poveste/shared'
-import { nextTick as bundledNextTick, reactive as bundledReactive } from '@poveste/vendors/vue'
+import { nextTick as bundledNextTick, reactive as bundledReactive, ref as bundledRef } from '@poveste/vendors/vue'
 import { describe, expect, it } from 'vitest'
-import { nextTick, reactive, watch } from 'vue'
+import { markRaw, nextTick, reactive, ref, watch } from 'vue'
 import { syncStateBundledAndExternal } from '../util.js'
 
 // These run against both Vue copies for real: `@poveste/vendors/vue` is the one
@@ -41,6 +41,82 @@ describe('syncStateBundledAndExternal', () => {
     sync.stop()
   })
 
+  // Each side's walker recurses with its own copy's `isRef`, and the bundled
+  // one used to hand its whole subtree to the external walker — so below the
+  // first level, bundled state was walked by the wrong copy of Vue. Nothing
+  // observable came of it, because `isRef` reads `__v_isRef` rather than an
+  // identity and either copy answers for the other's ref; this pins the
+  // recursion either way, which is coverage the bridge did not have.
+  it('unwraps a ref nested below the first level, on both sides', async () => {
+    const { bundled, external, sync } = setup({ count: 0 })
+    await settle()
+
+    bundled.deep = { inner: { value: bundledRef('from bundled') } }
+    await settle()
+    expect(external.deep.inner.value).toBe('from bundled')
+
+    external.other = { inner: { value: ref('from external') } }
+    await settle()
+    expect(bundled.other.inner.value).toBe('from external')
+
+    sync.stop()
+  })
+
+  // Both walkers rebuilt every object from its own enumerable keys, so a `Date`
+  // crossed as `{}` — and the baseline's `isEquivalent`, which refuses to
+  // compare anything that is not plain precisely so two distinct `Date`s are
+  // never called equal, was handed two empty plain objects instead (#977).
+  it('carries a Date across, rather than emptying it', async () => {
+    const { bundled, external, sync } = setup({ count: 0 })
+    await settle()
+
+    external.at = new Date(1790071200000)
+    await settle()
+
+    expect(bundled.at).toBeInstanceOf(Date)
+    expect(bundled.at.getTime()).toBe(1790071200000)
+
+    sync.stop()
+  })
+
+  it('carries a Map and a class instance the same way', async () => {
+    class Point {
+      constructor(public x: number, public y: number) {}
+      get len() { return Math.hypot(this.x, this.y) }
+    }
+    const { bundled, external, sync } = setup({ count: 0 })
+    await settle()
+
+    external.m = new Map([['a', 1]])
+    external.p = new Point(3, 4)
+    await settle()
+
+    expect(bundled.m).toBeInstanceOf(Map)
+    expect(bundled.m.get('a')).toBe(1)
+    // In one realm the reference crosses, so the prototype survives too — which
+    // the sandbox bridge cannot promise and does not (#977).
+    expect(bundled.p.len).toBe(5)
+
+    sync.stop()
+  })
+
+  // The half the walker was destroying upstream of: two different dates must
+  // not settle as equivalent, or an edit is dropped rather than mirrored.
+  it('mirrors a change from one Date to another', async () => {
+    const { bundled, external, sync } = setup({ count: 0 })
+    await settle()
+
+    external.at = new Date(1790071200000)
+    await settle()
+
+    external.at = new Date(0)
+    await settle()
+
+    expect(bundled.at.getTime()).toBe(0)
+
+    sync.stop()
+  })
+
   it('stops mirroring once stopped', async () => {
     const { bundled, external, sync } = setup({ count: 0 })
     await settle()
@@ -385,3 +461,38 @@ describe('keys the sync is told to omit', () => {
     sync.stop()
   })
 })
+
+describe('a binding Vue has marked raw', () => {
+  // Not `setup()` above: that clones its argument, and `structuredClone` is
+  // exactly what a mark does not survive.
+  function setupWithGraph() {
+    const graph = markRaw({ nodes: { deep: 1 } })
+    const bundled = bundledReactive<Record<string, any>>({ text: '', graph })
+    const external = reactive<Record<string, any>>({ text: '' })
+    const sync = syncStateBundledAndExternal(bundled, external)
+    return { bundled, external, sync, graph }
+  }
+
+  it('crosses between the two Vues as itself, not as a rebuilt copy', async () => {
+    const { external, sync, graph } = setupWithGraph()
+    await settle()
+
+    // Both sides live in one realm, so the reference is the useful thing to
+    // hand over — and handing it over is what lets the compare settle on
+    // identity instead of walking whatever is behind it (#957).
+    expect(external.graph).toBe(graph)
+    sync.stop()
+  })
+
+  it('stays that object over later passes, and does not hold up the keys beside it', async () => {
+    const { bundled, external, sync, graph } = setupWithGraph()
+    await settle()
+
+    bundled.text = 'a'
+    await settle()
+
+    expect(external.graph).toBe(graph)
+    expect(external.text).toBe('a')
+    sync.stop()
+  })
+})

package/src/client/app/__tests__/writable-binding.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { computed, readonly, ref, shallowRef, useTemplateRef } from 'vue'
+import { isWritableBinding } from '../util.js'
+
+// `useTemplateRef` returns a readonly ref in a dev build and a writable one in a
+// production build, so this file is the only place the defect in #959 can be
+// caught: vitest runs the dev build, and the e2e suites serve built books where
+// the bug does not exist.
+
+describe('isWritableBinding', () => {
+  it('rejects the ref useTemplateRef returns, which is what loops the sync', () => {
+    expect(isWritableBinding(useTemplateRef('el'))).toBe(false)
+  })
+
+  it('rejects a readonly ref however it was made', () => {
+    expect(isWritableBinding(readonly(ref(0)))).toBe(false)
+    expect(isWritableBinding(readonly(shallowRef(null)))).toBe(false)
+  })
+
+  // Same rule, and the reason is the same: a control that cannot write is not a
+  // control. Called out because it is a behaviour change beyond the defect.
+  it('rejects a computed, which could never take the write either', () => {
+    expect(isWritableBinding(computed(() => 1))).toBe(false)
+  })
+
+  // The shape every existing story uses for a template ref, which has to keep
+  // working — a story that writes its own state through one still syncs.
+  it('accepts the pre-3.5 ref(null) form', () => {
+    expect(isWritableBinding(ref(null))).toBe(true)
+    expect(isWritableBinding(shallowRef(null))).toBe(true)
+  })
+
+  it('accepts ordinary bindings, ref and plain alike', () => {
+    expect(isWritableBinding(ref(0))).toBe(true)
+    expect(isWritableBinding({ a: 1 })).toBe(true)
+    expect(isWritableBinding('text')).toBe(true)
+    expect(isWritableBinding(undefined)).toBe(true)
+  })
+})

package/src/client/app/context.ts

@@ -0,0 +1,17 @@
+import type { ComputedRef } from 'vue'
+import { createContext } from '../context.js'
+
+/*
+ * App mode's contexts. Both are optional, and both were guarded by hand before
+ * being able to say so (#981).
+ */
+
+/** The story a variant belongs to. Read with `?.` throughout. */
+export const storyContext = createContext<ComputedRef<any>>('poveste-app-story', '<Story>')
+
+/**
+ * The story's implicit state, absent when the story has none. A variant skips
+ * its state sync rather than failing, which is behaviour rather than an
+ * oversight — this is the type saying so.
+ */
+export const implicitStateContext = createContext<() => any>('poveste-app-implicit-state', '<Story>')