@dfosco/storyboard-core 1.1.0

package/src/localStorage.test.js

@@ -0,0 +1,148 @@
+import {
+  getLocal,
+  setLocal,
+  removeLocal,
+  getAllLocal,
+  subscribeToStorage,
+  getStorageSnapshot,
+} from './localStorage.js'
+
+describe('getLocal', () => {
+  it('returns null for missing key', () => {
+    expect(getLocal('nonexistent')).toBeNull()
+  })
+
+  it('reads stored value using "storyboard:" prefix internally', () => {
+    localStorage.setItem('storyboard:mykey', 'hello')
+    expect(getLocal('mykey')).toBe('hello')
+  })
+
+  it('returns null if localStorage throws', () => {
+    const original = localStorage.getItem
+    localStorage.getItem = () => { throw new Error('fail') }
+    expect(getLocal('anything')).toBeNull()
+    localStorage.getItem = original
+  })
+})
+
+describe('setLocal', () => {
+  it('stores value with prefix', () => {
+    setLocal('color', 'blue')
+    expect(localStorage.getItem('storyboard:color')).toBe('blue')
+  })
+
+  it('converts value to string', () => {
+    setLocal('num', 42)
+    expect(localStorage.getItem('storyboard:num')).toBe('42')
+  })
+
+  it('dispatches storyboard-storage event on window', () => {
+    const cb = vi.fn()
+    window.addEventListener('storyboard-storage', cb)
+    setLocal('x', '1')
+    expect(cb).toHaveBeenCalledTimes(1)
+    window.removeEventListener('storyboard-storage', cb)
+  })
+})
+
+describe('removeLocal', () => {
+  it('removes prefixed key', () => {
+    setLocal('temp', 'val')
+    expect(localStorage.getItem('storyboard:temp')).toBe('val')
+    removeLocal('temp')
+    expect(localStorage.getItem('storyboard:temp')).toBeNull()
+  })
+
+  it('dispatches storyboard-storage event', () => {
+    setLocal('temp', 'val')
+    const cb = vi.fn()
+    window.addEventListener('storyboard-storage', cb)
+    removeLocal('temp')
+    expect(cb).toHaveBeenCalled()
+    window.removeEventListener('storyboard-storage', cb)
+  })
+})
+
+describe('getAllLocal', () => {
+  it('returns empty object when no storyboard keys', () => {
+    expect(getAllLocal()).toEqual({})
+  })
+
+  it('returns all prefixed entries with prefix stripped', () => {
+    setLocal('a', '1')
+    setLocal('b', '2')
+    expect(getAllLocal()).toEqual({ a: '1', b: '2' })
+  })
+
+  it('ignores non-storyboard keys', () => {
+    localStorage.setItem('other-key', 'nope')
+    setLocal('only', 'this')
+    const result = getAllLocal()
+    expect(result).toEqual({ only: 'this' })
+    expect(result['other-key']).toBeUndefined()
+  })
+})
+
+describe('subscribeToStorage', () => {
+  it('calls callback on storyboard-storage event', () => {
+    const cb = vi.fn()
+    const unsub = subscribeToStorage(cb)
+    window.dispatchEvent(new Event('storyboard-storage'))
+    expect(cb).toHaveBeenCalledTimes(1)
+    unsub()
+  })
+
+  it('calls callback on storage event', () => {
+    const cb = vi.fn()
+    const unsub = subscribeToStorage(cb)
+    window.dispatchEvent(new Event('storage'))
+    expect(cb).toHaveBeenCalledTimes(1)
+    unsub()
+  })
+
+  it('returns unsubscribe function that works', () => {
+    const cb = vi.fn()
+    const unsub = subscribeToStorage(cb)
+    unsub()
+    window.dispatchEvent(new Event('storyboard-storage'))
+    window.dispatchEvent(new Event('storage'))
+    expect(cb).not.toHaveBeenCalled()
+  })
+})
+
+describe('getStorageSnapshot', () => {
+  it('returns serialized string of all entries', () => {
+    setLocal('z', '3')
+    setLocal('a', '1')
+    // Force cache invalidation so snapshot recomputes
+    window.dispatchEvent(new Event('storyboard-storage'))
+    const snap = getStorageSnapshot()
+    // Entries are sorted alphabetically
+    expect(snap).toBe('storyboard:a=1&storyboard:z=3')
+  })
+
+  it('caches result (same reference on repeated calls)', () => {
+    setLocal('k', 'v')
+    // Invalidate cache first
+    window.dispatchEvent(new Event('storyboard-storage'))
+    const snap1 = getStorageSnapshot()
+    const snap2 = getStorageSnapshot()
+    expect(snap1).toBe(snap2)
+  })
+
+  it('invalidates cache on storage event', () => {
+    setLocal('k', 'v')
+    // Subscribe so events invalidate the cache
+    const unsub = subscribeToStorage(() => {})
+
+    const snap1 = getStorageSnapshot()
+    // Directly mutate localStorage and fire event to invalidate
+    localStorage.setItem('storyboard:k', 'changed')
+    window.dispatchEvent(new Event('storyboard-storage'))
+    const snap2 = getStorageSnapshot()
+
+    expect(snap1).not.toBe(snap2)
+    expect(snap2).toContain('storyboard:k=changed')
+    unsub()
+  })
+})

