@dfosco/storyboard 0.5.0-alpha.0

package/src/internals/hooks/useHideMode.js

@@ -0,0 +1,31 @@
+import { useCallback, useSyncExternalStore } from 'react'
+import { isHideMode, activateHideMode, deactivateHideMode } from '../../core/index.js'
+import { subscribeToStorage, getStorageSnapshot } from '../../core/index.js'
+
+/**
+ * Read/control hide mode.
+ *
+ * Hide mode moves all URL hash overrides into localStorage so the URL
+ * stays clean — useful when sharing storyboards with customers.
+ *
+ * @returns {{ isHidden: boolean, hide: function, show: function }}
+ *   - isHidden – true when hide mode is active
+ *   - hide()   – activate hide mode (copies hash → localStorage, cleans URL)
+ *   - show()   – deactivate hide mode (restores localStorage → hash)
+ */
+export function useHideMode() {
+  // Re-render when localStorage changes (hide flag lives there)
+  useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  const isHidden = isHideMode()
+
+  const hide = useCallback(() => {
+    activateHideMode()
+  }, [])
+
+  const show = useCallback(() => {
+    deactivateHideMode()
+  }, [])
+
+  return { isHidden, hide, show }
+}

package/src/internals/hooks/useHideMode.test.js

@@ -0,0 +1,43 @@
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData } from '../../test-utils.js'
+import { useHideMode } from './useHideMode.js'
+
+beforeEach(() => {
+  seedTestData()
+})
+
+describe('useHideMode', () => {
+  it('returns { isHidden, hide, show }', () => {
+    const { result } = renderHook(() => useHideMode())
+    expect(result.current).toHaveProperty('isHidden')
+    expect(typeof result.current.hide).toBe('function')
+    expect(typeof result.current.show).toBe('function')
+  })
+
+  it('isHidden is false initially', () => {
+    const { result } = renderHook(() => useHideMode())
+    expect(result.current.isHidden).toBe(false)
+  })
+
+  it('after calling hide(), isHidden becomes true', () => {
+    const { result } = renderHook(() => useHideMode())
+
+    act(() => {
+      result.current.hide()
+    })
+
+    expect(result.current.isHidden).toBe(true)
+  })
+
+  it('after calling show(), isHidden becomes false', () => {
+    // Activate hide mode directly via localStorage to set known state
+    localStorage.setItem('storyboard:__hide__', '1')
+    const { result } = renderHook(() => useHideMode())
+    expect(result.current.isHidden).toBe(true)
+
+    act(() => {
+      result.current.show()
+    })
+    expect(result.current.isHidden).toBe(false)
+  })
+})

package/src/internals/hooks/useLocalStorage.js

@@ -0,0 +1,57 @@
+import { useCallback, useContext, useSyncExternalStore } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { getByPath } from '../../core/index.js'
+import { getParam } from '../../core/index.js'
+import { getLocal, setLocal, removeLocal, subscribeToStorage, getStorageSnapshot } from '../../core/index.js'
+import { subscribeToHash, getHashSnapshot } from '../../core/index.js'
+
+/**
+ * Persistent localStorage override on top of scene data.
+ *
+ * Read priority:  URL hash param → localStorage → Scene JSON value → undefined
+ * Write target:   localStorage (not the URL hash)
+ *
+ * Use this hook for values that should survive page refreshes (e.g. theme).
+ * For ephemeral URL-based overrides, use `useOverride()`.
+ *
+ * @param {string} path - Dot-notation key (e.g. 'settings.theme')
+ * @returns {[any, function, function]}
+ *   [0] current value (hash ?? localStorage ?? scene default)
+ *   [1] setValue(newValue) – write to localStorage
+ *   [2] clearValue()      – remove from localStorage
+ */
+export function useLocalStorage(path) {
+  const context = useContext(StoryboardContext)
+  if (context === null) {
+    throw new Error('useLocalStorage must be used within a <StoryboardProvider>')
+  }
+
+  const { data } = context
+
+  // Scene default for this path
+  const sceneDefault = data != null ? getByPath(data, path) : undefined
+
+  // Subscribe to both hash and localStorage changes for reactivity
+  useSyncExternalStore(subscribeToHash, getHashSnapshot)
+  useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  // Read priority: hash → localStorage → scene default
+  const hashValue = getParam(path)
+  const localValue = getLocal(path)
+  const value = hashValue !== null ? hashValue : (localValue !== null ? localValue : sceneDefault)
+
+  /** Write a value to localStorage */
+  const setValue = useCallback(
+    (newValue) => {
+      setLocal(path, newValue)
+    },
+    [path],
+  )
+
+  /** Remove the localStorage value, reverting to scene default */
+  const clearValue = useCallback(() => {
+    removeLocal(path)
+  }, [path])
+
+  return [value, setValue, clearValue]
+}

