@dfosco/storyboard 0.5.0-alpha.0

package/src/core/data/viewfinder.test.js

@@ -0,0 +1,456 @@
+import { init } from './loader.js'
+import { hash, resolveFlowRoute, getFlowMeta, resolveSceneRoute, getSceneMeta, buildPrototypeIndex, appendTokens } from './viewfinder.js'
+
+const makeIndex = () => ({
+  flows: {
+    default: { title: 'Default Scene' },
+    Dashboard: { heading: 'Dashboard' },
+    'custom-route': { route: 'Overview', title: 'Custom' },
+    'absolute-route': { route: '/Forms', title: 'Absolute' },
+    'no-route': { title: 'No route key' },
+    'meta-route': { flowMeta: { route: 'Repositories' }, title: 'Meta Route' },
+    'meta-author': { flowMeta: { author: 'dfosco' }, title: 'With Author' },
+    'meta-authors': { flowMeta: { author: ['dfosco', 'heyamie', 'branonconor'] }, title: 'Multi Author' },
+    'meta-both': { flowMeta: { route: '/Overview', author: 'octocat' }, title: 'Both' },
+    'inferred-route': { _route: '/Dashboard', title: 'Inferred' },
+    'inferred-default': { _route: '/Settings', meta: { default: true }, title: 'Default Flow' },
+    'explicit-wins': { route: '/Forms', _route: '/Dashboard', title: 'Explicit Wins' },
+  },
+  objects: {},
+  records: {},
+})
+
+beforeEach(() => {
+  init(makeIndex())
+})
+
+describe('hash', () => {
+  it('returns a number', () => {
+    expect(typeof hash('test')).toBe('number')
+  })
+
+  it('is deterministic', () => {
+    expect(hash('hello')).toBe(hash('hello'))
+  })
+
+  it('produces different values for different strings', () => {
+    expect(hash('foo')).not.toBe(hash('bar'))
+  })
+
+  it('returns non-negative values', () => {
+    expect(hash('abc')).toBeGreaterThanOrEqual(0)
+    expect(hash('')).toBeGreaterThanOrEqual(0)
+    expect(hash('a very long string with lots of characters')).toBeGreaterThanOrEqual(0)
+  })
+})
+
+describe('resolveFlowRoute', () => {
+  const routes = ['Dashboard', 'Overview', 'Forms', 'Repositories']
+
+  it('matches flow name to route (exact case)', () => {
+    expect(resolveFlowRoute('Dashboard', routes)).toBe('/Dashboard')
+  })
+
+  it('matches flow name to route (case-insensitive)', () => {
+    expect(resolveFlowRoute('dashboard', routes)).toBe('/Dashboard')
+  })
+
+  it('uses route key from flow data when no route matches', () => {
+    expect(resolveFlowRoute('custom-route', routes)).toBe('/Overview?flow=custom-route')
+  })
+
+  it('handles absolute route key (with leading slash)', () => {
+    expect(resolveFlowRoute('absolute-route', routes)).toBe('/Forms?flow=absolute-route')
+  })
+
+  it('falls back to root when no match and no route key', () => {
+    expect(resolveFlowRoute('no-route', routes)).toBe('/?flow=no-route')
+  })
+
+  it('falls back to root for default flow', () => {
+    expect(resolveFlowRoute('default', routes)).toBe('/?flow=default')
+  })
+
+  it('falls back to root when flow does not exist', () => {
+    expect(resolveFlowRoute('nonexistent', routes)).toBe('/?flow=nonexistent')
+  })
+
+  it('works with empty routes array', () => {
+    expect(resolveFlowRoute('Dashboard', [])).toBe('/?flow=Dashboard')
+  })
+
+  it('works with no routes argument', () => {
+    expect(resolveFlowRoute('custom-route')).toBe('/Overview?flow=custom-route')
+  })
+
+  it('encodes special characters in flow name', () => {
+    init({
+      flows: { 'has spaces': { title: 'Spaces' } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('has spaces', [])).toBe('/?flow=has%20spaces')
+  })
+
+  it('uses flowMeta.route when no route matches', () => {
+    expect(resolveFlowRoute('meta-route', routes)).toBe('/Repositories?flow=meta-route')
+  })
+
+  it('uses flowMeta.route with absolute path', () => {
+    expect(resolveFlowRoute('meta-both', routes)).toBe('/Overview?flow=meta-both')
+  })
+
+  it('prefers top-level route over flowMeta.route', () => {
+    init({
+      flows: { conflict: { route: 'Forms', flowMeta: { route: 'Dashboard' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('conflict', [])).toBe('/Forms?flow=conflict')
+  })
+
+  it('uses _route when no explicit route exists', () => {
+    expect(resolveFlowRoute('inferred-route', routes)).toBe('/Dashboard?flow=inferred-route')
+  })
+
+  it('prefers explicit route over _route', () => {
+    expect(resolveFlowRoute('explicit-wins', routes)).toBe('/Forms?flow=explicit-wins')
+  })
+
+  it('omits ?flow= when meta.default is true (inferred route)', () => {
+    expect(resolveFlowRoute('inferred-default', routes)).toBe('/Settings')
+  })
+
+  it('omits ?flow= when meta.default is true (explicit route)', () => {
+    init({
+      flows: { 'default-explicit': { route: '/Overview', meta: { default: true } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('default-explicit', [])).toBe('/Overview')
+  })
+
+  it('still appends ?flow= when meta.default is absent even with _route', () => {
+    expect(resolveFlowRoute('inferred-route', [])).toBe('/Dashboard?flow=inferred-route')
+  })
+})
+
+describe('getFlowMeta', () => {
+  it('returns flowMeta when present', () => {
+    expect(getFlowMeta('meta-author')).toEqual({ author: 'dfosco' })
+  })
+
+  it('returns flowMeta with both fields', () => {
+    expect(getFlowMeta('meta-both')).toEqual({ route: '/Overview', author: 'octocat' })
+  })
+
+  it('returns flowMeta with array author', () => {
+    expect(getFlowMeta('meta-authors')).toEqual({ author: ['dfosco', 'heyamie', 'branonconor'] })
+  })
+
+  it('returns null when no flowMeta', () => {
+    expect(getFlowMeta('default')).toBeNull()
+  })
+
+  it('returns null for nonexistent flow', () => {
+    expect(getFlowMeta('nonexistent')).toBeNull()
+  })
+})
+
+// ── Deprecated aliases ──
+
+describe('resolveSceneRoute (deprecated alias)', () => {
+  it('is the same function as resolveFlowRoute', () => {
+    expect(resolveSceneRoute).toBe(resolveFlowRoute)
+  })
+
+  it('resolves a flow route', () => {
+    expect(resolveSceneRoute('Dashboard', ['Dashboard'])).toBe('/Dashboard')
+  })
+})
+
+describe('getSceneMeta (deprecated alias)', () => {
+  it('is the same function as getFlowMeta', () => {
+    expect(getSceneMeta).toBe(getFlowMeta)
+  })
+
+  it('returns flow meta', () => {
+    expect(getSceneMeta('meta-author')).toEqual({ author: 'dfosco' })
+  })
+})
+
+// ── buildPrototypeIndex ──
+
+describe('buildPrototypeIndex', () => {
+  it('passes hideFlows from prototype metadata', () => {
+    init({
+      flows: { 'MyProto/only-flow': { meta: { title: 'Only Flow' } } },
+      objects: {},
+      records: {},
+      prototypes: {
+        MyProto: { meta: { title: 'My Proto', hideFlows: true } },
+      },
+    })
+    const { prototypes } = buildPrototypeIndex([])
+    const proto = prototypes.find(p => p.dirName === 'MyProto')
+    expect(proto.hideFlows).toBe(true)
+    expect(proto.flows).toHaveLength(1)
+  })
+
+  it('defaults hideFlows to true when not set', () => {
+    init({
+      flows: { 'Other/flow-a': { meta: { title: 'A' } } },
+      objects: {},
+      records: {},
+      prototypes: {
+        Other: { meta: { title: 'Other Proto' } },
+      },
+    })
+    const { prototypes } = buildPrototypeIndex([])
+    const proto = prototypes.find(p => p.dirName === 'Other')
+    expect(proto.hideFlows).toBe(true)
+  })
+
+  it('reads hideFlows from top-level prototype metadata (outside meta key)', () => {
+    init({
+      flows: { 'TopLevel/only-flow': { meta: { title: 'Only Flow' } } },
+      objects: {},
+      records: {},
+      prototypes: {
+        TopLevel: { meta: { title: 'Top Level' }, hideFlows: true },
+      },
+    })
+    const { prototypes } = buildPrototypeIndex([])
+    const proto = prototypes.find(p => p.dirName === 'TopLevel')
+    expect(proto.hideFlows).toBe(true)
+  })
+
+  it('groups prototypes into folders when folder field is set', () => {
+    init({
+      flows: {
+        'Example/basic': { meta: { title: 'Basic' } },
+        'Signup/default': { meta: { title: 'Default' } },
+      },
+      objects: {},
+      records: {},
+      prototypes: {
+        Example: { meta: { title: 'Examples' }, folder: 'Getting Started' },
+        Signup: { meta: { title: 'Sign Up' }, folder: 'Getting Started' },
+      },
+      folders: {
+        'Getting Started': { meta: { title: 'Getting Started', description: 'Intro prototypes', icon: '📚' } },
+      },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(1)
+    expect(result.prototypes).toHaveLength(0)
+
+    const folder = result.folders[0]
+    expect(folder.name).toBe('Getting Started')
+    expect(folder.description).toBe('Intro prototypes')
+    expect(folder.icon).toBe('📚')
+    expect(folder.prototypes).toHaveLength(2)
+    expect(folder.prototypes.map(p => p.dirName)).toContain('Example')
+    expect(folder.prototypes.map(p => p.dirName)).toContain('Signup')
+  })
+
+  it('keeps prototypes without a folder as ungrouped', () => {
+    init({
+      flows: {
+        'Grouped/flow-a': {},
+        'Standalone/flow-b': {},
+      },
+      objects: {},
+      records: {},
+      prototypes: {
+        Grouped: { meta: { title: 'Grouped' }, folder: 'MyFolder' },
+        Standalone: { meta: { title: 'Standalone' } },
+      },
+      folders: {
+        MyFolder: { meta: { title: 'My Folder' } },
+      },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(1)
+    expect(result.prototypes).toHaveLength(1)
+    expect(result.prototypes[0].dirName).toBe('Standalone')
+    expect(result.folders[0].prototypes).toHaveLength(1)
+    expect(result.folders[0].prototypes[0].dirName).toBe('Grouped')
+  })
+
+  it('creates implicit folder when prototype references a folder with no metadata', () => {
+    init({
+      flows: { 'Proto/flow': {} },
+      objects: {},
+      records: {},
+      prototypes: {
+        Proto: { meta: { title: 'Proto' }, folder: 'Implicit' },
+      },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(1)
+    expect(result.folders[0].name).toBe('Implicit')
+    expect(result.folders[0].prototypes).toHaveLength(1)
+  })
+
+  it('uses folder directory name as display name when no title in metadata', () => {
+    init({
+      flows: {},
+      objects: {},
+      records: {},
+      prototypes: {},
+      folders: {
+        'My Folder': {},
+      },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(1)
+    expect(result.folders[0].name).toBe('My Folder')
+  })
+
+  it('returns empty folders array when no folders exist', () => {
+    init({
+      flows: { 'A/flow': {} },
+      objects: {},
+      records: {},
+      prototypes: { A: { meta: { title: 'A' } } },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(0)
+    expect(result.prototypes).toHaveLength(1)
+  })
+
+  it('passes through lastModified from prototype metadata', () => {
+    const ts = '2025-01-15T10:30:00-05:00'
+    init({
+      flows: { 'App/home': {} },
+      objects: {},
+      records: {},
+      prototypes: { App: { meta: { title: 'My App' }, lastModified: ts } },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.prototypes[0].lastModified).toBe(ts)
+  })
+
+  it('defaults lastModified to null when not provided', () => {
+    init({
+      flows: { 'App/home': {} },
+      objects: {},
+      records: {},
+      prototypes: { App: { meta: { title: 'My App' } } },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.prototypes[0].lastModified).toBeNull()
+  })
+})
+
+// ── appendTokens ──
+
+describe('appendTokens', () => {
+  it('returns url unchanged when tokens is null', () => {
+    expect(appendTokens('/foo', null)).toBe('/foo')
+  })
+
+  it('returns url unchanged when tokens is undefined', () => {
+    expect(appendTokens('/foo', undefined)).toBe('/foo')
+  })
+
+  it('returns url unchanged when tokens is empty', () => {
+    expect(appendTokens('/foo', {})).toBe('/foo')
+  })
+
+  it('appends single token with ?', () => {
+    expect(appendTokens('/foo', { token: 'abc' })).toBe('/foo?token=abc')
+  })
+
+  it('appends multiple tokens', () => {
+    const result = appendTokens('/foo', { token: 'abc', model: 'gpt-4' })
+    expect(result).toBe('/foo?token=abc&model=gpt-4')
+  })
+
+  it('uses & separator when url already has query params', () => {
+    expect(appendTokens('/foo?flow=bar', { token: 'abc' })).toBe('/foo?flow=bar&token=abc')
+  })
+
+  it('filters out reserved key "flow"', () => {
+    expect(appendTokens('/foo', { flow: 'bad', token: 'good' })).toBe('/foo?token=good')
+  })
+
+  it('filters out reserved key "scene"', () => {
+    expect(appendTokens('/foo', { scene: 'bad', token: 'good' })).toBe('/foo?token=good')
+  })
+
+  it('filters out null and undefined values', () => {
+    expect(appendTokens('/foo', { a: null, b: undefined, c: 'ok' })).toBe('/foo?c=ok')
+  })
+
+  it('filters out object and array values', () => {
+    expect(appendTokens('/foo', { a: { nested: true }, b: [1, 2], c: 'ok' })).toBe('/foo?c=ok')
+  })
+
+  it('encodes special characters', () => {
+    expect(appendTokens('/foo', { key: 'hello world' })).toBe('/foo?key=hello%20world')
+  })
+
+  it('handles numeric and boolean values', () => {
+    expect(appendTokens('/foo', { count: 42, active: true })).toBe('/foo?count=42&active=true')
+  })
+})
+
+// ── resolveFlowRoute with tokens ──
+
+describe('resolveFlowRoute with tokens', () => {
+  it('appends tokens to a flow with explicit route', () => {
+    init({
+      flows: { 'with-tokens': { route: '/Overview', tokens: { token: 'sk-abc' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('with-tokens', [])).toBe('/Overview?flow=with-tokens&token=sk-abc')
+  })
+
+  it('appends tokens to a known-route match', () => {
+    init({
+      flows: { Dashboard: { heading: 'Hi', tokens: { model: 'gpt-4' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('Dashboard', ['Dashboard'])).toBe('/Dashboard?model=gpt-4')
+  })
+
+  it('appends tokens to inferred route', () => {
+    init({
+      flows: { 'inferred': { _route: '/Settings', tokens: { key: 'val' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('inferred', [])).toBe('/Settings?flow=inferred&key=val')
+  })
+
+  it('appends tokens to default flow fallback', () => {
+    init({
+      flows: { 'no-route': { title: 'No route', tokens: { api: '123' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('no-route', [])).toBe('/?flow=no-route&api=123')
+  })
+
+  it('does not append tokens when flow has none', () => {
+    init({
+      flows: { simple: { route: '/Page' } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('simple', [])).toBe('/Page?flow=simple')
+  })
+
+  it('appends tokens with meta.default route (no ?flow=)', () => {
+    init({
+      flows: { 'default-tokens': { _route: '/Home', meta: { default: true }, tokens: { key: 'val' } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('default-tokens', [])).toBe('/Home?key=val')
+  })
+})

package/src/core/devtools/devtools-consumer.js

@@ -0,0 +1,28 @@
+/**
+ * Consumer-safe proxy for mountDevTools.
+ *
+ * Delegates to the compiled UI bundle (@dfosco/storyboard/ui-runtime)
+ * so consumers don't need internal dependencies. The real mountDevTools in
+ * devtools.js imports internal deps and is only usable in the source repo
+ * or via the compiled UI bundle.
+ */
+
+export async function mountDevTools(options = {}) {
+  const ui = await import('@dfosco/storyboard/ui-runtime')
+  return ui.mountDevTools(options)
+}
+
+export async function unmountDevTools() {
+  const ui = await import('@dfosco/storyboard/ui-runtime')
+  return ui.unmountDevTools()
+}
+
+/** @deprecated Use mountDevTools instead. */
+export function mountFlowDebug(options = {}) {
+  return mountDevTools(options)
+}
+
+/** @deprecated Use mountDevTools instead. */
+export function mountSceneDebug(options = {}) {
+  return mountDevTools(options)
+}

package/src/core/devtools/devtools.js

@@ -0,0 +1,144 @@
+/**
+ * Storyboard Core UI Bar — React-based floating toolbar.
+ *
+ * Mounts the CoreUIBar React component into the DOM.
+ * Contains the command menu and mode-specific buttons (workshop, etc.).
+ * Uses dynamic import() for the React component to avoid
+ * breaking non-React test environments.
+ *
+ * Usage:
+ *   import { mountDevTools } from '../index.js'
+ *   mountDevTools() // call once at app startup
+ */
+
+let root = null
+let wrapper = null
+let skipLink = null
+
+/**
+ * Mount the Storyboard Core UI Bar to the DOM.
+ * Call once at app startup. Safe to call multiple times (no-ops after first).
+ *
+ * @param {object} [options]
+ * @param {HTMLElement} [options.container=document.body] - Where to mount
+ * @param {string} [options.basePath='/'] - Base URL path
+ * @param {object} [options.toolbarConfig] - Merged toolbar config
+ * @param {Record<string, () => Promise<any>>} [options.customHandlers] - Custom tool handlers
+ */
+export async function mountDevTools(options = {}) {
+  const container = options.container || document.body
+  const basePath = options.basePath || '/'
+
+  // Prevent double-mount
+  if (wrapper) return
+
+  // Skip mounting entirely when loaded inside a prototype embed iframe
+  if (typeof window !== 'undefined' && new URLSearchParams(window.location.search).has('_sb_embed')) return
+
+  const { createElement } = await import('react')
+  const { createRoot } = await import('react-dom/client')
+  const { default: CoreUIBar } = await import('../ui/CoreUIBar.jsx')
+
+  // Inject skip link as the first child of <body> so it is the
+  // first element in the tab order, regardless of where CoreUIBar
+  // is mounted. Works in both this repo and client repos.
+  skipLink = document.createElement('a')
+  skipLink.href = '#storyboard-controls'
+  skipLink.textContent = 'Skip to controls'
+  skipLink.setAttribute('data-sb-skip-link', '')
+  skipLink.addEventListener('click', (e) => {
+    e.preventDefault()
+    const firstBtn = document.querySelector('[data-core-ui-bar] [data-slot="button"]')
+    if (firstBtn) firstBtn.focus()
+  })
+
+  // Inline styles so it works without any CSS framework loaded
+  Object.assign(skipLink.style, {
+    position: 'fixed',
+    top: '1rem',
+    left: '1rem',
+    zIndex: '10000',
+    clip: 'rect(0 0 0 0)',
+    clipPath: 'inset(50%)',
+    width: '1px',
+    height: '1px',
+    overflow: 'hidden',
+    whiteSpace: 'nowrap',
+    textDecoration: 'none',
+  })
+
+  skipLink.addEventListener('focus', () => {
+    Object.assign(skipLink.style, {
+      clip: 'auto',
+      clipPath: 'none',
+      width: 'auto',
+      height: 'auto',
+      overflow: 'visible',
+      padding: '0.375rem 0.75rem',
+      background: '#fff',
+      color: '#111',
+      border: '1px solid #ddd',
+      borderRadius: '0.5rem',
+      boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
+      fontSize: '0.875rem',
+      fontFamily: "'Mona Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
+    })
+  })
+
+  skipLink.addEventListener('blur', () => {
+    Object.assign(skipLink.style, {
+      clip: 'rect(0 0 0 0)',
+      clipPath: 'inset(50%)',
+      width: '1px',
+      height: '1px',
+      overflow: 'hidden',
+      padding: '0',
+      background: '',
+      color: '',
+      border: '',
+      borderRadius: '',
+      boxShadow: '',
+      fontSize: '',
+      fontFamily: '',
+    })
+  })
+
+  document.body.insertBefore(skipLink, document.body.firstChild)
+
+  wrapper = document.createElement('div')
+  wrapper.id = 'sb-core-ui'
+  container.appendChild(wrapper)
+
+  root = createRoot(wrapper)
+  root.render(createElement(CoreUIBar, {
+    basePath,
+    toolbarConfig: options.toolbarConfig,
+    customHandlers: options.customHandlers,
+  }))
+}
+
+/**
+ * Remove the Core UI Bar from the DOM.
+ */
+export async function unmountDevTools() {
+  if (root) {
+    root.unmount()
+    root = null
+  }
+  if (wrapper) { wrapper.remove(); wrapper = null }
+  if (skipLink) { skipLink.remove(); skipLink = null }
+}
+
+/**
+ * @deprecated Use mountDevTools instead.
+ */
+export function mountFlowDebug(options = {}) {
+  return mountDevTools(options)
+}
+
+/**
+ * @deprecated Use mountDevTools instead.
+ */
+export function mountSceneDebug(options = {}) {
+  return mountDevTools(options)
+}

package/src/core/devtools/devtools.test.js

@@ -0,0 +1,75 @@
+/**
+ * Tests for devtools.js — command menu mount lifecycle.
+ * Mocks the React component to avoid jsdom lifecycle issues.
+ */
+
+import { vi } from 'vitest'
+
+const mockRender = vi.fn()
+const mockUnmount = vi.fn()
+const mockCreateRoot = vi.fn(() => ({ render: mockRender, unmount: mockUnmount }))
+
+vi.mock('react', () => ({
+  createElement: vi.fn((comp, props) => ({ comp, props })),
+}))
+
+vi.mock('react-dom/client', () => ({
+  createRoot: mockCreateRoot,
+}))
+
+vi.mock('../ui/CoreUIBar.jsx', () => ({ default: () => null }))
+
+describe('mountDevTools', () => {
+  let mountDevTools, unmountDevTools
+
+  beforeEach(async () => {
+    document.body.innerHTML = ''
+    vi.resetModules()
+
+    vi.doMock('react', () => ({
+      createElement: vi.fn((comp, props) => ({ comp, props })),
+    }))
+    vi.doMock('react-dom/client', () => ({
+      createRoot: vi.fn(() => ({ render: vi.fn(), unmount: vi.fn() })),
+    }))
+    vi.doMock('../ui/CoreUIBar.jsx', () => ({ default: () => null }))
+
+    const mod = await import('./devtools.js')
+    mountDevTools = mod.mountDevTools
+    unmountDevTools = mod.unmountDevTools
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('creates a wrapper element in the DOM', async () => {
+    await mountDevTools()
+    expect(document.getElementById('sb-command-menu')).not.toBeNull()
+  })
+
+  it('appends to document.body by default', async () => {
+    await mountDevTools()
+    expect(document.getElementById('sb-command-menu')).toBeInTheDocument()
+  })
+
+  it('accepts a custom container', async () => {
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    await mountDevTools({ container })
+    expect(container.querySelector('#sb-command-menu')).not.toBeNull()
+  })
+
+  it('is idempotent — calling twice does not double-mount', async () => {
+    await mountDevTools()
+    await mountDevTools()
+    expect(document.querySelectorAll('#sb-command-menu').length).toBe(1)
+  })
+
+  it('unmountDevTools removes the wrapper', async () => {
+    await mountDevTools()
+    expect(document.getElementById('sb-command-menu')).not.toBeNull()
+    await unmountDevTools()
+    expect(document.getElementById('sb-command-menu')).toBeNull()
+  })
+})