package/src/sceneDebug.js

@@ -0,0 +1,108 @@
+/**
+ * Storyboard SceneDebug — a vanilla JS debug panel that displays scene data.
+ *
+ * Framework-agnostic: creates a DOM element, no React/Vue/etc. needed.
+ *
+ * Usage:
+ *   import { mountSceneDebug } from '@dfosco/storyboard-core'
+ *   mountSceneDebug(document.getElementById('debug'))
+ *   // or
+ *   mountSceneDebug() // appends to document.body
+ */
+import { loadScene } from './loader.js'
+
+const STYLES = `
+.sb-scene-debug {
+  padding: 16px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+}
+.sb-scene-debug-title {
+  font-size: 20px;
+  font-weight: 600;
+  margin-bottom: 8px;
+  color: #c9d1d9;
+}
+.sb-scene-debug-code {
+  padding: 16px;
+  background-color: #161b22;
+  border-radius: 8px;
+  overflow: auto;
+  font-size: 13px;
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+  line-height: 1.5;
+  max-height: 70vh;
+  color: #c9d1d9;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.sb-scene-debug-error {
+  padding: 16px;
+  background-color: rgba(248, 81, 73, 0.1);
+  border-radius: 8px;
+}
+.sb-scene-debug-error-title {
+  color: #f85149;
+  font-weight: 600;
+}
+.sb-scene-debug-error-message {
+  color: #f85149;
+  margin-top: 4px;
+}
+`
+
+let stylesInjected = false
+
+/**
+ * Mount a scene debug panel into the DOM.
+ *
+ * @param {HTMLElement} [container=document.body] - Where to mount
+ * @param {string} [sceneName] - Scene name override (defaults to ?scene= param or "default")
+ * @returns {HTMLElement} The created debug element
+ */
+export function mountSceneDebug(container, sceneName) {
+  const target = container || document.body
+  const activeSceneName = sceneName
+    || new URLSearchParams(window.location.search).get('scene')
+    || 'default'
+
+  // Inject styles once
+  if (!stylesInjected) {
+    const styleEl = document.createElement('style')
+    styleEl.textContent = STYLES
+    document.head.appendChild(styleEl)
+    stylesInjected = true
+  }
+
+  const el = document.createElement('div')
+  el.className = 'sb-scene-debug'
+
+  let data = null
+  let error = null
+  try {
+    data = loadScene(activeSceneName)
+  } catch (err) {
+    error = err.message
+  }
+
+  if (error) {
+    el.innerHTML = `
+      <div class="sb-scene-debug-error">
+        <div class="sb-scene-debug-error-title">Error loading scene</div>
+        <p class="sb-scene-debug-error-message">${error}</p>
+      </div>`
+  } else {
+    const title = document.createElement('h2')
+    title.className = 'sb-scene-debug-title'
+    title.textContent = `Scene: ${activeSceneName}`
+
+    const pre = document.createElement('pre')
+    pre.className = 'sb-scene-debug-code'
+    pre.textContent = JSON.stringify(data, null, 2)
+
+    el.appendChild(title)
+    el.appendChild(pre)
+  }
+
+  target.appendChild(el)
+  return el
+}

package/src/sceneDebug.test.js