package/src/internals/hooks/useLocalStorage.test.js

@@ -0,0 +1,75 @@
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData, createWrapper, TEST_SCENES } from '../../test-utils.js'
+import { useLocalStorage } from './useLocalStorage.js'
+
+beforeEach(() => {
+  seedTestData()
+})
+
+const wrapper = createWrapper(TEST_SCENES.default)
+
+describe('useLocalStorage', () => {
+  it('returns [value, setValue, clearValue]', () => {
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+    expect(result.current).toHaveLength(3)
+    expect(typeof result.current[1]).toBe('function')
+    expect(typeof result.current[2]).toBe('function')
+  })
+
+  it('falls back to scene default when no override exists', () => {
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+    expect(result.current[0]).toBe('dark_dimmed')
+  })
+
+  it('reads from localStorage when present', () => {
+    localStorage.setItem('storyboard:settings.theme', 'light')
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+    expect(result.current[0]).toBe('light')
+  })
+
+  it('hash override takes priority over localStorage', () => {
+    localStorage.setItem('storyboard:settings.theme', 'light')
+    window.location.hash = 'settings.theme=high-contrast'
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+    expect(result.current[0]).toBe('high-contrast')
+  })
+
+  it('setValue writes to localStorage', () => {
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+
+    act(() => {
+      result.current[1]('light')
+    })
+
+    expect(localStorage.getItem('storyboard:settings.theme')).toBe('light')
+  })
+
+  it('clearValue removes from localStorage', () => {
+    localStorage.setItem('storyboard:settings.theme', 'light')
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+
+    act(() => {
+      result.current[2]()
+    })
+
+    expect(localStorage.getItem('storyboard:settings.theme')).toBeNull()
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useLocalStorage('settings.theme'))
+    }).toThrow('useLocalStorage must be used within a <StoryboardProvider>')
+  })
+})

package/src/internals/hooks/useMode.js

@@ -0,0 +1,43 @@
+import { useCallback, useSyncExternalStore } from 'react'
+import {
+  getCurrentMode,
+  getRegisteredModes,
+  activateMode,
+  subscribeToMode,
+  getModeSnapshot,
+} from '../../core/index.js'
+
+/**
+ * React hook for the design-mode system.
+ *
+ * Uses useSyncExternalStore so the component re-renders whenever
+ * the active mode or the set of registered modes changes.
+ *
+ * @returns {{
+ *   mode: string,
+ *   modes: Array<{ name: string, label: string, icon?: string }>,
+ *   switchMode: (name: string, options?: object) => void,
+ *   currentModeConfig: object | undefined,
+ * }}
+ */
+export function useMode() {
+  const snapshot = useSyncExternalStore(subscribeToMode, getModeSnapshot)
+
+  // snapshot is "modeName|registeredNames" — we only use it to trigger re-renders
+  void snapshot
+
+  const mode = getCurrentMode()
+  const modes = getRegisteredModes()
+  const currentModeConfig = modes.find((m) => m.name === mode)
+
+  const switchMode = useCallback((name, options) => {
+    activateMode(name, options)
+  }, [])
+
+  return {
+    mode,
+    modes,
+    switchMode,
+    currentModeConfig,
+  }
+}

package/src/internals/hooks/useObject.js

