@dfosco/storyboard-core 1.1.0

package/src/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/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/loader.js

@@ -0,0 +1,212 @@
+/**
+ * Deep merges two objects. Source values take priority over target.
+ * Arrays are replaced, not concatenated.
+ */
+function deepMerge(target, source) {
+  const result = { ...target }
+  
+  for (const key of Object.keys(source)) {
+    const sourceValue = source[key]
+    const targetValue = target[key]
+    
+    if (
+      sourceValue !== null &&
+      typeof sourceValue === 'object' &&
+      !Array.isArray(sourceValue) &&
+      targetValue !== null &&
+      typeof targetValue === 'object' &&
+      !Array.isArray(targetValue)
+    ) {
+      result[key] = deepMerge(targetValue, sourceValue)
+    } else {
+      result[key] = sourceValue
+    }
+  }
+  
+  return result
+}
+
+/**
+ * Module-level data index, seeded by init().
+ * Shape: { scenes: {}, objects: {}, records: {} }
+ */
+let dataIndex = { scenes: {}, objects: {}, records: {} }
+
+/**
+ * Seed the data index. Call once at app startup before any load functions.
+ * The Vite data plugin calls this automatically via the generated virtual module.
+ *
+ * @param {{ scenes: object, objects: object, records: object }} index
+ */
+export function init(index) {
+  if (!index || typeof index !== 'object') {
+    throw new Error('[storyboard-core] init() requires { scenes, objects, records }')
+  }
+  dataIndex = {
+    scenes: index.scenes || {},
+    objects: index.objects || {},
+    records: index.records || {},
+  }
+}
+
+/**
+ * Loads a data file by name and type from the data index.
+ * Data is pre-parsed at build time — returns a deep clone to prevent mutation.
+ * @param {string} name - Data file name (e.g., "jane-doe", "default")
+ * @param {string} [type] - Data type: "scenes", "objects", or "records". If omitted, searches all types.
+ * @returns {object} Parsed file contents
+ */
+function loadDataFile(name, type) {
+  if (type && dataIndex[type]?.[name] != null) {
+    return dataIndex[type][name]
+  }
+
+  // Search all types if no specific type given
+  if (!type) {
+    for (const t of ['scenes', 'objects', 'records']) {
+      if (dataIndex[t]?.[name] != null) {
+        return dataIndex[t][name]
+      }
+    }
+  }
+
+  // Case-insensitive fallback for scenes
+  if (type === 'scenes' || !type) {
+    const lower = name.toLowerCase()
+    for (const key of Object.keys(dataIndex.scenes)) {
+      if (key.toLowerCase() === lower) {
+        return dataIndex.scenes[key]
+      }
+    }
+  }
+
+  throw new Error(`Data file not found: ${name}${type ? ` (type: ${type})` : ''}`)
+}
+
+/**
+ * Recursively resolves $ref objects within data.
+ * A $ref is a name resolved from the data index (objects first, then any type).
+ *
+ * @param {*} node - Current data node
+ * @param {Set} seen - Tracks visited names to prevent circular refs
+ * @returns {*} Resolved data
+ */
+function resolveRefs(node, seen = new Set()) {
+  if (node === null || typeof node !== 'object') return node
+  if (Array.isArray(node)) {
+    return node.map((item) => resolveRefs(item, seen))
+  }
+
+  // Handle $ref replacement
+  if (node.$ref && typeof node.$ref === 'string') {
+    const refName = node.$ref
+    if (seen.has(refName)) {
+      throw new Error(`Circular $ref detected: ${refName}`)
+    }
+    seen.add(refName)
+    const refData = loadDataFile(refName, 'objects')
+    return resolveRefs(refData, seen)
+  }
+
+  // Recurse into object values
+  const result = {}
+  for (const [key, value] of Object.entries(node)) {
+    result[key] = resolveRefs(value, seen)
+  }
+  return result
+}
+
+/**
+ * Returns the names of all registered scenes.
+ * @returns {string[]}
+ */
+export function listScenes() {
+  return Object.keys(dataIndex.scenes)
+}
+
+/**
+ * Checks whether a scene file exists for the given name.
+ * @param {string} sceneName - e.g., "Overview"
+ * @returns {boolean}
+ */
+export function sceneExists(sceneName) {
+  if (dataIndex.scenes[sceneName] != null) return true
+  const lower = sceneName.toLowerCase()
+  for (const key of Object.keys(dataIndex.scenes)) {
+    if (key.toLowerCase() === lower) return true
+  }
+  return false
+}
+
+/**
+ * Loads a scene file and resolves $global and $ref references.
+ *
+ * - $global: array of data names merged into root (scene wins on conflicts)
+ * - $ref: inline object replacement at any nesting level
+ *
+ * @param {string} sceneName - Name of the scene (e.g., "default")
+ * @returns {object} Resolved scene data
+ */
+export function loadScene(sceneName = 'default') {
+  let sceneData
+
+  try {
+    sceneData = loadDataFile(sceneName, 'scenes')
+  } catch {
+    throw new Error(`Failed to load scene: ${sceneName}`)
+  }
+
+  // Handle $global: root-level merge from referenced data files
+  if (Array.isArray(sceneData.$global)) {
+    const globalNames = sceneData.$global
+    delete sceneData.$global
+
+    let mergedGlobals = {}
+    for (const name of globalNames) {
+      try {
+        let globalData = loadDataFile(name)
+        globalData = resolveRefs(globalData)
+        mergedGlobals = deepMerge(mergedGlobals, globalData)
+      } catch (err) {
+        console.warn(`Failed to load $global: ${name}`, err)
+      }
+    }
+
+    sceneData = deepMerge(mergedGlobals, sceneData)
+  }
+
+  sceneData = resolveRefs(sceneData)
+
+  // Single clone at the boundary — resolveRefs builds new objects internally,
+  // so the index data is safe. Clone here to prevent consumer mutation.
+  return structuredClone(sceneData)
+}
+
+/**
+ * Loads a record collection by name.
+ * @param {string} recordName - Name of the record file (e.g., "posts")
+ * @returns {Array} Parsed record collection
+ */
+export function loadRecord(recordName) {
+  const data = dataIndex.records[recordName]
+  if (data == null) {
+    throw new Error(`Record not found: ${recordName}`)
+  }
+  if (!Array.isArray(data)) {
+    throw new Error(`Record "${recordName}" must be an array, got ${typeof data}`)
+  }
+  return structuredClone(data)
+}
+
+/**
+ * Finds a single record entry by id within a collection.
+ * @param {string} recordName - Record collection name (e.g., "posts")
+ * @param {string} id - The id to match
+ * @returns {object|null} The matched entry, or null
+ */
+export function findRecord(recordName, id) {
+  const records = loadRecord(recordName)
+  return records.find((entry) => entry.id === id) ?? null
+}
+
+export { deepMerge }