@@ -0,0 +1,128 @@
+import { vi } from 'vitest'
+
+const { mockLoadScene } = vi.hoisted(() => ({
+  mockLoadScene: vi.fn(() => ({ hello: 'world', count: 42 })),
+}))
+
+vi.mock('./loader.js', () => ({
+  loadScene: mockLoadScene,
+}))
+
+// We need a fresh module for each test since sceneDebug has a module-level
+// `stylesInjected` boolean. We test style injection on the very first call,
+// then subsequent tests just verify other behavior.
+import { mountSceneDebug } from './sceneDebug.js'
+
+afterEach(() => {
+  document.body.innerHTML = ''
+  mockLoadScene.mockReset()
+  mockLoadScene.mockReturnValue({ hello: 'world', count: 42 })
+})
+
+describe('mountSceneDebug', () => {
+  it('injects styles into document.head on first call', () => {
+    // This MUST run first to capture the stylesInjected=false → true transition
+    mountSceneDebug()
+
+    const styles = document.head.querySelectorAll('style')
+    const hasDebugStyle = Array.from(styles).some((el) =>
+      el.textContent.includes('.sb-scene-debug')
+    )
+    expect(hasDebugStyle).toBe(true)
+  })
+
+  it('creates an element with class sb-scene-debug', () => {
+    const el = mountSceneDebug()
+
+    expect(el.classList.contains('sb-scene-debug')).toBe(true)
+  })
+
+  it('appends to document.body by default', () => {
+    mountSceneDebug()
+
+    expect(document.body.querySelector('.sb-scene-debug')).toBeInTheDocument()
+  })
+
+  it('appends to a custom container', () => {
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+
+    mountSceneDebug(container)
+
+    expect(container.querySelector('.sb-scene-debug')).not.toBeNull()
+  })
+
+  it('returns the created element', () => {
+    const el = mountSceneDebug()
+
+    expect(el).toBeInstanceOf(HTMLElement)
+    expect(el.className).toBe('sb-scene-debug')
+  })
+
+  it('renders the scene name in the title', () => {
+    mountSceneDebug(undefined, 'my-scene')
+
+    const title = document.body.querySelector('.sb-scene-debug-title')
+    expect(title).not.toBeNull()
+    expect(title.textContent).toContain('my-scene')
+  })
+
+  it('defaults scene name to "default" when none is provided', () => {
+    mountSceneDebug()
+
+    const title = document.body.querySelector('.sb-scene-debug-title')
+    expect(title.textContent).toContain('default')
+    expect(mockLoadScene).toHaveBeenCalledWith('default')
+  })
+
+  it('renders JSON data in a pre element', () => {
+    mountSceneDebug()
+
+    const pre = document.body.querySelector('.sb-scene-debug-code')
+    expect(pre).not.toBeNull()
+    expect(pre.tagName).toBe('PRE')
+
+    const parsed = JSON.parse(pre.textContent)
+    expect(parsed).toEqual({ hello: 'world', count: 42 })
+  })
+
+  it('shows error when loadScene throws', () => {
+    mockLoadScene.mockImplementation(() => {
+      throw new Error('Scene not found')
+    })
+
+    const el = mountSceneDebug()
+
+    const errorTitle = el.querySelector('.sb-scene-debug-error-title')
+    expect(errorTitle).not.toBeNull()
+    expect(errorTitle.textContent).toContain('Error')
+
+    const errorMsg = el.querySelector('.sb-scene-debug-error-message')
+    expect(errorMsg.textContent).toContain('Scene not found')
+
+    // Should NOT render the normal title/pre
+    expect(el.querySelector('.sb-scene-debug-title')).toBeNull()
+    expect(el.querySelector('.sb-scene-debug-code')).toBeNull()
+  })
+
+  it('uses ?scene query param when no sceneName argument is given', () => {
+    window.history.pushState(null, '', '?scene=overview')
+
+    mountSceneDebug()
+
+    expect(mockLoadScene).toHaveBeenCalledWith('overview')
+    const title = document.body.querySelector('.sb-scene-debug-title')
+    expect(title.textContent).toContain('overview')
+
+    // Clean up
+    window.history.pushState(null, '', '/')
+  })
+
+  it('allows multiple debug panels to be mounted', () => {
+    mountSceneDebug()
+    mountSceneDebug()
+
+    const panels = document.body.querySelectorAll('.sb-scene-debug')
+    expect(panels).toHaveLength(2)
+  })
+})

package/src/session.js

