@dfosco/storyboard-core 4.0.0-beta.2 → 4.0.0-beta.21

package/src/vite/server-plugin.js

@@ -13,6 +13,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { parse as parseJsonc } from 'jsonc-parser'
+import { getConfig } from '../configSchema.js'
 import { serverFeatures as workshopFeatures } from '../workshop/features/registry-server.js'
 import { docsHandler, collectFiles } from './docs-handler.js'
 import { createCanvasHandler } from '../canvas/server.js'
@@ -45,16 +46,16 @@ function sendJson(res, status, data) {
 }
 
 /**
- * Read storyboard.config.json from the project root.
+ * Read storyboard.config.json from the project root and apply defaults.
  */
 function readConfig(root) {
   const configPath = path.join(root, 'storyboard.config.json')
-  if (!fs.existsSync(configPath)) return {}
+  if (!fs.existsSync(configPath)) return getConfig({})
   try {
     const raw = fs.readFileSync(configPath, 'utf-8')
-    return parseJsonc(raw) || {}
+    return getConfig(parseJsonc(raw) || {})
   } catch {
-    return {}
+    return getConfig({})
   }
 }
 
@@ -74,6 +75,19 @@ export default function storyboardServer() {
   return {
     name: 'storyboard-server',
 
+    config() {
+      return {
+        optimizeDeps: {
+          include: [
+            'highlight.js/lib/core',
+            'highlight.js/lib/languages/javascript',
+            'highlight.js/lib/languages/typescript',
+            'highlight.js/lib/languages/xml',
+          ],
+        },
+      }
+    },
+
     configResolved(viteConfig) {
       root = viteConfig.root
       base = viteConfig.base || '/'
@@ -82,6 +96,82 @@ export default function storyboardServer() {
     },
 
     configureServer(server) {
+      // --- Canvas reload guard ---------------------------------------------------
+      // Suppress full-reloads and HMR updates for clients on canvas routes.
+      // Canvas pages send heartbeats via import.meta.hot; the guard auto-expires
+      // 5s after the last heartbeat so closed tabs never leave it stuck.
+      // Opt out with ?canvas-hmr in the URL when developing canvas UI code.
+      {
+        let recentCanvasMutationAt = 0
+        const CANVAS_WINDOW_MS = 1500
+        const GUARD_TTL_MS = 5000
+        const isCanvasFile = (file = '') => /\.canvas\.jsonl$/i.test(file.replace(/\\/g, '/'))
+
+        const markCanvasMutation = (file = '') => {
+          if (isCanvasFile(file)) recentCanvasMutationAt = Date.now()
+        }
+
+        server.watcher.on('change', markCanvasMutation)
+        server.watcher.on('add', markCanvasMutation)
+        server.watcher.on('unlink', markCanvasMutation)
+
+        const guardedClients = new Map()
+
+        server.hot.on('storyboard:canvas-hmr-guard', (data, client) => {
+          if (data.active && !data.hmrEnabled) {
+            guardedClients.set(client, Date.now() + GUARD_TTL_MS)
+          } else {
+            guardedClients.delete(client)
+          }
+        })
+
+        const cleanup = setInterval(() => {
+          const now = Date.now()
+          for (const [client, until] of guardedClients) {
+            if (now > until || !server.ws.clients.has(client)) {
+              guardedClients.delete(client)
+            }
+          }
+        }, 10000)
+        server.httpServer?.on('close', () => clearInterval(cleanup))
+
+        function isClientGuarded(client) {
+          const until = guardedClients.get(client)
+          return until != null && Date.now() < until
+        }
+
+        const originalSend = server.ws.send.bind(server.ws)
+        server.ws.send = (payload, ...rest) => {
+          // Suppress broadcast reloads within the canvas mutation window
+          if (
+            payload &&
+            payload.type === 'full-reload' &&
+            Date.now() - recentCanvasMutationAt < CANVAS_WINDOW_MS
+          ) {
+            return
+          }
+
+          // No guarded clients → broadcast normally
+          if (guardedClients.size === 0) {
+            return originalSend(payload, ...rest)
+          }
+
+          // For reload/update payloads, send only to unguarded clients
+          if (payload && (payload.type === 'full-reload' || payload.type === 'update')) {
+            for (const client of server.ws.clients) {
+              if (!isClientGuarded(client)) {
+                client.send(payload)
+              }
+            }
+            return
+          }
+
+          // Everything else (custom events, errors) broadcasts normally
+          return originalSend(payload, ...rest)
+        }
+      }
+      // --- End canvas reload guard -----------------------------------------------
+
       const workshopConfig = config.workshop || {}
       const enabledFeatures = workshopConfig.features || {}
 
@@ -109,9 +199,9 @@ export default function storyboardServer() {
       // Wire canvas API routes (always enabled — CRUD for .canvas.jsonl files)
       routeHandlers.set('canvas', createCanvasHandler({ root, sendJson }))
 
-      // Ignore src/canvas/images/ so pasted image writes don't trigger reloads
-      const canvasImagesDir = path.join(root, 'src', 'canvas', 'images')
-      server.watcher.unwatch(canvasImagesDir)
+      // Ignore assets/canvas/ so image/snapshot writes don't trigger reloads
+      server.watcher.unwatch(path.join(root, 'assets', 'canvas', 'images'))
+      server.watcher.unwatch(path.join(root, 'assets', 'canvas', 'snapshots'))
 
       // Wire autosync API routes (always enabled — git automation for dev)
       routeHandlers.set('autosync', createAutosyncHandler({ root, sendJson }))
@@ -300,6 +390,47 @@ export default function storyboardServer() {
         })
       }
 
+      // Emit story sources JSON so the "show code" widget action works in
+      // deployed builds. In dev, StoryWidget uses Vite's ?raw import; in prod
+      // it fetches this static JSON instead.
+      const storySources = {}
+      const storyExts = ['.story.jsx', '.story.tsx', '.story.js', '.story.ts']
+      for (const relPath of allSrcFiles) {
+        if (storyExts.some(ext => relPath.endsWith(ext))) {
+          storySources[relPath] = sources[relPath] || ''
+        }
+      }
+      if (Object.keys(storySources).length > 0) {
+        this.emitFile({
+          type: 'asset',
+          fileName: '_storyboard/stories/sources.json',
+          source: JSON.stringify(storySources),
+        })
+      }
+
+      // Emit canvas images and snapshots so they're available in deployed (static) builds.
+      // Dev server serves these dynamically; production needs the static files.
+      // Private images (prefixed with _) are excluded from the build.
+      for (const dir of [
+        path.join(root, 'assets', 'canvas', 'images'),
+        path.join(root, 'assets', 'canvas', 'snapshots'),
+      ]) {
+        try {
+          const imageFiles = await fs.promises.readdir(dir)
+          for (const file of imageFiles) {
+            if (file.startsWith('_') || file.startsWith('.')) continue
+            try {
+              const data = await fs.promises.readFile(path.join(dir, file))
+              this.emitFile({
+                type: 'asset',
+                fileName: `_storyboard/canvas/images/${file}`,
+                source: data,
+              })
+            } catch { /* skip unreadable files */ }
+          }
+        } catch { /* directory doesn't exist */ }
+      }
+
       // GitHub Pages uses Jekyll which ignores _-prefixed directories.
       // Emit .nojekyll to ensure _storyboard/ is served.
       this.emitFile({
@@ -307,6 +438,18 @@ export default function storyboardServer() {
         fileName: '.nojekyll',
         source: '',
       })
+
+      // Emit CNAME for GitHub Pages custom domain if configured.
+      // Without this, deploy scripts that clean the gh-pages root will
+      // delete the CNAME on every push, causing intermittent 404s.
+      const customDomain = (config.customDomain || '').trim()
+      if (customDomain && !customDomain.includes('/') && !customDomain.includes(':') && !customDomain.includes(' ')) {
+        this.emitFile({
+          type: 'asset',
+          fileName: 'CNAME',
+          source: customDomain + '\n',
+        })
+      }
     },
   }
 }

package/src/workshop/features/createCanvas/CreateCanvasForm.svelte

@@ -18,6 +18,7 @@
   let name = $state('')
   let title = $state('')
   let titleTouched = $state(false)
+  let description = $state('')
   let folder = $state('')
   let includeJsx = $state(false)
   let grid = $state(true)
@@ -45,7 +46,7 @@
   const canSubmit = $derived(!!kebabName && !nameError && !submitting)
 
   function getApiUrl() {
-    const basePath = document.querySelector('base')?.getAttribute('href') || '/'
+    const basePath = window.__STORYBOARD_BASE_PATH__ || '/'
     return basePath.replace(/\/$/, '') + '/_storyboard/canvas'
   }
 
@@ -81,7 +82,7 @@
     try {
       const res = await fetch(getApiUrl() + '/create', {
         method: 'POST', headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ name: kebabName, title: displayTitle, folder: folder || undefined, grid, includeJsx }),
+        body: JSON.stringify({ name: kebabName, title: displayTitle, description: description || undefined, folder: folder || undefined, grid, includeJsx }),
       })
       const data = await res.json()
       if (!res.ok) { error = data.error || 'Failed to create canvas'; return }
