@poveste/plugin-svelte 0.4.0 → 0.5.1

package/README.md

@@ -0,0 +1,60 @@
+# Poveste + Svelte 5 and SvelteKit
+
+Requires `svelte@^5.46.4` and `@sveltejs/vite-plugin-svelte@^7.0.0`. SvelteKit is supported
+by this same package — there is no separate plugin — through an optional
+`@sveltejs/kit@^2.53.0` peer.
+
+The floor is not `^5.0.0` for a reason: Poveste requires Vite 8, only
+`@sveltejs/vite-plugin-svelte` v7 peers Vite 8, and v7 in turn requires `svelte@^5.46.4`.
+Svelte `5.0`–`5.46.3` cannot be assembled into a working project at all.
+
+```bash
+pnpm add -D poveste @poveste/plugin-svelte
+```
+
+Register the plugin in your Poveste config:
+
+```ts
+import { HstSvelte } from '@poveste/plugin-svelte'
+import { defineConfig } from 'poveste'
+
+export default defineConfig({
+  plugins: [
+    HstSvelte(),
+  ],
+})
+```
+
+Write stories as `*.story.svelte`. State that your controls drive belongs on `initState`,
+and your content reads it from the snippet:
+
+```svelte
+<script>
+  import MyButton from './MyButton.svelte'
+
+  export let Hst
+
+  const initState = () => ({ disabled: false })
+</script>
+
+<Hst.Story title="MyButton" {initState}>
+  {#snippet children({ state })}
+    <MyButton disabled={state.disabled} />
+  {/snippet}
+
+  {#snippet controls({ state })}
+    <Hst.Checkbox bind:value={state.disabled} title="Disabled" />
+  {/snippet}
+</Hst.Story>
+```
+
+> **Coming from histoire?** Story state must move onto `initState`. Svelte 5 removed the API
+> histoire used to read a story's state, so a plain `let` in your story no longer reaches the
+> preview — Poveste owns the state instead. A story with controls but no `initState` logs an
+> error explaining this.
+>
+> [How, and why](https://poveste.dev/guide/migration-from-histoire.html#svelte-story-state-moves-to-initstate)
+
+[Svelte guide](https://poveste.dev/guide/svelte/getting-started.html) ·
+[SvelteKit](https://poveste.dev/guide/svelte/getting-started.html#sveltekit) ·
+[Documentation](https://poveste.dev)

package/dist/client/RenderStory.js

@@ -1 +1 @@
-import{getContext as e,setContext as t}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as n from"svelte/internal/client";var r=n.from_html(`<!> <!>`,1);function i(i,a){n.push(a,!1);let o=e(`__pvtStory`),s=e(`__pvtVariant`),c=e(`__pvtSlot`);t(`__pvtIndex`,{value:0});let l=n.prop(a,`source`,8,null);n.legacy_pre_effect(()=>n.deep_read_state(l()),()=>{l()!=null&&Object.assign(s,{source:l()})}),n.legacy_pre_effect_reset(),n.init();var u=r(),d=n.first_child(u),f=e=>{var t=n.comment(),r=n.first_child(t);n.slot(r,a,`controls`,{},null),n.append(e,t)};n.if(d,e=>{c===`controls`&&e(f)});var p=n.sibling(d,2),m=e=>{var t=n.comment(),r=n.first_child(t);n.slot(r,a,`default`,{},null),n.append(e,t)};n.if(p,e=>{n.untrack(()=>c==="default"||o.meta?.hasVariantChildComponents)&&e(m)}),n.append(i,u),n.pop()}export{i as default};
+import{watch as e}from"@poveste/vendors/vue";import{getContext as t,onDestroy as n,setContext as r}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as i from"svelte/internal/client";var a=i.from_html(`<!> <!>`,1);function o(o,s){let c=i.sanitize_slots(s);i.push(s,!1);let l=t(`__pvtStory`),u=i.mutable_source(t(`__pvtVariant`)),d=t(`__pvtSlot`);r(`__pvtIndex`,{value:0});let f=i.prop(s,`source`,8,null),p=i.prop(s,`initState`,8,null);p()&&i.get(u)&&!i.get(u).__pvtStateSeeded&&(i.mutate(u,i.get(u).__pvtStateSeeded=!0),i.mutate(u,i.get(u).state={...i.get(u).state,...p()()})),!p()&&d===`controls`&&c.controls&&i.get(u)&&!i.get(u).__pvtStateWarned&&(i.mutate(u,i.get(u).__pvtStateWarned=!0),console.error([`[poveste] Story "${l?.title??l?.id}" has a controls slot but no \`initState\`.`,`Controls will render and appear to work, but their edits cannot reach the story:`,`the story is mounted separately for each slot, so a component-local variable is not shared.`,"Pass `initState` and read state from the snippet —",`https://poveste.dev/guide/migration-from-histoire.html#svelte-story-state-moves-to-initstate`].join(` `)));let m=i.mutable_source(i.get(u)?.state),h=e(()=>i.get(u)?.state,()=>{i.set(m,i.get(u)?.state)},{deep:!0});n(h),i.legacy_pre_effect(()=>(i.deep_read_state(f()),i.get(m),i.get(u)),()=>{let e=typeof f()==`function`?f()(i.get(m)):f();e!=null&&Object.assign(i.get(u),{source:e})}),i.legacy_pre_effect_reset(),i.init();var g=a(),_=i.first_child(g),v=e=>{var t=i.comment(),n=i.first_child(t);i.slot(n,s,`controls`,{get state(){return i.get(m)}},null),i.append(e,t)};i.if(_,e=>{d===`controls`&&e(v)});var y=i.sibling(_,2),b=e=>{var t=i.comment(),n=i.first_child(t);i.slot(n,s,`default`,{get state(){return i.get(m)}},null),i.append(e,t)};i.if(y,e=>{i.untrack(()=>d==="default"||l.meta?.hasVariantChildComponents)&&e(b)}),i.append(o,g),i.pop()}export{o as default};

package/dist/client/RenderStory.svelte

@@ -1,5 +1,6 @@
 <script>
-  import { getContext, setContext } from 'svelte'
+  import { watch as _watch } from '@poveste/vendors/vue'
+  import { getContext, onDestroy, setContext } from 'svelte'
 
   const story = getContext('__pvtStory')
   const currentVariant = getContext('__pvtVariant')
@@ -9,19 +10,68 @@
   setContext('__pvtIndex', index)
 
   export let source = null
+  export let initState = null
 
+  // Poveste owns the state, not the story component.
+  //
+  // The story is mounted once per slot — the app renders it with
+  // `slot-name="controls"`, the preview with the default — so a `let count` in
+  // the story exists twice and cannot be shared. Svelte 4 bridged the two
+  // instances with `$capture_state` / `$inject_state`; Svelte 5 provides neither,
+  // and no shim does either. So state lives on the variant, which both mounts
+  // read from the same context object and which the sandbox bridge already
+  // serialises across the iframe boundary (#81).
+  //
+  // Whichever mount arrives first seeds it; the second must not, or it would
+  // clobber whatever the user has already changed.
+  if (initState && currentVariant && !currentVariant.__pvtStateSeeded) {
+    currentVariant.__pvtStateSeeded = true
+    currentVariant.state = { ...currentVariant.state, ...initState() }
+  }
+
+  // Only from the mount that renders the controls. The story is mounted once per
+  // slot and, for an iframe layout, in a different realm — so the flag below cannot
+  // dedupe across them and the warning would appear twice.
+  if (!initState && slotName === 'controls' && $$slots.controls && currentVariant && !currentVariant.__pvtStateWarned) {
+    currentVariant.__pvtStateWarned = true
+    console.error([
+      `[poveste] Story "${story?.title ?? story?.id}" has a controls slot but no \`initState\`.`,
+      'Controls will render and appear to work, but their edits cannot reach the story:',
+      'the story is mounted separately for each slot, so a component-local variable is not shared.',
+      'Pass `initState` and read state from the snippet —',
+      'https://poveste.dev/guide/migration-from-histoire.html#svelte-story-state-moves-to-initstate',
+    ].join(' '))
+  }
+
+  // `variant.state` is a Vue-reactive object, so Svelte has no way to know when a
+  // control writes into it. Mirroring the reference back into a local on every
+  // Vue tick is what makes the template re-render: Svelte's invalidation treats
+  // any object assignment as a change, so reassigning the same proxy is enough.
+  let state = currentVariant?.state
+
+  const stopWatchingState = _watch(() => currentVariant?.state, () => {
+    state = currentVariant?.state
+  }, { deep: true })
+
+  onDestroy(stopWatchingState)
+
+  // `source` may be a function of the state. Story props are evaluated in the
+  // component's script, where the slot's `state` is not in scope, so a string
+  // literal cannot reflect what the controls are doing — which is most of the
+  // point of the source panel (#81).
   $: {
-    if (source != null) {
+    const resolvedSource = typeof source === 'function' ? source(state) : source
+    if (resolvedSource != null) {
       Object.assign(currentVariant, {
-        source,
+        source: resolvedSource,
       })
     }
   }
 </script>
 
 {#if slotName === 'controls'}
-  <slot name="controls" />
+  <slot name="controls" {state} />
 {/if}
 {#if slotName === 'default' || story.meta?.hasVariantChildComponents}
-  <slot />
+  <slot {state} />
 {/if}

package/dist/client/RenderVariant.js

@@ -1 +1 @@
-import{getContext as e}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as t from"svelte/internal/client";var n=t.from_html(`<!> <!>`,1);function r(r,i){t.push(i,!1);let a=e(`__pvtStory`),o=e(`__pvtVariant`),s=e(`__pvtSlot`),c=e(`__pvtIndex`),l=a.variants[c.value];c.value++;let u=o.id===l.id,d=t.prop(i,`source`,8,null);t.legacy_pre_effect(()=>t.deep_read_state(d()),()=>{d()!=null&&Object.assign(o,{source:d()})}),t.legacy_pre_effect_reset(),t.init();var f=t.comment(),p=t.first_child(f),m=e=>{var r=n(),a=t.first_child(r),o=e=>{var n=t.comment(),r=t.first_child(n);t.slot(r,i,`default`,{},null),t.append(e,n)};t.if(a,e=>{s==="default"&&e(o)});var c=t.sibling(a,2),l=e=>{var n=t.comment(),r=t.first_child(n);t.slot(r,i,`controls`,{},null),t.append(e,n)};t.if(c,e=>{s===`controls`&&e(l)}),t.append(e,r)};t.if(p,e=>{u&&e(m)}),t.append(r,f),t.pop()}export{r as default};
+import{watch as e}from"@poveste/vendors/vue";import{getContext as t,onDestroy as n}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as r from"svelte/internal/client";var i=r.from_html(`<!> <!>`,1);function a(a,o){let s=r.sanitize_slots(o);r.push(o,!1);let c=t(`__pvtStory`),l=r.mutable_source(t(`__pvtVariant`)),u=t(`__pvtSlot`),d=t(`__pvtIndex`),f=c.variants[d.value];d.value++;let p=r.get(l).id===f.id,m=r.prop(o,`source`,8,null),h=r.prop(o,`initState`,8,null);h()&&p&&!r.get(l).__pvtStateSeeded&&(r.mutate(l,r.get(l).__pvtStateSeeded=!0),r.mutate(l,r.get(l).state={...r.get(l).state,...h()()})),!h()&&p&&u===`controls`&&s.controls&&!r.get(l).__pvtStateWarned&&(r.mutate(l,r.get(l).__pvtStateWarned=!0),console.error([`[poveste] Variant "${f?.title??f?.id}" has a controls slot but no \`initState\`.`,`Controls will render and appear to work, but their edits cannot reach the story:`,`the story is mounted separately for each slot, so a component-local variable is not shared.`,"Pass `initState` and read state from the snippet —",`https://poveste.dev/guide/migration-from-histoire.html#svelte-story-state-moves-to-initstate`].join(` `)));let g=r.mutable_source(r.get(l)?.state),_=e(()=>r.get(l)?.state,()=>{r.set(g,r.get(l)?.state)},{deep:!0});n(_),r.legacy_pre_effect(()=>(r.deep_read_state(m()),r.get(g),r.get(l)),()=>{let e=typeof m()==`function`?m()(r.get(g)):m();e!=null&&Object.assign(r.get(l),{source:e})}),r.legacy_pre_effect_reset(),r.init();var v=r.comment(),y=r.first_child(v),b=e=>{var t=i(),n=r.first_child(t),a=e=>{var t=r.comment(),n=r.first_child(t);r.slot(n,o,`default`,{get state(){return r.get(g)}},null),r.append(e,t)};r.if(n,e=>{u==="default"&&e(a)});var s=r.sibling(n,2),c=e=>{var t=r.comment(),n=r.first_child(t);r.slot(n,o,`controls`,{get state(){return r.get(g)}},null),r.append(e,t)};r.if(s,e=>{u===`controls`&&e(c)}),r.append(e,t)};r.if(y,e=>{p&&e(b)}),r.append(a,v),r.pop()}export{a as default};

package/dist/client/RenderVariant.svelte

@@ -1,5 +1,6 @@
 <script>
-  import { getContext } from 'svelte'
+  import { watch as _watch } from '@poveste/vendors/vue'
+  import { getContext, onDestroy } from 'svelte'
 
   const story = getContext('__pvtStory')
   const currentVariant = getContext('__pvtVariant')
@@ -15,11 +16,47 @@
   const shouldRender = currentVariant.id === variant.id
 
   export let source = null
+  export let initState = null
 
+  // Same contract as `RenderStory`: poveste owns the state because the story is
+  // mounted once per slot, so a component-local variable cannot be shared (#81).
+  // `variant.state` is also the only bucket the sandbox bridge carries across the
+  // iframe boundary, which is why state is per variant rather than per story.
+  if (initState && shouldRender && !currentVariant.__pvtStateSeeded) {
+    currentVariant.__pvtStateSeeded = true
+    currentVariant.state = { ...currentVariant.state, ...initState() }
+  }
+
+  // Controls mount only — see the note in RenderStory: the two mounts do not share
+  // a realm for iframe layouts, so this is what keeps it to one warning.
+  if (!initState && shouldRender && slotName === 'controls' && $$slots.controls && !currentVariant.__pvtStateWarned) {
+    currentVariant.__pvtStateWarned = true
+    console.error([
+      `[poveste] Variant "${variant?.title ?? variant?.id}" has a controls slot but no \`initState\`.`,
+      'Controls will render and appear to work, but their edits cannot reach the story:',
+      'the story is mounted separately for each slot, so a component-local variable is not shared.',
+      'Pass `initState` and read state from the snippet —',
+      'https://poveste.dev/guide/migration-from-histoire.html#svelte-story-state-moves-to-initstate',
+    ].join(' '))
+  }
+
+  let state = currentVariant?.state
+
+  const stopWatchingState = _watch(() => currentVariant?.state, () => {
+    state = currentVariant?.state
+  }, { deep: true })
+
+  onDestroy(stopWatchingState)
+
+  // `source` may be a function of the state. Story props are evaluated in the
+  // component's script, where the slot's `state` is not in scope, so a string
+  // literal cannot reflect what the controls are doing — which is most of the
+  // point of the source panel (#81).
   $: {
-    if (source != null) {
+    const resolvedSource = typeof source === 'function' ? source(state) : source
+    if (resolvedSource != null) {
       Object.assign(currentVariant, {
-        source,
+        source: resolvedSource,
       })
     }
   }
@@ -27,9 +64,9 @@
 
 {#if shouldRender}
   {#if slotName === 'default'}
-    <slot />
+    <slot {state} />
   {/if}
   {#if slotName === 'controls'}
-    <slot name="controls" />
+    <slot name="controls" {state} />
   {/if}
 {/if}

package/dist/client/Wrap.js

@@ -1 +1 @@
-import{createApp as e,h as t,reactive as n}from"@poveste/vendors/vue";import{createEventDispatcher as r,onMount as i}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as a from"svelte/internal/client";var o=a.from_html(`<div> </div>`);function s(s,c){let l=a.legacy_rest_props(c,[`children`,`$$slots`,`$$events`,`$$legacy`]),u=a.legacy_rest_props(l,[`controlComponent`,`value`]);a.push(c,!1);let d=a.prop(c,`controlComponent`,8),f=a.prop(c,`value`,12),p=r(),m=a.mutable_source(),h,g=n({});function _(e,t){Object.assign(g,{value:e,attrs:t})}i(()=>{_(f(),u),h=e({render(){let e={};if(d().emits)for(let t in d().emits){let n=Array.isArray(d().emits)?d().emits[t]:t,r=n===`input`?`update:modelValue`:n;e[`on${r.charAt(0).toUpperCase()}${r.substring(1)}`]=(...e)=>{n===`update:modelValue`?f(e[0]):p(n,...e)}}return t(d(),{modelValue:f(),...g.attrs,...e,key:`component`})}}),h.mount(a.get(m))}),a.legacy_pre_effect(()=>(a.deep_read_state(f()),a.deep_read_state(u)),()=>{_(f(),u)}),a.legacy_pre_effect_reset(),a.init();var v=o(),y=a.child(v,!0);a.reset(v),a.bind_this(v,e=>a.set(m,e),()=>a.get(m)),a.template_effect(()=>a.set_text(y,(a.deep_read_state(d()),a.untrack(()=>d().name)))),a.append(s,v),a.pop()}export{s as default};
+import{createApp as e,h as t,reactive as n}from"@poveste/vendors/vue";import{createEventDispatcher as r,onMount as i}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as a from"svelte/internal/client";var o=a.from_html(`<div> </div>`);function s(s,c){let l=a.legacy_rest_props(c,[`children`,`$$slots`,`$$events`,`$$legacy`]),u=a.legacy_rest_props(l,[`controlComponent`,`value`]);a.push(c,!1);let d=a.prop(c,`controlComponent`,8),f=a.prop(c,`value`,12),p=r(),m=a.mutable_source(),h,g=n({});function _(e,t){Object.assign(g,{value:e,attrs:t})}i(()=>{_(f(),u),h=e({render(){let e={};if(d().emits)for(let t in d().emits){let n=Array.isArray(d().emits)?d().emits[t]:t,r=n===`input`?`update:modelValue`:n;e[`on${r.charAt(0).toUpperCase()}${r.substring(1)}`]=(...e)=>{n===`update:modelValue`?f(e[0]):p(n,...e)}}return t(d(),{modelValue:g.value,...g.attrs,...e,key:`component`})}}),h.mount(a.get(m))}),a.legacy_pre_effect(()=>(a.deep_read_state(f()),a.deep_read_state(u)),()=>{_(f(),u)}),a.legacy_pre_effect_reset(),a.init();var v=o(),y=a.child(v,!0);a.reset(v),a.bind_this(v,e=>a.set(m,e),()=>a.get(m)),a.template_effect(()=>a.set_text(y,(a.deep_read_state(d()),a.untrack(()=>d().name)))),a.append(s,v),a.pop()}export{s as default};

package/dist/client/Wrap.svelte

@@ -45,8 +45,12 @@
           }
         }
 
+        // `state` is the Vue-reactive mirror kept in sync by the `$:` below.
+        // Reading the plain `value` here would make the render depend on a
+        // variable Vue cannot track — it only saw fresh values because the
+        // `state` mutation was what triggered the re-render in the first place.
         return _h(controlComponent, {
-          modelValue: value,
+          modelValue: state.value,
           ...state.attrs,
           ...finalListeners,
           key: 'component',

package/dist/collect/Story.js

@@ -1 +1 @@
-import{getContext as e,setContext as t}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as n from"svelte/internal/client";function r(r,i){n.push(i,!1);let a=n.prop(i,`title`,8,null),o=n.prop(i,`id`,8,null),s=n.prop(i,`group`,8,null),c=n.prop(i,`layout`,8,null),l=n.prop(i,`icon`,8,null),u=n.prop(i,`iconColor`,8,null),d=n.prop(i,`docsOnly`,8,!1),f=e(`__pvtAddStory`),p=e(`__pvtStoryFile`),m={id:o()??p.id,title:a()??p.fileName,group:s(),layout:c(),icon:l(),iconColor:u(),docsOnly:d(),variants:[]};f(m),t(`__pvtStory`,m),t(`__pvtAddVariant`,e=>{m.variants.push(e)}),n.init();var h=n.comment(),g=n.first_child(h);n.slot(g,i,`default`,{},null),n.append(r,h),n.pop()}export{r as default};
+import{getContext as e,setContext as t}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as n from"svelte/internal/client";function r(r,i){n.push(i,!1);let a=n.prop(i,`title`,8,null),o=n.prop(i,`id`,8,null),s=n.prop(i,`group`,8,null),c=n.prop(i,`layout`,8,null),l=n.prop(i,`icon`,8,null),u=n.prop(i,`iconColor`,8,null),d=n.prop(i,`docsOnly`,8,!1),f=n.prop(i,`initState`,8,null),p=e(`__pvtAddStory`),m=e(`__pvtStoryFile`),h={id:o()??m.id,title:a()??m.fileName,group:s(),layout:c(),icon:l(),iconColor:u(),docsOnly:d(),variants:[]};p(h);let g=f()?f()():{};t(`__pvtStory`,h),t(`__pvtAddVariant`,e=>{h.variants.push(e)}),n.init();var _=n.comment(),v=n.first_child(_);n.slot(v,i,`default`,{get state(){return g}},null),n.append(r,_),n.pop()}export{r as default};

package/dist/collect/Story.svelte

@@ -8,6 +8,7 @@
   export let icon = null
   export let iconColor = null
   export let docsOnly = false
+  export let initState = null
 
   const addStory = getContext('__pvtAddStory')
   const file = getContext('__pvtStoryFile')
@@ -25,10 +26,16 @@
 
   addStory(story)
 
+  // Collection renders the story's markup purely to discover its variants, but
+  // that markup now reads `state`. Without a value here every expression
+  // referencing it throws and collection fails with a bare
+  // `Cannot read properties of undefined` (#81).
+  const state = initState ? initState() : {}
+
   setContext('__pvtStory', story)
   setContext('__pvtAddVariant', (variant) => {
     story.variants.push(variant)
   })
 </script>
 
-<slot />
+<slot {state} />

package/dist/collect/Variant.js

@@ -1 +1 @@
-import{getContext as e}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as t from"svelte/internal/client";function n(n,r){t.push(r,!1);let i=t.prop(r,`title`,8,`untitled`),a=t.prop(r,`id`,8,null),o=t.prop(r,`icon`,8,null),s=t.prop(r,`iconColor`,8,null),c=e(`__pvtStory`),l=e(`__pvtAddVariant`);function u(){return`${c.id}-${c.variants.length}`}l({id:a()??u(),title:i(),icon:o(),iconColor:s()}),t.init(),t.pop()}export{n as default};
+import{getContext as e}from"svelte";import"svelte/internal/disclose-version";import"svelte/internal/flags/legacy";import*as t from"svelte/internal/client";function n(n,r){t.push(r,!1);let i=t.prop(r,`title`,8,`untitled`),a=t.prop(r,`id`,8,null),o=t.prop(r,`icon`,8,null),s=t.prop(r,`iconColor`,8,null);t.prop(r,`initState`,8,null);let c=e(`__pvtStory`),l=e(`__pvtAddVariant`);function u(){return`${c.id}-${c.variants.length}`}l({id:a()??u(),title:i(),icon:o(),iconColor:s()}),t.init(),t.pop()}export{n as default};

package/dist/collect/Variant.svelte

@@ -5,6 +5,9 @@
   export let id = null
   export let icon = null
   export let iconColor = null
+  // Declared but unused: collection does not render variant children, and an
+  // undeclared prop would warn on every story that passes one.
+  export let initState = null
 
   const story = getContext('__pvtStory')
   const addVariant = getContext('__pvtAddVariant')

package/dist/helpers.d.ts

@@ -1,6 +1,6 @@
 import type { HstControlOption } from '@poveste/controls';
 import type { Story, StoryProps, Variant, VariantProps } from '@poveste/shared';
-import type { SvelteComponentTyped } from 'svelte';
+import type { Component, Snippet } from 'svelte';
 export interface SvelteStorySetupApi {
     app: any;
     story?: Story;
@@ -11,77 +11,110 @@ export declare function defineSetupSvelte(handler: SvelteStorySetupHandler): Sve
 export declare const defineSetupSvelte3: typeof defineSetupSvelte;
 export declare const defineSetupSvelte4: typeof defineSetupSvelte;
 export declare const defineSetupSvelte5: typeof defineSetupSvelte;
+export type StoryState = Record<string, any>;
+/**
+ * Props plus Svelte 5 children.
+ *
+ * `StoryProps` and `VariantProps` live in `@poveste/shared` and are shared with
+ * the Vue plugin, so a Svelte-only `Snippet` cannot be added there — it is
+ * intersected in here instead.
+ *
+ * This is what the move off `SvelteComponentTyped` needed. The class form carried
+ * Svelte 4 slot typing, so nested content type-checked implicitly; `Component<P>`
+ * has no slots, and Svelte 5 passes children as a prop (#99).
+ */
+type WithChildren<P> = P & {
+    children?: Snippet<[{
+        state: StoryState;
+    }]>;
+    controls?: Snippet<[{
+        state: StoryState;
+    }]>;
+};
+/**
+ * Story state is owned by poveste, not by the story component.
+ *
+ * The story is mounted once per slot, so a component-local variable exists twice
+ * and cannot be shared. `initState` seeds `variant.state`, which both mounts read
+ * and which the sandbox bridge carries across the iframe boundary (#81).
+ */
+type WithState<P> = Omit<P, 'source'> & {
+    initState?: () => StoryState;
+    /** A literal, or a function of the variant state so the source panel can track the controls. */
+    source?: string | ((state: StoryState) => string);
+};
 export interface Hst {
-    Story: typeof SvelteComponentTyped<StoryProps>;
-    Variant: typeof SvelteComponentTyped<VariantProps>;
-    Button: typeof SvelteComponentTyped;
-    ButtonGroup: typeof SvelteComponentTyped<{
+    Story: Component<WithState<WithChildren<StoryProps>>>;
+    Variant: Component<WithState<WithChildren<VariantProps>>>;
+    Button: Component<WithChildren<Record<string, any>>>;
+    ButtonGroup: Component<{
         value?: string;
         options: (string | HstControlOption)[];
         title?: string;
     }>;
-    Checkbox: typeof SvelteComponentTyped<{
+    Checkbox: Component<{
         value?: boolean;
         title: string;
     }>;
-    CheckboxList: typeof SvelteComponentTyped<{
+    CheckboxList: Component<{
         value: string[];
         options: (string | HstControlOption)[];
         title?: string;
     }>;
-    Text: typeof SvelteComponentTyped<{
+    Text: Component<{
         value?: string;
         title: string;
     }>;
-    Number: typeof SvelteComponentTyped<{
+    Number: Component<{
         value?: number;
         title: string;
         step?: number;
     }>;
-    Slider: typeof SvelteComponentTyped<{
+    Slider: Component<{
         value?: number;
         title: string;
         min: number;
         max: number;
         step?: number;
     }>;
-    Textarea: typeof SvelteComponentTyped<{
+    Textarea: Component<{
         value?: string;
         title: string;
     }>;
-    Select: typeof SvelteComponentTyped<{
+    Select: Component<{
         value?: string;
         title: string;
         options: Record<string, any> | string[] | HstControlOption[];
     }>;
-    Radio: typeof SvelteComponentTyped<{
+    Radio: Component<{
         value?: string;
         options: HstControlOption[];
         title?: string;
     }>;
-    Json: typeof SvelteComponentTyped<{
+    Json: Component<{
         value: unknown;
         title: string;
     }>;
-    Shades: typeof SvelteComponentTyped<{
+    Shades: Component<{
         shades: Record<string, any>;
         getName?: (key: string, color: string) => string;
         search?: string;
     }>;
-    TokenList: typeof SvelteComponentTyped<{
+    TokenList: Component<{
         tokens: Record<string, string | number | any[] | Record<string, any>>;
         getName?: (key: string, value: string | number | any[] | Record<string, any>) => string;
     }>;
-    TokenGrid: typeof SvelteComponentTyped<{
+    TokenGrid: Component<{
         tokens: Record<string, string | number | any[] | Record<string, any>>;
         getName?: (key: string, value: string | number | any[] | Record<string, any>) => string;
         colSize?: number;
     }>;
-    CopyIcon: typeof SvelteComponentTyped<{
+    CopyIcon: Component<{
         content: string;
     }>;
-    ColorSelect: typeof SvelteComponentTyped<{
+    ColorSelect: Component<{
         value?: string;
         title: string;
     }>;
 }
+export {};

package/dist/util/svelte.js

@@ -79,21 +79,36 @@ export async function callSetupFunctions(generatedSetup, setup, setupApi, varian
         await variantSetupApp(setupApi);
     }
 }
+/**
+ * Adds `controlComponent` to a props object **without** spreading it.
+ *
+ * Svelte 5 passes a bound prop as an accessor pair — `bind:value` becomes a
+ * `get value()` / `set value(v)` on the props object. Spreading invokes the
+ * getter and writes a plain data property, so the setter is dropped and the
+ * child's write-back silently goes nowhere: reads keep working, writes stop.
+ * That was the whole of #81.
+ *
+ * Copying the descriptors keeps the setter intact.
+ */
+function withControlComponent(props, controlComponent) {
+    const merged = Object.defineProperties({}, Object.getOwnPropertyDescriptors(props ?? {}));
+    Object.defineProperty(merged, 'controlComponent', {
+        value: controlComponent,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+    return merged;
+}
 export function createWrappedComponent(Wrap, controlComponent) {
     function ProxyWrap(anchorOrOptions, props) {
         if (new.target) {
             return new Wrap({
                 ...anchorOrOptions,
-                props: {
-                    ...anchorOrOptions?.props,
-                    controlComponent,
-                },
+                props: withControlComponent(anchorOrOptions?.props, controlComponent),
             });
         }
-        return Wrap(anchorOrOptions, {
-            ...props,
-            controlComponent,
-        });
+        return Wrap(anchorOrOptions, withControlComponent(props, controlComponent));
     }
     if (Wrap?.element) {
         ProxyWrap.element = Wrap.element;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/plugin-svelte",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Poveste plugin for Svelte 5 and SvelteKit support",
   "author": {
     "name": "Sorin Gitlan"
@@ -28,7 +28,7 @@
     "@sveltejs/kit": "^2.53.0",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "svelte": "^5.46.4",
-    "poveste": "^0.4.0"
+    "poveste": "^0.5.1"
   },
   "peerDependenciesMeta": {
     "@sveltejs/kit": {
@@ -40,9 +40,9 @@
     "globby": "^14.0.2",
     "launch-editor": "^2.9.1",
     "pathe": "^1.1.2",
-    "@poveste/controls": "^0.4.0",
-    "@poveste/shared": "^0.4.0",
-    "@poveste/vendors": "^0.4.0"
+    "@poveste/controls": "^0.5.1",
+    "@poveste/shared": "^0.5.1",
+    "@poveste/vendors": "^0.5.1"
   },
   "devDependencies": {
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
@@ -54,7 +54,7 @@
     "svelte-preprocess": "^6.0.3",
     "typescript": "5.6.3",
     "vite": "^8.0.0",
-    "poveste": "0.4.0"
+    "poveste": "0.5.1"
   },
   "scripts": {
     "build": "rimraf dist && vite build && tsc -d -P tsconfig.build.json && pnpm run build:types",

package/src/client/RenderStory.svelte

@@ -1,5 +1,6 @@
 <script>
-  import { getContext, setContext } from 'svelte'
+  import { watch as _watch } from '@poveste/vendors/vue'
+  import { getContext, onDestroy, setContext } from 'svelte'
 
   const story = getContext('__pvtStory')
   const currentVariant = getContext('__pvtVariant')
@@ -9,19 +10,68 @@
   setContext('__pvtIndex', index)
 
   export let source = null
+  export let initState = null
 
+  // Poveste owns the state, not the story component.
+  //
+  // The story is mounted once per slot — the app renders it with
+  // `slot-name="controls"`, the preview with the default — so a `let count` in
+  // the story exists twice and cannot be shared. Svelte 4 bridged the two
+  // instances with `$capture_state` / `$inject_state`; Svelte 5 provides neither,
+  // and no shim does either. So state lives on the variant, which both mounts
+  // read from the same context object and which the sandbox bridge already
+  // serialises across the iframe boundary (#81).
+  //
+  // Whichever mount arrives first seeds it; the second must not, or it would
+  // clobber whatever the user has already changed.
+  if (initState && currentVariant && !currentVariant.__pvtStateSeeded) {
+    currentVariant.__pvtStateSeeded = true
+    currentVariant.state = { ...currentVariant.state, ...initState() }
+  }
+
+  // Only from the mount that renders the controls. The story is mounted once per
+  // slot and, for an iframe layout, in a different realm — so the flag below cannot
+  // dedupe across them and the warning would appear twice.
+  if (!initState && slotName === 'controls' && $$slots.controls && currentVariant && !currentVariant.__pvtStateWarned) {
+    currentVariant.__pvtStateWarned = true
+    console.error([
+      `[poveste] Story "${story?.title ?? story?.id}" has a controls slot but no \`initState\`.`,
+      'Controls will render and appear to work, but their edits cannot reach the story:',
+      'the story is mounted separately for each slot, so a component-local variable is not shared.',
+      'Pass `initState` and read state from the snippet —',
+      'https://poveste.dev/guide/migration-from-histoire.html#svelte-story-state-moves-to-initstate',
+    ].join(' '))
+  }
+
+  // `variant.state` is a Vue-reactive object, so Svelte has no way to know when a
+  // control writes into it. Mirroring the reference back into a local on every
+  // Vue tick is what makes the template re-render: Svelte's invalidation treats
+  // any object assignment as a change, so reassigning the same proxy is enough.
+  let state = currentVariant?.state
+
+  const stopWatchingState = _watch(() => currentVariant?.state, () => {
+    state = currentVariant?.state
+  }, { deep: true })
+
+  onDestroy(stopWatchingState)
+
+  // `source` may be a function of the state. Story props are evaluated in the
+  // component's script, where the slot's `state` is not in scope, so a string
+  // literal cannot reflect what the controls are doing — which is most of the
+  // point of the source panel (#81).
   $: {
-    if (source != null) {
+    const resolvedSource = typeof source === 'function' ? source(state) : source
+    if (resolvedSource != null) {
       Object.assign(currentVariant, {
-        source,
+        source: resolvedSource,
       })
     }
   }
 </script>
 
 {#if slotName === 'controls'}
-  <slot name="controls" />
+  <slot name="controls" {state} />
 {/if}
 {#if slotName === 'default' || story.meta?.hasVariantChildComponents}
-  <slot />
+  <slot {state} />
 {/if}

package/src/client/RenderVariant.svelte

@@ -1,5 +1,6 @@
 <script>
-  import { getContext } from 'svelte'
+  import { watch as _watch } from '@poveste/vendors/vue'
+  import { getContext, onDestroy } from 'svelte'
 
   const story = getContext('__pvtStory')
   const currentVariant = getContext('__pvtVariant')
@@ -15,11 +16,47 @@
   const shouldRender = currentVariant.id === variant.id
 
   export let source = null
+  export let initState = null
 
+  // Same contract as `RenderStory`: poveste owns the state because the story is
+  // mounted once per slot, so a component-local variable cannot be shared (#81).
+  // `variant.state` is also the only bucket the sandbox bridge carries across the
+  // iframe boundary, which is why state is per variant rather than per story.
+  if (initState && shouldRender && !currentVariant.__pvtStateSeeded) {
+    currentVariant.__pvtStateSeeded = true
+    currentVariant.state = { ...currentVariant.state, ...initState() }
+  }
+
+  // Controls mount only — see the note in RenderStory: the two mounts do not share
+  // a realm for iframe layouts, so this is what keeps it to one warning.
+  if (!initState && shouldRender && slotName === 'controls' && $$slots.controls && !currentVariant.__pvtStateWarned) {
+    currentVariant.__pvtStateWarned = true
+    console.error([
+      `[poveste] Variant "${variant?.title ?? variant?.id}" has a controls slot but no \`initState\`.`,
+      'Controls will render and appear to work, but their edits cannot reach the story:',
+      'the story is mounted separately for each slot, so a component-local variable is not shared.',
+      'Pass `initState` and read state from the snippet —',
+      'https://poveste.dev/guide/migration-from-histoire.html#svelte-story-state-moves-to-initstate',
+    ].join(' '))
+  }
+
+  let state = currentVariant?.state
+
+  const stopWatchingState = _watch(() => currentVariant?.state, () => {
+    state = currentVariant?.state
+  }, { deep: true })
+
+  onDestroy(stopWatchingState)
+
+  // `source` may be a function of the state. Story props are evaluated in the
+  // component's script, where the slot's `state` is not in scope, so a string
+  // literal cannot reflect what the controls are doing — which is most of the
+  // point of the source panel (#81).
   $: {
-    if (source != null) {
+    const resolvedSource = typeof source === 'function' ? source(state) : source
+    if (resolvedSource != null) {
       Object.assign(currentVariant, {
-        source,
+        source: resolvedSource,
       })
     }
   }
@@ -27,9 +64,9 @@
 
 {#if shouldRender}
   {#if slotName === 'default'}
-    <slot />
+    <slot {state} />
   {/if}
   {#if slotName === 'controls'}
-    <slot name="controls" />
+    <slot name="controls" {state} />
   {/if}
 {/if}

package/src/client/Wrap.svelte

@@ -45,8 +45,12 @@
           }
         }
 
+        // `state` is the Vue-reactive mirror kept in sync by the `$:` below.
+        // Reading the plain `value` here would make the render depend on a
+        // variable Vue cannot track — it only saw fresh values because the
+        // `state` mutation was what triggered the re-render in the first place.
         return _h(controlComponent, {
-          modelValue: value,
+          modelValue: state.value,
           ...state.attrs,
           ...finalListeners,
           key: 'component',

package/src/collect/Story.svelte

@@ -8,6 +8,7 @@
   export let icon = null
   export let iconColor = null
   export let docsOnly = false
+  export let initState = null
 
   const addStory = getContext('__pvtAddStory')
   const file = getContext('__pvtStoryFile')
@@ -25,10 +26,16 @@
 
   addStory(story)
 
+  // Collection renders the story's markup purely to discover its variants, but
+  // that markup now reads `state`. Without a value here every expression
+  // referencing it throws and collection fails with a bare
+  // `Cannot read properties of undefined` (#81).
+  const state = initState ? initState() : {}
+
   setContext('__pvtStory', story)
   setContext('__pvtAddVariant', (variant) => {
     story.variants.push(variant)
   })
 </script>
 
-<slot />
+<slot {state} />

package/src/collect/Variant.svelte

@@ -5,6 +5,9 @@
   export let id = null
   export let icon = null
   export let iconColor = null
+  // Declared but unused: collection does not render variant children, and an
+  // undeclared prop would warn on every story that passes one.
+  export let initState = null
 
   const story = getContext('__pvtStory')
   const addVariant = getContext('__pvtAddVariant')

package/src/helpers.ts

@@ -1,6 +1,6 @@
 import type { HstControlOption } from '@poveste/controls'
 import type { Story, StoryProps, Variant, VariantProps } from '@poveste/shared'
-import type { SvelteComponentTyped } from 'svelte'
+import type { Component, Snippet } from 'svelte'
 
 export interface SvelteStorySetupApi {
   app: any
@@ -18,78 +18,113 @@ export const defineSetupSvelte3 = defineSetupSvelte
 export const defineSetupSvelte4 = defineSetupSvelte
 export const defineSetupSvelte5 = defineSetupSvelte
 
+export type StoryState = Record<string, any>
+
+/**
+ * Props plus Svelte 5 children.
+ *
+ * `StoryProps` and `VariantProps` live in `@poveste/shared` and are shared with
+ * the Vue plugin, so a Svelte-only `Snippet` cannot be added there — it is
+ * intersected in here instead.
+ *
+ * This is what the move off `SvelteComponentTyped` needed. The class form carried
+ * Svelte 4 slot typing, so nested content type-checked implicitly; `Component<P>`
+ * has no slots, and Svelte 5 passes children as a prop (#99).
+ */
+type WithChildren<P> = P & {
+  children?: Snippet<[{ state: StoryState }]>
+  controls?: Snippet<[{ state: StoryState }]>
+}
+
+/**
+ * Story state is owned by poveste, not by the story component.
+ *
+ * The story is mounted once per slot, so a component-local variable exists twice
+ * and cannot be shared. `initState` seeds `variant.state`, which both mounts read
+ * and which the sandbox bridge carries across the iframe boundary (#81).
+ */
+type WithState<P> = Omit<P, 'source'> & {
+  initState?: () => StoryState
+  /** A literal, or a function of the variant state so the source panel can track the controls. */
+  source?: string | ((state: StoryState) => string)
+}
+
 export interface Hst {
   // Main built-ins
-  Story: typeof SvelteComponentTyped<StoryProps>
-  Variant: typeof SvelteComponentTyped<VariantProps>
+  Story: Component<WithState<WithChildren<StoryProps>>>
+  Variant: Component<WithState<WithChildren<VariantProps>>>
   // Controls
-  Button: typeof SvelteComponentTyped
-  ButtonGroup: typeof SvelteComponentTyped<{
+  // Deliberately permissive. This was previously a bare `SvelteComponentTyped`,
+  // i.e. props `any`; it wraps a Vue control whose default slot renders the label,
+  // and the prop set `Wrap` forwards is not pinned down. Narrowing it is its own
+  // change rather than a silent break.
+  Button: Component<WithChildren<Record<string, any>>>
+  ButtonGroup: Component<{
     value?: string
     options: (string | HstControlOption)[]
     title?: string
   }>
-  Checkbox: typeof SvelteComponentTyped<{
+  Checkbox: Component<{
     value?: boolean
     title: string
   }>
-  CheckboxList: typeof SvelteComponentTyped<{
+  CheckboxList: Component<{
     value: string[]
     options: (string | HstControlOption)[]
     title?: string
   }>
-  Text: typeof SvelteComponentTyped<{
+  Text: Component<{
     value?: string
     title: string
   }>
-  Number: typeof SvelteComponentTyped<{
+  Number: Component<{
     value?: number
     title: string
     step?: number
   }>
-  Slider: typeof SvelteComponentTyped<{
+  Slider: Component<{
     value?: number
     title: string
     min: number
     max: number
     step?: number
   }>
-  Textarea: typeof SvelteComponentTyped<{
+  Textarea: Component<{
     value?: string
     title: string
   }>
-  Select: typeof SvelteComponentTyped<{
+  Select: Component<{
     value?: string
     title: string
     options: Record<string, any> | string[] | HstControlOption[]
   }>
-  Radio: typeof SvelteComponentTyped<{
+  Radio: Component<{
     value?: string
     options: HstControlOption[]
     title?: string
   }>
-  Json: typeof SvelteComponentTyped<{
+  Json: Component<{
     value: unknown
     title: string
   }>
-  Shades: typeof SvelteComponentTyped<{
+  Shades: Component<{
     shades: Record<string, any>
     getName?: (key: string, color: string) => string
     search?: string
   }>
-  TokenList: typeof SvelteComponentTyped<{
+  TokenList: Component<{
     tokens: Record<string, string | number | any[] | Record<string, any>>
     getName?: (key: string, value: string | number | any[] | Record<string, any>) => string
   }>
-  TokenGrid: typeof SvelteComponentTyped<{
+  TokenGrid: Component<{
     tokens: Record<string, string | number | any[] | Record<string, any>>
     getName?: (key: string, value: string | number | any[] | Record<string, any>) => string
     colSize?: number
   }>
-  CopyIcon: typeof SvelteComponentTyped<{
+  CopyIcon: Component<{
     content: string
   }>
-  ColorSelect: typeof SvelteComponentTyped<{
+  ColorSelect: Component<{
     value?: string
     title: string
   }>

package/src/util/svelte.ts

@@ -111,22 +111,38 @@ export async function callSetupFunctions(
   }
 }
 
+/**
+ * Adds `controlComponent` to a props object **without** spreading it.
+ *
+ * Svelte 5 passes a bound prop as an accessor pair — `bind:value` becomes a
+ * `get value()` / `set value(v)` on the props object. Spreading invokes the
+ * getter and writes a plain data property, so the setter is dropped and the
+ * child's write-back silently goes nowhere: reads keep working, writes stop.
+ * That was the whole of #81.
+ *
+ * Copying the descriptors keeps the setter intact.
+ */
+function withControlComponent(props: any, controlComponent: any) {
+  const merged = Object.defineProperties({}, Object.getOwnPropertyDescriptors(props ?? {}))
+  Object.defineProperty(merged, 'controlComponent', {
+    value: controlComponent,
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  })
+  return merged
+}
+
 export function createWrappedComponent(Wrap: any, controlComponent: any) {
   function ProxyWrap(anchorOrOptions: any, props?: any) {
     if (new.target) {
       return new Wrap({
         ...anchorOrOptions,
-        props: {
-          ...anchorOrOptions?.props,
-          controlComponent,
-        },
+        props: withControlComponent(anchorOrOptions?.props, controlComponent),
       })
     }
 
-    return Wrap(anchorOrOptions, {
-      ...props,
-      controlComponent,
-    })
+    return Wrap(anchorOrOptions, withControlComponent(props, controlComponent))
   }
 
   if (Wrap?.element) {