@@ -0,0 +1,76 @@
+/**
+ * URL hash-based utilities for storyboard session state.
+ *
+ * Session params are stored in the URL hash fragment (after #) to avoid
+ * triggering React Router re-renders. React Router (used by generouted)
+ * patches history.replaceState/pushState, so any search-param change
+ * causes a full route tree re-render. The hash is invisible to the router.
+ *
+ * Format:  #key1=value1&key2=value2
+ * Example: /page?scene=default#user.name=Alice&settings.theme=dark
+ */
+
+/**
+ * Parse the current hash into a Map of key→value pairs.
+ * @returns {URLSearchParams}
+ */
+function parseHash() {
+  const raw = window.location.hash.replace(/^#/, '')
+  return new URLSearchParams(raw)
+}
+
+/**
+ * Write a URLSearchParams back to the hash.
+ * Uses window.location.hash (NOT history.replaceState) because
+ * generouted/React Router patches replaceState and would trigger
+ * a full route re-render. Native hash assignment only fires
+ * 'hashchange' which React Router ignores.
+ * @param {URLSearchParams} params
+ */
+function writeHash(params) {
+  const str = params.toString()
+  window.location.hash = str
+}
+
+/**
+ * Read a single session param value.
+ * @param {string} key
+ * @returns {string|null}
+ */
+export function getParam(key) {
+  return parseHash().get(key)
+}
+
+/**
+ * Write a single session param. Updates the hash in-place.
+ * @param {string} key
+ * @param {string} value
+ */
+export function setParam(key, value) {
+  const params = parseHash()
+  params.set(key, String(value))
+  writeHash(params)
+}
+
+/**
+ * Return all session params as a plain object.
+ * @returns {Record<string, string>}
+ */
+export function getAllParams() {
+  const params = parseHash()
+  const result = {}
+  for (const [key, value] of params.entries()) {
+    result[key] = value
+  }
+  return result
+}
+
+/**
+ * Remove a single session param from the hash.
+ * @param {string} key
+ */
+export function removeParam(key) {
+  const params = parseHash()
+  params.delete(key)
+  writeHash(params)
+}

package/src/session.test.js

@@ -0,0 +1,91 @@
+import { getParam, setParam, getAllParams, removeParam } from './session.js'
+
+describe('getParam', () => {
+  it('returns null when hash is empty', () => {
+    window.location.hash = ''
+    expect(getParam('key')).toBeNull()
+  })
+
+  it('returns value for existing param', () => {
+    window.location.hash = 'foo=bar'
+    expect(getParam('foo')).toBe('bar')
+  })
+
+  it('returns null for missing param', () => {
+    window.location.hash = 'foo=bar'
+    expect(getParam('missing')).toBeNull()
+  })
+
+  it('handles URL-encoded values', () => {
+    window.location.hash = 'name=hello%20world'
+    expect(getParam('name')).toBe('hello world')
+  })
+})
+
+describe('setParam', () => {
+  it('sets a new param in hash', () => {
+    window.location.hash = ''
+    setParam('key', 'value')
+    expect(getParam('key')).toBe('value')
+  })
+
+  it('updates existing param', () => {
+    window.location.hash = 'key=old'
+    setParam('key', 'new')
+    expect(getParam('key')).toBe('new')
+  })
+
+  it('preserves other params', () => {
+    window.location.hash = 'a=1&b=2'
+    setParam('c', '3')
+    expect(getParam('a')).toBe('1')
+    expect(getParam('b')).toBe('2')
+    expect(getParam('c')).toBe('3')
+  })
+
+  it('converts value to string', () => {
+    window.location.hash = ''
+    setParam('num', 42)
+    expect(getParam('num')).toBe('42')
+  })
+})
+
+describe('getAllParams', () => {
+  it('returns empty object for empty hash', () => {
+    window.location.hash = ''
+    expect(getAllParams()).toEqual({})
+  })
+
+  it('returns all params', () => {
+    window.location.hash = 'a=1&b=2'
+    expect(getAllParams()).toEqual({ a: '1', b: '2' })
+  })
+
+  it('handles multiple params', () => {
+    window.location.hash = 'x=hello&y=world&z=test'
+    const params = getAllParams()
+    expect(Object.keys(params)).toHaveLength(3)
+    expect(params).toEqual({ x: 'hello', y: 'world', z: 'test' })
+  })
+})
+
+describe('removeParam', () => {
+  it('removes existing param', () => {
+    window.location.hash = 'a=1&b=2'
+    removeParam('a')
+    expect(getParam('a')).toBeNull()
+  })
+
+  it('preserves other params', () => {
+    window.location.hash = 'a=1&b=2&c=3'
+    removeParam('b')
+    expect(getParam('a')).toBe('1')
+    expect(getParam('c')).toBe('3')
+  })
+
+  it('no-ops for missing param', () => {
+    window.location.hash = 'a=1'
+    removeParam('nonexistent')
+    expect(getParam('a')).toBe('1')
+  })
+})

package/src/viewfinder.js

@@ -0,0 +1,47 @@
+import { loadScene } from './loader.js'
+
+/**
+ * Deterministic hash from a string — used for seeding generative placeholders.
+ * @param {string} str
+ * @returns {number}
+ */
+export function hash(str) {
+  let h = 0
+  for (let i = 0; i < str.length; i++) {
+    h = ((h << 5) - h + str.charCodeAt(i)) | 0
+  }
+  return Math.abs(h)
+}
+
+/**
+ * Resolve the target route path for a scene.
+ *
+ * 1. If scene name matches a known route (case-insensitive), use that route
+ * 2. If scene data has a `route` key, use that
+ * 3. Fall back to root "/"
+ *
+ * @param {string} sceneName
+ * @param {string[]} knownRoutes - Array of route names (e.g. ["Dashboard", "Repositories"])
+ * @returns {string} Full path with ?scene= param
+ */
+export function resolveSceneRoute(sceneName, knownRoutes = []) {
+  // Case-insensitive match against known routes
+  for (const route of knownRoutes) {
+    if (route.toLowerCase() === sceneName.toLowerCase()) {
+      return `/${route}?scene=${encodeURIComponent(sceneName)}`
+    }
+  }
+
+  // Check for explicit `route` key in scene data
+  try {
+    const data = loadScene(sceneName)
+    if (data?.route) {
+      const route = data.route.startsWith('/') ? data.route : `/${data.route}`
+      return `${route}?scene=${encodeURIComponent(sceneName)}`
+    }
+  } catch {
+    // ignore load errors
+  }
+
+  return `/?scene=${encodeURIComponent(sceneName)}`
+}

package/src/viewfinder.test.js

@@ -0,0 +1,87 @@
+import { init } from './loader.js'
+import { hash, resolveSceneRoute } from './viewfinder.js'
+
+const makeIndex = () => ({
+  scenes: {
+    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' },
+  },
+  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('resolveSceneRoute', () => {
+  const routes = ['Dashboard', 'Overview', 'Forms', 'Repositories']
+
+  it('matches scene name to route (exact case)', () => {
+    expect(resolveSceneRoute('Dashboard', routes)).toBe('/Dashboard?scene=Dashboard')
+  })
+
+  it('matches scene name to route (case-insensitive)', () => {
+    expect(resolveSceneRoute('dashboard', routes)).toBe('/Dashboard?scene=dashboard')
+  })
+
+  it('uses route key from scene data when no route matches', () => {
+    expect(resolveSceneRoute('custom-route', routes)).toBe('/Overview?scene=custom-route')
+  })
+
+  it('handles absolute route key (with leading slash)', () => {
+    expect(resolveSceneRoute('absolute-route', routes)).toBe('/Forms?scene=absolute-route')
+  })
+
+  it('falls back to root when no match and no route key', () => {
+    expect(resolveSceneRoute('no-route', routes)).toBe('/?scene=no-route')
+  })
+
+  it('falls back to root for default scene', () => {
+    expect(resolveSceneRoute('default', routes)).toBe('/?scene=default')
+  })
+
+  it('falls back to root when scene does not exist', () => {
+    expect(resolveSceneRoute('nonexistent', routes)).toBe('/?scene=nonexistent')
+  })
+
+  it('works with empty routes array', () => {
+    expect(resolveSceneRoute('Dashboard', [])).toBe('/?scene=Dashboard')
+  })
+
+  it('works with no routes argument', () => {
+    expect(resolveSceneRoute('custom-route')).toBe('/Overview?scene=custom-route')
+  })
+
+  it('encodes special characters in scene name', () => {
+    init({
+      scenes: { 'has spaces': { title: 'Spaces' } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveSceneRoute('has spaces', [])).toBe('/?scene=has%20spaces')
+  })
+})