@poveste/app 0.18.3 → 0.19.1

package/dist/bundled/util/const.js

@@ -6,5 +6,6 @@ var PREVIEW_SETTINGS_SYNC = "__poveste:preview-settings-sync";
 var PREVIEW_SETTINGS_REQUEST = "__poveste:preview-settings-request";
 var SANDBOX_HEIGHT = "__poveste:sandbox-height";
 var SANDBOX_RETARGET = "__poveste:sandbox-retarget";
+var SANDBOX_COLOR_SCHEME = "__poveste:sandbox-color-scheme";
 //#endregion
-export { EVENT_SEND, PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_HEIGHT, SANDBOX_READY, SANDBOX_RETARGET, STATE_SYNC };
+export { EVENT_SEND, PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_COLOR_SCHEME, SANDBOX_HEIGHT, SANDBOX_READY, SANDBOX_RETARGET, STATE_SYNC };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/app",
   "type": "module",
-  "version": "0.18.3",
+  "version": "0.19.1",
   "description": "Pre-bundled UI for Poveste",
   "author": {
     "name": "Sorin Gitlan",
@@ -27,6 +27,8 @@
     "./*": "./*"
   },
   "files": [
+    "!src/**/*.spec.ts",
+    "!src/**/__tests__",
     "dist",
     "src"
   ],
@@ -34,9 +36,9 @@
     "node": ">=22.22.2"
   },
   "dependencies": {
-    "@poveste/controls": "^0.18.3",
-    "@poveste/shared": "^0.18.3",
-    "@poveste/vendors": "^0.18.3",
+    "@poveste/controls": "^0.19.1",
+    "@poveste/shared": "^0.19.1",
+    "@poveste/vendors": "^0.19.1",
     "fuse.js": "^7.0.0",
     "shiki": "^4.4.3"
   },

package/src/app/components/command/PromptSelect.vue