@@ -0,0 +1,101 @@
+import { useContext, useMemo, useSyncExternalStore } from 'react'
+import { loadObject, resolveObjectName } from '../../core/index.js'
+import { getByPath, deepClone, setByPath } from '../../core/index.js'
+import { getParam, getAllParams } from '../../core/index.js'
+import { isHideMode, getShadow, getAllShadows } from '../../core/index.js'
+import { subscribeToHash, getHashSnapshot } from '../../core/index.js'
+import { subscribeToStorage, getStorageSnapshot } from '../../core/index.js'
+import { StoryboardContext } from '../StoryboardContext.js'
+
+/**
+ * Load an object data file directly by name, without going through a scene.
+ * Supports dot-notation path access and URL hash overrides.
+ * Objects inside prototypes are automatically resolved with prototype scope.
+ *
+ * Hash override convention: object.{objectName}.{field}=value
+ *
+ * @param {string} objectName - Name of the object file (e.g., "jane-doe")
+ * @param {string} [path] - Optional dot-notation path (e.g., "profile.name")
+ * @returns {*} The resolved value, or undefined if loading fails
+ *
+ * @example
+ * const user = useObject('jane-doe')
+ * const name = useObject('jane-doe', 'profile.name')
+ *
+ * // Override via URL hash: #object.jane-doe.name=Alice
+ */
+export function useObject(objectName, path) {
+  const context = useContext(StoryboardContext)
+  const prototypeName = context?.prototypeName ?? null
+  const hashString = useSyncExternalStore(subscribeToHash, getHashSnapshot)
+  const storageString = useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  return useMemo(() => {
+    const resolvedName = resolveObjectName(prototypeName, objectName)
+    let data
+    try {
+      data = loadObject(resolvedName)
+    } catch (err) {
+      console.error(`[useObject] ${err.message}`)
+      return undefined
+    }
+
+    const hidden = isHideMode()
+    const readParam = hidden ? getShadow : getParam
+    const readAllParams = hidden ? getAllShadows : getAllParams
+
+    // Apply overrides scoped to this object.
+    // Check both the resolved (scoped) prefix and the plain (unscoped) prefix
+    // so overrides work whether written with the bare or scoped name.
+    const resolvedPrefix = `object.${resolvedName}.`
+    const plainPrefix = objectName !== resolvedName ? `object.${objectName}.` : null
+    const allParams = readAllParams()
+    const overrideKeys = Object.keys(allParams).filter(k =>
+      k.startsWith(resolvedPrefix) || (plainPrefix && k.startsWith(plainPrefix))
+    )
+
+    if (overrideKeys.length > 0) {
+      data = deepClone(data)
+      for (const key of overrideKeys) {
+        const fieldPath = key.startsWith(resolvedPrefix)
+          ? key.slice(resolvedPrefix.length)
+          : key.slice(plainPrefix.length)
+        setByPath(data, fieldPath, allParams[key])
+      }
+    }
+
+    if (!path) return data
+
+    // Exact match for this sub-path override (check both prefixes)
+    const exactResolved = `${resolvedPrefix}${path}`
+    const exactPlain = plainPrefix ? `${plainPrefix}${path}` : null
+    const exact = readParam(exactResolved) ?? (exactPlain ? readParam(exactPlain) : null)
+    if (exact !== null) return exact
+
+    // Child overrides under the sub-path
+    const subResolved = exactResolved + '.'
+    const subPlain = exactPlain ? exactPlain + '.' : null
+    const childKeys = overrideKeys.filter(k =>
+      k.startsWith(subResolved) || (subPlain && k.startsWith(subPlain))
+    )
+    const baseValue = getByPath(data, path)
+
+    if (childKeys.length > 0 && baseValue !== undefined) {
+      const merged = deepClone(baseValue)
+      for (const key of childKeys) {
+        const relativePath = key.startsWith(subResolved)
+          ? key.slice(subResolved.length)
+          : key.slice(subPlain.length)
+        setByPath(merged, relativePath, allParams[key])
+      }
+      return merged
+    }
+
+    if (baseValue === undefined) {
+      console.warn(`[useObject] Path "${path}" not found in object "${objectName}".`)
+      return undefined
+    }
+
+    return baseValue
+  }, [objectName, prototypeName, path, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
+}

package/src/internals/hooks/useObject.test.js

@@ -0,0 +1,74 @@
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData, TEST_OBJECTS } from '../../test-utils.js'
+import { activateHideMode, setShadow } from '../../core/index.js'
+import { useObject } from './useObject.js'
+
+beforeEach(() => {
+  seedTestData()
+  window.location.hash = ''
+})
+
+describe('useObject', () => {
+  it('loads an object by name', () => {
+    const { result } = renderHook(() => useObject('jane-doe'))
+    expect(result.current).toEqual(TEST_OBJECTS['jane-doe'])
+  })
+
+  it('returns undefined for missing object', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { result } = renderHook(() => useObject('nonexistent'))
+    expect(result.current).toBeUndefined()
+    console.error.mockRestore()
+  })
+
+  it('resolves dot-notation path', () => {
+    const { result } = renderHook(() => useObject('jane-doe', 'name'))
+    expect(result.current).toBe('Jane Doe')
+  })
+
+  it('returns undefined for missing path', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const { result } = renderHook(() => useObject('jane-doe', 'missing.path'))
+    expect(result.current).toBeUndefined()
+    console.warn.mockRestore()
+  })
+
+  it('applies hash overrides to full object', () => {
+    window.location.hash = 'object.jane-doe.name=Alice'
+    const { result } = renderHook(() => useObject('jane-doe'))
+    expect(result.current.name).toBe('Alice')
+    expect(result.current.role).toBe('admin')
+  })
+
+  it('applies hash overrides when accessing by path', () => {
+    window.location.hash = 'object.jane-doe.name=Alice'
+    const { result } = renderHook(() => useObject('jane-doe', 'name'))
+    expect(result.current).toBe('Alice')
+  })
+
+  it('returns deep clone (mutations do not affect source data)', () => {
+    const { result: r1 } = renderHook(() => useObject('jane-doe'))
+    r1.current.name = 'Mutated'
+    // A fresh hook call should return original data, not the mutated reference
+    const { result: r2 } = renderHook(() => useObject('jane-doe'))
+    expect(r2.current.name).toBe('Jane Doe')
+  })
+})
+
+describe('useObject (hide mode)', () => {
+  beforeEach(() => {
+    act(() => { activateHideMode() })
+  })
+
+  it('reads overrides from localStorage shadow in hide mode', () => {
+    act(() => { setShadow('object.jane-doe.name', 'Shadow Jane') })
+    const { result } = renderHook(() => useObject('jane-doe'))
+    expect(result.current.name).toBe('Shadow Jane')
+  })
+
+  it('reads path-specific overrides from shadow in hide mode', () => {
+    act(() => { setShadow('object.jane-doe.role', 'superadmin') })
+    const { result } = renderHook(() => useObject('jane-doe', 'role'))
+    expect(result.current).toBe('superadmin')
+  })
+})

