@poveste/app 0.5.3 → 0.6.0

package/src/app/components/story/StoryVariantSinglePreviewRemote.vue

@@ -1,23 +1,27 @@
 <script lang="ts" setup>
 import type { HstEvent } from '../../stores/events'
 import type { Story, Variant } from '../../types'
-import { applyState } from '@poveste/shared'
 import { useEventListener } from '@vueuse/core'
 import { computed, onBeforeUnmount, ref, toRaw, watch } from 'vue'
 import { useEventsStore } from '../../stores/events'
 import { usePreviewSettingsStore } from '../../stores/preview-settings'
 import { useStoryStore } from '../../stores/story'
-import { EVENT_SEND, PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_HEIGHT, SANDBOX_READY, STATE_SYNC } from '../../util/const'
+import { EVENT_SEND, PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_HEIGHT, SANDBOX_READY, SANDBOX_RETARGET, STATE_SYNC } from '../../util/const'
+import { firstReportedHeight } from '../../util/grid-cell-height'
 import { trackWindow } from '../../util/keyboard'
 import { getSandboxUrl } from '../../util/sandbox'
 import { toRawDeep } from '../../util/state'
+import { createStateBridge } from '../../util/state-bridge'
 import StoryResponsivePreview from './StoryResponsivePreview.vue'
 
-const props = defineProps<{
+const props = withDefaults(defineProps<{
   story: Story
   variant: Variant
   autoHeight?: boolean
-}>()
+  responsive?: boolean
+}>(), {
+  responsive: true,
+})
 
 const settings = usePreviewSettingsStore().currentSettings
 
@@ -25,67 +29,105 @@ const settings = usePreviewSettingsStore().currentSettings
 
 const iframe = ref<HTMLIFrameElement>()
 
