@dfosco/storyboard-core 3.2.0 → 3.3.1

package/scaffold/skills/vitest/references/features-mocking.md

@@ -0,0 +1,265 @@
+---
+name: mocking
+description: Mock functions, modules, timers, and dates with vi utilities
+---
+
+# Mocking
+
+## Mock Functions
+
+```ts
+import { expect, vi } from 'vitest'
+
+// Create mock function
+const fn = vi.fn()
+fn('hello')
+
+expect(fn).toHaveBeenCalled()
+expect(fn).toHaveBeenCalledWith('hello')
+
+// With implementation
+const add = vi.fn((a, b) => a + b)
+expect(add(1, 2)).toBe(3)
+
+// Mock return values
+fn.mockReturnValue(42)
+fn.mockReturnValueOnce(1).mockReturnValueOnce(2)
+fn.mockResolvedValue({ data: true })
+fn.mockRejectedValue(new Error('fail'))
+
+// Mock implementation
+fn.mockImplementation((x) => x * 2)
+fn.mockImplementationOnce(() => 'first call')
+```
+
+## Spying on Objects
+
+```ts
+const cart = {
+  getTotal: () => 100,
+}
+
+const spy = vi.spyOn(cart, 'getTotal')
+cart.getTotal()
+
+expect(spy).toHaveBeenCalled()
+
+// Mock implementation
+spy.mockReturnValue(200)
+expect(cart.getTotal()).toBe(200)
+
+// Restore original
+spy.mockRestore()
+```
+
+## Module Mocking
+
+```ts
+// vi.mock is hoisted to top of file
+vi.mock('./api', () => ({
+  fetchUser: vi.fn(() => ({ id: 1, name: 'Mock' })),
+}))
+
+import { fetchUser } from './api'
+
+test('mocked module', () => {
+  expect(fetchUser()).toEqual({ id: 1, name: 'Mock' })
+})
+```
+
+### Partial Mock
+
+```ts
+vi.mock('./utils', async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    specificFunction: vi.fn(),
+  }
+})
+```
+
+### Auto-mock with Spy
+
+```ts
+// Keep implementation but spy on calls
+vi.mock('./calculator', { spy: true })
+
+import { add } from './calculator'
+
+test('spy on module', () => {
+  const result = add(1, 2) // Real implementation
+  expect(result).toBe(3)
+  expect(add).toHaveBeenCalledWith(1, 2)
+})
+```
+
+### Manual Mocks (__mocks__)
+
+```
+src/
+  __mocks__/
+    axios.ts      # Mocks 'axios'
+  api/
+    __mocks__/
+      client.ts   # Mocks './client'
+    client.ts
+```
+
+```ts
+// Just call vi.mock with no factory
+vi.mock('axios')
+vi.mock('./api/client')
+```
+
+## Dynamic Mocking (vi.doMock)
+
+Not hoisted - use for dynamic imports:
+
+```ts
+test('dynamic mock', async () => {
+  vi.doMock('./config', () => ({
+    apiUrl: 'http://test.local',
+  }))
+  
+  const { apiUrl } = await import('./config')
+  expect(apiUrl).toBe('http://test.local')
+  
+  vi.doUnmock('./config')
+})
+```
+
+## Mock Timers
+
+```ts
+import { afterEach, beforeEach, vi } from 'vitest'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+test('timers', () => {
+  const fn = vi.fn()
+  setTimeout(fn, 1000)
+  
+  expect(fn).not.toHaveBeenCalled()
+  
+  vi.advanceTimersByTime(1000)
+  expect(fn).toHaveBeenCalled()
+})
+
+// Other timer methods
+vi.runAllTimers()           // Run all pending timers
+vi.runOnlyPendingTimers()   // Run only currently pending
+vi.advanceTimersToNextTimer() // Advance to next timer
+```
+
+### Async Timer Methods
+
+```ts
+test('async timers', async () => {
+  vi.useFakeTimers()
+  
+  let resolved = false
+  setTimeout(() => Promise.resolve().then(() => { resolved = true }), 100)
+  
+  await vi.advanceTimersByTimeAsync(100)
+  expect(resolved).toBe(true)
+})
+```
+
+## Mock Dates
+
+```ts
+vi.setSystemTime(new Date('2024-01-01'))
+expect(new Date().getFullYear()).toBe(2024)
+
+vi.useRealTimers() // Restore
+```
+
+## Mock Globals
+
+```ts
+vi.stubGlobal('fetch', vi.fn(() => 
+  Promise.resolve({ json: () => ({ data: 'mock' }) })
+))
+
+// Restore
+vi.unstubAllGlobals()
+```
+
+## Mock Environment Variables
+
+```ts
+vi.stubEnv('API_KEY', 'test-key')
+expect(import.meta.env.API_KEY).toBe('test-key')
+
+// Restore
+vi.unstubAllEnvs()
+```
+
+## Clearing Mocks
+
+```ts
+const fn = vi.fn()
+fn()
+
+fn.mockClear()       // Clear call history
+fn.mockReset()       // Clear history + implementation
+fn.mockRestore()     // Restore original (for spies)
+
+// Global
+vi.clearAllMocks()
+vi.resetAllMocks()
+vi.restoreAllMocks()
+```
+
+## Config Auto-Reset
+
+```ts
+// vitest.config.ts
+defineConfig({
+  test: {
+    clearMocks: true,    // Clear before each test
+    mockReset: true,     // Reset before each test
+    restoreMocks: true,  // Restore after each test
+    unstubEnvs: true,    // Restore env vars
+    unstubGlobals: true, // Restore globals
+  },
+})
+```
+
+## Hoisted Variables for Mocks
+
+```ts
+const mockFn = vi.hoisted(() => vi.fn())
+
+vi.mock('./module', () => ({
+  getData: mockFn,
+}))
+
+import { getData } from './module'
+
+test('hoisted mock', () => {
+  mockFn.mockReturnValue('test')
+  expect(getData()).toBe('test')
+})
+```
+
+## Key Points
+
+- `vi.mock` is hoisted - called before imports
+- Use `vi.doMock` for dynamic, non-hoisted mocking
+- Always restore mocks to avoid test pollution
+- Use `{ spy: true }` to keep implementation but track calls
+- `vi.hoisted` lets you reference variables in mock factories
+
+<!-- 
+Source references:
+- https://vitest.dev/guide/mocking.html
+- https://vitest.dev/api/vi.html
+-->

