@dfosco/storyboard-core 1.17.3 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "1.17.3",
+  "version": "1.18.0",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/devtools.js

@@ -16,6 +16,7 @@
 import { loadScene } from './loader.js'
 import { isCommentsEnabled } from './comments/config.js'
 import { isHideMode, activateHideMode, deactivateHideMode } from './hideMode.js'
+import { getAllFlags, toggleFlag, getFlagKeys } from './featureFlags.js'
 
 const STYLES = `
 .sb-devtools-wrapper {
@@ -67,7 +68,7 @@ const STYLES = `
   border: none;
   color: #c9d1d9;
   font-size: 14px;
-  font-family: inherit;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
   cursor: pointer;
   text-align: left;
 }
@@ -101,6 +102,7 @@ const STYLES = `
   width: 100%;
   max-width: 640px;
   max-height: 60vh;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
   background-color: #0d1117;
   border: 1px solid #30363d;
   border-radius: 12px;
@@ -151,6 +153,19 @@ const STYLES = `
   word-break: break-word;
 }
 .sb-devtools-error { color: #f85149; }
+.sb-devtools-separator {
+  height: 1px;
+  background-color: #21262d;
+  margin: 4px 0;
+}
+.sb-devtools-group-header {
+  padding: 6px 16px 2px;
+  font-size: 12px;
+  font-weight: 600;
+  color: #8b949e;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
 `
 
 // SVG icons (inline to avoid external deps)
@@ -161,6 +176,8 @@ const VIEWFINDER_ICON = '<svg viewBox="0 0 16 16"><path d="M8.5 1.75a.75.75 0 0
 const X_ICON = '<svg viewBox="0 0 16 16"><path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"/></svg>'
 const EYE_ICON = '<svg viewBox="0 0 16 16"><path d="M8 2c1.981 0 3.671.992 4.933 2.078 1.27 1.091 2.187 2.345 2.637 3.023a1.62 1.62 0 0 1 0 1.798c-.45.678-1.367 1.932-2.637 3.023C11.67 13.008 9.981 14 8 14s-3.671-.992-4.933-2.078C1.797 10.831.88 9.577.43 8.899a1.62 1.62 0 0 1 0-1.798c.45-.678 1.367-1.932 2.637-3.023C4.33 2.992 6.019 2 8 2ZM1.679 7.932a.12.12 0 0 0 0 .136c.411.622 1.241 1.75 2.366 2.717C5.176 11.758 6.527 12.5 8 12.5s2.823-.742 3.955-1.715c1.124-.967 1.954-2.096 2.366-2.717a.12.12 0 0 0 0-.136c-.412-.621-1.242-1.75-2.366-2.717C10.824 4.242 9.473 3.5 8 3.5s-2.824.742-3.955 1.715c-1.124.967-1.954 2.096-2.366 2.717ZM8 10a2 2 0 1 1-.001-3.999A2 2 0 0 1 8 10Z"/></svg>'
 const EYE_CLOSED_ICON = '<svg viewBox="0 0 16 16"><path d="M.143 2.31a.75.75 0 0 1 1.047-.167l14.5 10.5a.75.75 0 1 1-.88 1.214l-2.248-1.628C11.346 13.19 9.792 14 8 14c-1.981 0-3.671-.992-4.933-2.078C1.797 10.831.88 9.577.43 8.899a1.62 1.62 0 0 1 0-1.798c.35-.527 1.06-1.476 2.019-2.398L.31 3.357A.75.75 0 0 1 .143 2.31Zm3.386 3.378a14.21 14.21 0 0 0-1.85 2.244.12.12 0 0 0 0 .136c.411.622 1.241 1.75 2.366 2.717C5.176 11.758 6.527 12.5 8 12.5c1.195 0 2.31-.488 3.29-1.191L9.063 9.695A2 2 0 0 1 6.058 7.39L3.529 5.688ZM8 3.5c-.516 0-1.017.09-1.499.251a.75.75 0 1 1-.473-1.423A6.23 6.23 0 0 1 8 2c1.981 0 3.671.992 4.933 2.078 1.27 1.091 2.187 2.345 2.637 3.023a1.62 1.62 0 0 1 0 1.798c-.11.166-.248.365-.41.587a.75.75 0 1 1-1.21-.887c.14-.191.26-.367.36-.524a.12.12 0 0 0 0-.136c-.412-.621-1.242-1.75-2.366-2.717C10.824 4.242 9.473 3.5 8 3.5Z"/></svg>'
+const CHECK_ICON = '<svg viewBox="0 0 16 16"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"/></svg>'
+const ZAP_ICON = '<svg viewBox="0 0 16 16"><path d="M9.504.43a1.516 1.516 0 0 1 2.437 1.713L10.415 5.5h2.123c1.57 0 2.346 1.909 1.22 3.004l-7.34 7.142a1.249 1.249 0 0 1-.871.354h-.302a1.25 1.25 0 0 1-1.157-1.723L5.633 10.5H3.462c-1.57 0-2.346-1.909-1.22-3.004Z"/></svg>'
 
 function getSceneName() {
   return new URLSearchParams(window.location.search).get('scene') || 'default'
@@ -227,10 +244,11 @@ export function mountDevTools(options = {}) {
   hint.className = 'sb-devtools-hint'
   hint.innerHTML = 'Press <code>⌘ + .</code> to hide'
 
-  menu.appendChild(viewfinderBtn)
-  menu.appendChild(showInfoBtn)
-  menu.appendChild(resetBtn)
-  menu.appendChild(hideModeBtn)
+  // Feature flags entry (opens a dedicated panel)
+  const featureFlagsBtn = document.createElement('button')
+  featureFlagsBtn.className = 'sb-devtools-menu-item'
+  featureFlagsBtn.innerHTML = `${ZAP_ICON} Feature Flags`
+  featureFlagsBtn.addEventListener('click', openFlagsPanel)
 
   // Comments menu items (injected dynamically if comments are enabled)
   function refreshCommentMenuItems() {
@@ -258,19 +276,104 @@ export function mountDevTools(options = {}) {
     })
   }
 
+  function renderMainMenu() {
+    while (menu.firstChild) menu.removeChild(menu.firstChild)
+    menu.appendChild(viewfinderBtn)
+    menu.appendChild(showInfoBtn)
+    menu.appendChild(resetBtn)
+    menu.appendChild(hideModeBtn)
+    if (getFlagKeys().length > 0) {
+      const sep = document.createElement('div')
+      sep.className = 'sb-devtools-separator'
+      menu.appendChild(sep)
+      menu.appendChild(featureFlagsBtn)
+    }
+    refreshCommentMenuItems()
+    menu.appendChild(hint)
+  }
+
   // Refresh dynamic items when menu opens
   trigger.addEventListener('click', () => {
-    refreshCommentMenuItems()
+    renderMainMenu()
     updateHideModeBtn()
   })
 
-  menu.appendChild(hint)
+  // Build initial (closed) menu content so tests and static DOM inspection work.
+  renderMainMenu()
   wrapper.appendChild(menu)
   wrapper.appendChild(trigger)
   container.appendChild(wrapper)
 
-  // Overlay (created lazily)
+  // Overlays (created lazily)
   let overlay = null
+  let flagsOverlay = null
+
+  function closeFlagsPanel() {
+    if (flagsOverlay) {
+      flagsOverlay.remove()
+      flagsOverlay = null
+    }
+  }
+
+  function openFlagsPanel() {
+    menuOpen = false
+    menu.classList.remove('open')
+    closeFlagsPanel()
+
+    flagsOverlay = document.createElement('div')
+    flagsOverlay.className = 'sb-devtools-overlay'
+
+    const backdrop = document.createElement('div')
+    backdrop.className = 'sb-devtools-backdrop'
+    backdrop.addEventListener('click', closeFlagsPanel)
+
+    const panel = document.createElement('div')
+    panel.className = 'sb-devtools-panel'
+
+    const header = document.createElement('div')
+    header.className = 'sb-devtools-panel-header'
+    header.innerHTML = '<span class="sb-devtools-panel-title">Feature Flags</span>'
+
+    const closeBtn = document.createElement('button')
+    closeBtn.className = 'sb-devtools-panel-close'
+    closeBtn.setAttribute('aria-label', 'Close feature flags panel')
+    closeBtn.innerHTML = X_ICON
+    closeBtn.addEventListener('click', closeFlagsPanel)
+    header.appendChild(closeBtn)
+
+    const body = document.createElement('div')
+    body.className = 'sb-devtools-panel-body'
+
+    function renderFlagItems() {
+      body.innerHTML = ''
+      const keys = getFlagKeys()
+      if (keys.length === 0) {
+        body.innerHTML = '<span class="sb-devtools-hint">No feature flags are configured.</span>'
+        return
+      }
+      const flags = getAllFlags()
+      for (const key of keys) {
+        const btn = document.createElement('button')
+        btn.className = 'sb-devtools-menu-item'
+        const icon = flags[key].current
+          ? `<span style="width:16px;height:16px;display:flex;align-items:center;justify-content:center;">${CHECK_ICON}</span>`
+          : '<span style="width:16px;height:16px;"></span>'
+        btn.innerHTML = `${icon} ${key}`
+        btn.addEventListener('click', () => {
+          toggleFlag(key)
+          renderFlagItems()
+        })
+        body.appendChild(btn)
+      }
+    }
+    renderFlagItems()
+
+    panel.appendChild(header)
+    panel.appendChild(body)
+    flagsOverlay.appendChild(backdrop)
+    flagsOverlay.appendChild(panel)
+    container.appendChild(flagsOverlay)
+  }
 
   function openPanel() {
     menuOpen = false
@@ -367,7 +470,7 @@ export function mountDevTools(options = {}) {
     menu.classList.remove('open')
   })
 
-  // Close menu when clicking outside
+  // Close menu when clicking outside — reset to main view
   document.addEventListener('click', (e) => {
     if (menuOpen && !wrapper.contains(e.target)) {
       menuOpen = false
@@ -385,6 +488,7 @@ export function mountDevTools(options = {}) {
         menuOpen = false
         menu.classList.remove('open')
         closePanel()
+        closeFlagsPanel()
       }
     }
   })

package/src/featureFlags.js

@@ -0,0 +1,112 @@
+/**
+ * Feature flag system for Storyboard.
+ *
+ * Flags are defined in storyboard.config.json under "featureFlags" and
+ * initialized at app startup via the Vite data plugin.
+ *
+ * Read priority:  URL hash → localStorage → config defaults
+ * Write target:   URL hash (shareable)
+ *
+ * All flag keys in hash/localStorage are prefixed with "flag." to avoid
+ * collisions with scene overrides.
+ */
+
+import { getParam, setParam, removeParam, getAllParams } from './session.js'
+import { getLocal, setLocal, removeLocal, getAllLocal } from './localStorage.js'
+
+const FLAG_PREFIX = 'flag.'
+
+/** Module-level storage for config defaults */
+let _defaults = {}
+
+/**
+ * Initialize the feature flag system with config defaults.
+ * Seeds localStorage with defaults (doesn't overwrite existing values).
+ * @param {Record<string, boolean>} defaults - Flag key → default value
+ */
+export function initFeatureFlags(defaults = {}) {
+  _defaults = { ...defaults }
+  // Seed localStorage with defaults (don't overwrite existing)
+  for (const [key, value] of Object.entries(_defaults)) {
+    if (getLocal(FLAG_PREFIX + key) === null) {
+      setLocal(FLAG_PREFIX + key, String(value))
+    }
+  }
+}
+
+/**
+ * Read a flag value. Priority: hash → localStorage → config default.
+ * @param {string} key - Flag key (without prefix)
+ * @returns {boolean}
+ */
+export function getFlag(key) {
+  // 1. URL hash (highest priority)
+  const hashVal = getParam(FLAG_PREFIX + key)
+  if (hashVal !== null) return hashVal === 'true'
+
+  // 2. localStorage
+  const localVal = getLocal(FLAG_PREFIX + key)
+  if (localVal !== null) return localVal === 'true'
+
+  // 3. Config default
+  return _defaults[key] ?? false
+}
+
+/**
+ * Set a flag value. Writes to URL hash for shareability.
+ * @param {string} key - Flag key (without prefix)
+ * @param {boolean} value
+ */
+export function setFlag(key, value) {
+  setParam(FLAG_PREFIX + key, String(value))
+}
+
+/**
+ * Toggle a flag. Reads current value, writes opposite to hash.
+ * @param {string} key - Flag key (without prefix)
+ */
+export function toggleFlag(key) {
+  setFlag(key, !getFlag(key))
+}
+
+/**
+ * Get all flags with their default and current (resolved) values.
+ * @returns {Record<string, { default: boolean, current: boolean }>}
+ */
+export function getAllFlags() {
+  const result = {}
+  for (const key of Object.keys(_defaults)) {
+    result[key] = {
+      default: _defaults[key] ?? false,
+      current: getFlag(key),
+    }
+  }
+  return result
+}
+
+/**
+ * Reset all flags — removes hash and localStorage overrides.
+ * Flags revert to config defaults.
+ */
+export function resetFlags() {
+  const allParams = getAllParams()
+  for (const paramKey of Object.keys(allParams)) {
+    if (paramKey.startsWith(FLAG_PREFIX)) {
+      removeParam(paramKey)
+    }
+  }
+  const allLocal = getAllLocal()
+  for (const localKey of Object.keys(allLocal)) {
+    if (localKey.startsWith(FLAG_PREFIX)) {
+      removeLocal(localKey)
+    }
+  }
+}
+
+/**
+ * Get all registered flag keys.
+ * @returns {string[]}
+ */
+export function getFlagKeys() {
+  return Object.keys(_defaults)
+}

package/src/index.js

@@ -37,5 +37,8 @@ export { mountSceneDebug } from './sceneDebug.js'
 // Viewfinder utilities
 export { hash, resolveSceneRoute, getSceneMeta } from './viewfinder.js'
 
+// Feature flags
+export { initFeatureFlags, getFlag, setFlag, toggleFlag, getAllFlags, resetFlags, getFlagKeys } from './featureFlags.js'
+
 // Comments system
 export { initCommentsConfig, getCommentsConfig, isCommentsEnabled } from './comments/config.js'