@@ -116,6 +117,11 @@
     <Input id="sb-canvas-title" placeholder={autoTitle || 'Auto-derived from name'} value={displayTitle} oninput={handleTitleInput} onblur={handleTitleBlur} />
   </div>
 
+  <div class="space-y-1">
+    <Label for="sb-canvas-description">Description <span class="text-muted-foreground font-normal">(optional)</span></Label>
+    <Input id="sb-canvas-description" placeholder="A brief description of this canvas" bind:value={description} />
+  </div>
+
   <div class="space-y-1">
     <Label for="sb-canvas-folder">Folder</Label>
     <select class="flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-xs transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50" id="sb-canvas-folder" bind:value={folder} disabled={loading}>

package/src/workshop/features/createFlow/CreateFlowForm.svelte

@@ -104,7 +104,7 @@
   )
 
   function getApiUrl() {
-    const basePath = document.querySelector('base')?.getAttribute('href') || '/'
+    const basePath = window.__STORYBOARD_BASE_PATH__ || '/'
     return basePath.replace(/\/$/, '') + '/_storyboard/workshop/flows'
   }
 

package/src/workshop/features/createPage/CreatePageForm.svelte

@@ -67,7 +67,7 @@
   )
 
   function getApiUrl() {
-    const basePath = document.querySelector('base')?.getAttribute('href') || '/'
+    const basePath = window.__STORYBOARD_BASE_PATH__ || '/'
     return basePath.replace(/\/$/, '') + '/_storyboard/workshop/pages'
   }
 

