@dfosco/storyboard-core 1.17.2 → 1.18.0

package/package.json

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

package/src/comments/commentCache.js

@@ -53,3 +53,57 @@ export function clearCachedComments(route) {
     // ignore
   }
 }
+
+// --- Pending (failed) comments ---
+
+const PENDING_PREFIX = 'sb-pending-comments:'
+
+/**
+ * Save a pending comment that failed to submit.
+ * @param {string} route
+ * @param {{ id: string, x: number, y: number, text: string, author: object }} comment
+ */
+export function savePendingComment(route, comment) {
+  try {
+    const pending = getPendingComments(route)
+    // Replace if same id already exists, else append
+    const idx = pending.findIndex(c => c.id === comment.id)
+    if (idx >= 0) pending[idx] = comment
+    else pending.push(comment)
+    localStorage.setItem(PENDING_PREFIX + route, JSON.stringify(pending))
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Get all pending (failed) comments for a route.
+ * @param {string} route
+ * @returns {Array<{ id: string, x: number, y: number, text: string, author: object }>}
+ */
+export function getPendingComments(route) {
+  try {
+    const raw = localStorage.getItem(PENDING_PREFIX + route)
+    return raw ? JSON.parse(raw) : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Remove a pending comment (after successful retry or dismissal).
+ * @param {string} route
+ * @param {string} pendingId
+ */
+export function removePendingComment(route, pendingId) {
+  try {
+    const pending = getPendingComments(route).filter(c => c.id !== pendingId)
+    if (pending.length > 0) {
+      localStorage.setItem(PENDING_PREFIX + route, JSON.stringify(pending))
+    } else {
+      localStorage.removeItem(PENDING_PREFIX + route)
+    }
+  } catch {
+    // ignore
+  }
+}

package/src/comments/index.js

@@ -33,7 +33,7 @@ export {
 } from './api.js'
 
 // Cache
-export { getCachedComments, setCachedComments, clearCachedComments } from './commentCache.js'
+export { getCachedComments, setCachedComments, clearCachedComments, savePendingComment, getPendingComments, removePendingComment } from './commentCache.js'
 
 // GraphQL client (for advanced use)
 export { graphql } from './graphql.js'

package/src/comments/ui/authModal.js

@@ -34,7 +34,7 @@ export function openAuthModal() {
         </div>
         <div class="pa4">
           <p class="ma0 mb3 lh-copy sb-fg-muted sb-f-sm">
-            Create a <a class="sb-fg-accent no-underline" href="https://github.com/settings/tokens/new?scopes=repo&description=Storyboard+Comments" target="_blank" rel="noopener">GitHub Personal Access Token</a> with access to <b>github/storyboard</b> repository and <b>Discussions</b> read/write scope. Then enter the token below to sign in and enable commenting features.
+            Create a <a class="sb-fg-accent no-underline" href="https://github.com/settings/personal-access-tokens/new" target="_blank" rel="noopener">GitHub Fine-Grained Personal Access Token</a> with access to <b>github/storyboard</b> repository and <b>Discussions</b> read/write scope. Then enter the token below to sign in and enable commenting features.
           </p>
           <label class="db mb1 fw5 sb-fg sb-f-sm" for="sb-auth-token-input">Personal Access Token</label>
           <input class="sb-input w-100 ph3 pv2 br2 f6 code db" id="sb-auth-token-input" type="password"

package/src/comments/ui/comments.css

@@ -139,7 +139,18 @@
 .sb-comment-window * { scrollbar-width: none; }
 .sb-comment-window *::-webkit-scrollbar { display: none; }
 .sb-composer        { width: 280px; z-index: 100001; }
-.sb-comment-overlay { z-index: 99998; pointer-events: none; }
+.sb-comment-overlay {
+  position: absolute;
+  top: 0; left: 0; right: 0; bottom: 0;
+  z-index: 99998;
+  pointer-events: none;
+}
+.sb-comment-mode {
+  position: relative;
+}
+.sb-comment-mode .sb-comment-overlay {
+  pointer-events: auto;
+}
 .sb-auth-backdrop   { z-index: 100000; background: rgba(0,0,0,0.5); backdrop-filter: blur(4px); }
 .sb-comments-drawer-backdrop { z-index: 99997; background: rgba(0,0,0,0.4); }
 .sb-comments-drawer { z-index: 99998; width: 420px; max-width: 90vw; }
@@ -187,6 +198,25 @@
   border-color: var(--sb-fg-muted);
   opacity: 0.5;
 }
+.sb-comment-pin-pending {
+  border-color: var(--sb-fg-muted) !important;
+  opacity: 0.6;
+  animation: sb-pin-pulse 1.2s ease-in-out infinite;
+}
+.sb-comment-pin-failed {
+  border-color: var(--sb-fg-danger) !important;
+  cursor: pointer;
+  animation: sb-pin-shake 0.4s ease-in-out;
+}
+@keyframes sb-pin-pulse {
+  0%, 100% { opacity: 0.6; }
+  50% { opacity: 1; }
+}
+@keyframes sb-pin-shake {
+  0%, 100% { transform: translateX(0); }
+  25% { transform: translateX(-3px); }
+  75% { transform: translateX(3px); }
+}
 
 /* Error alert */
 .sb-error-alert {

package/src/comments/ui/composer.js

@@ -5,7 +5,6 @@
  * Styled with Tachyons + sb-* custom classes for light/dark mode support.
  */
 
-import { createComment } from '../api.js'
 import { getCachedUser } from '../auth.js'
 
 /**
@@ -16,7 +15,7 @@ import { getCachedUser } from '../auth.js'
  * @param {string} route - Current route path
  * @param {object} [callbacks] - Optional callbacks
  * @param {() => void} [callbacks.onCancel] - Called when composer is dismissed
- * @param {(comment: object) => void} [callbacks.onSubmit] - Called after successful submit
+ * @param {(text: string) => void} [callbacks.onSubmitOptimistic] - Called with text for optimistic submission
  * @returns {{ el: HTMLElement, destroy: () => void }}
  */
 export function showComposer(container, xPct, yPct, route, callbacks = {}) {
@@ -47,8 +46,8 @@ export function showComposer(container, xPct, yPct, route, callbacks = {}) {
       </template>
       <div class="flex items-center justify-end pa3">
         <button class="sb-btn-cancel ph3 pv2 br2 f7 fw5 pointer mr1" @click="cancel()">Cancel</button>
-        <button class="sb-btn-success ph3 pv2 br2 f7 fw5 pointer bn" :disabled="submitting"
-                @click="submit()" x-text="submitting ? 'Posting…' : 'Comment'">Comment</button>
+        <button class="sb-btn-success ph3 pv2 br2 f7 fw5 pointer bn"
+                @click="submit()">Comment</button>
       </div>
     </div>
   `
@@ -81,22 +80,13 @@ export function showComposer(container, xPct, yPct, route, callbacks = {}) {
       submitting: false,
       error: null,
 
-      async submit() {
+      submit() {
         const val = this.text.trim()
         if (!val) return
 
-        this.submitting = true
-        this.error = null
-
-        try {
-          const comment = await createComment(route, xPct, yPct, val)
-          destroy()
-          callbacks.onSubmit?.(comment)
-        } catch (err) {
-          this.error = err.message
-          this.submitting = false
-          console.error('[storyboard] Failed to post comment:', err)
-        }
+        // Close composer immediately and hand off to optimistic handler
+        destroy()
+        callbacks.onSubmitOptimistic?.(val)
       },
 
       cancel() {

package/src/comments/ui/mount.js

@@ -7,10 +7,10 @@
 
 import Alpine from 'alpinejs'
 import { isCommentsEnabled } from '../config.js'
-import { isAuthenticated } from '../auth.js'
+import { isAuthenticated, getCachedUser } from '../auth.js'
 import { toggleCommentMode, setCommentMode, isCommentModeActive, subscribeToCommentMode } from '../commentMode.js'
-import { fetchRouteCommentsSummary, fetchCommentDetail, moveComment } from '../api.js'
-import { getCachedComments, setCachedComments, clearCachedComments } from '../commentCache.js'
+import { fetchRouteCommentsSummary, fetchCommentDetail, moveComment, createComment } from '../api.js'
+import { getCachedComments, setCachedComments, clearCachedComments, savePendingComment, getPendingComments, removePendingComment } from '../commentCache.js'
 import { showComposer } from './composer.js'
 import { openAuthModal } from './authModal.js'
 import { showCommentWindow, closeCommentWindow } from './commentWindow.js'
@@ -27,17 +27,19 @@ function esc(str) {
   return d.innerHTML
 }
 
-function getContentContainer() {
-  return document.body
-}
-
 function ensureOverlay() {
   if (overlay) return overlay
-  const container = getContentContainer()
 
   overlay = document.createElement('div')
-  overlay.className = 'sb-comment-overlay absolute top-0 right-0 bottom-0 left-0 pe-none'
-  container.appendChild(overlay)
+  overlay.className = 'sb-comment-overlay'
+  document.body.appendChild(overlay)
+
+  // Click handler for placing comments lives on the overlay itself
+  overlay.addEventListener('click', (e) => {
+    if (!isCommentModeActive()) return
+    if (e.target.closest('.sb-composer') || e.target.closest('.sb-comment-pin') || e.target.closest('.sb-comment-window')) return
+    handleOverlayClick(e)
+  })
 
   return overlay
 }
@@ -74,6 +76,99 @@ function reloadComments() {
   loadAndRenderComments()
 }
 
+/**
+ * Render an optimistic pin immediately after the user submits a comment.
+ * Returns callbacks to mark it as succeeded or failed.
+ */
+function renderOptimisticPin(ov, xPct, yPct, text, user) {
+  const pendingId = `pending-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  const pin = document.createElement('div')
+  pin.className = 'sb-comment-pin sb-comment-pin-pending absolute br-100 sb-bg pointer sb-shadow pe-auto overflow-hidden'
+  pin.style.left = `${xPct}%`
+  pin.style.top = `${yPct}%`
+  pin.title = `${user?.login ?? 'you'}: ${text.slice(0, 80)}`
+
+  pin.innerHTML = user?.avatarUrl
+    ? `<img class="br-100 db sb-pin-img" src="${esc(user.avatarUrl)}" alt="${esc(user.login)}" draggable="false" />`
+    : ''
+
+  ov.appendChild(pin)
+  renderedPins.push(pin)
+
+  return {
+    pendingId,
+    succeed: () => {
+      pin.classList.remove('sb-comment-pin-pending')
+    },
+    fail: () => {
+      pin.classList.remove('sb-comment-pin-pending')
+      pin.classList.add('sb-comment-pin-failed')
+      pin.title = `⚠ Failed to post — click to retry: ${text.slice(0, 60)}`
+
+      // Save to localStorage for persistence
+      const route = getCurrentRoute()
+      savePendingComment(route, { id: pendingId, x: xPct, y: yPct, text, author: user })
+
+      // Click to retry
+      pin.addEventListener('click', async (e) => {
+        e.stopPropagation()
+        pin.classList.remove('sb-comment-pin-failed')
+        pin.classList.add('sb-comment-pin-pending')
+        pin.title = 'Retrying…'
+        try {
+          await createComment(route, xPct, yPct, text)
+          removePendingComment(route, pendingId)
+          pin.classList.remove('sb-comment-pin-pending')
+          reloadComments()
+        } catch {
+          pin.classList.remove('sb-comment-pin-pending')
+          pin.classList.add('sb-comment-pin-failed')
+          pin.title = `⚠ Failed to post — click to retry: ${text.slice(0, 60)}`
+        }
+      })
+    },
+  }
+}
+
+/**
+ * Render pins for pending (failed) comments from localStorage.
+ */
+function renderPendingPins(ov) {
+  const route = getCurrentRoute()
+  const pending = getPendingComments(route)
+  for (const p of pending) {
+    const pin = document.createElement('div')
+    pin.className = 'sb-comment-pin sb-comment-pin-failed absolute br-100 sb-bg pointer sb-shadow pe-auto overflow-hidden'
+    pin.style.left = `${p.x}%`
+    pin.style.top = `${p.y}%`
+    pin.title = `⚠ Failed to post — click to retry: ${p.text?.slice(0, 60) ?? ''}`
+
+    pin.innerHTML = p.author?.avatarUrl
+      ? `<img class="br-100 db sb-pin-img" src="${esc(p.author.avatarUrl)}" alt="${esc(p.author.login)}" draggable="false" />`
+      : ''
+
+    pin.addEventListener('click', async (e) => {
+      e.stopPropagation()
+      pin.classList.remove('sb-comment-pin-failed')
+      pin.classList.add('sb-comment-pin-pending')
+      pin.title = 'Retrying…'
+      try {
+        await createComment(route, p.x, p.y, p.text)
+        removePendingComment(route, p.id)
+        pin.remove()
+        reloadComments()
+      } catch {
+        pin.classList.remove('sb-comment-pin-pending')
+        pin.classList.add('sb-comment-pin-failed')
+        pin.title = `⚠ Failed to post — click to retry: ${p.text?.slice(0, 60) ?? ''}`
+      }
+    })
+
+    ov.appendChild(pin)
+    renderedPins.push(pin)
+  }
+}
+
 function renderPin(ov, comment, index) {
   const hue = Math.round((index * 137.5) % 360)
   const pin = document.createElement('div')
@@ -97,21 +192,19 @@ function renderPin(ov, comment, index) {
   pin.addEventListener('mousedown', (e) => {
     if (e.button !== 0) return
     dragged = false
-    const container = getContentContainer()
-    const containerRect = container.getBoundingClientRect()
     const startX = e.clientX
     const startY = e.clientY
-    const startLeft = (parseFloat(pin.style.left) / 100) * containerRect.width
-    const startTop = (parseFloat(pin.style.top) / 100) * containerRect.height
+    const startLeftPct = parseFloat(pin.style.left)
+    const startTopPct = parseFloat(pin.style.top)
 
     const onMove = (ev) => {
       const dx = ev.clientX - startX
       const dy = ev.clientY - startY
       if (!dragged && Math.abs(dx) < 4 && Math.abs(dy) < 4) return
       dragged = true
-      const cr = container.getBoundingClientRect()
-      const xPct = Math.round(((startLeft + dx) / cr.width) * 1000) / 10
-      const yPct = Math.round(((startTop + dy) / cr.height) * 1000) / 10
+      const xPct = Math.round((startLeftPct + (dx / window.innerWidth) * 100) * 10) / 10
+      const docHeight = document.documentElement.scrollHeight
+      const yPct = Math.round((startTopPct + (dy / docHeight) * 100) * 10) / 10
       pin.style.left = `${xPct}%`
       pin.style.top = `${yPct}%`
     }
@@ -121,11 +214,11 @@ function renderPin(ov, comment, index) {
       document.removeEventListener('mouseup', onUp)
       if (!dragged) return
 
-      const cr = container.getBoundingClientRect()
       const dx = ev.clientX - startX
       const dy = ev.clientY - startY
-      const xPct = Math.round(((startLeft + dx) / cr.width) * 1000) / 10
-      const yPct = Math.round(((startTop + dy) / cr.height) * 1000) / 10
+      const xPct = Math.round((startLeftPct + (dx / window.innerWidth) * 100) * 10) / 10
+      const docHeight = document.documentElement.scrollHeight
+      const yPct = Math.round((startTopPct + (dy / docHeight) * 100) * 10) / 10
       comment.meta = { ...comment.meta, x: xPct, y: yPct }
 
       try {
@@ -183,6 +276,7 @@ function renderCachedPins() {
       renderPin(ov, comment, i)
     }
   })
+  renderPendingPins(ov)
 }
 
 async function loadAndRenderComments() {
@@ -206,13 +300,17 @@ async function loadAndRenderComments() {
       setCachedComments(route, discussion)
     }
     clearPins()
-    if (!discussion?.comments?.length) return
+    if (!discussion?.comments?.length) {
+      renderPendingPins(ov)
+      return
+    }
 
     discussion.comments.forEach((comment, i) => {
       if (comment.meta?.x != null && comment.meta?.y != null) {
         renderPin(ov, comment, i)
       }
     })
+    renderPendingPins(ov)
 
     autoOpenCommentFromUrl(ov, discussion)
   } catch (err) {
@@ -228,9 +326,9 @@ async function autoOpenCommentFromUrl(ov, discussion) {
   if (!comment) return
 
   if (comment.meta?.y != null) {
-    const container = getContentContainer()
-    const yPx = (comment.meta.y / 100) * container.scrollHeight
-    const viewTop = container.scrollTop || window.scrollY
+    const docHeight = document.documentElement.scrollHeight
+    const yPx = (comment.meta.y / 100) * docHeight
+    const viewTop = window.scrollY
     const viewBottom = viewTop + window.innerHeight
     if (yPx < viewTop || yPx > viewBottom) {
       const scrollTarget = Math.max(0, yPx - window.innerHeight / 3)
@@ -272,17 +370,29 @@ function handleOverlayClick(e) {
     activeComposer = null
   }
 
-  const container = getContentContainer()
-  const rect = container.getBoundingClientRect()
-  const xPct = Math.round(((e.clientX - rect.left) / rect.width) * 1000) / 10
-  const yPct = Math.round(((e.clientY - rect.top + container.scrollTop) / container.scrollHeight) * 1000) / 10
+  // x as percentage of viewport width, y as percentage of full document height
+  const xPct = Math.round((e.clientX / window.innerWidth) * 1000) / 10
+  const docHeight = document.documentElement.scrollHeight
+  const yPct = Math.round(((e.clientY + window.scrollY) / docHeight) * 1000) / 10
 
   const ov = ensureOverlay()
-  activeComposer = showComposer(ov, xPct, yPct, getCurrentRoute(), {
+  const route = getCurrentRoute()
+  activeComposer = showComposer(ov, xPct, yPct, route, {
     onCancel: () => { activeComposer = null },
-    onSubmit: () => {
+    onSubmitOptimistic: (text) => {
       activeComposer = null
-      reloadComments()
+      const user = getCachedUser()
+      const opt = renderOptimisticPin(ov, xPct, yPct, text, user)
+      // Fire API call in background
+      createComment(route, xPct, yPct, text)
+        .then(() => {
+          opt.succeed()
+          reloadComments()
+        })
+        .catch((err) => {
+          console.error('[storyboard] Failed to post comment:', err)
+          opt.fail()
+        })
     },
   })
 }
@@ -327,17 +437,6 @@ export function mountComments() {
 
   subscribeToCommentMode(setBodyCommentMode)
 
-  // Click handler for placing comments — uses document so devtools/modals can be excluded
-  document.addEventListener('click', (e) => {
-    if (!isCommentModeActive()) return
-    // Let devtools, modals, drawers, and existing comment UI handle their own clicks
-    if (e.target.closest('.sb-devtools-wrapper') || e.target.closest('.sb-auth-backdrop') ||
-        e.target.closest('.sb-comments-drawer') || e.target.closest('.sb-comments-drawer-backdrop') ||
-        e.target.closest('.sb-composer') || e.target.closest('.sb-comment-pin') ||
-        e.target.closest('.sb-comment-window')) return
-    handleOverlayClick(e)
-  })
-
   window.addEventListener('keydown', (e) => {
     const tag = e.target.tagName
     if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || e.target.isContentEditable) {

package/src/comments/ui/mount.test.js

@@ -21,12 +21,16 @@ vi.mock('../api.js', () => ({
   fetchRouteCommentsSummary: vi.fn(),
   fetchCommentDetail: vi.fn(),
   moveComment: vi.fn(),
+  createComment: vi.fn(),
 }))
 
 vi.mock('../commentCache.js', () => ({
   getCachedComments: vi.fn(() => null),
   setCachedComments: vi.fn(),
   clearCachedComments: vi.fn(),
+  savePendingComment: vi.fn(),
+  getPendingComments: vi.fn(() => []),
+  removePendingComment: vi.fn(),
 }))
 
 vi.mock('./composer.js', () => ({
@@ -74,11 +78,15 @@ describe('mount.js', () => {
       fetchRouteCommentsSummary: vi.fn(),
       fetchCommentDetail: vi.fn(),
       moveComment: vi.fn(),
+      createComment: vi.fn(),
     }))
     vi.doMock('../commentCache.js', () => ({
       getCachedComments: vi.fn(() => null),
       setCachedComments: vi.fn(),
       clearCachedComments: vi.fn(),
+      savePendingComment: vi.fn(),
+      getPendingComments: vi.fn(() => []),
+      removePendingComment: vi.fn(),
     }))
     vi.doMock('./composer.js', () => ({ showComposer: vi.fn() }))
     vi.doMock('./authModal.js', () => ({ openAuthModal: vi.fn() }))

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'