@dfosco/storyboard 0.5.0-alpha.0

package/src/core/tools/handlers/devtools.js

@@ -0,0 +1,122 @@
+/**
+ * Devtools tool module — developer utilities submenu.
+ *
+ * Renders as a submenu in the command menu with:
+ * - Show flow info
+ * - Reset all params
+ * - Hide mode toggle
+ * - Logout (when authenticated)
+ */
+export const id = 'devtools'
+
+/**
+ * @param {object} ctx
+ * @param {Function} ctx.showFlowInfoDialog - callback to open flow info dialog
+ */
+export async function handler(ctx) {
+  let loader = null
+  let hm = null
+  let commentsAuth = null
+  let prodMode = null
+  let ff = null
+  try { loader = await import('../../index.js') } catch { /* optional */ }
+  try { hm = await import('../../index.js') } catch { /* optional */ }
+  try { commentsAuth = await import('../../comments/auth.js') } catch { /* optional */ }
+  try { prodMode = await import('../../utils/prodMode.js') } catch { /* optional */ }
+  try { ff = await import('../../index.js') } catch { /* optional */ }
+
+  return {
+    getChildren: () => {
+      const children = []
+      const canToggleProdMode = prodMode
+        && typeof window !== 'undefined'
+        && window.__SB_LOCAL_DEV__ === true
+
+      if (canToggleProdMode) {
+        children.push({
+          id: 'core/prod-mode',
+          label: 'Production mode',
+          type: 'toggle',
+          active: prodMode.isProdMode(),
+          execute: () => { prodMode.toggleProdMode() },
+        })
+      }
+      if (loader) {
+        children.push({
+          id: 'core/show-flow-info',
+          label: 'Show flow info',
+          type: 'default',
+          execute: () => {
+            const p = new URLSearchParams(window.location.search)
+            const name = p.get('flow') || p.get('scene') || 'default'
+            try {
+              const data = loader.loadFlow(name)
+              if (ctx.showFlowInfoDialog) {
+                ctx.showFlowInfoDialog(name, JSON.stringify(data, null, 2), null)
+              }
+            } catch (e) {
+              if (ctx.showFlowInfoDialog) {
+                ctx.showFlowInfoDialog(name, '', e.message)
+              }
+            }
+          },
+        })
+      }
+      children.push({
+        id: 'core/reset-params',
+        label: 'Reset all params',
+        type: 'default',
+        execute: () => { window.location.hash = '' },
+      })
+      if (hm) {
+        children.push({
+          id: 'core/hide-mode',
+          label: 'Hide mode',
+          type: 'toggle',
+          active: hm.isHideMode(),
+          execute: () => {
+            if (hm.isHideMode()) hm.deactivateHideMode()
+            else hm.activateHideMode()
+          },
+        })
+      }
+      if (commentsAuth?.isAuthenticated()) {
+        children.push({
+          id: 'core/logout',
+          label: 'Logout (remove token)',
+          type: 'default',
+          execute: () => {
+            commentsAuth.clearToken()
+            console.log('[storyboard] Token removed')
+          },
+        })
+      }
+      if (ff) {
+        children.push({
+          id: 'core/dev-logs',
+          label: 'Dev logs',
+          type: 'toggle',
+          active: ff.getFlag('dev-logs'),
+          execute: () => { ff.toggleFlag('dev-logs') },
+        })
+      }
+      if (ff) {
+        children.push({
+          id: 'core/canvas-auto-reload',
+          label: 'Canvas auto-reload',
+          type: 'toggle',
+          active: ff.getFlag('canvas-auto-reload'),
+          execute: () => { ff.toggleFlag('canvas-auto-reload') },
+        })
+        children.push({
+          id: 'core/prototype-auto-reload',
+          label: 'Prototype auto-reload',
+          type: 'toggle',
+          active: ff.getFlag('prototype-auto-reload'),
+          execute: () => { ff.toggleFlag('prototype-auto-reload') },
+        })
+      }
+      return children
+    },
+  }
+}

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