package/src/workshop/features/createPrototype/CreatePrototypeForm.svelte

@@ -88,7 +88,7 @@
   let templateMenuOpen = $state(false)
 
   function getApiUrl() {
-    const basePath = document.querySelector('base')?.getAttribute('href') || '/'
+    const basePath = window.__STORYBOARD_BASE_PATH__ || '/'
     return basePath.replace(/\/$/, '') + '/_storyboard/workshop/prototypes'
   }
 
@@ -136,7 +136,7 @@
         // External prototype — no local route to navigate to, just close after a moment
         setTimeout(() => onClose?.(), 1500)
       } else {
-        setTimeout(() => { const base = document.querySelector('base')?.href || '/'; window.location.href = base + data.route.slice(1) }, 1500)
+        setTimeout(() => { const base = (window.__STORYBOARD_BASE_PATH__ || '/').replace(/\/$/, ''); window.location.href = base + data.route }, 1500)
       }
     } catch (err: any) { error = err.message || 'Network error' } finally { submitting = false }
   }

package/src/workshop/features/createStory/CreateStoryForm.svelte

@@ -0,0 +1,160 @@
+<!--
+  CreateStoryForm — workshop form for creating a new .story.jsx/.tsx file.
+  Scaffolds a story file via the canvas server API.
+-->
+
+<script lang="ts">
+  import { onMount } from 'svelte'
+  import { Button } from '../../../lib/components/ui/button/index.js'
+  import { Input } from '../../../lib/components/ui/input/index.js'
+  import { Label } from '../../../lib/components/ui/label/index.js'
+  import * as Panel from '../../../lib/components/ui/panel/index.js'
+  import * as Alert from '../../../lib/components/ui/alert/index.js'
+
+  interface Props { onClose?: () => void }
+  let { onClose }: Props = $props()
+
+  let name = $state('')
+  let location = $state('canvas')
+  let format = $state('jsx')
+
+  let submitting = $state(false)
+  let error: string | null = $state(null)
+  let success: string | null = $state(null)
+  let createdPath: string | null = $state(null)
+
+  // Pre-fill canvasName from the active canvas (set by CanvasPage bridge)
+  let canvasName = $state('')
+
+  const kebabName = $derived(
+    name.replace(/[^a-zA-Z0-9\s_-]/g, '').trim().replace(/[\s_]+/g, '-').toLowerCase().replace(/-+/g, '-').replace(/^-|-$/g, '')
+  )
+
+  const nameError = $derived(
+    name.trim() && !kebabName ? 'Name must contain at least one alphanumeric character'
+    : name.trim() && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(kebabName) ? 'Name must be kebab-case'
+    : null
+  )
+
+  const filePreview = $derived(
+    kebabName ? `${kebabName}.story.${format}` : ''
+  )
+
+  const canSubmit = $derived(!!kebabName && !nameError && !submitting)
+
+  const STORY_SUCCESS_KEY = 'sb-story-created'
+
+  function getApiUrl() {
+    const basePath = (window as any).__STORYBOARD_BASE_PATH__ || '/'
+    return basePath.replace(/\/$/, '') + '/_storyboard/canvas'
+  }
+
+  onMount(() => {
+    // Read active canvas name from the bridge state (window, not sessionStorage)
+    try {
+      const bridgeState = (window as any).__storyboardCanvasBridgeState
+      if (bridgeState?.name) canvasName = bridgeState.name
+    } catch {}
+
+    // Restore success state after Vite full-reload
+    try {
+      const saved = sessionStorage.getItem(STORY_SUCCESS_KEY)
+      if (saved) {
+        const parsed = JSON.parse(saved)
+        success = parsed.success
+        createdPath = parsed.path
+        sessionStorage.removeItem(STORY_SUCCESS_KEY)
+      }
+    } catch {}
+  })
+
+  async function submit() {
+    if (!canSubmit) return
+    submitting = true; error = null; success = null; createdPath = null
+    try {
+      const res = await fetch(getApiUrl() + '/create-story', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: kebabName,
+          location,
+          format,
+          canvasName: location === 'canvas' ? canvasName : undefined,
+        }),
+      })
+      const data = await res.json()
+      if (!res.ok) { error = data.error || 'Failed to create story'; return }
+      success = `Created ${data.path}`
+      createdPath = data.path
+      // Persist for toast after Vite reload
+      try {
+        sessionStorage.setItem(STORY_SUCCESS_KEY, JSON.stringify({
+          success: `Created ${data.name}.story.${format}`,
+          path: data.path,
+        }))
+      } catch {}
+    } catch (err: any) { error = err.message || 'Network error' } finally { submitting = false }
+  }
+
+  function handleKeydown(e: KeyboardEvent) { if (e.key === 'Enter' && canSubmit) submit() }
+</script>
+
+<Panel.Header>
+  <Panel.Title>Create story</Panel.Title>
+  <Panel.Close />
+</Panel.Header>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="p-4 pt-2 space-y-3" onkeydown={handleKeydown}>
+  <div class="space-y-1">
+    <Label for="sb-story-name">Component name</Label>
+    <Input id="sb-story-name" placeholder="e.g. user-card" autocomplete="off" spellcheck="false" bind:value={name} />
+    {#if nameError}<p class="text-sm text-destructive">{nameError}</p>{/if}
+    {#if filePreview}<p class="text-xs text-muted-foreground">File: <code class="px-1 py-0.5 bg-muted rounded font-mono text-foreground text-xs">{filePreview}</code></p>{/if}
+  </div>
+
+  <fieldset class="space-y-1.5">
+    <Label>Location</Label>
+    <div class="flex flex-col gap-1.5">
+      <label class="flex items-center gap-2 text-sm cursor-pointer">
+        <input type="radio" name="sb-story-location" value="canvas" bind:group={location} class="accent-primary" />
+        This canvas directory
+      </label>
+      <label class="flex items-center gap-2 text-sm cursor-pointer">
+        <input type="radio" name="sb-story-location" value="components" bind:group={location} class="accent-primary" />
+        <code class="text-xs bg-muted px-1 py-0.5 rounded">src/components/</code>
+      </label>
+    </div>
+  </fieldset>
+
+  <fieldset class="space-y-1.5">
+    <Label>Format</Label>
+    <div class="flex gap-3">
+      <label class="flex items-center gap-2 text-sm cursor-pointer">
+        <input type="radio" name="sb-story-format" value="jsx" bind:group={format} class="accent-primary" />
+        JSX
+      </label>
+      <label class="flex items-center gap-2 text-sm cursor-pointer">
+        <input type="radio" name="sb-story-format" value="tsx" bind:group={format} class="accent-primary" />
+        TSX
+      </label>
+    </div>
+  </fieldset>
+
+  {#if error}<Alert.Root variant="destructive"><Alert.Description>{error}</Alert.Description></Alert.Root>{/if}
+  {#if success}
+    <Alert.Root>
+      <Alert.Description class="text-success">
+        {success}
+        {#if createdPath}
+          <br /><span class="text-xs text-muted-foreground">To edit your component, go to <code class="px-1 py-0.5 bg-muted rounded font-mono text-xs">{createdPath}</code></span>
+        {/if}
+      </Alert.Description>
+    </Alert.Root>
+  {/if}
+</div>
+
+<Panel.Footer>
+  <Button variant="outline" onclick={onClose}>Cancel</Button>
+  <Button onclick={submit} disabled={!canSubmit}>{submitting ? 'Creating\u2026' : 'Create'}</Button>
+</Panel.Footer>

package/src/workshop/features/createStory/index.js

@@ -0,0 +1,14 @@
+/**
+ * Create Story feature — workshop form for creating .story.jsx/.tsx files.
+ *
+ * Server routes are handled by the canvas handler at /_storyboard/canvas/create-story.
+ * This feature provides the workshop UI overlay.
+ */
+
+import CreateStoryForm from './CreateStoryForm.svelte'
+
+export const name = 'createStory'
+export const label = 'Create story'
+export const icon = '⚡'
+export const overlayId = 'createStory'
+export const overlay = CreateStoryForm

package/src/workshop/features/registry.js

@@ -14,6 +14,7 @@ import * as createPrototype from './createPrototype/index.js'
 import * as createFlow from './createFlow/index.js'
 import * as createPage from './createPage/index.js'
 import * as createCanvas from './createCanvas/index.js'
+import * as createStory from './createStory/index.js'
 
 /**
  * All available workshop features, keyed by config name.
@@ -23,4 +24,5 @@ export const features = {
   createFlow,
   createPage,
   createCanvas,
+  createStory,
 }

package/src/worktree/port.js

@@ -11,7 +11,7 @@
  *   import { getPort, detectWorktreeName, resolvePort } from '@dfosco/storyboard-core/worktree/port'
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, realpathSync } from 'fs'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, realpathSync } from 'fs'
 import { join, dirname, basename } from 'path'
 import { execSync } from 'child_process'
 
@@ -60,6 +60,10 @@ export function detectWorktreeName() {
     const worktreeMatch = realCwd.match(/\.worktrees[/\\]([^/\\]+)/)
     if (worktreeMatch) return worktreeMatch[1]
 
+    // Not a worktree — check the current branch name
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim()
+    if (branch && branch !== 'main' && branch !== 'master') return branch
+
     return 'main'
   } catch {
     return 'main'
@@ -138,3 +142,55 @@ export function slugify(name) {
     .map((s) => s.replace(/^-+|-+$/g, ''))
     .join('/')
 }
+
+/**
+ * Resolve the repo root — the directory that contains `.worktrees/`.
+ *
+ * Works whether cwd is the repo root itself or inside `.worktrees/<name>/`.
+ *
+ * @param {string} [cwd]
+ * @returns {string} absolute path to repo root
+ */
+export function repoRoot(cwd = process.cwd()) {
+  const realCwd = realpathSync(cwd)
+
+  const worktreeMatch = realCwd.match(/^(.+)[/\\]\.worktrees[/\\][^/\\]+/)
+  if (worktreeMatch) return worktreeMatch[1]
+
+  return realCwd
+}
+
+/**
+ * Resolve the full path to a worktree directory.
+ *
+ * Returns repo root for 'main', `.worktrees/<name>` otherwise.
+ *
+ * @param {string} name — worktree name
+ * @param {string} [cwd]
+ * @returns {string} absolute path
+ */
+export function worktreeDir(name, cwd) {
+  const root = repoRoot(cwd)
+  if (name === 'main') return root
+  return join(root, '.worktrees', name)
+}
+
+/**
+ * List existing worktree directory names from `.worktrees/`.
+ *
+ * Only returns directories that look like real worktrees (contain a `.git` file).
+ * Does not include 'main'.
+ *
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+export function listWorktrees(cwd) {
+  const root = repoRoot(cwd)
+  const worktreesDir = join(root, '.worktrees')
+
+  if (!existsSync(worktreesDir)) return []
+
+  return readdirSync(worktreesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(worktreesDir, d.name, '.git')))
+    .map((d) => d.name)
+}

package/src/worktree/port.test.js

@@ -4,7 +4,7 @@ import { join } from 'path'
 import { tmpdir } from 'os'
 
 // We test the pure functions by importing and overriding cwd
-import { portsFilePath, getPort, resolvePort, slugify } from './port.js'
+import { portsFilePath, getPort, resolvePort, slugify, repoRoot, worktreeDir, listWorktrees } from './port.js'
 
 describe('slugify', () => {
   it('lowercases and replaces dots with hyphens', () => {
@@ -130,3 +130,93 @@ describe('getPort / resolvePort', () => {
     expect(port).toBe(1235)
   })
 })
+
+describe('repoRoot', () => {
+  let tempRoot
+
+  beforeEach(() => {
+    tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-root-test-')))
+    mkdirSync(join(tempRoot, '.worktrees', 'my-branch'), { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('returns cwd when at repo root', () => {
+    expect(repoRoot(tempRoot)).toBe(tempRoot)
+  })
+
+  it('returns parent of .worktrees when inside a worktree', () => {
+    const wt = join(tempRoot, '.worktrees', 'my-branch')
+    expect(repoRoot(wt)).toBe(tempRoot)
+  })
+})
+
+describe('worktreeDir', () => {
+  let tempRoot
+
+  beforeEach(() => {
+    tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-wtdir-test-')))
+    mkdirSync(join(tempRoot, '.worktrees'), { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('returns repo root for main', () => {
+    expect(worktreeDir('main', tempRoot)).toBe(tempRoot)
+  })
+
+  it('returns .worktrees/<name> for branches', () => {
+    expect(worktreeDir('my-feature', tempRoot)).toBe(join(tempRoot, '.worktrees', 'my-feature'))
+  })
+})
+
+describe('listWorktrees', () => {
+  let tempRoot
+
+  beforeEach(() => {
+    tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-list-test-')))
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('returns empty array when .worktrees does not exist', () => {
+    expect(listWorktrees(tempRoot)).toEqual([])
+  })
+
+  it('returns only directories with a .git file', () => {
+    const wtDir = join(tempRoot, '.worktrees')
+    mkdirSync(wtDir)
+
+    // Valid worktree — has .git file
+    mkdirSync(join(wtDir, 'valid'))
+    writeFileSync(join(wtDir, 'valid', '.git'), 'gitdir: /some/path')
+
+    // Not a worktree — no .git file
+    mkdirSync(join(wtDir, 'no-git'))
+
+    // Not a directory — file
+    writeFileSync(join(wtDir, 'ports.json'), '{}')
+
+    const result = listWorktrees(tempRoot)
+    expect(result).toEqual(['valid'])
+  })
+
+  it('returns multiple worktrees', () => {
+    const wtDir = join(tempRoot, '.worktrees')
+    mkdirSync(wtDir)
+
+    for (const name of ['alpha', 'beta', 'gamma']) {
+      mkdirSync(join(wtDir, name))
+      writeFileSync(join(wtDir, name, '.git'), 'gitdir: /some/path')
+    }
+
+    const result = listWorktrees(tempRoot)
+    expect(result.sort()).toEqual(['alpha', 'beta', 'gamma'])
+  })
+})

package/toolbar.config.json

@@ -63,7 +63,7 @@
       "handler": "core:inspector",
       "modes": ["*"],
       "prod": true,
-      "excludeRoutes": ["^/$", "/viewfinder", "/canvas/"],
+      "excludeRoutes": ["^/$", "/viewfinder", "/canvas/", "/components/"],
       "meta": { "strokeWeight": 2, "scale": 1.1 },
       "shortcut": { "key": "i", "label": "⌘I" }
     },    
@@ -80,8 +80,8 @@
       "actions": [
         { "type": "header", "label": "Create" },
         { "id": "workshop/create-prototype", "label": "New prototype", "type": "default", "modes": ["*"], "feature": "createPrototype" },
-        { "id": "workshop/create-flow", "label": "New flow", "type": "default", "modes": ["*"], "feature": "createFlow" },
-        { "id": "workshop/create-page", "label": "New page",  "type": "default", "modes": ["*"], "feature": "createPage" },
+        { "id": "workshop/create-flow", "label": "New flow", "type": "default", "modes": ["*"], "feature": "createFlow", "excludeRoutes": ["/canvas/", "/components/"] },
+        { "id": "workshop/create-page", "label": "New page",  "type": "default", "modes": ["*"], "feature": "createPage", "excludeRoutes": ["/canvas/", "/components/"] },
         { "id": "workshop/create-canvas", "label": "New canvas", "type": "default", "modes": ["*"], "feature": "createCanvas" },
         { "type": "footer", "label": "Only available in dev environment" }
       ]