-function syncState() {
-  if (iframe.value?.contentWindow && props.variant.previewReady) {
-    iframe.value.contentWindow.postMessage({
-      type: STATE_SYNC,
-      state: toRawDeep(props.variant.state, true),
-    })
-  }
+// The host end of the bridge. It sends what this side changed rather than the
+// whole state, so a write here and a write in the story cannot overwrite each
+// other — see `createStateBridge` for what that used to cost.
+function postState(changes: Record<string, any>) {
+  iframe.value?.contentWindow?.postMessage({
+    type: STATE_SYNC,
+    state: changes,
+  })
 }
 
-// The host end of the bridge, and the same flag as `plugin-vue`'s state sync
-// with the same #95 caveat: `synced` may only be set when the write below will
-// actually provoke the watcher. `applyState` reports that now. Setting it
-// unconditionally means an apply that changes nothing leaves it set, and the
-// next real edit is skipped instead — a control that does nothing.
-let synced = false
+let bridge = createStateBridge(postState)
 
-watch(() => props.variant.state, () => {
-  if (synced) {
-    synced = false
-    return
-  }
+function syncState() {
+  // Nothing can be sent yet, so nothing may be recorded as agreed either — the
+  // baseline would then hold changes the sandbox has never seen, and send it
+  // only the ones that came after. Returning early leaves the first message
+  // that does go out carrying the whole state, which is what it carried before.
+  if (!iframe.value?.contentWindow || !props.variant.previewReady) return
+
+  bridge.send(toRawDeep(props.variant.state, true))
+}
+
+watch(() => props.variant.state, (state, previous) => {
+  // Another variant's state, not a change to this one: this cell was handed a
+  // new occupant (#240). The handover below syncs once the realm reports it in;
+  // sending now would put the new variant's state into the old occupant.
+  if (state !== previous) return
   syncState()
 }, {
   deep: true,
-  immediate: true,
 })
 
 const storyStore = useStoryStore()
 
 storyStore.setPreviewReady(props.variant, false)
 
+// Floor for a reported height, and what a cell shows before its sandbox reports.
+const MIN_HEIGHT = 40
+
+// A cell may grow to its story but not past this, because a grid row is as tall
+// as its tallest item — one long variant would otherwise stretch every sibling
+// in its row to match.
+const MAX_AUTO_HEIGHT = 400
+
 const reportedHeight = ref<number | null>(null)
 
+const placeholderHeight = computed(() => (
+  firstReportedHeight.value?.storyId === props.story.id ? firstReportedHeight.value.height : MIN_HEIGHT
+))
+
+// Whether a message is about the variant this cell shows now. A realm that has
+// just been retargeted can still speak for its old occupant — a height from an
+// observer, a state change from a timer — until it processes the handover, and
+// those must not land on the new one. Unnamed messages come from sandboxes that
+// predate retargeting; take those.
+function fromCurrentOccupant(data: { storyId?: string, variantId?: string }) {
+  return !data.variantId || (data.variantId === props.variant.id && data.storyId === props.story.id)
+}
+
 useEventListener(window, 'message', (event) => {
   // With many grid iframes mounted, every sandbox postMessage hits every
   // parent listener. Skip events that didn't originate from this iframe.
   if (event.source !== iframe.value?.contentWindow) return
   switch (event.data?.type) {
     case STATE_SYNC:
+      if (!fromCurrentOccupant(event.data)) break
       updateVariantState(event.data.state)
       break
     case EVENT_SEND:
       logEvent(event.data.event)
       break
     case SANDBOX_READY:
+      if (!fromCurrentOccupant(event.data)) break
       setPreviewReady()
       break
     case PREVIEW_SETTINGS_REQUEST:
       syncSettings()
       break
     case SANDBOX_HEIGHT:
-      if (typeof event.data.h === 'number') {
-        const next = Math.max(40, event.data.h)
+      if (!fromCurrentOccupant(event.data)) break
+      // The sandbox reports on its first frames, before the story mounts, and
+      // those carry the empty body — 0, or a few px of margin. Clamping one to
+      // the floor would count as a real measurement and lock the cell out of
+      // the placeholder below, which is what left rows stuck at 40px. Anything
+      // under the floor renders as the floor anyway, so nothing is lost by
+      // waiting for a bigger number.
+      if (typeof event.data.h === 'number' && event.data.h >= MIN_HEIGHT) {
+        const next = event.data.h
         if (next !== reportedHeight.value) reportedHeight.value = next
+        if (props.autoHeight && firstReportedHeight.value?.storyId !== props.story.id) {
+          firstReportedHeight.value = { storyId: props.story.id, height: next }
+        }
       }
       break
   }
 })
 
 function updateVariantState(state: any) {
-  synced = applyState(props.variant.state, state)
+  bridge.receive(props.variant.state, state)
 }
 
 function logEvent(event: HstEvent) {
@@ -93,28 +135,97 @@ function logEvent(event: HstEvent) {
   eventsStore.addEvent(event)
 }
 
+// Realm reuse state (#240) — see the block below `sandboxUrl` for the design.
+const REUSE_LIMIT = 30
+const RETARGET_TIMEOUT = 8_000
+const retargeting = ref(false)
+let retargetTimer: ReturnType<typeof setTimeout> | undefined
+
 function setPreviewReady() {
+  retargeting.value = false
+  clearTimeout(retargetTimer)
   storyStore.setPreviewReady(props.variant, true)
+  // A fresh mount starts from the story's own state; what this side holds for
+  // the variant — earlier control edits, or the state it had the last time this
+  // realm showed it — is the truth the story should render.
+  syncState()
 }
 
 const sandboxUrl = computed(() => {
   return getSandboxUrl(props.story, props.variant)
 })
 
+/*
+ * Realm reuse (#240). A sandbox document is a full realm boot — bundle
+ * evaluation, story mount — and same-origin iframes boot serially on one main
+ * thread, so a grid that scrolls pays that for every cell that enters the
+ * window. Instead of changing `src`, a warm realm is told which variant to
+ * show next and remounts it in place: the order of the realm boot cost becomes
+ * the number of cells on screen, not the number scrolled past.
+ *
+ * What survives between occupants is the realm's JS state — globals a story
+ * patched, timers it leaked. Style isolation is untouched. Two valves for
+ * stories that cannot share: `layout.isolate` opts a story back into a cold
+ * document per render — on the way in and on the way out, since what it
+ * leaves behind is the point — and a realm is cold-reloaded after REUSE_LIMIT
+ * retargets so what does accumulate stays bounded. A retarget that never
+ * reports ready falls back to a reload.
+ */
+// What the iframe actually loads. Only a cold (re)load assigns it.
+const iframeSrc = ref(sandboxUrl.value)
 const isIframeLoaded = ref(false)
+let retargets = 0
+// The story whose document the realm holds — booted or retargeted into it.
+let servedStory = props.story
 
 let stopTrackKeyboard: (() => void) | undefined
 let unmounted = false
 
-watch(sandboxUrl, () => {
+function reload(url: string) {
+  retargets = 0
+  retargeting.value = false
+  clearTimeout(retargetTimer)
   isIframeLoaded.value = false
-  storyStore.setPreviewReady(props.variant, false)
+  reportedHeight.value = null
+  servedStory = props.story
   stopTrackKeyboard?.()
   stopTrackKeyboard = undefined
+  // The document the realm booted with is the one wanted again — after a
+  // retarget that timed out, or one past the reuse limit. The binding would
+  // not change, so nothing would load; set the attribute by hand.
+  if (iframeSrc.value === url && iframe.value) iframe.value.src = url
+  iframeSrc.value = url
+}
+
+watch(sandboxUrl, (url) => {
+  // A new occupant has agreed to nothing, so neither has this end. Kept as a
+  // new bridge rather than a reset so there is one way to be in that state.
+  bridge = createStateBridge(postState)
+  storyStore.setPreviewReady(props.variant, false)
+
+  const reuse = props.story.layout?.isolate !== true && servedStory.layout?.isolate !== true
+  const target = iframe.value?.contentWindow
+  if (reuse && isIframeLoaded.value && target && retargets < REUSE_LIMIT) {
+    // Within a story the last height is the best guess until the new occupant
+    // reports; snapping to the placeholder in between made rows jump twice.
+    if (servedStory.id !== props.story.id) reportedHeight.value = null
+    servedStory = props.story
+    retargets++
+    retargeting.value = true
+    target.postMessage({ type: SANDBOX_RETARGET, storyId: props.story.id, variantId: props.variant.id }, window.location.origin)
+    clearTimeout(retargetTimer)
+    retargetTimer = setTimeout(() => {
+      if (retargeting.value && !unmounted) reload(url)
+    }, RETARGET_TIMEOUT)
+    return
+  }
+
+  reload(url)
 })
 
 onBeforeUnmount(() => {
   unmounted = true
+  clearTimeout(retargetTimer)
   stopTrackKeyboard?.()
 })
 
@@ -136,12 +247,33 @@ watch(() => settings, () => {
   immediate: true,
 })
 
+// `auto-height` — the grid — sizes a cell to the story it renders, and that
+// wins over the responsive height. The responsive size is for examining one
+// component at a viewport; applied to every cell it just makes the grid
+// unreadable. A stored `responsiveHeight` of 600 gives 729px cells holding one
+// small button, which is the shape #198 was filed about.
+function previewStyle(isResponsiveEnabled: boolean, finalWidth: number | null, finalHeight: number | null) {
+  const style: Record<string, string> = {}
+
+  if (isResponsiveEnabled) {
+    if (finalWidth) style.width = `${finalWidth}px`
+    if (finalHeight) style.height = `${finalHeight}px`
+  }
+
+  if (props.autoHeight) {
+    style.height = `${Math.min(reportedHeight.value ?? placeholderHeight.value, MAX_AUTO_HEIGHT)}px`
+  }
+
+  return style
+}
+
 // Iframe load
 
 function onIframeLoad() {
   if (unmounted) {
     return
   }
+  retargets = 0
   isIframeLoaded.value = true
   syncState()
   syncSettings()
@@ -157,20 +289,18 @@ function onIframeLoad() {
     v-slot="{ isResponsiveEnabled, finalWidth, finalHeight, resizing }"
     class="poveste-story-variant-single-preview-remote"
     :variant="variant"
+    :responsive="responsive"
   >
     <iframe
       ref="iframe"
-      :src="sandboxUrl"
+      :src="iframeSrc"
       class="w-full h-full relative"
       :class="{
-        'invisible': !isIframeLoaded,
+        'invisible': !isIframeLoaded || retargeting,
         'pointer-events-none': resizing,
       }"
-      :style="isResponsiveEnabled ? {
-        width: finalWidth ? `${finalWidth}px` : null,
-        height: finalHeight ? `${finalHeight}px` : null,
-      } : (props.autoHeight && reportedHeight ? { height: `${reportedHeight}px` } : undefined)"
-      data-test-id="preview-iframe"
+      :style="previewStyle(isResponsiveEnabled, finalWidth, finalHeight)"
+      data-testid="preview-iframe"
       @load="onIframeLoad()"
     />
   </StoryResponsivePreview>

package/src/app/components/story/StoryVariantSingleView.vue

@@ -12,7 +12,7 @@ defineProps<{
 <template>
   <div
     class="poveste-story-variant-single-view h-full flex flex-col"
-    data-test-id="story-variant-single-view"
+    data-testid="story-variant-single-view"
   >
     <StoryVariantSinglePreviewNative
       v-if="story.layout?.iframe === false"

package/src/app/components/toolbar/ToolbarBackground.vue

@@ -26,7 +26,7 @@ const showDropdown = showColorScheme || !!povesteConfig.backgroundPresets.length
     placement="bottom-end"
     :skidding="6"
     class="poveste-toolbar-background flex-none"
-    data-test-id="toolbar-background"
+    data-testid="toolbar-background"
   >
     <!-- The tooltip would sit on top of the first row of the dropdown, so drop
     it while the dropdown is open. -->
@@ -49,17 +49,17 @@ const showDropdown = showColorScheme || !!povesteConfig.backgroundPresets.length
     <template #popper="{ hide }">
       <div
         class="flex flex-col items-stretch"
-        data-test-id="background-popper"
+        data-testid="background-popper"
       >
         <div
           v-if="showColorScheme"
           class="flex items-stretch gap-1 px-2 pt-2"
-          data-test-id="sandbox-color-scheme"
+          data-testid="sandbox-color-scheme"
         >
           <button
             v-for="option in colorSchemeOptions"
             :key="option.value"
-            :data-test-id="`sandbox-color-scheme-${option.value}`"
+            :data-testid="`sandbox-color-scheme-${option.value}`"
             class="flex-1 px-3 py-1.5 rounded flex items-center justify-center gap-1.5 cursor-pointer text-sm"
             :class="[
               settings.colorScheme === option.value

package/src/app/components/tree/StoryGroup.vue

@@ -26,7 +26,7 @@ function toggleOpen() {
 
 <template>
   <div
-    data-test-id="story-group"
+    data-testid="story-group"
     class="poveste-story-group my-2 first:mt-0 last:mb-0 group"
   >
     <template v-if="group.title">

package/src/app/components/tree/StoryListFolder.vue

@@ -31,7 +31,7 @@ const folderPadding = computed(() => {
 
 <template>
   <div
-    data-test-id="story-list-folder"
+    data-testid="story-list-folder"
     class="poveste-story-list-folder"
   >
     <div

package/src/app/components/tree/StoryListItem.vue

@@ -26,7 +26,7 @@ useScrollOnActive(isActive, el)
 <template>
   <div
     ref="el"
-    data-test-id="story-list-item"
+    data-testid="story-list-item"
     class="poveste-story-list-item"
   >
     <BaseListItemLink

package/src/app/index.ts

@@ -1,12 +1,22 @@
+import { addCollection } from '@iconify/vue'
 import FloatingVue from 'floating-vue'
 import { createPinia } from 'pinia'
 import { createApp } from 'vue'
 import App from './App.vue'
 import { setupPluginApi } from './plugin.js'
 import { router } from './router'
+import { iconCollections } from './util/icons.generated.js'
 import 'virtual:$poveste-theme'
 
 export async function mountMainApp() {
+  // The chrome's icon data ships with the app. Without this every Icon fetched
+  // its data from api.iconify.design at runtime — a handful of CDN requests per
+  // boot, and no toolbar offline (#219). Story icons a user sets still resolve
+  // through the runtime lookup.
+  for (const collection of iconCollections) {
+    addCollection(collection)
+  }
+
   const app = createApp(App)
   app.use(createPinia())
   app.use(FloatingVue, {

package/src/app/sandbox.ts

@@ -1,22 +1,42 @@
 import type { StoryFile } from './types'
-import { applyState } from '@poveste/shared'
 import { usePreferredDark } from '@vueuse/core'
 import { createPinia } from 'pinia'
-import { files } from 'virtual:$poveste-stories'
+import { files, onUpdate } from 'virtual:$poveste-stories'
 import { computed, createApp, h, onMounted, ref, watch } from 'vue'
 import { parseQuery } from 'vue-router'
 import GenericMountStory from './components/story/GenericMountStory.vue'
 import GenericRenderStory from './components/story/GenericRenderStory.vue'
-import { setupPluginApi } from './plugin.js'
 import { previewDarkClasses, resolvePreviewDark } from './util/color-scheme.js'
-import { PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_HEIGHT, SANDBOX_READY, STATE_SYNC } from './util/const.js'
+import { PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_HEIGHT, SANDBOX_READY, SANDBOX_RETARGET, STATE_SYNC } from './util/const.js'
 import { isDark } from './util/dark.js'
 import { mapFile } from './util/mapping'
 import { applyPreviewSettings, loadStoredPreviewSettings, receivedSettings } from './util/preview-settings.js'
+import { createStateBridge } from './util/state-bridge.js'
 import { toRawDeep } from './util/state.js'
 
 const query = parseQuery(window.location.search)
-const file = ref<StoryFile>(mapFile(files.find(f => f.id === query.storyId)))
+
+// What this realm serves. Set from the URL on boot, and again by a
+// SANDBOX_RETARGET from the host: a warm realm is handed the next story or
+// variant instead of being torn down for a new document (#240).
+const storyId = ref(typeof query.storyId === 'string' ? query.storyId : null)
+const variantId = ref(typeof query.variantId === 'string' ? query.variantId : null)
+
+// `files` is `[]` until the dev server's first collect lands. The app's iframe
+// never sees that — it mounts after — but a sandbox opened on its own does, and
+// the list only arrives through `onUpdate`.
+const file = ref<StoryFile | null>(null)
+function resolveFile(list: StoryFile[] = files) {
+  const found = list.find(f => f.id === storyId.value)
+  // Same story, different variant: keep the mapped file so the story component
+  // is not remounted for a variant switch.
+  if (found && file.value?.story.id === found.id) return
+  file.value = found ? mapFile(found) : null
+}
+resolveFile()
+onUpdate((newFiles: StoryFile[]) => {
+  if (!file.value) resolveFile(newFiles)
+})
 
 // Sandboxes opened on their own (the "open in a new tab" toolbar button) never
 // receive a PREVIEW_SETTINGS_SYNC, and inside the app the first one only lands
@@ -72,41 +92,64 @@ watch(previewDark, (value) => {
   immediate: true,
 })
 
+// Height reporting state, declared here because the retarget handler inside the
+// app resets it.
+let pendingFrame: number | null = null
+let lastReportedHeight = -1
+
 const app = createApp({
   name: 'SandboxApp',
 
   setup() {
-    const story = computed(() => file.value.story)
-    const variant = computed(() => story.value?.variants.find(v => v.id === query.variantId))
-
-    // `synced` is the sandbox end of the same flag the host holds, with the same
-    // #95 caveat: only set it when the apply will actually provoke the watcher
-    // below, which is what `applyState`'s return value reports. Set it
-    // unconditionally and an apply that changes nothing leaves it stuck, so the
-    // next edit the story makes never reaches the host.
-    let synced = false
+    const story = computed(() => file.value?.story)
+    const variant = computed(() => story.value?.variants.find(v => v.id === variantId.value))
+
+    // The sandbox end of the bridge. It sends what the story changed rather than
+    // the whole state, so a write here and a control edit on the host cannot
+    // overwrite each other — see `createStateBridge` for what that used to cost.
+    // Named, like SANDBOX_READY and SANDBOX_HEIGHT: after a retarget the host
+    // is waiting on the new occupant, and anything the old one still says
+    // must be told apart from that.
+    const postState = (changes: Record<string, any>) => {
+      window.parent?.postMessage({
+        type: STATE_SYNC,
+        state: changes,
+        storyId: storyId.value,
+        variantId: variantId.value,
+      })
+    }
+    let bridge = createStateBridge(postState)
     let mounted = false
 
     window.addEventListener('message', (event) => {
       // console.log('[sandbox] received message', event.data)
       if (event.data?.type === STATE_SYNC) {
-        if (!mounted) return
-        synced = applyState(variant.value.state, event.data.state)
+        if (!mounted || !variant.value) return
+        bridge.receive(variant.value.state, event.data.state)
       }
       else if (event.data?.type === PREVIEW_SETTINGS_SYNC) {
         applyPreviewSettings(event.data.settings)
       }
+      else if (event.data?.type === SANDBOX_RETARGET) {
+        // A new occupant: nothing has been agreed with the host about it, and
+        // the last height belonged to the old one. The keyed render below
+        // remounts and reports both afresh.
+        bridge = createStateBridge(postState)
+        lastReportedHeight = -1
+        variantId.value = typeof event.data.variantId === 'string' ? event.data.variantId : null
+        storyId.value = typeof event.data.storyId === 'string' ? event.data.storyId : null
+        resolveFile()
+      }
     })
 
-    watch(() => variant.value.state, (value) => {
-      if (synced && mounted) {
-        synced = false
-        return
-      }
-      window.parent?.postMessage({
-        type: STATE_SYNC,
-        state: toRawDeep(value, true),
-      })
+    watch(() => variant.value?.state, (value, previous) => {
+      // A retarget swapped the occupant, not a story writing its state. The
+      // new one has agreed to nothing yet, and a send here would carry its
+      // whole state — defaults, or a copy left from the last time this realm
+      // served it — over what the host holds, and the host's does come down
+      // once the new mount reports ready.
+      if (!value || value !== previous) return
+      bridge.send(toRawDeep(value, true))
     }, {
       deep: true,
     })
@@ -122,18 +165,36 @@ const app = createApp({
   },
 
   render() {
+    if (!file.value) {
+      return null
+    }
+
     return [
       h('div', { class: '__poveste-sandbox-hidden' }, [
         h(GenericMountStory, {
           key: file.value.story.id,
           story: file.value.story,
+          // This realm serves exactly one variant at a time; a plugin that
+          // mounts variants can skip all the others (#197). Falls through
+          // GenericMountStory as an attr, so plugins that don't know the prop
+          // ignore it.
+          targetVariantId: variantId.value,
         }),
       ]),
       this.story && this.variant
-        ? h(GenericRenderStory, { story: this.story, variant: this.variant, onReady: () => {
+        // Keyed so a retarget is a clean unmount and mount, not a prop update
+        // into a host that is halfway through rendering the previous occupant.
+        ? h(GenericRenderStory, { key: `${this.story.id}/${this.variant.id}`, story: this.story, variant: this.variant, onReady: () => {
+            // Named, so a host that has since retargeted this realm can tell a
+            // late ready for the old occupant from the one it is waiting for.
             window.parent?.postMessage({
               type: SANDBOX_READY,
+              storyId: this.story.id,
+              variantId: this.variant.id,
             })
+            // A retarget to a same-height story would otherwise never report:
+            // the observer only fires on a change.
+            scheduleReport()
           } })
         : null,
     ]
@@ -148,8 +209,6 @@ app.mount('#app')
 // source-level rules that add overflow/min-height to the render root.
 document.body.classList.add('__poveste-render-story', '__poveste-render-custom-controls')
 
-let pendingFrame: number | null = null
-let lastReportedHeight = -1
 function reportHeight() {
   pendingFrame = null
   const renderRoot = document.querySelector('.__poveste-render-story')
@@ -160,7 +219,7 @@ function reportHeight() {
   lastReportedHeight = h
   // Same-origin: parent and iframe are both served by the poveste dev /
   // build server, so scope the target rather than broadcasting.
-  window.parent?.postMessage({ type: SANDBOX_HEIGHT, h }, window.location.origin)
+  window.parent?.postMessage({ type: SANDBOX_HEIGHT, h, storyId: storyId.value, variantId: variantId.value }, window.location.origin)
 }
 function scheduleReport() {
   if (pendingFrame !== null) return
@@ -170,6 +229,11 @@ const ro = new ResizeObserver(scheduleReport)
 ro.observe(document.body)
 requestAnimationFrame(scheduleReport)
 
-if (import.meta.hot) {
-  /* #__PURE__ */ setupPluginApi()
+// Dev only, and loaded lazily on purpose: a static import of `plugin.js`
+// carried the app router — and through its lazy routes every app view and
+// their CSS — into the sandbox graph, so each sandbox realm parsed ~100 KB of
+// chrome styles it can never match (#219). `import.meta.env.DEV` is a build-time
+// literal, so the whole branch, dynamic import included, drops out of a build.
+if (import.meta.env.DEV && import.meta.hot) {
+  import('./plugin.js').then(({ setupPluginApi }) => setupPluginApi())
 }