@poveste/plugin-vue 0.15.0 → 0.16.0

package/src/client/app/render-context.ts

@@ -1,6 +1,5 @@
 import type { Variant } from '@poveste/shared'
-import type { InjectionKey } from 'vue'
-import { inject, provide } from 'vue'
+import { createContext } from '../context.js'
 
 export interface PreviewRenderContext {
   mode: 'mount' | 'render'
@@ -12,18 +11,39 @@ 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
   }
 }
 
-const previewRenderContextKey: InjectionKey<PreviewRenderContext> = Symbol('poveste-preview-render-context')
+/*
+ * This one was already a typed symbol with its provide and inject together —
+ * it was the pattern the other six were measured against (#981). It goes
+ * through the shared helper so the package has one shape rather than two,
+ * which is the mistake #978 is about, in miniature.
+ */
+const renderContext = createContext<PreviewRenderContext>('poveste-preview-render-context', '<Story>')
 
 export function provideRenderContext(value: PreviewRenderContext) {
-  provide(previewRenderContextKey, value)
+  renderContext.provide(value)
 }
 
+/** Null outside a preview, which several call sites read with `?.`. */
 export function useRenderContext() {
-  return inject(previewRenderContextKey, null)
+  return renderContext.injectOptional()
 }

package/src/client/app/util.ts

@@ -1,14 +1,27 @@
 import type { ComponentInternalInstance } from 'vue'
-import { applyState, createStateBaseline } from '@poveste/shared'
+import { applyState, createStateBaseline, isMarkedRaw, isPlainObject } from '@poveste/shared'
 import {
   isRef as _isRef,
   unref as _unref,
   watch as _watch,
 } from '@poveste/vendors/vue'
-import { getCurrentInstance, isRef, unref, watch } from 'vue'
+import { getCurrentInstance, isReadonly, isRef, markRaw, unref, watch } from 'vue'
 
 const isObject = (val: unknown): val is object => val !== null && typeof val === 'object'
 
+/**
+ * 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
  */
@@ -23,10 +36,32 @@ export function toRawDeep(val: unknown, seen = new WeakMap()): any {
     return unwrappedValue
   }
 
+  if (isMarkedRaw(unwrappedValue)) {
+    return unwrappedValue
+  }
+
   if (seen.has(unwrappedValue)) {
     return seen.get(unwrappedValue)
   }
 