package/src/loader.test.js

@@ -0,0 +1,232 @@
+import { init, loadScene, listScenes, sceneExists, loadRecord, findRecord, deepMerge } from './loader.js'
+
+const makeIndex = () => ({
+  scenes: {
+    default: {
+      title: 'Default Scene',
+      user: { $ref: 'jane-doe' },
+    },
+    Dashboard: {
+      $global: ['navigation'],
+      heading: 'Dashboard',
+      nav: 'scene-wins',
+    },
+    empty: {},
+    'with-nested-ref': {
+      team: {
+        lead: { $ref: 'jane-doe' },
+      },
+    },
+    'circular-a': {
+      thing: { $ref: 'circular-obj-a' },
+    },
+  },
+  objects: {
+    'jane-doe': {
+      name: 'Jane Doe',
+      role: 'admin',
+    },
+    navigation: {
+      nav: 'global-nav',
+      links: ['home', 'about'],
+    },
+    'circular-obj-a': {
+      nested: { $ref: 'circular-obj-b' },
+    },
+    'circular-obj-b': {
+      nested: { $ref: 'circular-obj-a' },
+    },
+  },
+  records: {
+    posts: [
+      { id: 'post-1', title: 'First Post' },
+      { id: 'post-2', title: 'Second Post' },
+    ],
+    'bad-record': { notAnArray: true },
+  },
+})
+
+beforeEach(() => {
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
+  init(makeIndex())
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('init', () => {
+  it('throws on null', () => {
+    expect(() => init(null)).toThrow()
+  })
+
+  it('throws on undefined', () => {
+    expect(() => init(undefined)).toThrow()
+  })
+
+  it('throws on non-object', () => {
+    expect(() => init('string')).toThrow()
+  })
+
+  it('stores data so loadScene works', () => {
+    init(makeIndex())
+    const scene = loadScene('default')
+    expect(scene.title).toBe('Default Scene')
+  })
+
+  it('handles missing properties gracefully', () => {
+    init({})
+    expect(sceneExists('anything')).toBe(false)
+  })
+})
+
+describe('loadScene', () => {
+  it('loads scene by name', () => {
+    const scene = loadScene('empty')
+    expect(scene).toEqual({})
+  })
+
+  it('resolves $ref to objects', () => {
+    const scene = loadScene('default')
+    expect(scene.user).toEqual({ name: 'Jane Doe', role: 'admin' })
+  })
+
+  it('resolves nested $ref', () => {
+    const scene = loadScene('with-nested-ref')
+    expect(scene.team.lead).toEqual({ name: 'Jane Doe', role: 'admin' })
+  })
+
+  it('resolves $global and merges into root, scene wins conflicts', () => {
+    const scene = loadScene('Dashboard')
+    expect(scene.links).toEqual(['home', 'about'])
+    expect(scene.heading).toBe('Dashboard')
+    // scene value should win over global value
+    expect(scene.nav).toBe('scene-wins')
+  })
+
+  it('throws for missing scene', () => {
+    expect(() => loadScene('nonexistent')).toThrow()
+  })
+
+  it('case-insensitive lookup', () => {
+    const scene = loadScene('dashboard')
+    expect(scene.heading).toBe('Dashboard')
+  })
+
+  it('returns deep clone (mutations do not affect index)', () => {
+    const scene1 = loadScene('empty')
+    scene1.injected = true
+    const scene2 = loadScene('empty')
+    expect(scene2.injected).toBeUndefined()
+  })
+
+  it('default param loads "default" scene', () => {
+    const scene = loadScene()
+    expect(scene.title).toBe('Default Scene')
+  })
+
+  it('detects circular $ref and throws', () => {
+    expect(() => loadScene('circular-a')).toThrow(/circular/i)
+  })
+})
+
+describe('sceneExists', () => {
+  it('returns true for existing scene', () => {
+    expect(sceneExists('default')).toBe(true)
+  })
+
+  it('returns false for missing scene', () => {
+    expect(sceneExists('nope')).toBe(false)
+  })
+
+  it('is case-insensitive', () => {
+    expect(sceneExists('dashboard')).toBe(true)
+    expect(sceneExists('DASHBOARD')).toBe(true)
+  })
+})
+
+describe('listScenes', () => {
+  it('returns all scene names', () => {
+    const names = listScenes()
+    expect(names).toContain('default')
+    expect(names).toContain('Dashboard')
+    expect(names).toContain('empty')
+  })
+
+  it('returns an array', () => {
+    expect(Array.isArray(listScenes())).toBe(true)
+  })
+
+  it('returns empty array when no scenes registered', () => {
+    init({ scenes: {}, objects: {}, records: {} })
+    expect(listScenes()).toEqual([])
+  })
+})
+
+describe('loadRecord', () => {
+  it('loads record array by name', () => {
+    const records = loadRecord('posts')
+    expect(records).toHaveLength(2)
+    expect(records[0].id).toBe('post-1')
+  })
+
+  it('throws for missing record', () => {
+    expect(() => loadRecord('nonexistent')).toThrow()
+  })
+
+  it('throws for non-array record', () => {
+    expect(() => loadRecord('bad-record')).toThrow(/array/i)
+  })
+
+  it('returns deep clone', () => {
+    const records1 = loadRecord('posts')
+    records1[0].title = 'Modified'
+    const records2 = loadRecord('posts')
+    expect(records2[0].title).toBe('First Post')
+  })
+})
+
+describe('findRecord', () => {
+  it('finds entry by id', () => {
+    const entry = findRecord('posts', 'post-2')
+    expect(entry).toEqual({ id: 'post-2', title: 'Second Post' })
+  })
+
+  it('returns null for missing id', () => {
+    const entry = findRecord('posts', 'nonexistent')
+    expect(entry).toBeNull()
+  })
+
+  it('throws for missing record', () => {
+    expect(() => findRecord('nonexistent', 'any')).toThrow()
+  })
+})
+
+describe('deepMerge', () => {
+  it('merges nested objects', () => {
+    const target = { a: { b: 1, c: 2 } }
+    const source = { a: { d: 3 } }
+    const result = deepMerge(target, source)
+    expect(result).toEqual({ a: { b: 1, c: 2, d: 3 } })
+  })
+
+  it('source wins conflicts', () => {
+    const target = { a: 1 }
+    const source = { a: 2 }
+    expect(deepMerge(target, source)).toEqual({ a: 2 })
+  })
+
+  it('arrays are replaced not concatenated', () => {
+    const target = { items: [1, 2, 3] }
+    const source = { items: [4, 5] }
+    expect(deepMerge(target, source)).toEqual({ items: [4, 5] })
+  })
+
+  it('handles null/undefined values', () => {
+    const target = { a: 1, b: 2 }
+    const source = { a: null, c: undefined }
+    const result = deepMerge(target, source)
+    expect(result.a).toBeNull()
+    expect(result.c).toBeUndefined()
+  })
+})

package/src/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'))
+}