@@ -0,0 +1,87 @@
+import { handler as createDevtoolsHandler } from './devtools.js'
+
+function getProdModeItem(children) {
+  return children.find(item => item.id === 'core/prod-mode')
+}
+
+function getCanvasAutoReloadItem(children) {
+  return children.find(item => item.id === 'core/canvas-auto-reload')
+}
+
+function getPrototypeAutoReloadItem(children) {
+  return children.find(item => item.id === 'core/prototype-auto-reload')
+}
+
+describe('devtools production mode toggle', () => {
+  const originalLocalDev = window.__SB_LOCAL_DEV__
+
+  beforeEach(() => {
+    window.history.replaceState({}, '', '/')
+    delete window.__SB_LOCAL_DEV__
+  })
+
+  afterAll(() => {
+    if (typeof originalLocalDev === 'undefined') delete window.__SB_LOCAL_DEV__
+    else window.__SB_LOCAL_DEV__ = originalLocalDev
+  })
+
+  it('shows the toggle in local dev', async () => {
+    window.__SB_LOCAL_DEV__ = true
+
+    const devtools = await createDevtoolsHandler({})
+    const prodModeItem = getProdModeItem(devtools.getChildren())
+
+    expect(prodModeItem).toBeTruthy()
+    expect(prodModeItem.active).toBe(false)
+  })
+
+  it('shows the toggle as active in local-dev prodMode simulation', async () => {
+    window.__SB_LOCAL_DEV__ = true
+    window.history.replaceState({}, '', '/?prodMode')
+
+    const devtools = await createDevtoolsHandler({})
+    const prodModeItem = getProdModeItem(devtools.getChildren())
+
+    expect(prodModeItem).toBeTruthy()
+    expect(prodModeItem.active).toBe(true)
+  })
+
+  it('hides the toggle in true production mode', async () => {
+    window.__SB_LOCAL_DEV__ = false
+
+    const devtools = await createDevtoolsHandler({})
+    const prodModeItem = getProdModeItem(devtools.getChildren())
+
+    expect(prodModeItem).toBeUndefined()
+  })
+})
+
+describe('devtools canvas auto-reload toggle', () => {
+  beforeEach(() => {
+    window.history.replaceState({}, '', '/')
+  })
+
+  it('shows the toggle as inactive by default (guard ON)', async () => {
+    const devtools = await createDevtoolsHandler({})
+    const item = getCanvasAutoReloadItem(devtools.getChildren())
+
+    expect(item).toBeTruthy()
+    expect(item.type).toBe('toggle')
+    expect(item.active).toBe(false)
+  })
+})
+
+describe('devtools prototype auto-reload toggle', () => {
+  beforeEach(() => {
+    window.history.replaceState({}, '', '/')
+  })
+
+  it('shows the toggle as active by default (reloads enabled)', async () => {
+    const devtools = await createDevtoolsHandler({})
+    const item = getPrototypeAutoReloadItem(devtools.getChildren())
+
+    expect(item).toBeTruthy()
+    expect(item.type).toBe('toggle')
+    expect(item.active).toBe(true)
+  })
+})

package/src/core/tools/handlers/featureFlags.js

@@ -0,0 +1,21 @@
+/**
+ * Feature Flags tool module — toggle feature flags submenu.
+ *
+ * Renders as a submenu in the command menu listing all declared flags.
+ */
+export const id = 'feature-flags'
+
+export async function handler() {
+  const ff = await import('../../index.js')
+
+  return {
+    getChildren: () =>
+      ff.getFlagKeys().map(key => ({
+        id: `flags/${key}`,
+        label: key,
+        type: 'toggle',
+        active: ff.getFlag(key),
+        execute: () => ff.toggleFlag(key),
+      })),
+  }
+}

package/src/core/tools/handlers/flows.js

@@ -0,0 +1,68 @@
+/**
+ * Flows tool module — flow switcher action menu.
+ *
+ * Registers a command action handler that lists available flows
+ * for the current prototype and lets users switch between them.
+ */
+export const id = 'flows'
+
+export async function handler(ctx) {
+  const loader = await import('../../index.js')
+  const vf = loader
+  const { basePath = '/' } = ctx
+
+  return {
+    getChildren: () => {
+      let path = window.location.pathname
+      const base = basePath.replace(/\/+$/, '')
+      if (base && path.startsWith(base)) path = path.slice(base.length)
+      path = path.replace(/\/+$/, '') || '/'
+      const segments = path.split('/').filter(Boolean)
+
+      // Detect and preserve branch-- segment on deployed branch builds
+      const branchSegment = (segments[0] && segments[0].startsWith('branch--')) ? segments[0] : null
+      const protoIdx = branchSegment ? 1 : 0
+      const proto = segments[protoIdx] || null
+      if (!proto) return []
+
+      const params = new URLSearchParams(window.location.search)
+      const explicit = params.get('flow') || params.get('scene')
+      let active
+      if (explicit) {
+        active = loader.resolveFlowName(proto, explicit)
+      } else {
+        const pageFlow = path === '/' ? 'index' : (path.split('/').pop() || 'index')
+        const scoped = loader.resolveFlowName(proto, pageFlow)
+        if (loader.flowExists(scoped)) active = scoped
+        else {
+          const protoFlow = loader.resolveFlowName(proto, proto)
+          active = loader.flowExists(protoFlow) ? protoFlow : 'default'
+        }
+      }
+
+      const flows = loader.getFlowsForPrototype(proto)
+      if (flows.length <= 1) return []
+
+      return flows.map(f => {
+        const meta = vf.getFlowMeta(f.key)
+        let url = vf.resolveFlowRoute(f.key)
+        // Re-apply basePath and branch-- prefix so deployed branch builds stay on the correct path
+        const prefix = (base || '') + (branchSegment ? `/${branchSegment}` : '')
+        if (prefix) url = prefix + url
+        return {
+          id: f.key,
+          label: meta?.title || f.name,
+          type: 'radio',
+          active: f.key === active,
+          href: url,
+          execute: () => { window.location.href = url },
+        }
+      })
+    },
+  }
+}
+
+export async function component() {
+  const mod = await import('../../ui/ActionMenuButton.jsx')
+  return mod.default
+}