+  if (!Array.isArray(unwrappedValue) && !isPlainObject(unwrappedValue)) {
+    // A `Date`, a `Map`, a class instance. Both sides of this bridge live in
+    // one realm, so the reference is the useful thing to hand over — the same
+    // answer `copyState` in `@poveste/shared` gives. Rebuilding it as a plain
+    // object emptied it: a `Date` has no own enumerable keys, so it arrived as
+    // `{}`, and the baseline's `isEquivalent` was handed two of those and
+    // called them equivalent (#977).
+    //
+    // Marked on the way through, which is not decoration. `applyState` writes
+    // this into the other Vue's reactive graph, and a reference to something
+    // like a Nuxt app instance — which a `<script setup>` binding can be — is
+    // then deep-watched: `useNuxtApp()` in a story recursed until the stack
+    // gave out. Flattening used to bound that by accident. `markRaw` bounds it
+    // deliberately, and is the treatment #974 already gives a value that must
+    // cross by reference.
+    return markRaw(unwrappedValue)
+  }
+
   if (Array.isArray(unwrappedValue)) {
     const result: unknown[] = []
     seen.set(unwrappedValue, result)
@@ -61,10 +96,25 @@ export function _toRawDeep(val: unknown, seen = new WeakMap()): any {
     return unwrappedValue
   }
 
+  if (isMarkedRaw(unwrappedValue)) {
+    return unwrappedValue
+  }
+
   if (seen.has(unwrappedValue)) {
     return seen.get(unwrappedValue)
   }
 
+  if (!Array.isArray(unwrappedValue) && !isPlainObject(unwrappedValue)) {
+    // A `Date`, a `Map`, a class instance. Both sides of this bridge live in
+    // one realm, so the reference is the useful thing to hand over — the same
+    // answer given to a marked value just above, and the same one `copyState`
+    // in `@poveste/shared` gives. Rebuilding it as a plain object emptied it: a
+    // `Date` has no own enumerable keys, so it arrived as `{}`, and the
+    // baseline's `isEquivalent` was handed two of those and called them
+    // equivalent (#977). Marked for the reason given on the walker above.
+    return markRaw(unwrappedValue)
+  }
+
   if (Array.isArray(unwrappedValue)) {
     const result: unknown[] = []
     seen.set(unwrappedValue, result)
@@ -79,9 +129,22 @@ export function _toRawDeep(val: unknown, seen = new WeakMap()): any {
   }
 }
 
+/**
+ * `_toRawDeep`, not `toRawDeep`: this is the bundled Vue's walker, and handing
+ * the subtree to the external one meant only the top level was ever walked by
+ * the copy of Vue that owns it.
+ *
+ * Nothing observable changes today, which is why it survived. The two walkers
+ * differ only in whose `isRef`/`unref` they call, and `isRef` is a read of
+ * `__v_isRef` — a property, not an identity — so either copy answers correctly
+ * for a ref the other created. It is fixed as a trap rather than as a defect:
+ * the next rule that lands on one walker and not the other would apply to the
+ * first level of bundled state and to nothing beneath it, and the diff would
+ * look right.
+ */
 function _toRawObject(obj: Record<any, any>, target: Record<any, any>, seen = new WeakMap()) {
   Object.keys(obj).forEach((key) => {
-    target[key] = toRawDeep(obj[key], seen)
+    target[key] = _toRawDeep(obj[key], seen)
   })
 }
 
@@ -149,6 +212,28 @@ export function syncStateBundledAndExternal(bundledState: Record<string, any>, e
 }
 
 /** 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 function isWritableBinding(value: unknown): boolean {
+  return !(isRef(value) && isReadonly(value))
+}
+
 export function useInstance(name: string): ComponentInternalInstance {
   const vm = getCurrentInstance()
   if (!vm) {

package/src/client/context.ts

@@ -0,0 +1,66 @@
+import type { InjectionKey } from 'vue'
+import { inject as vueInject, provide as vueProvide } from 'vue'
+
+/**
+ * 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 function createContext<T>(description: string, provider: string): Context<T> {
+  const key: InjectionKey<T> = Symbol.for(description)
+
+  return {
+    provide(value) {
+      vueProvide(key, value)
+    },
+
+    inject(consumer) {
+      const value = vueInject(key, null)
+
+      if (value === null) {
+        throw new Error(`[poveste] a ${consumer} has to be inside a ${provider}`)
+      }
+
+      return value
+    },
+
+    injectOptional() {
+      return vueInject(key, null)
+    },
+  }
+}

package/src/client/server/Story.ts

@@ -1,6 +1,7 @@
-import type { ServerStory, ServerStoryFile, ServerVariant } from '@poveste/shared'
+import type { ServerStory, ServerVariant } from '@poveste/shared'
 import type { PropType } from 'vue'
-import { defineComponent, inject, onMounted, provide } from 'vue'
+import { defineComponent, onMounted } from 'vue'
+import { addStoryContext, addVariantContext, serverStoryContext, storyFileContext } from './context.js'
 import { autoStubComponents } from './stub.js'
 
 export default defineComponent({
@@ -51,7 +52,7 @@ export default defineComponent({
   },
 
   setup(props) {
-    const file = inject<ServerStoryFile>('hstStoryFile')
+    const file = storyFileContext.injectOptional()
 
     // Story
 
@@ -72,14 +73,13 @@ export default defineComponent({
       meta: props.meta,
       variants: [],
     }
-    const addStory = inject<((story: ServerStory) => void) | null>('addStory', null)
-    addStory?.(story)
+    addStoryContext.injectOptional()?.(story)
 
     // Variants
 
-    provide('story', story)
+    serverStoryContext.provide(story)
 
-    provide('addVariant', (variant: ServerVariant) => {
+    addVariantContext.provide((variant: ServerVariant) => {
       story.variants.push(variant)
     })
 

package/src/client/server/Variant.ts

@@ -1,6 +1,7 @@
-import type { ServerStory, ServerVariant } from '@poveste/shared'
+import type { ServerVariant } from '@poveste/shared'
 import type { PropType } from 'vue'
-import { defineComponent, inject } from 'vue'
+import { defineComponent } from 'vue'
+import { addVariantContext, serverStoryContext } from './context.js'
 
 export default defineComponent({
   name: 'PovesteVariant',
@@ -33,25 +34,20 @@ export default defineComponent({
   },
 
   setup(props) {
-    const story = inject<ServerStory>('story')
-
-    function generateId() {
-      if (!story) {
-        throw new Error('[poveste] a <Variant> with no `id` has to be inside a <Story>')
-      }
-      return `${story.id}-${story.variants.length}`
-    }
-
-    const variant: ServerVariant = {
-      id: props.id ?? generateId(),
+    // Asked for before anything reads it, so a missing `<Story>` is reported
+    // once and the same way whether or not the variant carries an `id`. The
+    // guard this replaces sat inside the branch that generates one, so an
+    // explicit `id` skipped it and reached `undefined(variant)` instead (#981).
+    const story = serverStoryContext.inject('<Variant>')
+    const addVariant = addVariantContext.inject('<Variant>')
+
+    addVariant({
+      id: props.id ?? `${story.id}-${story.variants.length}`,
       title: props.title,
       icon: props.icon,
       iconColor: props.iconColor,
       meta: props.meta,
-    }
-
-    const addVariant = inject('addVariant') as (variant: ServerVariant) => void
-    addVariant(variant)
+    })
   },
 
   render() {

package/src/client/server/__tests__/nesting-errors.spec.ts

@@ -0,0 +1,48 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { createApp, h } from 'vue'
+import Story from '../Story.js'
+import Variant from '../Variant.js'
+
+/*
+ * What a story author gets for a nesting mistake in collect mode, where the
+ * stack has nothing in it about stories (#981).
+ *
+ * Mounted the way `run.ts` mounts them — a bare `createApp` — rather than
+ * through a test-utils wrapper, because the missing provider is the whole
+ * subject and a harness that supplies one would prove nothing.
+ */
+function mountAlone(component: any, props: Record<string, unknown> = {}) {
+  const app = createApp({ render: () => h(component, props) })
+  const el = document.createElement('div')
+  try {
+    app.mount(el)
+  }
+  finally {
+    app.unmount()
+  }
+}
+
+describe('a <Variant> outside a <Story>', () => {
+  it('says which component it needed, when it carries an id', () => {
+    // The branch that generates an id already threw a good error, so an
+    // explicit id was the case that reached `undefined(variant)` and said
+    // `addVariant is not a function`.
+    expect(() => mountAlone(Variant, { id: 'mine', title: 'Solo' })).toThrow(/<Variant>.*<Story>/)
+  })
+
+  it('says the same thing when it does not', () => {
+    expect(() => mountAlone(Variant, { title: 'Solo' })).toThrow(/<Variant>.*<Story>/)
+  })
+
+  it('never reports that a function is not a function', () => {
+    expect(() => mountAlone(Variant, { id: 'mine', title: 'Solo' })).not.toThrow(/is not a function/)
+  })
+})
+
+describe('a <Story> outside the collect runner', () => {
+  it('says which provider it needed', () => {
+    // `hstStoryFile` comes from `run.ts`, the only thing that mounts these.
+    expect(() => mountAlone(Story, { title: 'Solo' })).toThrow(/<Story>/)
+  })
+})

package/src/client/server/context.ts

@@ -0,0 +1,18 @@
+import type { ServerStory, ServerStoryFile, ServerVariant } from '@poveste/shared'
+import { createContext } from '../context.js'
+
+/*
+ * Collect mode's contexts. The story one is deliberately not the app's: they
+ * carry different shapes in different realms and shared one string key, so
+ * nothing stopped one being injected where the other was expected (#981).
+ */
+
+/** The file being collected, provided by `run.ts` rather than by a component. */
+export const storyFileContext = createContext<ServerStoryFile>('poveste-server-story-file', 'story file')
+
+/** Optional: a `<Story>` collected outside a run has nowhere to report to. */
+export const addStoryContext = createContext<(story: ServerStory) => void>('poveste-server-add-story', 'story file')
+
+export const serverStoryContext = createContext<ServerStory>('poveste-server-story', '<Story>')
+
+export const addVariantContext = createContext<(variant: ServerVariant) => void>('poveste-server-add-variant', '<Story>')

package/src/client/server/run.ts

@@ -7,6 +7,7 @@ import * as generatedSetup from 'virtual:$poveste-generated-global-setup'
 import * as setup from 'virtual:$poveste-setup'
 import { createApp, h } from 'vue'
 import { VUE_SETUP_HOOK_NAMES } from '../../setup-hooks.js'
+import { addStoryContext, storyFileContext } from './context.js'
 import Story from './Story.js'
 import Variant from './Variant.js'
 
@@ -14,11 +15,13 @@ export async function run({ file, storyData, el }: ServerRunPayload) {
   const { default: Comp } = await import(/* @vite-ignore */ file.moduleId)
 
   const app = createApp({
-    provide: {
-      addStory(data: ServerStory) {
+    // Provided from `setup` rather than the options object so the keys can be
+    // the symbols the components inject; the options form takes string keys.
+    setup() {
+      addStoryContext.provide((data: ServerStory) => {
         storyData.push(data)
-      },
-      hstStoryFile: file,
+      })
+      storyFileContext.provide(file)
     },
     render() {
       return h(Comp)