package/scaffold/skills/vitest/references/features-snapshots.md

@@ -0,0 +1,207 @@
+---
+name: snapshot-testing
+description: Snapshot testing with file, inline, and file snapshots
+---
+
+# Snapshot Testing
+
+Snapshot tests capture output and compare against stored references.
+
+## Basic Snapshot
+
+```ts
+import { expect, test } from 'vitest'
+
+test('snapshot', () => {
+  const result = generateOutput()
+  expect(result).toMatchSnapshot()
+})
+```
+
+First run creates `.snap` file:
+
+```js
+// __snapshots__/test.spec.ts.snap
+exports['snapshot 1'] = `
+{
+  "id": 1,
+  "name": "test"
+}
+`
+```
+
+## Inline Snapshots
+
+Stored directly in test file:
+
+```ts
+test('inline snapshot', () => {
+  const data = { foo: 'bar' }
+  expect(data).toMatchInlineSnapshot()
+})
+```
+
+Vitest updates the test file:
+
+```ts
+test('inline snapshot', () => {
+  const data = { foo: 'bar' }
+  expect(data).toMatchInlineSnapshot(`
+    {
+      "foo": "bar",
+    }
+  `)
+})
+```
+
+## File Snapshots
+
+Compare against explicit file:
+
+```ts
+test('render html', async () => {
+  const html = renderComponent()
+  await expect(html).toMatchFileSnapshot('./expected/component.html')
+})
+```
+
+## Snapshot Hints
+
+Add descriptive hints:
+
+```ts
+test('multiple snapshots', () => {
+  expect(header).toMatchSnapshot('header')
+  expect(body).toMatchSnapshot('body content')
+  expect(footer).toMatchSnapshot('footer')
+})
+```
+
+## Object Shape Matching
+
+Match partial structure:
+
+```ts
+test('shape snapshot', () => {
+  const data = { 
+    id: Math.random(), 
+    created: new Date(),
+    name: 'test' 
+  }
+  
+  expect(data).toMatchSnapshot({
+    id: expect.any(Number),
+    created: expect.any(Date),
+  })
+})
+```
+
+## Error Snapshots
+
+```ts
+test('error message', () => {
+  expect(() => {
+    throw new Error('Something went wrong')
+  }).toThrowErrorMatchingSnapshot()
+})
+
+test('inline error', () => {
+  expect(() => {
+    throw new Error('Bad input')
+  }).toThrowErrorMatchingInlineSnapshot(`[Error: Bad input]`)
+})
+```
+
+## Updating Snapshots
+
+```bash
+# Update all snapshots
+vitest -u
+vitest --update
+
+# In watch mode, press 'u' to update failed snapshots
+```
+
+## Custom Serializers
+
+Add custom snapshot formatting:
+
+```ts
+expect.addSnapshotSerializer({
+  test(val) {
+    return val && typeof val.toJSON === 'function'
+  },
+  serialize(val, config, indentation, depth, refs, printer) {
+    return printer(val.toJSON(), config, indentation, depth, refs)
+  },
+})
+```
+
+Or via config:
+
+```ts
+// vitest.config.ts
+defineConfig({
+  test: {
+    snapshotSerializers: ['./my-serializer.ts'],
+  },
+})
+```
+
+## Snapshot Format Options
+
+```ts
+defineConfig({
+  test: {
+    snapshotFormat: {
+      printBasicPrototype: false, // Don't print Array/Object prototypes
+      escapeString: false,
+    },
+  },
+})
+```
+
+## Concurrent Test Snapshots
+
+Use context's expect:
+
+```ts
+test.concurrent('concurrent 1', async ({ expect }) => {
+  expect(await getData()).toMatchSnapshot()
+})
+
+test.concurrent('concurrent 2', async ({ expect }) => {
+  expect(await getOther()).toMatchSnapshot()
+})
+```
+
+## Snapshot File Location
+
+Default: `__snapshots__/<test-file>.snap`
+
+Customize:
+
+```ts
+defineConfig({
+  test: {
+    resolveSnapshotPath: (testPath, snapExtension) => {
+      return testPath.replace('__tests__', '__snapshots__') + snapExtension
+    },
+  },
+})
+```
+
+## Key Points
+
+- Commit snapshot files to version control
+- Review snapshot changes in code review
+- Use hints for multiple snapshots in one test
+- Use `toMatchFileSnapshot` for large outputs (HTML, JSON)
+- Inline snapshots auto-update in test file
+- Use context's `expect` for concurrent tests
+
+<!-- 
+Source references:
+- https://vitest.dev/guide/snapshot.html
+- https://vitest.dev/api/expect.html#tomatchsnapshot
+-->

