@dfosco/storyboard-react 4.0.0-beta.22 → 4.0.0-beta.24

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "4.0.0-beta.22",
+  "version": "4.0.0-beta.24",
   "type": "module",
   "dependencies": {
-    "@dfosco/storyboard-core": "4.0.0-beta.22",
-    "@dfosco/tiny-canvas": "4.0.0-beta.22",
+    "@dfosco/storyboard-core": "4.0.0-beta.24",
+    "@dfosco/tiny-canvas": "4.0.0-beta.24",
     "@neodrag/react": "^2.3.1",
     "glob": "^11.0.0",
     "jsonc-parser": "^3.3.1",

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -1,6 +1,6 @@
 import { useState, useRef, useEffect, useCallback, useMemo, forwardRef, useImperativeHandle } from 'react'
 import { createPortal } from 'react-dom'
-import { buildPrototypeIndex } from '@dfosco/storyboard-core'
+import { buildPrototypeIndex, getFlag } from '@dfosco/storyboard-core'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import { readProp, prototypeEmbedSchema } from './widgetProps.js'
 import { getEmbedChromeVars } from './embedTheme.js'
@@ -9,6 +9,10 @@ import { useIframeQueue } from './useViewportEntry.js'
 import styles from './PrototypeEmbed.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
+function devLog(...args) {
+  try { if (getFlag('dev-logs')) console.log('[canvas:prototype-embed]', ...args) } catch { /* */ }
+}
+
 function formatName(name) {
   return name
     .replace(/[-_]/g, ' ')
@@ -72,26 +76,40 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
 
   // Sequential iframe queue — prevents stampede when many embeds lack snapshots.
   // Widgets with snapshots skip the queue entirely; others load one at a time.
-  const { ready: queueReady, releaseSlot } = useIframeQueue(hasSnapshot || isExternal)
+  const { ready: queueReady, releaseSlot } = useIframeQueue(hasSnapshot || isExternal, widgetId)
   const [preloadIframe, setPreloadIframe] = useState(hasSnapshot || isExternal)
   const [iframeLoaded, setIframeLoaded] = useState(false)
   const [showIframe, setShowIframe] = useState(hasSnapshot || isExternal)
   const [showSpinner, setShowSpinner] = useState(false)
   const capturingRef = useRef(false)
 
+  devLog(widgetId, { hasSnapshot, isExternal, queueReady, preloadIframe, showIframe, iframeLoaded, src })
+
   // Start loading when the queue grants this widget a slot
   useEffect(() => {
     if (queueReady && !preloadIframe) {
+      devLog(widgetId, 'queue ready → loading iframe')
       setPreloadIframe(true)
       setShowIframe(true)
     }
   }, [queueReady, preloadIframe])
 
-  // Release the queue slot once the iframe has loaded
+  // Release the queue slot once the iframe has loaded or user clicked to interact
   useEffect(() => {
-    if (iframeLoaded) releaseSlot()
+    if (iframeLoaded) {
+      devLog(widgetId, 'iframe loaded')
+      releaseSlot()
+    }
   }, [iframeLoaded, releaseSlot])
 
+  // Click-to-interact: immediately start iframe and release queue slot for others
+  const activateIframe = useCallback(() => {
+    devLog(widgetId, 'user activated → jumping queue')
+    setShowIframe(true)
+    setPreloadIframe(true)
+    releaseSlot()
+  }, [releaseSlot])
+
   // Show spinner only after 500ms of loading
   useEffect(() => {
     if (showIframe && !iframeLoaded && hasSnapshot) {
@@ -553,8 +571,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
                 }}
                 onClick={(e) => {
                   if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
-                  setShowIframe(true)
-                  setPreloadIframe(true)
+                  activateIframe()
                   enterInteractive()
                 }}
                 role="button"
@@ -563,8 +580,7 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
                   if (e.key === 'Enter' || e.key === ' ') {
                     e.preventDefault()
                     e.stopPropagation()
-                    setShowIframe(true)
-                    setPreloadIframe(true)
+                    activateIframe()
                     enterInteractive()
                   }
                 }}

package/src/canvas/widgets/StoryWidget.jsx

@@ -12,7 +12,7 @@
  * Props: { storyId, exportName, width, height }
  */
 import { forwardRef, useImperativeHandle, useRef, useCallback, useState, useEffect, useMemo } from 'react'
-import { getStoryData } from '@dfosco/storyboard-core'
+import { getStoryData, getFlag } from '@dfosco/storyboard-core'
 import { createInspectorHighlighter } from '@dfosco/storyboard-core/inspector/highlighter'
 import WidgetWrapper from './WidgetWrapper.jsx'
 import ResizeHandle from './ResizeHandle.jsx'
@@ -21,6 +21,10 @@ import { useIframeQueue } from './useViewportEntry.js'
 import styles from './StoryWidget.module.css'
 import overlayStyles from './embedOverlay.module.css'
 
+function devLog(...args) {
+  try { if (getFlag('dev-logs')) console.log('[canvas:story-widget]', ...args) } catch { /* */ }
+}
+
 function resolveStoryUrl(storyId, exportName) {
   const story = getStoryData(storyId)
   if (!story?._route) return null
@@ -114,26 +118,40 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   const hasSnapshot = !!currentSnapshot
 
   // Sequential iframe queue — prevents stampede when many embeds lack snapshots.
-  const { ready: queueReady, releaseSlot } = useIframeQueue(hasSnapshot)
+  const { ready: queueReady, releaseSlot } = useIframeQueue(hasSnapshot, widgetId)
   const [preloadIframe, setPreloadIframe] = useState(hasSnapshot)
   const [iframeLoaded, setIframeLoaded] = useState(false)
   const [showIframe, setShowIframe] = useState(hasSnapshot)
   const [showSpinner, setShowSpinner] = useState(false)
   const capturingRef = useRef(false)
 
+  devLog(widgetId, { hasSnapshot, queueReady, preloadIframe, showIframe, iframeLoaded, storyId })
+
   // Start loading when the queue grants this widget a slot
   useEffect(() => {
     if (queueReady && !preloadIframe) {
+      devLog(widgetId, 'queue ready → loading iframe')
       setPreloadIframe(true)
       setShowIframe(true)
     }
   }, [queueReady, preloadIframe])
 
-  // Release the queue slot once the iframe has loaded
+  // Release the queue slot once the iframe has loaded or user clicked to interact
   useEffect(() => {
-    if (iframeLoaded) releaseSlot()
+    if (iframeLoaded) {
+      devLog(widgetId, 'iframe loaded')
+      releaseSlot()
+    }
   }, [iframeLoaded, releaseSlot])
 
+  // Click-to-interact: immediately start iframe and release queue slot for others
+  const activateIframe = useCallback(() => {
+    devLog(widgetId, 'user activated → jumping queue')
+    setShowIframe(true)
+    setPreloadIframe(true)
+    releaseSlot()
+  }, [releaseSlot, widgetId])
+
   // Show spinner only after 500ms of loading
   useEffect(() => {
     if (showIframe && !iframeLoaded && hasSnapshot) {
@@ -452,8 +470,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
                 }}
                 onClick={(e) => {
                   if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
-                  setShowIframe(true)
-                  setPreloadIframe(true)
+                  activateIframe()
                   enterInteractive()
                 }}
                 role="button"
@@ -462,8 +479,7 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
                   if (e.key === 'Enter' || e.key === ' ') {
                     e.preventDefault()
                     e.stopPropagation()
-                    setShowIframe(true)
-                    setPreloadIframe(true)
+                    activateIframe()
                     enterInteractive()
                   }
                 }}

package/src/canvas/widgets/useViewportEntry.js

@@ -1,4 +1,9 @@
 import { useState, useEffect, useCallback, useRef } from 'react'
+import { getFlag } from '@dfosco/storyboard-core'
+
+function devLog(...args) {
+  try { if (getFlag('dev-logs')) console.log('[canvas:iframe-queue]', ...args) } catch { /* flag system not initialized */ }
+}
 
 /**
  * Sequential iframe loading queue.
@@ -19,13 +24,15 @@ let _active = false
 function processQueue() {
   if (_active || _queue.length === 0) return
   _active = true
-  const { resolve } = _queue.shift()
+  const { resolve, label } = _queue.shift()
+  devLog(`slot granted → ${label} (${_queue.length} queued)`)
 
   let released = false
   const release = () => {
     if (released) return
     released = true
     _active = false
+    devLog(`slot released ← ${label}`)
     processQueue()
   }
 
@@ -34,9 +41,10 @@ function processQueue() {
   resolve(release)
 }
 
-function requestSlot() {
+function requestSlot(label = '?') {
   return new Promise((resolve) => {
-    _queue.push({ resolve })
+    _queue.push({ resolve, label })
+    devLog(`queued ${label} (position ${_queue.length})`)
     processQueue()
   })
 }
@@ -49,9 +57,10 @@ function requestSlot() {
  * it's this widget's turn.
  *
  * @param {boolean} hasUsableSnapshot - whether the widget has a working snapshot
- * @returns {{ ready: boolean }}
+ * @param {string} [label] - debug label for dev logs
+ * @returns {{ ready: boolean, releaseSlot: Function }}
  */
-export function useIframeQueue(hasUsableSnapshot) {
+export function useIframeQueue(hasUsableSnapshot, label = '?') {
   const [ready, setReady] = useState(hasUsableSnapshot)
   const releaseRef = useRef(null)
 
@@ -59,7 +68,7 @@ export function useIframeQueue(hasUsableSnapshot) {
     if (hasUsableSnapshot || ready) return
 
     let cancelled = false
-    requestSlot().then((release) => {
+    requestSlot(label).then((release) => {
       if (cancelled) {
         release()
         return