package/src/internals/hooks/useOverride.js

@@ -0,0 +1,84 @@
+import { useCallback, useContext, useSyncExternalStore } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { getByPath } from '../../core/index.js'
+import { getParam, setParam, removeParam } from '../../core/index.js'
+import { subscribeToHash } from '../../core/index.js'
+import { isHideMode, getShadow, setShadow, removeShadow } from '../../core/index.js'
+import { subscribeToStorage, getStorageSnapshot } from '../../core/index.js'
+
+/**
+ * Read/write overrides on top of scene data or object data.
+ *
+ * **Normal mode:**
+ *   Read priority:  URL hash param → Scene JSON value → undefined
+ *   Write target:   URL hash + shadow copy to localStorage
+ *
+ * **Hide mode** (activated by `?hide`):
+ *   Read priority:  shadow localStorage → Scene JSON value → undefined
+ *   Write target:   shadow localStorage only (URL stays clean)
+ *
+ * Every write also mirrors to localStorage shadow keys, so hide mode
+ * can hot-swap without data loss.
+ *
+ * Works with any override namespace — scene paths (e.g. 'settings.theme'),
+ * object paths (e.g. 'object.jane-doe.name'), or record paths
+ * (e.g. 'record.posts.post-1.title').
+ *
+ * When used outside a StoryboardProvider (e.g. for object overrides),
+ * the scene fallback is skipped and value resolves to override ?? undefined.
+ *
+ * @param {string} path - Dot-notation key (e.g. 'settings.theme')
+ * @returns {[any, function, function]}
+ *   [0] current value (override ?? scene default ?? undefined)
+ *   [1] setValue(newValue)  – write an override
+ *   [2] clearValue()       – remove the override, reverting to scene default
+ */
+export function useOverride(path) {
+  const context = useContext(StoryboardContext)
+
+  const data = context?.data
+  const hidden = isHideMode()
+
+  // Scene default for this path (fallback when no override exists)
+  const sceneDefault = data != null ? getByPath(data, path) : undefined
+
+  // Subscribe to both sources for reactivity
+  const getHashSnap = useCallback(() => getParam(path), [path])
+  const hashValue = useSyncExternalStore(subscribeToHash, getHashSnap)
+  useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  // Resolved value depends on mode
+  let value
+  if (hidden) {
+    const shadowValue = getShadow(path)
+    value = shadowValue !== null ? shadowValue : sceneDefault
+  } else {
+    value = hashValue !== null ? hashValue : sceneDefault
+  }
+
+  /** Write a value — targets hash or shadow depending on mode */
+  const setValue = useCallback(
+    (newValue) => {
+      if (isHideMode()) {
+        setShadow(path, newValue)
+      } else {
+        setParam(path, newValue)
+        // Always mirror to shadow so hide mode can hot-swap
+        setShadow(path, newValue)
+      }
+    },
+    [path],
+  )
+
+  /** Remove the override, reverting to scene default */
+  const clearValue = useCallback(() => {
+    if (isHideMode()) {
+      removeShadow(path)
+    } else {
+      removeParam(path)
+      removeShadow(path)
+    }
+  }, [path])
+
+  return [value, setValue, clearValue]
+}

