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

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "4.0.0-beta.21",
+  "version": "4.0.0-beta.22",
   "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.22",
+    "@dfosco/tiny-canvas": "4.0.0-beta.22",
     "@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

@@ -5,6 +5,7 @@ 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'
 
@@ -68,12 +69,29 @@ 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)
+  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)
 
+  // Start loading when the queue grants this widget a slot
+  useEffect(() => {
+    if (queueReady && !preloadIframe) {
+      setPreloadIframe(true)
+      setShowIframe(true)
+    }
+  }, [queueReady, preloadIframe])
+
+  // Release the queue slot once the iframe has loaded
+  useEffect(() => {
+    if (iframeLoaded) releaseSlot()
+  }, [iframeLoaded, releaseSlot])
+
   // Show spinner only after 500ms of loading
   useEffect(() => {
     if (showIframe && !iframeLoaded && hasSnapshot) {

package/src/canvas/widgets/StoryWidget.jsx

@@ -17,6 +17,7 @@ import { createInspectorHighlighter } from '@dfosco/storyboard-core/inspector/hi
 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'
 
@@ -111,12 +112,28 @@ 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)
+  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)
 
+  // Start loading when the queue grants this widget a slot
+  useEffect(() => {
+    if (queueReady && !preloadIframe) {
+      setPreloadIframe(true)
+      setShowIframe(true)
+    }
+  }, [queueReady, preloadIframe])
+
+  // Release the queue slot once the iframe has loaded
+  useEffect(() => {
+    if (iframeLoaded) releaseSlot()
+  }, [iframeLoaded, releaseSlot])
+
   // Show spinner only after 500ms of loading
   useEffect(() => {
     if (showIframe && !iframeLoaded && hasSnapshot) {

package/src/canvas/widgets/useViewportEntry.js

@@ -0,0 +1,84 @@
+import { useState, useEffect, useCallback, useRef } from 'react'
+
+/**
+ * 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 } = _queue.shift()
+
+  let released = false
+  const release = () => {
+    if (released) return
+    released = true
+    _active = false
+    processQueue()
+  }
+
+  // Safety timeout — if the iframe never signals load, release after 15s
+  setTimeout(release, SLOT_TIMEOUT)
+  resolve(release)
+}
+
+function requestSlot() {
+  return new Promise((resolve) => {
+    _queue.push({ resolve })
+    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
+ * @returns {{ ready: boolean }}
+ */
+export function useIframeQueue(hasUsableSnapshot) {
+  const [ready, setReady] = useState(hasUsableSnapshot)
+  const releaseRef = useRef(null)
+
+  useEffect(() => {
+    if (hasUsableSnapshot || ready) return
+
+    let cancelled = false
+    requestSlot().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 }
+}