@dfosco/storyboard 0.5.0-alpha.0

package/src/core/session/hideMode.test.js

@@ -0,0 +1,268 @@
+import {
+  isHideMode,
+  activateHideMode,
+  deactivateHideMode,
+  pushSnapshot,
+  undo,
+  redo,
+  getOverrideHistory,
+  getCurrentIndex,
+  canUndo,
+  canRedo,
+  getShadow,
+  setShadow,
+  removeShadow,
+  getAllShadows,
+  syncHashToHistory,
+  installHistorySync,
+} from './hideMode.js'
+
+// ── Hide Mode Toggle ──
+
+describe('Hide mode toggle', () => {
+  it('isHideMode() returns false by default', () => {
+    expect(isHideMode()).toBe(false)
+  })
+
+  it('activateHideMode() sets hide flag and clears URL hash', () => {
+    window.location.hash = '#foo=bar'
+    activateHideMode()
+    expect(isHideMode()).toBe(true)
+    expect(window.location.hash).toBe('')
+  })
+
+  it('deactivateHideMode() removes hide flag and restores params to hash', () => {
+    window.location.hash = '#color=red'
+    activateHideMode()
+    expect(isHideMode()).toBe(true)
+    expect(window.location.hash).toBe('')
+
+    deactivateHideMode()
+    expect(isHideMode()).toBe(false)
+    expect(window.location.hash).toContain('color=red')
+  })
+
+  it('round-trip: activate with hash params → deactivate → hash restored', () => {
+    window.location.hash = '#a=1&b=2'
+    activateHideMode()
+    expect(window.location.hash).toBe('')
+
+    deactivateHideMode()
+    const params = new URLSearchParams(window.location.hash.replace(/^#/, ''))
+    expect(params.get('a')).toBe('1')
+    expect(params.get('b')).toBe('2')
+  })
+})
+
+// ── History Stack ──
+
+describe('History stack', () => {
+  it('pushSnapshot() creates first entry from current hash', () => {
+    window.location.hash = '#x=1'
+    pushSnapshot()
+    const history = getOverrideHistory()
+    expect(history.length).toBe(1)
+    expect(history[0][2]).toContain('x=1')
+    expect(getCurrentIndex()).toBe(0)
+  })
+
+  it('pushSnapshot(paramString, route) uses explicit values', () => {
+    pushSnapshot('theme=dark', '/settings')
+    const history = getOverrideHistory()
+    expect(history[0][1]).toBe('/settings')
+    expect(history[0][2]).toBe('theme=dark')
+  })
+
+  it('multiple pushes build a stack, getCurrentIndex advances', () => {
+    pushSnapshot('a=1', '/')
+    pushSnapshot('b=2', '/')
+    pushSnapshot('c=3', '/')
+    expect(getOverrideHistory().length).toBe(3)
+    expect(getCurrentIndex()).toBe(2)
+  })
+
+  it('duplicate push (same route+params) is ignored', () => {
+    pushSnapshot('a=1', '/')
+    pushSnapshot('a=1', '/')
+    expect(getOverrideHistory().length).toBe(1)
+  })
+
+  it('history max is 200 entries (push 201, oldest trimmed)', () => {
+    for (let i = 0; i < 201; i++) {
+      pushSnapshot(`i=${i}`, '/')
+    }
+    const history = getOverrideHistory()
+    expect(history.length).toBe(200)
+    // Oldest entry should have been trimmed; first entry should be i=1
+    expect(history[0][2]).toBe('i=1')
+    // Positions should be re-indexed 0..199
+    expect(history[0][0]).toBe(0)
+    expect(history[199][0]).toBe(199)
+  })
+})
+
+// ── Undo/Redo ──
+
+describe('Undo/redo', () => {
+  it('canUndo() false initially, true after 2+ pushes', () => {
+    expect(canUndo()).toBe(false)
+    pushSnapshot('a=1', '/')
+    expect(canUndo()).toBe(false)
+    pushSnapshot('b=2', '/')
+    expect(canUndo()).toBe(true)
+  })
+
+  it('canRedo() false initially, true after undo', () => {
+    expect(canRedo()).toBe(false)
+    pushSnapshot('a=1', '/')
+    pushSnapshot('b=2', '/')
+    expect(canRedo()).toBe(false)
+    undo()
+    expect(canRedo()).toBe(true)
+  })
+
+  it('undo() returns previous {route, params}, moves index back', () => {
+    pushSnapshot('a=1', '/page1')
+    pushSnapshot('b=2', '/page2')
+    const result = undo()
+    expect(result).toEqual({ route: '/page1', params: 'a=1' })
+    expect(getCurrentIndex()).toBe(0)
+  })
+
+  it('redo() returns next {route, params}, moves index forward', () => {
+    pushSnapshot('a=1', '/page1')
+    pushSnapshot('b=2', '/page2')
+    undo()
+    const result = redo()
+    expect(result).toEqual({ route: '/page2', params: 'b=2' })
+    expect(getCurrentIndex()).toBe(1)
+  })
+
+  it('undo() returns null when at start', () => {
+    pushSnapshot('a=1', '/')
+    expect(undo()).toBeNull()
+  })
+
+  it('redo() returns null when no redo target', () => {
+    pushSnapshot('a=1', '/')
+    pushSnapshot('b=2', '/')
+    expect(redo()).toBeNull()
+  })
+
+  it('new push after undo clears redo (forks timeline)', () => {
+    pushSnapshot('a=1', '/')
+    pushSnapshot('b=2', '/')
+    pushSnapshot('c=3', '/')
+    undo() // back to b=2
+    expect(canRedo()).toBe(true)
+
+    pushSnapshot('d=4', '/')
+    expect(canRedo()).toBe(false)
+    expect(getOverrideHistory().length).toBe(3) // a, b, d (c trimmed)
+    expect(getCurrentIndex()).toBe(2)
+  })
+})
+
+// ── Shadow Read/Write ──
+
+describe('Shadow read/write', () => {
+  it('getShadow(key) returns null when no snapshot', () => {
+    expect(getShadow('foo')).toBeNull()
+  })
+
+  it('setShadow(key, value) pushes new snapshot with key', () => {
+    pushSnapshot('', '/')
+    setShadow('color', 'blue')
+    expect(getShadow('color')).toBe('blue')
+    expect(getOverrideHistory().length).toBe(2)
+  })
+
+  it('removeShadow(key) pushes new snapshot without key', () => {
+    pushSnapshot('color=blue', '/')
+    removeShadow('color')
+    expect(getShadow('color')).toBeNull()
+  })
+
+  it('getAllShadows() returns all entries from current snapshot', () => {
+    pushSnapshot('a=1&b=2', '/')
+    expect(getAllShadows()).toEqual({ a: '1', b: '2' })
+  })
+})
+
+// ── syncHashToHistory ──
+
+describe('syncHashToHistory', () => {
+  it('skips when in hide mode', () => {
+    pushSnapshot('a=1', '/')
+    activateHideMode()
+    window.location.hash = '#new=val'
+    const historyBefore = getOverrideHistory().length
+    syncHashToHistory()
+    expect(getOverrideHistory().length).toBe(historyBefore)
+  })
+
+  it('pushes new snapshot when hash does not match any history entry', () => {
+    pushSnapshot('a=1', '/')
+    window.location.hash = '#x=9'
+    syncHashToHistory()
+    const history = getOverrideHistory()
+    expect(history.length).toBe(2)
+    expect(history[1][2]).toContain('x=9')
+  })
+
+  it('no-ops when hash matches current entry', () => {
+    pushSnapshot('a=1', '/')
+    // Set hash to match the current entry
+    window.location.hash = '#a=1'
+    const lengthBefore = getOverrideHistory().length
+    syncHashToHistory()
+    expect(getOverrideHistory().length).toBe(lengthBefore)
+  })
+})
+
+// ── installHistorySync ──
+
+describe('installHistorySync', () => {
+  it('records initial page state in normal mode', () => {
+    window.location.hash = '#x=1'
+    installHistorySync()
+    const history = getOverrideHistory()
+    expect(history.length).toBe(1)
+    expect(history[0][2]).toContain('x=1')
+  })
+
+  it('does NOT push empty snapshot on startup when in hide mode', () => {
+    // Simulate: user had data, activated hide mode, then refreshed
+    window.location.hash = '#color=red'
+    activateHideMode()                       // snapshots hash, clears URL
+    setShadow('color', 'blue')               // update shadow data
+    const historyBefore = getOverrideHistory().length
+    const indexBefore = getCurrentIndex()
+
+    // Now simulate page refresh — hash is empty, hide mode still active
+    window.location.hash = ''
+    installHistorySync()
+
+    // History should NOT have gained an empty snapshot
+    expect(getOverrideHistory().length).toBe(historyBefore)
+    expect(getCurrentIndex()).toBe(indexBefore)
+    // Shadow data should still be intact
+    expect(getShadow('color')).toBe('blue')
+  })
+
+  it('preserves shadow data through hide→refresh→show cycle', () => {
+    window.location.hash = '#name=Alice'
+    activateHideMode()
+    setShadow('name', 'Bob')
+
+    // Simulate refresh in hide mode
+    window.location.hash = ''
+    installHistorySync()
+
+    // Now deactivate (show mode) — shadow data should restore to hash
+    deactivateHideMode()
+    expect(isHideMode()).toBe(false)
+    const params = new URLSearchParams(window.location.hash.replace(/^#/, ''))
+    expect(params.get('name')).toBe('Bob')
+  })
+})

package/src/core/session/interceptHideParams.js

@@ -0,0 +1,35 @@
+/**
+ * Intercept ?hide and ?show URL params.
+ *
+ * Called at app startup AND on every client-side navigation.
+ * Checks the URL for the special params, triggers the corresponding
+ * hide-mode transition, and strips the param from the URL.
+ */
+import { activateHideMode, deactivateHideMode } from './hideMode.js'
+
+/**
+ * Check for ?hide or ?show in the current URL and act on them.
+ * Safe to call multiple times (idempotent — only acts if the param exists).
+ */
+export function interceptHideParams() {
+  const url = new URL(window.location.href)
+
+  if (url.searchParams.has('hide')) {
+    activateHideMode()
+    return
+  }
+
+  if (url.searchParams.has('show')) {
+    deactivateHideMode()
+    return
+  }
+}
+
+/**
+ * Install a popstate listener so ?hide/?show are detected on
+ * browser back/forward navigation too.
+ */
+export function installHideParamListener() {
+  interceptHideParams()
+  window.addEventListener('popstate', () => interceptHideParams())
+}

package/src/core/session/interceptHideParams.test.js

@@ -0,0 +1,90 @@
+import { vi } from 'vitest'
+import { interceptHideParams, installHideParamListener } from './interceptHideParams.js'
+
+vi.mock('./hideMode.js', () => ({
+  activateHideMode: vi.fn(),
+  deactivateHideMode: vi.fn(),
+}))
+
+import { activateHideMode, deactivateHideMode } from './hideMode.js'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  window.history.pushState(null, '', '/')
+})
+
+describe('interceptHideParams', () => {
+  it('no-ops when no hide/show params are present', () => {
+    interceptHideParams()
+
+    expect(activateHideMode).not.toHaveBeenCalled()
+    expect(deactivateHideMode).not.toHaveBeenCalled()
+  })
+
+  it('calls activateHideMode when ?hide is present', () => {
+    window.history.pushState(null, '', '?hide')
+
+    interceptHideParams()
+
+    expect(activateHideMode).toHaveBeenCalledTimes(1)
+    expect(deactivateHideMode).not.toHaveBeenCalled()
+  })
+
+  it('calls deactivateHideMode when ?show is present', () => {
+    window.history.pushState(null, '', '?show')
+
+    interceptHideParams()
+
+    expect(deactivateHideMode).toHaveBeenCalledTimes(1)
+    expect(activateHideMode).not.toHaveBeenCalled()
+  })
+
+  it('prefers ?hide over ?show when both are present', () => {
+    window.history.pushState(null, '', '?hide&show')
+
+    interceptHideParams()
+
+    expect(activateHideMode).toHaveBeenCalledTimes(1)
+    expect(deactivateHideMode).not.toHaveBeenCalled()
+  })
+
+  it('is idempotent — safe to call multiple times', () => {
+    window.history.pushState(null, '', '?hide')
+
+    interceptHideParams()
+    interceptHideParams()
+    interceptHideParams()
+
+    expect(activateHideMode).toHaveBeenCalledTimes(3)
+  })
+
+  it('no-ops when URL has unrelated query params', () => {
+    window.history.pushState(null, '', '?scene=overview&foo=bar')
+
+    interceptHideParams()
+
+    expect(activateHideMode).not.toHaveBeenCalled()
+    expect(deactivateHideMode).not.toHaveBeenCalled()
+  })
+})
+
+describe('installHideParamListener', () => {
+  it('calls interceptHideParams immediately', () => {
+    window.history.pushState(null, '', '?hide')
+    const spy = vi.spyOn(window, 'addEventListener')
+
+    installHideParamListener()
+
+    expect(activateHideMode).toHaveBeenCalled()
+    spy.mockRestore()
+  })
+
+  it('adds a popstate listener', () => {
+    const spy = vi.spyOn(window, 'addEventListener')
+
+    installHideParamListener()
+
+    expect(spy).toHaveBeenCalledWith('popstate', expect.any(Function))
+    spy.mockRestore()
+  })
+})

package/src/core/session/localStorage.js

@@ -0,0 +1,134 @@
+/**
+ * localStorage utilities for persistent storyboard overrides.
+ *
+ * Mirrors the session.js (URL hash) API but persists values in localStorage.
+ * All keys are prefixed with "storyboard:" to avoid collisions.
+ *
+ * Reactivity:
+ * - Cross-tab: native "storage" event (fires in other tabs automatically)
+ * - Intra-tab: custom "storyboard-storage" event on window (the native
+ *   "storage" event does NOT fire in the tab that made the change)
+ */
+
+const PREFIX = 'storyboard:'
+
+/**
+ * Read a single value from localStorage.
+ * @param {string} key - Unprefixed key (e.g. "settings.theme")
+ * @returns {string|null}
+ */
+export function getLocal(key) {
+  try {
+    return localStorage.getItem(PREFIX + key)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write a single value to localStorage and notify listeners.
+ * @param {string} key - Unprefixed key
+ * @param {string} value
+ */
+export function setLocal(key, value) {
+  try {
+    localStorage.setItem(PREFIX + key, String(value))
+    notifyChange()
+  } catch {
+    // localStorage full or unavailable — silently degrade
+  }
+}
+
+/**
+ * Remove a single key from localStorage and notify listeners.
+ * @param {string} key - Unprefixed key
+ */
+export function removeLocal(key) {
+  try {
+    localStorage.removeItem(PREFIX + key)
+    notifyChange()
+  } catch {
+    // silently degrade
+  }
+}
+
+/**
+ * Return all storyboard-prefixed localStorage entries as a plain object.
+ * Keys are returned WITHOUT the prefix.
+ * @returns {Record<string, string>}
+ */
+export function getAllLocal() {
+  const result = {}
+  try {
+    for (let i = 0; i < localStorage.length; i++) {
+      const raw = localStorage.key(i)
+      if (raw && raw.startsWith(PREFIX)) {
+        result[raw.slice(PREFIX.length)] = localStorage.getItem(raw)
+      }
+    }
+  } catch {
+    // silently degrade
+  }
+  return result
+}
+
+/**
+ * Subscribe to localStorage changes (both cross-tab and intra-tab).
+ * Compatible with useSyncExternalStore.
+ * @param {function} callback
+ * @returns {function} unsubscribe
+ */
+export function subscribeToStorage(callback) {
+  const wrappedCallback = () => {
+    invalidateSnapshotCache()
+    callback()
+  }
+  // Cross-tab: native storage event
+  window.addEventListener('storage', wrappedCallback)
+  // Intra-tab: custom event
+  window.addEventListener('storyboard-storage', wrappedCallback)
+  return () => {
+    window.removeEventListener('storage', wrappedCallback)
+    window.removeEventListener('storyboard-storage', wrappedCallback)
+  }
+}
+
+// ── Snapshot cache ──
+
+let _snapshotCache = null
+
+/** Invalidate the snapshot cache so the next getStorageSnapshot() recomputes. */
+function invalidateSnapshotCache() {
+  _snapshotCache = null
+}
+
+/**
+ * Snapshot of all storyboard localStorage entries as a serialized string.
+ * Used by useSyncExternalStore to detect changes.
+ * Cached — invalidated on writes and storage events.
+ * @returns {string}
+ */
+export function getStorageSnapshot() {
+  if (_snapshotCache !== null) return _snapshotCache
+  try {
+    const entries = []
+    for (let i = 0; i < localStorage.length; i++) {
+      const raw = localStorage.key(i)
+      if (raw && raw.startsWith(PREFIX)) {
+        entries.push(raw + '=' + localStorage.getItem(raw))
+      }
+    }
+    _snapshotCache = entries.sort().join('&')
+    return _snapshotCache
+  } catch {
+    return ''
+  }
+}
+
+// ── Internal ──
+
+/** Fire a custom event so intra-tab listeners re-render. */
+export function notifyChange() {
+  invalidateSnapshotCache()
+  window.dispatchEvent(new Event('storyboard-storage'))
+}

package/src/core/session/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()
+  })
+})