package/src/core/tools/handlers/hideChrome.js

@@ -0,0 +1,9 @@
+/**
+ * Hide Chrome tool — toolbar button that toggles toolbar/branch bar visibility.
+ */
+export const id = 'hide-chrome'
+
+export async function component() {
+  const mod = await import('../../ui/HideChromeTrigger.jsx')
+  return mod.default
+}

package/src/core/tools/handlers/hideToolbars.js

@@ -0,0 +1,25 @@
+/**
+ * Hide/Show toolbars tool — command palette only.
+ *
+ * Toggles the `storyboard-chrome-hidden` class (same as Cmd+.).
+ * Label flips between "Hide toolbars" and "Show toolbars" based on state.
+ */
+export const id = 'hide-toolbars'
+
+export async function handler() {
+  return {
+    getChildren() {
+      const hidden = document.documentElement.classList.contains('storyboard-chrome-hidden')
+      return [{
+        id: 'core/toggle-toolbars',
+        label: hidden ? 'Show toolbars' : 'Hide toolbars',
+        type: 'default',
+        execute: () => {
+          const isHidden = document.documentElement.classList.contains('storyboard-chrome-hidden')
+          document.documentElement.classList.toggle('storyboard-chrome-hidden', !isHidden)
+          document.documentElement.classList.remove('storyboard-chrome-completely-hidden')
+        },
+      }]
+    },
+  }
+}

package/src/core/tools/handlers/inspector.js

@@ -0,0 +1,19 @@
+/**
+ * Inspector tool module — component inspector sidepanel.
+ *
+ * Auto-opens the panel if ?inspect= is in the URL.
+ */
+export const id = 'inspector'
+
+export async function setup() {
+  const { openPanel } = await import('../../stores/sidePanelStore.js')
+
+  try {
+    const inspectParam = new URL(window.location.href).searchParams.get('inspect')
+    if (inspectParam) {
+      openPanel('inspector')
+    }
+  } catch { /* ignore */ }
+}
+
+// No component needed — sidepanel tools use generic TriggerButton

package/src/core/tools/handlers/paletteTheme.js

@@ -0,0 +1,35 @@
+/**
+ * Palette Theme tool — theme submenu for the command palette.
+ *
+ * Returns theme options as children, plus a "Theme settings" entry
+ * that opens the toolbar Theme menu with the settings submenu expanded.
+ */
+export const id = 'palette-theme'
+
+export async function handler() {
+  const { themeState, setTheme, THEMES } = await import('../../index.js')
+
+  return {
+    getChildren() {
+      const current = themeState.theme
+      return [
+        // Theme options
+        ...THEMES.map(t => ({
+          id: `theme:${t.value}`,
+          label: t.name,
+          type: 'toggle',
+          active: current === t.value,
+          execute: () => setTheme(t.value),
+        })),
+        // "Theme settings" opens the toolbar theme menu at the settings submenu
+        {
+          id: 'theme:settings',
+          label: 'Theme settings',
+          execute: () => {
+            document.dispatchEvent(new CustomEvent('storyboard:open-theme-settings'))
+          },
+        },
+      ]
+    },
+  }
+}

package/src/core/tools/handlers/theme.js

@@ -0,0 +1,9 @@
+/**
+ * Theme tool module — theme switcher menu.
+ */
+export const id = 'theme'
+
+export async function component() {
+  const mod = await import('../../ui/ThemeMenuButton.jsx')
+  return mod.default
+}

package/src/core/tools/registry.js

