@dfosco/storyboard-react 4.0.0-beta.21 → 4.0.0-beta.23

package/package.json

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

package/src/canvas/CanvasPage.jsx

@@ -344,6 +344,7 @@ export default function CanvasPage({ name, siblingPages = [], canvasMeta = null
   const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasThemeFromStorage())
   const [snapEnabled, setSnapEnabled] = useState(canvas?.snapToGrid ?? false)
   const [snapGridSize, setSnapGridSize] = useState(canvas?.gridSize || 40)
+
   // Refs for snap settings (used by drop handler inside effect closure)
   const snapEnabledRef = useRef(snapEnabled)
   const snapGridSizeRef = useRef(snapGridSize)

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -1,13 +1,18 @@
 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'
 import { uploadImage } from '../canvasApi.js'
+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, ' ')
@@ -68,12 +73,43 @@ export default forwardRef(function PrototypeEmbed({ id: widgetId, props, onUpdat
   const validSnapshotDark = snapshotMatchesWidget(snapshotDark) ? snapshotDark : null
   const currentSnapshot = canvasTheme?.startsWith('dark') ? validSnapshotDark : validSnapshotLight
   const hasSnapshot = !!currentSnapshot
-  const [preloadIframe, setPreloadIframe] = useState(!hasSnapshot || isExternal)
+
+  // 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, widgetId)
+  const [preloadIframe, setPreloadIframe] = useState(hasSnapshot || isExternal)
   const [iframeLoaded, setIframeLoaded] = useState(false)
-  const [showIframe, setShowIframe] = useState(!hasSnapshot || isExternal)
+  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 or user clicked to interact
+  useEffect(() => {
+    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) {
@@ -535,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"
@@ -545,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,14 +12,19 @@
  * 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'
 import { uploadImage } from '../canvasApi.js'
+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
@@ -111,12 +116,42 @@ export default forwardRef(function StoryWidget({ id: widgetId, props, onUpdate,
   const validSnapshotDark = snapshotMatchesWidget(snapshotDark) ? snapshotDark : null
   const currentSnapshot = isDark ? validSnapshotDark : validSnapshotLight
   const hasSnapshot = !!currentSnapshot
-  const [preloadIframe, setPreloadIframe] = useState(!hasSnapshot)
+
+  // Sequential iframe queue — prevents stampede when many embeds lack snapshots.
+  const { ready: queueReady, releaseSlot } = useIframeQueue(hasSnapshot, widgetId)
+  const [preloadIframe, setPreloadIframe] = useState(hasSnapshot)
   const [iframeLoaded, setIframeLoaded] = useState(false)
-  const [showIframe, setShowIframe] = useState(!hasSnapshot)
+  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 or user clicked to interact
+  useEffect(() => {
+    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) {
@@ -435,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"
@@ -445,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

@@ -0,0 +1,93 @@
+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.
+ *
+ * Embed widgets (prototype, story) that lack snapshots call `requestSlot()`
+ * which returns a promise that resolves when it's their turn to load.
+ * Only one iframe loads at a time — the next starts when the previous
+ * calls the returned `release()` function (or on timeout).
+ *
+ * This prevents the "iframe stampede" when many embeds lack snapshots
+ * and would otherwise all try to load simultaneously.
+ */
+const SLOT_TIMEOUT = 15_000
+
+let _queue = []
+let _active = false
+
+function processQueue() {
+  if (_active || _queue.length === 0) return
+  _active = true
+  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()
+  }
+
+  // Safety timeout — if the iframe never signals load, release after 15s
+  setTimeout(release, SLOT_TIMEOUT)
+  resolve(release)
+}
+
+function requestSlot(label = '?') {
+  return new Promise((resolve) => {
+    _queue.push({ resolve, label })
+    devLog(`queued ${label} (position ${_queue.length})`)
+    processQueue()
+  })
+}
+
+/**
+ * Hook for embed widgets that need sequential iframe loading.
+ *
+ * When the widget has a usable snapshot, this is a no-op (returns ready immediately).
+ * When no snapshot exists, it queues the widget and returns `ready: true` when
+ * it's this widget's turn.
+ *
+ * @param {boolean} hasUsableSnapshot - whether the widget has a working snapshot
+ * @param {string} [label] - debug label for dev logs
+ * @returns {{ ready: boolean, releaseSlot: Function }}
+ */
+export function useIframeQueue(hasUsableSnapshot, label = '?') {
+  const [ready, setReady] = useState(hasUsableSnapshot)
+  const releaseRef = useRef(null)
+
+  useEffect(() => {
+    if (hasUsableSnapshot || ready) return
+
+    let cancelled = false
+    requestSlot(label).then((release) => {
+      if (cancelled) {
+        release()
+        return
+      }
+      releaseRef.current = release
+      setReady(true)
+    })
+
+    return () => {
+      cancelled = true
+      releaseRef.current?.()
+    }
+  }, [hasUsableSnapshot]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Release the slot when the component unmounts
+  const releaseSlot = useCallback(() => {
+    releaseRef.current?.()
+    releaseRef.current = null
+  }, [])
+
+  return { ready, releaseSlot }
+}