@@ -46,7 +46,8 @@ watchEffect(async () => {
     const rId = ++requestId
     const result = await props.prompt.options(search.value, props.answers)
     if (rId === requestId) {
-      options.value = result
+      // Undefined when no plugin answered, or the one that should have threw (#1170).
+      options.value = result ?? []
     }
   }
   else {

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

@@ -0,0 +1,23 @@
+<!--
+  Around a story the app renders itself, so the dark class on its render root is
+  reachable by the book's CSS (#332).
+
+  A book's CSS is wrapped in `@scope (.__poveste-render-story)`, where a rule
+  shaped `.dark .foo` needs `.dark` strictly inside a scope root: on the root
+  itself it matches nothing. This is a second root one level out, which makes the
+  render root an element inside a scope. The sandbox has the same two levels,
+  `body` and `#app` (#101).
+
+  No box, so nothing is laid out differently, and `!important` because a book's
+  `:root { display }` rule lands on every scope root. The custom-controls class
+  keeps this from being the boundary the chrome's own CSS stops at, which stays
+  the render root, as `body` does in the sandbox.
+-->
+<template>
+  <div
+    class="__poveste-render-story __poveste-render-custom-controls"
+    style="display: contents !important"
+  >
+    <slot />
+  </div>
+</template>

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

@@ -8,7 +8,7 @@ import { computed, nextTick, ref, toRefs, watch } from 'vue'
 import { useRouter } from 'vue-router'
 import { usePreviewSettingsStore } from '../../stores/preview-settings'
 import { useStoryStore } from '../../stores/story'
-import { previewDarkClasses, usePreviewDark } from '../../util/color-scheme'
+import { previewDarkClasses, usePreviewColorScheme, usePreviewDark } from '../../util/color-scheme'
 import { povesteConfig } from '../../util/config'
 import { getSourceCode } from '../../util/docs'
 import { getContrastColor } from '../../util/preview-settings'
@@ -17,6 +17,7 @@ import { useCurrentVariantRoute } from '../../util/variant'
 import CheckerboardPattern from '../misc/CheckerboardPattern.vue'
 import ToolbarNewTab from '../toolbar/ToolbarNewTab.vue'
 import GenericRenderStory from './GenericRenderStory.vue'
+import StoryNativeScope from './StoryNativeScope.vue'
 import StoryVariantSinglePreviewRemote from './StoryVariantSinglePreviewRemote.vue'
 
 const props = defineProps({
@@ -91,6 +92,7 @@ watch(() => props.variant.previewReady, (ready) => {
 const settings = usePreviewSettingsStore().currentSettings
 
 const previewDark = usePreviewDark(settings)
+const previewColorScheme = usePreviewColorScheme(settings)
 
 const contrastColor = computed(() => getContrastColor(settings))
 const autoApplyContrastColor = computed(() => !!povesteConfig.autoApplyContrastColor)
@@ -183,15 +185,17 @@ const useIframe = computed(() => {
           auto-height
           :responsive="false"
         />
-        <GenericRenderStory
-          v-else
-          :key="`${story.id}-${variant.id}`"
-          :variant="variant"
-          :story="story"
-          :dir="settings.textDirection"
-          :class="previewDark ? previewDarkClasses() : undefined"
-          @ready="onReady"
-        />
+        <StoryNativeScope v-else>
+          <GenericRenderStory
+            :key="`${story.id}-${variant.id}`"
+            :variant="variant"
+            :story="story"
+            :dir="settings.textDirection"
+            :class="previewDark ? previewDarkClasses() : undefined"
+            :style="{ '--poveste-color-scheme': previewColorScheme }"
+            @ready="onReady"
+          />
+        </StoryNativeScope>
       </div>
     </div>
   </div>

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

@@ -3,10 +3,11 @@ import type { Story, Variant } from '../../types'
 import { computed, watch } from 'vue'
 import { usePreviewSettingsStore } from '../../stores/preview-settings'
 import { useStoryStore } from '../../stores/story'
-import { previewDarkClasses, usePreviewDark } from '../../util/color-scheme'
+import { previewDarkClasses, usePreviewColorScheme, usePreviewDark } from '../../util/color-scheme'
 import { povesteConfig } from '../../util/config'
 import { getContrastColor } from '../../util/preview-settings'
 import GenericRenderStory from './GenericRenderStory.vue'
+import StoryNativeScope from './StoryNativeScope.vue'
 import StoryResponsivePreview from './StoryResponsivePreview.vue'
 
 const props = defineProps<{
@@ -36,6 +37,7 @@ function onReady() {
 const settings = usePreviewSettingsStore().currentSettings
 
 const previewDark = usePreviewDark(settings)
+const previewColorScheme = usePreviewColorScheme(settings)
 
 const contrastColor = computed(() => getContrastColor(settings))
 const autoApplyContrastColor = computed(() => !!povesteConfig.autoApplyContrastColor)
@@ -63,15 +65,18 @@ const autoApplyContrastColor = computed(() => !!povesteConfig.autoApplyContrastC
       class="relative"
       data-testid="sandbox-render"
     >
-      <GenericRenderStory
-        :key="`${story.id}-${variant.id}`"
-        :variant="variant"
-        :story="story"
-        class="h-full"
-        :class="previewDark ? previewDarkClasses() : undefined"
-        :dir="settings.textDirection"
-        @ready="onReady"
-      />
+      <StoryNativeScope>
+        <GenericRenderStory
+          :key="`${story.id}-${variant.id}`"
+          :variant="variant"
+          :story="story"
+          class="h-full"
+          :class="previewDark ? previewDarkClasses() : undefined"
+          :style="{ '--poveste-color-scheme': previewColorScheme }"
+          :dir="settings.textDirection"
+          @ready="onReady"
+        />
+      </StoryNativeScope>
     </div>
   </StoryResponsivePreview>
 </template>

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

@@ -9,7 +9,8 @@ import { useEventsStore } from '../../stores/events'
 import { usePreviewSettingsStore } from '../../stores/preview-settings'
 import { useStoryStore } from '../../stores/story'
 import { useStoryErrorStore } from '../../stores/story-errors'
-import { EVENT_SEND, PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_HEIGHT, SANDBOX_READY, SANDBOX_RETARGET, STATE_SYNC } from '../../util/const'
+import { usePreviewColorScheme } from '../../util/color-scheme'
+import { EVENT_SEND, PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_COLOR_SCHEME, SANDBOX_HEIGHT, SANDBOX_READY, SANDBOX_RETARGET, STATE_SYNC } from '../../util/const'
 import { firstReportedHeight } from '../../util/grid-cell-height'
 import { trackWindow } from '../../util/keyboard'
 import { createRenderTracker } from '../../util/render-tracker'
@@ -28,6 +29,10 @@ const props = withDefaults(defineProps<{
 })
 
 const settings = usePreviewSettingsStore().currentSettings
+const previewColorScheme = usePreviewColorScheme(settings)
+// What the sandbox root computed, which a book's own rule can make differ from
+// the setting. Until its document reports, the setting is the best guess.
+const sandboxColorScheme = ref<string | null>(null)
 const errorStore = useStoryErrorStore()
 
 const storyError = computed(() => errorStore.forVariant(props.story.id, props.variant.id))
@@ -133,6 +138,9 @@ useEventListener(window, 'message', (event) => {
     case PREVIEW_SETTINGS_REQUEST:
       syncSettings()
       break
+    case SANDBOX_COLOR_SCHEME:
+      if (typeof event.data.scheme === 'string') sandboxColorScheme.value = event.data.scheme
+      break
     case SANDBOX_HEIGHT:
       if (!fromCurrentOccupant(event.data)) break
       // The sandbox reports on its first frames, before the story mounts, and
@@ -288,7 +296,10 @@ watch(() => settings, () => {
 // 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> = {}
+  // The sandbox root's own value, on the element that embeds it. Where the two
+  // differ the browser paints the frame opaque, and the background preset and
+  // checkerboard behind it are gone (#1167).
+  const style: Record<string, string> = { colorScheme: sandboxColorScheme.value ?? previewColorScheme.value }
 
   if (isResponsiveEnabled) {
     if (finalWidth) style['width'] = `${finalWidth}px`

package/src/app/index.ts

@@ -1,10 +1,12 @@
 import { addCollection } from '@iconify/vue'
 import { createPinia } from 'pinia'
 import { generation } from 'virtual:$poveste-stories'
-import { createApp } from 'vue'
+import { createApp, watch } from 'vue'
 import App from './App.vue'
 import { setupPluginApi } from './plugin.js'
 import { router } from './router'
+import { installRenderRootColorScheme } from './util/color-scheme.js'
+import { isDark } from './util/dark.js'
 import { iconCollections } from './util/icons.generated.js'
 import 'virtual:$poveste-theme'
 
@@ -17,6 +19,14 @@ export async function mountMainApp() {
     addCollection(collection)
   }
 
+  // The chrome's own scheme, for the browser: it paints the chrome's native
+  // controls and scrollbars, and reads no class (#991). Here rather than in the
+  // chrome stylesheet, which style isolation rewrites from `html` to the app root.
+  watch(isDark, (dark) => {
+    document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
+  }, { immediate: true })
+  installRenderRootColorScheme()
+
   const app = createApp(App)
   app.use(createPinia())
   app.use(router)
@@ -26,6 +36,8 @@ export async function mountMainApp() {
     // Which story list this page holds, so a page that missed its update is sent it (#1218).
     import.meta.hot.send('poveste:mount', { generation })
 
-    /* #__PURE__ */ setupPluginApi()
+    // Not `#__PURE__`: the call is nothing but side effects, and that annotation
+    // let the bundler drop it, so dev never had the plugin API here (#1064).
+    setupPluginApi()
   }
 }

package/src/app/router.ts

@@ -1,3 +1,4 @@
+import type { Router } from 'vue-router'
 import { createRouter, createWebHashHistory, createWebHistory } from 'vue-router'
 import { povesteConfig } from './util/config'
 
@@ -12,18 +13,28 @@ function createRouterHistory() {
   }
 }
 
-export const router = createRouter({
-  history: createRouterHistory(),
-  routes: [
-    {
-      path: '/',
-      name: 'home',
-      component: () => import('./components/HomeView.vue'),
-    },
-    {
-      path: '/story/:storyId',
-      name: 'story',
-      component: () => import('./components/story/StoryView.vue'),
-    },
-  ],
-})
+function newRouter(): Router {
+  return createRouter({
+    history: createRouterHistory(),
+    routes: [
+      {
+        path: '/',
+        name: 'home',
+        component: () => import('./components/HomeView.vue'),
+      },
+      {
+        path: '/story/:storyId',
+        name: 'story',
+        component: () => import('./components/story/StoryView.vue'),
+      },
+    ],
+  })
+}
+
+// A page in `poveste dev` can hold two copies of this module: each importer's
+// URL is stamped when the server serves it, and a story edit stamps most of the
+// chrome. Every copy hands out the router the app installed, or the story store
+// read one still at `/` and the page showed no story until reloaded (#1320).
+export const router: Router = import.meta.hot
+  ? (import.meta.hot.data.router ??= newRouter())
+  : newRouter()

package/src/app/sandbox.ts

@@ -1,4 +1,5 @@
 import type { StoryFile } from './types'
+import { addCollection } from '@iconify/vue'
 import { reportStoryError } from '@poveste/shared'
 import { usePreferredDark } from '@vueuse/core'
 import { createPinia } from 'pinia'
@@ -7,9 +8,10 @@ import { computed, createApp, h, onMounted, ref, watch, watchEffect } from 'vue'
 import { parseQuery } from 'vue-router'
 import GenericMountStory from './components/story/GenericMountStory.vue'
 import GenericRenderStory from './components/story/GenericRenderStory.vue'
-import { previewDarkClasses, resolvePreviewDark } from './util/color-scheme.js'
-import { PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_HEIGHT, SANDBOX_READY, SANDBOX_RETARGET, STATE_SYNC } from './util/const.js'
+import { lowPriorityColorScheme, previewColorScheme, previewDarkClasses, resolvePreviewDark } from './util/color-scheme.js'
+import { PREVIEW_SETTINGS_REQUEST, PREVIEW_SETTINGS_SYNC, SANDBOX_COLOR_SCHEME, SANDBOX_HEIGHT, SANDBOX_READY, SANDBOX_RETARGET, STATE_SYNC } from './util/const.js'
 import { isDark } from './util/dark.js'
+import { iconCollections } from './util/icons.generated.js'
 import { mapFile } from './util/mapping'
 import { occupant } from './util/occupant.js'
 import { applyPreviewSettings, loadStoredPreviewSettings, receivedSettings } from './util/preview-settings.js'
@@ -117,11 +119,46 @@ watch(previewDark, (value) => {
   immediate: true,
 })
 
+// The `<iframe>` element has to declare what this root ends up with, or the
+// browser paints the frame opaque over the background preset (#1167). A book
+// rule may win over the setting, so only this side knows: report the computed
+// value whenever a stylesheet or the root's class can have changed it.
+let reportedColorScheme = ''
+function reportColorScheme() {
+  if (window.parent === window) return
+  const scheme = getComputedStyle(document.documentElement).colorScheme
+  if (scheme === reportedColorScheme) return
+  reportedColorScheme = scheme
+  window.parent.postMessage({ type: SANDBOX_COLOR_SCHEME, scheme }, window.location.origin)
+}
+new MutationObserver(reportColorScheme).observe(document.head, { childList: true, subtree: true, characterData: true })
+new MutationObserver(reportColorScheme).observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'style'] })
+// A `<link>` applies when it loads, after the mutation that inserted it.
+document.addEventListener('load', reportColorScheme, true)
+
+// The sandbox is a document of its own, so the property goes on its root, where
+// it reaches every native widget the story renders (#991).
+const setRootColorScheme = lowPriorityColorScheme(':root')
+watch(() => previewColorScheme(receivedSettings.colorScheme, isDark.value), (value) => {
+  setRootColorScheme(value)
+  reportColorScheme()
+}, {
+  immediate: true,
+})
+
 // Height reporting state, declared here because the retarget handler inside the
 // app resets it.
 let pendingFrame: number | null = null
 let lastReportedHeight = -1
 
+// A builtin control rendered in a story draws the chrome's icons, and each
+// realm has an icon store of its own. Without the data here, a select or a date
+// control in a story fetched its icon from api.iconify.design, in every sandbox,
+// and had none offline (#255).
+for (const collection of iconCollections) {
+  addCollection(collection)
+}
+
 const app = createApp({
   name: 'SandboxApp',
 
@@ -249,6 +286,8 @@ document.body.classList.add('__poveste-render-story', '__poveste-render-custom-c
 
 function reportHeight() {
   pendingFrame = null
+  // A story mounting or resizing can change which book rules match the root.
+  reportColorScheme()
   const renderRoot = document.querySelector('.__poveste-render-story')
   const h = renderRoot
     ? Math.ceil(renderRoot.getBoundingClientRect().height)

package/src/app/stores/preview-settings.ts

@@ -1,33 +1,71 @@
 import type { PreviewSettings } from '../types'
 import { useStorage } from '@vueuse/core'
 import { defineStore } from 'pinia'
+import { watch } from 'vue'
 import { defaultPreviewColorScheme } from '../util/color-scheme'
 import { povesteConfig } from '../util/config'
 import { PREVIEW_SETTINGS_STORAGE_KEY } from '../util/preview-settings'
 
+// What a book can open the preview at, as groups of settings that change
+// together: a preset or a drag sets the width and height at once.
+const UNITS: (keyof PreviewSettings)[][] = [
+  ['responsiveWidth', 'responsiveHeight'],
+  ['backgroundColor'],
+  ['rotate'],
+  ['checkerboard'],
+  ['textDirection'],
+]
+
+/** The book's `preview` config, with the deprecated `defaultBackgroundColor` under it. */
+function configured(): Partial<PreviewSettings> {
+  // eslint-disable-next-line ts/no-deprecated
+  const legacy = povesteConfig.defaultBackgroundColor
+  return { ...(legacy === undefined ? {} : { backgroundColor: legacy }), ...povesteConfig.preview }
+}
+
 export const usePreviewSettingsStore = defineStore('preview-settings', () => {
+  const book = configured()
   const currentSettings = useStorage<PreviewSettings>(PREVIEW_SETTINGS_STORAGE_KEY, {
     responsiveWidth: 720,
     responsiveHeight: null,
     rotate: false,
-    backgroundColor: povesteConfig.defaultBackgroundColor ?? 'transparent',
+    backgroundColor: 'transparent',
     backgroundColorPicked: false,
     checkerboard: false,
     textDirection: 'ltr',
     colorScheme: defaultPreviewColorScheme,
+    ...book,
   })
 
-  // useStorage honors its default only on first run, so already-stored settings
-  // would never see `defaultBackgroundColor` (nor a later change to it). Re-apply
-  // it on every load until the user picks a color from the toolbar; the flag lives
-  // in the settings object so it travels with the value it describes.
-  const configBg = povesteConfig.defaultBackgroundColor
-  if (configBg && !currentSettings.value.backgroundColorPicked) {
-    currentSettings.value.backgroundColor = configBg
+  // useStorage honours its default only on first run, so a reader with stored
+  // settings would never see the book's values, nor a later change to them.
+  // Re-applied on every load, per unit, until the reader changes that unit. A
+  // stored `backgroundColorPicked` predates `picked` and counts as picking.
+  const picked = new Set(currentSettings.value.picked ?? [])
+  if (currentSettings.value.backgroundColorPicked) {
+    picked.add('backgroundColor')
+  }
+  for (const unit of UNITS) {
+    if (picked.has(unit[0]!)) {
+      continue
+    }
+    for (const key of unit) {
+      if (book[key] !== undefined) {
+        Object.assign(currentSettings.value, { [key]: book[key] })
+      }
+    }
+  }
+
+  // Set up after the re-apply, so only the reader's own changes count: the
+  // toolbar, the size inputs and the drag handles all write these settings.
+  for (const unit of UNITS) {
+    watch(() => unit.map(key => currentSettings.value[key]), () => {
+      currentSettings.value.picked = [...new Set([...(currentSettings.value.picked ?? []), unit[0]!])]
+    })
   }
 
-  // Same reason: settings stored before `colorScheme` existed would leave it
-  // undefined, so the toolbar would show no active option.
+  // Settings stored before `colorScheme` existed would leave it undefined, so
+  // the toolbar would show no active option.
   currentSettings.value.colorScheme ??= defaultPreviewColorScheme
 
   function setBackgroundColor(color: string) {

package/src/app/types.ts

@@ -78,11 +78,17 @@ export interface PreviewSettings {
   backgroundColor: string
   /**
    * Whether `backgroundColor` came from an explicit toolbar pick rather than
-   * from the `defaultBackgroundColor` config option.
+   * from the book's config. Kept for settings stored before `picked`.
    *
    * @default false
    */
   backgroundColorPicked: boolean
+  /**
+   * The settings the reader has changed from the toolbar, which a book's
+   * `preview` config stops re-applying. The size is one entry,
+   * `responsiveWidth`, for both its width and height.
+   */
+  picked?: string[]
   /**
    * Show a checkerboard pattern behind the story, to spot transparency.
    *

package/src/app/util/color-scheme.ts

@@ -25,6 +25,50 @@ export function resolvePreviewDark(colorScheme: SandboxColorScheme | undefined,
   }
 }
 
+/**
+ * The CSS `color-scheme` a preview declares, from the same inputs as the class.
+ *
+ * The class tells the book's CSS; this tells the browser, which paints native
+ * widgets, scrollbars and the canvas itself and reads no class (#991). `auto`
+ * becomes `light dark`, so the browser follows the OS preference on its own
+ * rather than being told the answer `prefersDark` already computed.
+ */
+export function previewColorScheme(colorScheme: SandboxColorScheme | undefined, chromeDark: boolean): 'light' | 'dark' | 'light dark' {
+  switch (colorScheme) {
+    case 'light': return 'light'
+    case 'dark': return 'dark'
+    case 'auto': return 'light dark'
+    default: return chromeDark ? 'dark' : 'light'
+  }
+}
+
+/**
+ * Declares `color-scheme` on `selector` beneath any rule a book writes: in the
+ * first cascade layer of the document, at zero specificity. Set inline, it beat
+ * a book's own `:root { color-scheme }` on every render path (#1167).
+ */
+export function lowPriorityColorScheme(selector: string) {
+  const style = document.createElement('style')
+  document.head.prepend(style)
+  return (value: string) => {
+    style.textContent = `@layer poveste-color-scheme { :where(${selector}) { color-scheme: ${value}; } }`
+  }
+}
+
+/**
+ * Previews the app renders itself carry their scheme as a custom property, which
+ * this applies to their root at the same low priority. Style isolation moves a
+ * book's own `:root` rule onto that root, so it wins.
+ */
+export function installRenderRootColorScheme() {
+  lowPriorityColorScheme('.__poveste-render-story')('var(--poveste-color-scheme)')
+}
+
+/** `previewColorScheme`, for previews rendered by the app itself. */
+export function usePreviewColorScheme(settings: PreviewSettings) {
+  return computed(() => previewColorScheme(settings.colorScheme, isDark.value))
+}
+
 /**
  * Whether the story preview should be rendered dark, for previews rendered by
  * the app itself. The sandbox resolves the same thing from the settings it

package/src/app/util/commands.ts

@@ -46,15 +46,27 @@ export const builtinCommands: ClientCommand[] = [
   },
 ]
 
-export function executeCommand(command: ClientCommand, params: Record<string, any>) {
-  if (import.meta.hot) {
-    import.meta.hot.send('poveste:dev-command', {
-      id: command.id,
-      params,
-    })
+export async function executeCommand(command: ClientCommand, params: Record<string, any>) {
+  const hot = import.meta.hot
+  if (!hot) return
 
-    command.clientAction?.(params, getCommandContext())
+  // The client half waits for the server's: a generated story was opened before its
+  // file existed, and opened anyway when writing it failed (#1176).
+  const result = await new Promise<{ id: string, error?: string }>((resolve) => {
+    const listener = (data: { id: string, error?: string }) => {
+      if (data.id !== command.id) return
+      hot.off('poveste:dev-command-result', listener)
+      resolve(data)
+    }
+    hot.on('poveste:dev-command-result', listener)
+    hot.send('poveste:dev-command', { id: command.id, params })
+  })
+
+  if (result.error) {
+    console.error(`[poveste] ${command.label}: ${result.error}`)
+    return
   }
+  command.clientAction?.(params, getCommandContext())
 }
 
 export function getCommandContext(): ClientCommandContext {

package/src/app/util/const.ts

@@ -5,3 +5,4 @@ export const PREVIEW_SETTINGS_SYNC = '__poveste:preview-settings-sync'
 export const PREVIEW_SETTINGS_REQUEST = '__poveste:preview-settings-request'
 export const SANDBOX_HEIGHT = '__poveste:sandbox-height'
 export const SANDBOX_RETARGET = '__poveste:sandbox-retarget'
+export const SANDBOX_COLOR_SCHEME = '__poveste:sandbox-color-scheme'

package/src/__tests__/base-select.spec.ts

@@ -1,25 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { describe, expect, it } from 'vitest'
-
-/*
- * The same defect as `@poveste/controls`' own select, in the chrome's copy: the
- * options are portalled to `body`, which carries no colour, so a background
- * without a text colour left them at the UA default — black on the dark panel.
- *
- * `__dirname` rather than `import.meta.url`, which vitest's transform does not
- * leave intact here — the trap `icons.spec.ts` records.
- */
-const source = readFileSync(resolve(__dirname, '../app/components/base/BaseSelect.vue'), 'utf8')
-
-describe('the chrome select options', () => {
-  const classes = /class="poveste-base-select-options([^"]*)"/.exec(source)?.[1] ?? ''
-
-  it('carries a text colour, not only a background', () => {
-    expect(classes).toMatch(/\btext-gray-\d+\b/)
-  })
-
-  it('carries one for dark as well', () => {
-    expect(classes).toMatch(/\bdark:text-gray-\d+\b/)
-  })
-})