package/scaffold/skills/worktree/SKILL.md

@@ -0,0 +1,51 @@
+# Worktree Skill
+
+> Triggered by: "create worktree", "new worktree", "worktree for", "worktree"
+
+## What This Does
+
+Creates a git worktree for a given branch name inside `.worktrees/` and switches into it.
+
+---
+
+## How to Execute
+
+When the user asks for a worktree named `<branch-name>`:
+
+### Step 1: Create the worktree
+
+If the branch already exists locally or on the remote:
+
+```bash
+git worktree add .worktrees/<branch-name> <branch-name>
+```
+
+If the branch does NOT exist yet, create it from the current HEAD:
+
+```bash
+git worktree add .worktrees/<branch-name> -b <branch-name>
+```
+
+### Step 2: Change into the worktree directory
+
+```bash
+cd .worktrees/<branch-name>
+```
+
+All subsequent commands in the session should run from this directory.
+
+### Step 3: Confirm
+
+Print the current working directory and branch to confirm:
+
+```bash
+pwd && git branch --show-current
+```
+
+---
+
+## Notes
+
+- Worktrees live in `.worktrees/` at the repo root — this directory is already gitignored.
+- The branch name comes from the user's request (e.g., "create worktree comments-redo" → branch is `comments-redo`).
+- If the worktree already exists, inform the user and `cd` into it instead of recreating it.

package/scaffold/storyboard.config.json

@@ -0,0 +1,26 @@
+{
+  "repository": {
+    "owner": "",
+    "name": ""
+  },
+  "modes": {
+    "enabled": false
+  },
+  "comments": {
+    "discussions": {
+      "category": "Comments"
+    }
+  },
+  "plugins": {
+    "devtools": true
+  },
+  "workshop": {
+    "enabled": false,
+    "features": {
+      "createPrototype": true,
+      "createFlow": true,
+      "createCanvas": true
+    }
+  },
+  "featureFlags": {}
+}

package/scaffold/svelte.config.js

@@ -0,0 +1 @@
+export default {}

package/scaffold/toolbar.config.json

@@ -0,0 +1,4 @@
+{
+  "_comment": "Client toolbar overrides. Deep-merged with core defaults. See @dfosco/storyboard-core/toolbar.config.json for all options.",
+  "menus": {}
+}

package/src/ActionMenuButton.svelte

@@ -4,7 +4,7 @@
   Renders a standalone toolbar button whose items come from the
   command action registry (via getActionChildren). This is the
   standalone equivalent of CommandMenu's submenu rendering — any
-  menu declared in core-ui.config.json with an "action" reference
+  menu declared in toolbar.config.json with an "action" reference
   gets rendered by this component.
 
   Supports child types: default, toggle, radio.

package/src/CanvasCreateMenu.svelte

