@dfosco/storyboard 0.7.1 → 0.9.0

package/src/core/stores/canvasInteractionStore.test.js

@@ -0,0 +1,126 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+
+import {
+  initCanvasInteraction,
+  setCanvasInteraction,
+  getCanvasInteraction,
+  subscribeToCanvasInteraction,
+  getCanvasInteractionSnapshot,
+  _resetCanvasInteraction,
+} from './canvasInteractionStore.js'
+
+describe('canvasInteractionStore', () => {
+  beforeEach(() => {
+    _resetCanvasInteraction()
+  })
+
+  it('starts with defaults: scrollAxis=both, zoomGestures=true', () => {
+    expect(getCanvasInteraction()).toEqual({ scrollAxis: 'both', zoomGestures: true })
+  })
+
+  it('initCanvasInteraction seeds from config', () => {
+    initCanvasInteraction({ scrollAxis: 'vertical', zoomGestures: false })
+    expect(getCanvasInteraction()).toEqual({ scrollAxis: 'vertical', zoomGestures: false })
+  })
+
+  it('initCanvasInteraction with no args / empty / invalid resets to defaults', () => {
+    initCanvasInteraction({ scrollAxis: 'vertical', zoomGestures: false })
+    initCanvasInteraction()
+    expect(getCanvasInteraction()).toEqual({ scrollAxis: 'both', zoomGestures: true })
+
+    initCanvasInteraction({ scrollAxis: 'vertical', zoomGestures: false })
+    initCanvasInteraction({})
+    expect(getCanvasInteraction()).toEqual({ scrollAxis: 'both', zoomGestures: true })
+  })
+
+  it('initCanvasInteraction ignores invalid scrollAxis values', () => {
+    initCanvasInteraction({ scrollAxis: 'sideways' })
+    expect(getCanvasInteraction().scrollAxis).toBe('both')
+
+    initCanvasInteraction({ scrollAxis: null })
+    expect(getCanvasInteraction().scrollAxis).toBe('both')
+
+    initCanvasInteraction({ scrollAxis: 42 })
+    expect(getCanvasInteraction().scrollAxis).toBe('both')
+  })
+
+  it('initCanvasInteraction ignores non-boolean zoomGestures', () => {
+    initCanvasInteraction({ zoomGestures: 'yes' })
+    expect(getCanvasInteraction().zoomGestures).toBe(true)
+
+    initCanvasInteraction({ zoomGestures: 1 })
+    expect(getCanvasInteraction().zoomGestures).toBe(true)
+  })
+
+  it('accepts all four valid axis values', () => {
+    for (const axis of ['both', 'vertical', 'horizontal', 'none']) {
+      initCanvasInteraction({ scrollAxis: axis })
+      expect(getCanvasInteraction().scrollAxis).toBe(axis)
+    }
+  })
+
+  it('setCanvasInteraction patches partial state without resetting other keys', () => {
+    initCanvasInteraction({ scrollAxis: 'vertical', zoomGestures: false })
+
+    setCanvasInteraction({ zoomGestures: true })
+    expect(getCanvasInteraction()).toEqual({ scrollAxis: 'vertical', zoomGestures: true })
+
+    setCanvasInteraction({ scrollAxis: 'horizontal' })
+    expect(getCanvasInteraction()).toEqual({ scrollAxis: 'horizontal', zoomGestures: true })
+  })
+
+  it('setCanvasInteraction with no-op patch does not notify subscribers', () => {
+    const cb = vi.fn()
+    subscribeToCanvasInteraction(cb)
+    // Reset count: subscribers fire on initial reset_+ subscribe etc.
+    cb.mockClear()
+
+    setCanvasInteraction({}) // no keys
+    setCanvasInteraction({ scrollAxis: 'invalid' }) // ignored
+    setCanvasInteraction({ scrollAxis: 'both' }) // same as default
+    setCanvasInteraction({ zoomGestures: true }) // same as default
+    expect(cb).not.toHaveBeenCalled()
+
+    setCanvasInteraction({ zoomGestures: false }) // real change
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+
+  it('subscribers are notified on init and meaningful set; unsubscribe stops further notifications', () => {
+    const cb = vi.fn()
+    const unsub = subscribeToCanvasInteraction(cb)
+
+    initCanvasInteraction({ scrollAxis: 'vertical' })
+    setCanvasInteraction({ zoomGestures: false })
+
+    expect(cb).toHaveBeenCalledTimes(2)
+    unsub()
+
+    setCanvasInteraction({ scrollAxis: 'horizontal' })
+    expect(cb).toHaveBeenCalledTimes(2)
+  })
+
+  it('snapshot version changes on every meaningful mutation', () => {
+    const v0 = getCanvasInteractionSnapshot()
+    initCanvasInteraction({ scrollAxis: 'vertical' })
+    const v1 = getCanvasInteractionSnapshot()
+    expect(v1).not.toBe(v0)
+
+    setCanvasInteraction({ zoomGestures: false })
+    const v2 = getCanvasInteractionSnapshot()
+    expect(v2).not.toBe(v1)
+  })
+
+  it('subscriber errors are isolated', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const goodCb = vi.fn()
+
+    subscribeToCanvasInteraction(() => { throw new Error('boom') })
+    subscribeToCanvasInteraction(goodCb)
+
+    setCanvasInteraction({ zoomGestures: false })
+
+    expect(goodCb).toHaveBeenCalled()
+    expect(errorSpy).toHaveBeenCalled()
+    errorSpy.mockRestore()
+  })
+})

package/src/core/stores/configSchema.js

@@ -42,7 +42,6 @@
  * @property {Record<string, CanvasAgentConfig>} [agents] — per-agent overrides
  * @property {CanvasZoomConfig} [zoom] — zoom min/max/step settings
  * @property {CanvasMessagingConfig} [messaging] — hub messaging settings
- * @property {boolean} [inlineStories] — render StoryWidget inline (no iframe). Default false.
  */
 
 /**
@@ -79,7 +78,7 @@
  * @property {number}  [default_max_pool_size] — default surge cap per pool (default: 3)
  * @property {boolean} [load_balancer] — enable auto-scaling (default: true)
  * @property {number}  [load_balancer_cooldown_mins] — minutes idle before scale-down (default: 10)
- * @property {Record<string, { pool_size?: number, max_pool_size?: number, webgl_ready_slots?: number }>} [pools] — per-pool overrides (terminal, prompt, copilot, claude, codex). webgl_ready_slots: how many front-of-queue sessions should start with PINNED WebGL priority (default: 0)
+ * @property {Record<string, { pool_size?: number, max_pool_size?: number }>} [pools] — per-pool overrides (terminal, prompt, copilot, claude, codex).
  */
 
 /**
@@ -121,10 +120,30 @@
 
 /**
  * @typedef {object} CustomerModeConfig
- * @property {boolean} enabled       — master toggle for customer mode
- * @property {boolean} hideChrome    — hides all toolbars (except canvas tools), branchbar, cmd+k, cmd+.
- * @property {boolean} hideHomepage  — removes the storyboard homepage (leaves empty page)
- * @property {string}  protoHomepage — internal /path that replaces homepage; redirects from / and /workspace
+ * @property {boolean} enabled        — master toggle for customer mode
+ * @property {boolean} hideChrome     — hides all toolbars (except canvas tools), branchbar, cmd+k, cmd+.
+ * @property {boolean} hideHomepage   — removes the storyboard homepage (leaves empty page)
+ * @property {string}  protoHomepage  — internal /path that replaces homepage; redirects from / and /workspace
+ * @property {string}  canvasHomepage — canvas id (e.g. "landing") that replaces homepage. Mutually exclusive with `protoHomepage` — when both are set, this wins.
+ */
+
+/**
+ * @typedef {object} ThemeDefinition
+ * @property {string} label                       — display name shown in theme switchers
+ * @property {Record<string,string>} [attrs]      — companion data attributes written onto each surface element when this theme is active (e.g. Primer's `data-color-mode`, `data-light-theme`). Storyboard core writes no companion attrs by default; consumers (Primer-using repos, etc.) add them via their own storyboard.config.json.
+ */
+
+/**
+ * @typedef {object} SurfaceDefinition
+ * @property {string}  label   — display label shown in the "Apply theme to" sub-menu
+ * @property {boolean} sync    — default value for whether this surface follows the global theme (true) or stays light (false). Persisted per-user in localStorage.
+ */
+
+/**
+ * @typedef {object} ThemesConfig
+ * @property {Record<string, ThemeDefinition>}   themes    — registry of available themes. Theme IDs are the values written to `data-sb-<surface>-theme`. Storyboard core ships only `light` and `dark`; consumers add more (e.g. `dark_dimmed`, `light_colorblind`).
+ * @property {Record<string, SurfaceDefinition>} surfaces  — registry of theming surfaces. Each surface ID is matched against `[data-sb-surface="<id>"]` elements in the DOM. The runtime writes `data-sb-<id>-theme` onto those elements plus the companion `attrs` from the active theme. Core ships `prototype`, `canvas`, `toolbar`, `codeBoxes`.
+ * @property {string}  [default]  — default global theme ID. Use `"system"` to follow OS preference.
  */
 
 /**
@@ -145,6 +164,7 @@
  * @property {HotPoolConfig} [hotPool]
  * @property {CommandPaletteConfig} [commandPalette]
  * @property {CustomerModeConfig} [customerMode]
+ * @property {ThemesConfig} [themes]
  */
 
 /** Built-in paste rules shipped with storyboard. */
@@ -169,7 +189,18 @@ export const configDefaults = {
   plugins: {},
   workshop: {
     enabled: false,
-    features: { createPrototype: true, createFlow: true, createCanvas: true },
+    // Each `create<X>` flag controls whether the corresponding item appears
+    // in the workspace Create-Artifact menu. Default true — set to false in
+    // a consumer's storyboard.config.json to hide that item.
+    features: {
+      createPrototype: true,
+      createCanvas: true,
+      createComponent: true,
+      createFlow: true,
+      createPage: true,
+      createObject: true,
+      createRecord: true,
+    },
   },
   featureFlags: {},
   ui: {},
@@ -184,6 +215,10 @@ export const configDefaults = {
       min: 10,
       max: 250,
       step: 10,
+      gestures: true, // when false, disables cmd+wheel and pinch-to-zoom; +/- buttons still work
+    },
+    scroll: {
+      axis: 'both', // "both" | "vertical" | "horizontal" | "none"
     },
     terminal: {
       resizable: false,
@@ -196,7 +231,6 @@ export const configDefaults = {
       pollIntervalMs: 2000,
       maxMessagesPerHub: 200,
     },
-    inlineStories: false,
   },
   commandPalette: {
     providers: ['prototypes', 'flows', 'canvases', 'pages'],
@@ -208,6 +242,28 @@ export const configDefaults = {
     hideChrome: false,
     hideHomepage: false,
     protoHomepage: '',
+    canvasHomepage: '',
+  },
+  theming: {
+    // Minimal default theme registry. Consumers add more in their own
+    // storyboard.config.json — see README#theming. IDs starting with "dark"
+    // are picked up by the Tailwind `dark:` variant via prefix match.
+    themes: {
+      light: { label: 'Light', attrs: {} },
+      dark:  { label: 'Dark',  attrs: {} },
+    },
+    // Surface registry. Each surface ID is looked up in the DOM as
+    // `[data-sb-surface="<id>"]`. The runtime writes
+    // `data-sb-<id>-theme="<resolved>"` plus the active theme's companion
+    // `attrs` onto every matching element.
+    surfaces: {
+      prototype: { label: 'Prototype',  sync: true  },
+      canvas:    { label: 'Canvas',     sync: true  },
+      toolbar:   { label: 'Tools',      sync: false },
+      codeBoxes: { label: 'Code boxes', sync: true  },
+    },
+    // Default global theme. "system" follows OS prefers-color-scheme.
+    default: 'system',
   },
 }
 

package/src/core/stores/configSchema.test.js

@@ -24,12 +24,15 @@ describe('configSchema', () => {
       expect(c.canvas.pasteRules).toEqual(builtinPasteRules)
       expect(c.canvas.github.embedBehavior).toBe('link-preview')
       expect(c.canvas.github.ghGuard).toBe('copy')
+      expect(c.canvas.zoom.gestures).toBe(true)
+      expect(c.canvas.scroll.axis).toBe('both')
       expect(c.commandPalette.providers).toEqual(['prototypes', 'flows', 'canvases', 'pages'])
       expect(c.commandPalette.ranking).toBe('frecency')
       expect(c.customerMode.enabled).toBe(false)
       expect(c.customerMode.hideChrome).toBe(false)
       expect(c.customerMode.hideHomepage).toBe(false)
       expect(c.customerMode.protoHomepage).toBe('')
+      expect(c.customerMode.canvasHomepage).toBe('')
     })
 
     it('returns full defaults when called with undefined', () => {

package/src/core/stores/customerModeConfig.js

@@ -3,19 +3,40 @@
  * Framework-agnostic (zero npm dependencies).
  */
 
-let _config = { enabled: false, hideChrome: false, hideHomepage: false, protoHomepage: '' }
+let _config = {
+  enabled: false,
+  hideChrome: false,
+  hideHomepage: false,
+  protoHomepage: '',
+  canvasHomepage: '',
+}
 
 /**
  * Initialize customer mode config.
+ * If both `protoHomepage` and `canvasHomepage` are set, `canvasHomepage` wins
+ * (it's the more specific landing-page case) and a console warning is logged.
  * @param {object} config - The customerMode object from storyboard.config.json
  */
 export function initCustomerModeConfig(config) {
-  _config = { enabled: false, hideChrome: false, hideHomepage: false, protoHomepage: '', ...config }
+  _config = {
+    enabled: false,
+    hideChrome: false,
+    hideHomepage: false,
+    protoHomepage: '',
+    canvasHomepage: '',
+    ...config,
+  }
+  if (_config.protoHomepage && _config.canvasHomepage) {
+    console.warn(
+      '[storyboard] customerMode has both `protoHomepage` and `canvasHomepage` set. ' +
+      '`canvasHomepage` takes precedence; ignoring `protoHomepage`.'
+    )
+  }
 }
 
 /**
  * Get the current customer mode config.
- * @returns {{ enabled: boolean, hideChrome: boolean, hideHomepage: boolean, protoHomepage: string }}
+ * @returns {{ enabled: boolean, hideChrome: boolean, hideHomepage: boolean, protoHomepage: string, canvasHomepage: string }}
  */
 export function getCustomerModeConfig() {
   return _config

package/src/core/stores/customerModeConfig.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+
+import {
+  initCustomerModeConfig,
+  getCustomerModeConfig,
+} from './customerModeConfig.js'
+
+describe('customerModeConfig', () => {
+  beforeEach(() => {
+    // Reset to a known empty state between tests
+    initCustomerModeConfig({})
+  })
+
+  it('defaults canvasHomepage to empty string', () => {
+    const cfg = getCustomerModeConfig()
+    expect(cfg.canvasHomepage).toBe('')
+    expect(cfg.protoHomepage).toBe('')
+  })
+
+  it('accepts canvasHomepage from config', () => {
+    initCustomerModeConfig({ enabled: true, canvasHomepage: 'landing' })
+    expect(getCustomerModeConfig().canvasHomepage).toBe('landing')
+  })
+
+  it('warns when both protoHomepage and canvasHomepage are set', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    initCustomerModeConfig({
+      enabled: true,
+      protoHomepage: '/MyProto',
+      canvasHomepage: 'landing',
+    })
+    expect(warnSpy).toHaveBeenCalledTimes(1)
+    expect(warnSpy.mock.calls[0][0]).toMatch(/protoHomepage.*canvasHomepage/)
+    expect(warnSpy.mock.calls[0][0]).toMatch(/canvasHomepage.*takes precedence/)
+    warnSpy.mockRestore()
+  })
+
+  it('does not warn when only one is set', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    initCustomerModeConfig({ enabled: true, canvasHomepage: 'landing' })
+    expect(warnSpy).not.toHaveBeenCalled()
+    initCustomerModeConfig({ enabled: true, protoHomepage: '/Proto' })
+    expect(warnSpy).not.toHaveBeenCalled()
+    warnSpy.mockRestore()
+  })
+})

package/src/core/stores/presentationStore.js

@@ -0,0 +1,118 @@
+/**
+ * Presentation Store — consumer-supplied overrides for storyboard chrome elements.
+ *
+ * A chrome element is any rendered piece of storyboard UI that is wrapped in
+ * `<ChromeSlot id="...">` (toolbar buttons, canvas title, page selector, etc.).
+ *
+ * Consumers seed this registry through `mountStoryboardCore({ presentation })`
+ * and the store applies per-element overrides at render time:
+ *
+ *   {
+ *     "tool:command-palette": {
+ *       style:     { transform: 'translateY(20px)', opacity: 0 },
+ *       className: 'landing-floating-button',
+ *       props:     { onPointerEnter: handleHover },
+ *       decorator: (Element, ctx) => <ScrollAnimator>{Element}</ScrollAnimator>,
+ *     },
+ *     "canvas:title": { hidden: true },
+ *   }
+ *
+ * This is an **advanced, undocumented** extension surface — intended for
+ * landing-page / hero canvas use cases where the consumer needs heavy
+ * customization of storyboard chrome. Not part of the public API.
+ *
+ * Framework-agnostic (zero npm dependencies).
+ */
+
+/**
+ * @typedef {object} PresentationOverride
+ * @property {React.CSSProperties} [style]     - Spread onto the chrome element root style
+ * @property {string}              [className] - Appended to the chrome element root className
+ * @property {object}              [props]     - Spread as additional props on the chrome element
+ * @property {Function}            [decorator] - (Element, ctx) => ReactNode wrapper
+ * @property {boolean}             [hidden]    - If true, render null (shorthand for full hide)
+ */
+
+/** @type {Map<string, PresentationOverride>} */
+let _overrides = new Map()
+
+/** @type {Set<Function>} */
+const _listeners = new Set()
+
+let _snapshotVersion = 0
+
+/**
+ * Seed the presentation registry from a consumer-supplied map.
+ * Replaces any previous overrides. Called once at app startup.
+ *
+ * @param {Record<string, PresentationOverride>} [map]
+ */
+export function initPresentation(map) {
+  _overrides = new Map()
+  if (map && typeof map === 'object') {
+    for (const [id, override] of Object.entries(map)) {
+      if (override && typeof override === 'object') {
+        _overrides.set(id, override)
+      }
+    }
+  }
+  _notify()
+}
+
+/**
+ * Set or replace a single chrome element's presentation override.
+ * @param {string} id
+ * @param {PresentationOverride|null|undefined} override Pass null/undefined to clear.
+ */
+export function setPresentation(id, override) {
+  if (override == null) {
+    _overrides.delete(id)
+  } else if (typeof override === 'object') {
+    _overrides.set(id, override)
+  }
+  _notify()
+}
+
+/**
+ * Get the presentation override for a chrome element ID, or null if none.
+ * @param {string} id
+ * @returns {PresentationOverride|null}
+ */
+export function getPresentation(id) {
+  return _overrides.get(id) || null
+}
+
+/**
+ * Subscribe to presentation registry changes. Returns an unsubscribe fn.
+ * Compatible with `useSyncExternalStore` shape.
+ * @param {Function} callback
+ * @returns {Function}
+ */
+export function subscribeToPresentation(callback) {
+  _listeners.add(callback)
+  return () => _listeners.delete(callback)
+}
+
+/**
+ * Snapshot version for change detection. Compatible with `useSyncExternalStore`.
+ * @returns {string}
+ */
+export function getPresentationSnapshot() {
+  return String(_snapshotVersion)
+}
+
+function _notify() {
+  _snapshotVersion++
+  for (const cb of _listeners) {
+    try { cb() } catch (err) {
+      console.error('[storyboard] Error in presentation subscriber:', err)
+    }
+  }
+}
+
+/** Reset all state. Only for tests. */
+export function _resetPresentation() {
+  _overrides = new Map()
+  _listeners.clear()
+  _snapshotVersion = 0
+}

package/src/core/stores/presentationStore.test.js

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+
+import {
+  initPresentation,
+  setPresentation,
+  getPresentation,
+  subscribeToPresentation,
+  getPresentationSnapshot,
+  _resetPresentation,
+} from './presentationStore.js'
+
+describe('presentationStore', () => {
+  beforeEach(() => {
+    _resetPresentation()
+  })
+
+  it('returns null when no override is registered', () => {
+    expect(getPresentation('tool:command-palette')).toBeNull()
+  })
+
+  it('seeds overrides from initPresentation', () => {
+    initPresentation({
+      'tool:command-palette': { hidden: true },
+      'canvas:title': { className: 'landing-title' },
+    })
+    expect(getPresentation('tool:command-palette')).toEqual({ hidden: true })
+    expect(getPresentation('canvas:title')).toEqual({ className: 'landing-title' })
+    expect(getPresentation('nope:nothing')).toBeNull()
+  })
+
+  it('ignores non-object values in initPresentation', () => {
+    initPresentation({
+      'tool:a': null,
+      'tool:b': 'invalid',
+      'tool:c': 42,
+      'tool:d': { hidden: true },
+    })
+    expect(getPresentation('tool:a')).toBeNull()
+    expect(getPresentation('tool:b')).toBeNull()
+    expect(getPresentation('tool:c')).toBeNull()
+    expect(getPresentation('tool:d')).toEqual({ hidden: true })
+  })
+
+  it('replaces previous overrides on subsequent initPresentation calls', () => {
+    initPresentation({ 'tool:a': { hidden: true } })
+    initPresentation({ 'tool:b': { hidden: true } })
+    expect(getPresentation('tool:a')).toBeNull()
+    expect(getPresentation('tool:b')).toEqual({ hidden: true })
+  })
+
+  it('initPresentation() with no arg clears all overrides', () => {
+    initPresentation({ 'tool:a': { hidden: true } })
+    initPresentation()
+    expect(getPresentation('tool:a')).toBeNull()
+  })
+
+  it('setPresentation adds and updates individual overrides', () => {
+    setPresentation('tool:a', { className: 'foo' })
+    expect(getPresentation('tool:a')).toEqual({ className: 'foo' })
+
+    setPresentation('tool:a', { className: 'bar' })
+    expect(getPresentation('tool:a')).toEqual({ className: 'bar' })
+  })
+
+  it('setPresentation with null/undefined deletes the override', () => {
+    setPresentation('tool:a', { hidden: true })
+    setPresentation('tool:a', null)
+    expect(getPresentation('tool:a')).toBeNull()
+
+    setPresentation('tool:b', { hidden: true })
+    setPresentation('tool:b', undefined)
+    expect(getPresentation('tool:b')).toBeNull()
+  })
+
+  it('subscribers are notified on init, set, and clear', () => {
+    const cb = vi.fn()
+    const unsub = subscribeToPresentation(cb)
+
+    initPresentation({ 'tool:a': { hidden: true } })
+    setPresentation('tool:b', { className: 'x' })
+    setPresentation('tool:a', null)
+
+    expect(cb).toHaveBeenCalledTimes(3)
+    unsub()
+
+    setPresentation('tool:c', { hidden: true })
+    expect(cb).toHaveBeenCalledTimes(3) // not called after unsubscribe
+  })
+
+  it('snapshot version changes on every mutation', () => {
+    const v0 = getPresentationSnapshot()
+    setPresentation('tool:a', { hidden: true })
+    const v1 = getPresentationSnapshot()
+    expect(v1).not.toBe(v0)
+
+    setPresentation('tool:b', { hidden: true })
+    const v2 = getPresentationSnapshot()
+    expect(v2).not.toBe(v1)
+  })
+
+  it('subscriber errors are isolated', () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const goodCb = vi.fn()
+
+    subscribeToPresentation(() => { throw new Error('boom') })
+    subscribeToPresentation(goodCb)
+
+    setPresentation('tool:a', { hidden: true })
+
+    expect(goodCb).toHaveBeenCalled()
+    expect(consoleSpy).toHaveBeenCalled()
+    consoleSpy.mockRestore()
+  })
+})

package/src/core/stores/recentArtifacts.js

@@ -1,13 +1,20 @@
 /**
- * Recent Artifacts — localStorage-backed recents for the command palette.
+ * Recent Artifacts — localStorage-backed recents for the workspace and
+ * command palette.
  *
  * Stores artifact identity (type + key + label), not routes.
  * Routes are derived at read time from the live data index so they
  * stay correct across branch/basePath changes.
+ *
+ * Subscribable via {@link subscribeToRecent} / {@link getRecentSnapshot}
+ * for `useSyncExternalStore` integration. Writes within the same tab
+ * are surfaced via a synthetic `storage` event so other listeners
+ * (including this module's own snapshot consumers) re-read immediately.
  */
 
 const STORAGE_KEY = 'storyboard:recent-artifacts'
-const MAX_ITEMS = 10
+const MAX_ITEMS = 30
+const CHANGE_EVENT = 'storyboard-recent-artifacts-changed'
 
 /**
  * @typedef {{ type: string, key: string, label: string }} RecentEntry
@@ -43,9 +50,42 @@ export function getRecent() {
 export function clearRecent() {
   try {
     localStorage.removeItem(STORAGE_KEY)
+    _notify()
   } catch { /* ignore */ }
 }
 