@@ -0,0 +1,26 @@
+/**
+ * Tool module registry — maps tool IDs to lazy-loaded handler modules.
+ *
+ * Each handler module exports: { id, component?, handler?, setup?, guard? }
+ * All imports are dynamic to enable code splitting.
+ */
+export const coreHandlers = {
+  create:               () => import('./handlers/create.js'),
+  theme:                () => import('./handlers/theme.js'),
+  'palette-theme':      () => import('./handlers/paletteTheme.js'),
+  comments:             () => import('./handlers/comments.js'),
+  flows:                () => import('./handlers/flows.js'),
+  inspector:            () => import('./handlers/inspector.js'),
+  devtools:             () => import('./handlers/devtools.js'),
+  'feature-flags':      () => import('./handlers/featureFlags.js'),
+  autosync:             () => import('./handlers/autosync.js'),
+  'canvas-add-widget':  () => import('./handlers/canvasAddWidget.js'),
+  'canvas-agents':      () => import('./handlers/canvasAgents.js'),
+  'canvas-toolbar':     () => import('./handlers/canvasToolbar.js'),
+  'hide-toolbars':      () => import('./handlers/hideToolbars.js'),
+  'command-palette':    () => import('./handlers/commandPalette.js'),
+  'hide-chrome':        () => import('./handlers/hideChrome.js'),
+}
+
+// Keep legacy export name for backward compatibility
+export const toolModules = coreHandlers

package/src/core/tools/surfaces/canvasToolbar.js

@@ -0,0 +1,10 @@
+/**
+ * Canvas Toolbar surface — floating bar at bottom-left on canvas pages.
+ *
+ * Only visible when a canvas page is active. Supports menus and
+ * custom render types like zoom-control.
+ */
+export const id = 'canvas-toolbar'
+export const label = 'Canvas Toolbar'
+export const position = 'bottom-left'
+export const renderTypes = ['menu', 'zoom-control']

package/src/core/tools/surfaces/commandList.js

@@ -0,0 +1,10 @@
+/**
+ * Command Palette surface — items rendered inside the ⌘K command palette.
+ *
+ * Tools here appear as menu items, submenus, or links within
+ * the command palette. They don't render as standalone buttons.
+ */
+export const id = 'command-palette'
+export const label = 'Command Palette'
+export const position = 'overlay'
+export const renderTypes = ['link', 'submenu']

package/src/core/tools/surfaces/mainToolbar.js

@@ -0,0 +1,11 @@
+/**
+ * Command Toolbar surface — the primary floating bar at bottom-right.
+ *
+ * Supports all standard render types. Tools appear in reverse JSON order
+ * (first in config = leftmost in toolbar). The command menu button is
+ * always the rightmost item and is not a tool.
+ */
+export const id = 'command-toolbar'
+export const label = 'Command Toolbar'
+export const position = 'bottom-right'
+export const renderTypes = ['button', 'menu', 'sidepanel', 'separator']

package/src/core/tools/surfaces/registry.js

@@ -0,0 +1,19 @@
+/**
+ * Surface registry — exports all available rendering surfaces.
+ *
+ * Surfaces define WHERE a tool renders. Each surface has a position,
+ * supported render types, and rendering logic in CoreUIBar.
+ *
+ * To add a new surface:
+ * 1. Create a definition file in this directory
+ * 2. Export it from this registry
+ * 3. Add rendering logic in CoreUIBar.jsx
+ */
+export { id as commandToolbar } from './mainToolbar.js'
+export { id as canvasToolbar } from './canvasToolbar.js'
+export { id as commandPalette } from './commandList.js'
+
+/**
+ * All surface IDs for validation.
+ */
+export const SURFACE_IDS = ['command-toolbar', 'canvas-toolbar', 'command-palette']

package/src/core/ui/ActionMenuButton.jsx