@@ -20,7 +20,7 @@
   const widgetTypes = [
     { type: 'sticky-note', label: 'Sticky Note' },
     { type: 'markdown', label: 'Markdown' },
-    { type: 'prototype', label: 'Prototype' },
+    { type: 'prototype', label: 'Prototype embed' },
   ]
 
   let menuOpen = $state(false)

package/src/CoreUIBar.svelte

@@ -17,13 +17,16 @@
   import * as Tooltip from './lib/components/ui/tooltip/index.js'
   import Icon from './svelte-plugin-ui/components/Icon.svelte'
   import { modeState } from './svelte-plugin-ui/stores/modeStore.js'
-  import { sidePanelState, togglePanel } from './stores/sidePanelStore.js'
+  import { sidePanelState, togglePanel, openPanel } from './stores/sidePanelStore.js'
   import { initCommandActions, registerCommandAction, getActionChildren, isExcludedByRoute, setRoutingBasePath } from './commandActions.js'
   import { isMenuHidden } from './uiConfig.js'
-  import coreUIConfig from '../core-ui.config.json'
+  import defaultToolbarConfig from '../toolbar.config.json'
 
-  interface Props { basePath?: string }
-  let { basePath = '/' }: Props = $props()
+  interface Props { basePath?: string; toolbarConfig?: any }
+  let { basePath = '/', toolbarConfig }: Props = $props()
+
+  // Use provided config (merged by mountStoryboardCore) or fall back to defaults
+  const config = $derived(toolbarConfig || defaultToolbarConfig)
 
   let visible = $state(true)
   // Hide the entire toolbar when loaded inside a prototype embed iframe
@@ -45,7 +48,7 @@
   let canvasActive = $state(false)
   let activeCanvasName = $state('')
   let canvasZoom = $state(100)
-  const canvasToolbarConfig = (coreUIConfig as any).canvasToolbar || {}
+  const canvasToolbarConfig = $derived((config as any).canvasToolbar || {})
 
   const ZOOM_STEP = 10
   const ZOOM_MIN = 25
@@ -54,18 +57,18 @@
   // Roving tabindex: only one button in the toolbar is tabbable at a time
   let activeToolbarIndex = $state(-1)
 
-  const commandMenuConfig = isMenuHidden('command') ? null : coreUIConfig.menus?.command
-  const shortcutsConfig = (coreUIConfig as any).shortcuts || {}
+  const commandMenuConfig = $derived(isMenuHidden('command') ? null : config.menus?.command)
+  const shortcutsConfig = $derived((config as any).shortcuts || {})
 
   // Build ordered menu list from JSON key order (excluding command, which is always rightmost)
-  const allMenus = (coreUIConfig.menus || {}) as Record<string, any>
-  const orderedMenus = Object.entries(allMenus)
+  const allMenus = $derived((config.menus || {}) as Record<string, any>)
+  const orderedMenus = $derived(Object.entries(allMenus)
     .filter(([key]) => key !== 'command')
     .filter(([key]) => !isMenuHidden(key))
-    .map(([key, menu]) => ({ key, ...menu }))
+    .map(([key, menu]) => ({ key, ...menu })))
 
   // Discover menus with sidepanel property
-  const sidepanelMenus = orderedMenus.filter(menu => menu.sidepanel)
+  const sidepanelMenus = $derived(orderedMenus.filter(menu => menu.sidepanel))
 
   function menuVisibleInMode(menu: any, mode: string): boolean {
     if (!menu?.modes) return false
@@ -215,6 +218,14 @@
       })
     }
 
+    // Auto-open inspector panel if ?inspect= param is in the URL
+    try {
+      const inspectParam = new URL(window.location.href).searchParams.get('inspect')
+      if (inspectParam) {
+        openPanel('inspector')
+      }
+    } catch {}
+
     // Register devtools submenu (show flow info, reset params, hide mode, logout)
     {
       let loader: any = null
@@ -552,7 +563,7 @@
   </div>
 {/if}
 
-{#if SidePanel}
+{#if !isEmbed && SidePanel}
   <SidePanel onClose={() => focusToolbarItem(activeToolbarIndex < 0 ? toolbarItemCount - 1 : activeToolbarIndex)} />
 {/if}
 

package/src/CreateMenuButton.svelte

@@ -1,7 +1,7 @@
 <!--
   CreateMenuButton — config-driven trigger for create/workshop features.
   Appears to the left of the command button in develop (inspect) mode.
-  Menu label and items are defined by core-ui.config.json buttons.create section.
+  Menu label and items are defined by toolbar.config.json buttons.create section.
 
   Icon options (set in config):
     - "icon": octicon name (e.g. "plus", "beaker") — rendered via Octicon.svelte