+/**
+ * Subscribe to changes in the recent artifacts store. Fires for both
+ * intra-tab writes (via a synthetic event) and cross-tab writes (via
+ * the native `storage` event).
+ *
+ * Designed for `useSyncExternalStore` — pair with {@link getRecentSnapshot}.
+ *
+ * @param {() => void} callback
+ * @returns {() => void} unsubscribe
+ */
+export function subscribeToRecent(callback) {
+  if (typeof window === 'undefined') return () => {}
+  const onStorage = (e) => { if (!e || !e.key || e.key === STORAGE_KEY) callback() }
+  window.addEventListener('storage', onStorage)
+  window.addEventListener(CHANGE_EVENT, callback)
+  return () => {
+    window.removeEventListener('storage', onStorage)
+    window.removeEventListener(CHANGE_EVENT, callback)
+  }
+}
+
+/**
+ * Return a stable string snapshot of the recent artifacts store for
+ * `useSyncExternalStore`. Returns the raw JSON (or `'[]'` if absent).
+ *
+ * @returns {string}
+ */
+export function getRecentSnapshot() {
+  try { return localStorage.getItem(STORAGE_KEY) || '[]' }
+  catch { return '[]' }
+}
+
 // ---------------------------------------------------------------------------
 // Internal
 // ---------------------------------------------------------------------------
@@ -64,5 +104,12 @@ function _read() {
 function _write(entries) {
   try {
     localStorage.setItem(STORAGE_KEY, JSON.stringify(entries))
+    _notify()
   } catch { /* quota exceeded or unavailable */ }
 }
+
+function _notify() {
+  if (typeof window === 'undefined') return
+  try { window.dispatchEvent(new Event(CHANGE_EVENT)) }
+  catch { /* ignore (e.g. SSR / non-browser) */ }
+}