@@ -0,0 +1,114 @@
+import { useState, useEffect, useCallback } from 'react'
+import { TriggerButton } from '../lib/components/ui/trigger-button/index.js'
+import * as DropdownMenu from '../lib/components/ui/dropdown-menu/index.js'
+import Icon from './Icon.jsx'
+import { getActionChildren, subscribeToCommandActions } from '../index.js'
+
+export default function ActionMenuButton({ config = {}, data: _data, localOnly: _localOnly, tabindex = -1 }) {
+  void _data
+  void _localOnly
+  const [menuOpen, setMenuOpen] = useState(false)
+  const [_actionsVersion, setActionsVersion] = useState(0)
+  void _actionsVersion
+
+  useEffect(() => {
+    const unsub = subscribeToCommandActions(() => { setActionsVersion((v) => v + 1) })
+    return unsub
+  }, [])
+
+  // Allow external callers (e.g. command palette) to open this menu
+  useEffect(() => {
+    const actionId = config.action
+    if (!actionId) return
+    function onTrigger(e) {
+      if (e.detail?.action === actionId) setMenuOpen(true)
+    }
+    window.addEventListener('storyboard:open-tool-menu', onTrigger)
+    return () => window.removeEventListener('storyboard:open-tool-menu', onTrigger)
+  }, [config.action])
+
+  const children = config.action ? getActionChildren(config.action) : []
+  const hasRadio = children.some((c) => c.type === 'radio')
+  const activeValue = children.find((c) => c.type === 'radio' && c.active)?.id || ''
+
+  const handleOpenChange = useCallback((open) => {
+    setMenuOpen(open)
+    if (open) setActionsVersion((v) => v + 1)
+  }, [])
+
+  if (children.length === 0) return null
+
+  return (
+    <DropdownMenu.Root open={menuOpen} onOpenChange={handleOpenChange}>
+      <DropdownMenu.Trigger>
+          <TriggerButton
+            active={menuOpen}
+            size="icon-xl"
+            aria-label={config.ariaLabel || config.label || 'Menu'}
+            tabIndex={tabindex}
+          >
+            <Icon name={config.icon || 'primer/gear'} size={16} {...(config.meta || {})} />
+          </TriggerButton>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content
+        side="top"
+        align="end"
+        sideOffset={16}
+        style={config.menuWidth ? { minWidth: config.menuWidth } : undefined}
+        className={config.menuWidth ? '' : 'min-w-[200px]'}
+      >
+        {config.label && <DropdownMenu.Label>{config.label}</DropdownMenu.Label>}
+
+        {hasRadio ? (
+          <DropdownMenu.RadioGroup value={activeValue}>
+            {children.map((child) => {
+              if (child.type !== 'radio') return null
+              return (
+                <DropdownMenu.RadioItem
+                  key={child.id || child.label}
+                  value={child.id}
+                  onClick={(e) => {
+                    if (child.href && (e.metaKey || e.ctrlKey)) {
+                      e.preventDefault(); window.open(child.href, '_blank'); setMenuOpen(false); return
+                    }
+                    if (child.execute) child.execute(); setMenuOpen(false)
+                  }}
+                >
+                  {child.label}
+                </DropdownMenu.RadioItem>
+              )
+            })}
+          </DropdownMenu.RadioGroup>
+        ) : (
+          children.map((child) => {
+            if (child.type === 'toggle') {
+              return (
+                <DropdownMenu.CheckboxItem
+                  key={child.id || child.label}
+                  checked={child.active}
+                  onSelect={(e) => { e.preventDefault(); if (child.execute) child.execute(); setActionsVersion((v) => v + 1) }}
+                >
+                  {child.label}
+                </DropdownMenu.CheckboxItem>
+              )
+            }
+            return (
+              <DropdownMenu.Item
+                key={child.id || child.label}
+                onClick={(e) => {
+                  if (child.href && (e.metaKey || e.ctrlKey)) {
+                    e.preventDefault(); window.open(child.href, '_blank'); setMenuOpen(false); return
+                  }
+                  if (child.execute) child.execute(); setMenuOpen(false)
+                }}
+              >
+                {child.label}
+              </DropdownMenu.Item>
+            )
+          })
+        )}
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}

package/src/core/ui/AutosyncMenuButton.css

@@ -0,0 +1,67 @@
+.menuTitle {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--fgColor-default, #e6edf3);
+  padding: 6px 6px 0;
+  margin: 0;
+}
+
+.description {
+  font-size: 12px;
+  color: var(--fgColor-muted, #848d97);
+  padding: 0 6px 4px;
+  margin: 0;
+  line-height: 1.4;
+}
+
+.branchRow {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 6px 6px;
+}
+
+.branchLabel {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--fgColor-default, #e6edf3);
+}
+
+.statusRow {
+  padding: 4px 6px 2px;
+}
+
+.scopeHint {
+  font-size: 11px;
+  color: var(--fgColor-muted, #848d97);
+  padding: 4px 0;
+  margin: 0;
+}
+
+.statusError {
+  font-size: 11px;
+  color: var(--fgColor-danger, #f85149);
+}
+
+.statusOk {
+  font-size: 11px;
+  color: var(--fgColor-muted, #848d97);
+}
+
+.footer {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  color: var(--fgColor-muted, #848d97);
+  padding: 2px 6px 0;
+  margin: 0;
+}
+
+.footerDot {
+  width: 8px;
+  height: 8px;
+  background: hsl(212, 92%, 45%);
+  border-radius: 50%;
+  flex-shrink: 0;
+}