package/src/internals/hooks/useOverride.test.js

@@ -0,0 +1,71 @@
+import { renderHook, act } from '@testing-library/react'
+import { useOverride } from './useOverride.js'
+import { seedTestData, createWrapper, TEST_SCENES } from '../test-utils.js'
+
+const sceneData = TEST_SCENES.default
+
+beforeEach(() => {
+  seedTestData()
+})
+
+describe('useOverride', () => {
+  it('returns [value, setValue, clearValue] tuple', () => {
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current).toHaveLength(3)
+    expect(typeof result.current[1]).toBe('function')
+    expect(typeof result.current[2]).toBe('function')
+  })
+
+  it('value falls back to scene default when no hash override', () => {
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current[0]).toBe('dark')
+  })
+
+  it('value reads from hash override when present', () => {
+    window.location.hash = '#settings.theme=light'
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current[0]).toBe('light')
+  })
+
+  it('setValue writes to hash', () => {
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+
+    act(() => {
+      result.current[1]('blue')
+    })
+
+    expect(window.location.hash).toContain('settings.theme=blue')
+  })
+
+  it('clearValue removes hash param', () => {
+    window.location.hash = '#settings.theme=red'
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+
+    act(() => {
+      result.current[2]()
+    })
+
+    expect(window.location.hash).not.toContain('settings.theme')
+  })
+
+  it('works without StoryboardProvider for object overrides', () => {
+    window.location.hash = '#object.jane-doe.name=Alice'
+    const { result } = renderHook(() => useOverride('object.jane-doe.name'))
+    expect(result.current[0]).toBe('Alice')
+  })
+
+  it('returns undefined without provider when no override exists', () => {
+    const { result } = renderHook(() => useOverride('object.jane-doe.name'))
+    expect(result.current[0]).toBeUndefined()
+  })
+})

package/src/internals/hooks/usePrototypeReloadGuard.js

@@ -0,0 +1,64 @@
+/**
+ * Prototype reload guard — suppresses Vite HMR full-reloads for non-canvas pages.
+ *
+ * Controlled by the "prototype-auto-reload" feature flag (default: true).
+ * When the flag is false (user opted out), sends heartbeat messages to the
+ * Vite dev server which suppresses full-reload and update payloads for this
+ * client. Custom storyboard events (canvas file changes, story changes, etc.)
+ * always pass through.
+ *
+ * Heartbeats are sent every 3s and auto-expire server-side after 5s, so
+ * closed tabs never leave the guard stuck.
+ */
+import { useEffect } from 'react'
+import { getFlag, subscribeToStorage } from '../../core/index.js'
+
+const FLAG_KEY = 'prototype-auto-reload'
+const HEARTBEAT_MS = 3000
+
+export default function usePrototypeReloadGuard() {
+  useEffect(() => {
+    if (!import.meta.hot) return
+
+    let interval = null
+
+    function start() {
+      if (interval) return
+      const msg = { active: true }
+      import.meta.hot.send('storyboard:prototype-reload-guard', msg)
+      interval = setInterval(() => {
+        import.meta.hot.send('storyboard:prototype-reload-guard', msg)
+      }, HEARTBEAT_MS)
+    }
+
+    function stop() {
+      if (interval) {
+        clearInterval(interval)
+        interval = null
+      }
+      import.meta.hot.send('storyboard:prototype-reload-guard', { active: false })
+    }
+
+    function sync() {
+      const autoReload = getFlag(FLAG_KEY)
+      if (autoReload) {
+        stop()
+      } else {
+        start()
+      }
+    }
+
+    // Initial sync
+    sync()
+
+    // Re-sync when the flag changes in localStorage (e.g. toggled from devtools)
+    const unsub = subscribeToStorage((key) => {
+      if (key === 'flag.' + FLAG_KEY) sync()
+    })
+
+    return () => {
+      stop()
+      unsub()
+    }
+  }, [])
+}