@dfosco/storyboard-react 4.0.0-beta.9 → 4.0.0

package/src/canvas/widgets/snapshotDisplay.test.jsx

@@ -0,0 +1,259 @@
+/**
+ * Tests for iframe snapshot display — single snapshot prop.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, fireEvent, waitFor, act } from '@testing-library/react'
+import PrototypeEmbed from './PrototypeEmbed.jsx'
+import StoryWidget from './StoryWidget.jsx'
+
+vi.mock('@dfosco/storyboard-core', () => ({
+  buildPrototypeIndex: () => ({
+    folders: [],
+    prototypes: [
+      {
+        name: 'Design Overview',
+        dirName: 'examples',
+        isExternal: false,
+        hideFlows: true,
+        flows: [{ route: '/test', name: 'default', meta: { title: 'Design Overview' } }],
+      },
+    ],
+    globalFlows: [],
+    sorted: { title: { prototypes: [], folders: [] } },
+  }),
+  getStoryData: (storyId) => ({ _route: `/components/${storyId}` }),
+}))
+
+vi.mock('./WidgetWrapper.jsx', () => ({
+  default: ({ children }) => <div data-testid="widget-wrapper">{children}</div>,
+}))
+
+vi.mock('@dfosco/storyboard-core/inspector/highlighter', () => ({
+  createInspectorHighlighter: async () => ({
+    codeToHtml: () => '<pre><code></code></pre>',
+  }),
+}), { virtual: true })
+
+vi.mock('./ResizeHandle.jsx', () => ({
+  default: () => <div data-testid="resize-handle" />,
+}))
+
+/**
+ * Render inside a wrapper with data-sb-canvas-theme, matching the real
+ * CanvasPage DOM structure that subscribeCanvasTheme reads from.
+ */
+function renderInCanvas(ui, theme = 'light') {
+  const wrapper = document.createElement('div')
+  wrapper.setAttribute('data-sb-canvas-theme', theme)
+  document.body.appendChild(wrapper)
+  const result = render(ui, { container: wrapper })
+  return { ...result, wrapper }
+}
+
+afterEach(() => {
+  document.querySelectorAll('[data-sb-canvas-theme]').forEach(el => el.remove())
+})
+
+describe('Snapshot display', () => {
+  describe('PrototypeEmbed', () => {
+    it('shows snapshot image when valid snapshot prop exists', () => {
+      const { wrapper } = renderInCanvas(
+        <PrototypeEmbed
+          id="proto-abc123"
+          props={{
+            src: '/test',
+            width: 400,
+            height: 300,
+            zoom: 100,
+            snapshot: '/_storyboard/canvas/images/snapshot-proto-abc123.webp?v=123',
+          }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      const img = wrapper.querySelector('img')
+      expect(img).toBeInTheDocument()
+      expect(img.src).toContain('snapshot-proto-abc123.webp')
+      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+    })
+
+    it('falls back to snapshotLight for backward compat', () => {
+      const { wrapper } = renderInCanvas(
+        <PrototypeEmbed
+          id="proto-abc123"
+          props={{
+            src: '/test',
+            width: 400,
+            height: 300,
+            zoom: 100,
+            snapshotLight: '/_storyboard/canvas/images/snapshot-proto-abc123--light.webp?v=1',
+          }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      const img = wrapper.querySelector('img')
+      expect(img).toBeInTheDocument()
+      expect(img.src).toContain('snapshot-proto-abc123--light.webp')
+    })
+
+    it('shows placeholder when no snapshot exists', () => {
+      const { wrapper } = renderInCanvas(
+        <PrototypeEmbed
+          id="proto-xyz"
+          props={{ src: '/test', width: 400, height: 300, zoom: 100 }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+    })
+
+    it('falls back to placeholder when snapshot image fails to load', () => {
+      const { wrapper } = renderInCanvas(
+        <PrototypeEmbed
+          id="proto-abc123"
+          props={{
+            src: '/test',
+            width: 400,
+            height: 300,
+            zoom: 100,
+            snapshot: '/_storyboard/canvas/images/snapshot-proto-abc123.webp?v=123',
+          }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      const img = wrapper.querySelector('img')
+      expect(img).toBeInTheDocument()
+      fireEvent.error(img)
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+    })
+
+    it('ignores snapshot that does not match widget ID', () => {
+      const { wrapper } = renderInCanvas(
+        <PrototypeEmbed
+          id="proto-abc123"
+          props={{
+            src: '/test',
+            width: 400,
+            height: 300,
+            zoom: 100,
+            snapshot: '/_storyboard/canvas/images/snapshot-other-widget.webp?v=123',
+          }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+    })
+
+    it('does not show snapshot for external URLs', () => {
+      const { wrapper } = renderInCanvas(
+        <PrototypeEmbed
+          id="proto-ext"
+          props={{
+            src: 'https://example.com',
+            width: 400,
+            height: 300,
+            zoom: 100,
+            snapshot: '/_storyboard/canvas/images/snapshot-proto-ext.webp?v=123',
+          }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('StoryWidget', () => {
+    it('shows snapshot image when valid snapshot prop exists', () => {
+      const { wrapper } = renderInCanvas(
+        <StoryWidget
+          id="story-abc123"
+          props={{
+            storyId: 'button-patterns',
+            exportName: 'Primary',
+            width: 400,
+            height: 300,
+            snapshot: '/_storyboard/canvas/images/snapshot-story-abc123.webp?v=456',
+          }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      const img = wrapper.querySelector('img')
+      expect(img).toBeInTheDocument()
+      expect(img.src).toContain('snapshot-story-abc123.webp')
+      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+    })
+
+    it('falls back to snapshotDark for backward compat', () => {
+      const { wrapper } = renderInCanvas(
+        <StoryWidget
+          id="story-abc123"
+          props={{
+            storyId: 'button-patterns',
+            snapshotDark: '/_storyboard/canvas/images/snapshot-story-abc123--dark.webp?v=1',
+          }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      const img = wrapper.querySelector('img')
+      expect(img).toBeInTheDocument()
+      expect(img.src).toContain('snapshot-story-abc123--dark.webp')
+    })
+
+    it('shows placeholder when no snapshot exists', () => {
+      const { wrapper } = renderInCanvas(
+        <StoryWidget
+          id="story-xyz"
+          props={{
+            storyId: 'button-patterns',
+            exportName: 'Primary',
+            width: 400,
+            height: 300,
+          }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+      expect(wrapper.querySelector('iframe')).not.toBeInTheDocument()
+    })
+
+    it('falls back to placeholder when snapshot image fails to load', () => {
+      const { wrapper } = renderInCanvas(
+        <StoryWidget
+          id="story-abc123"
+          props={{
+            storyId: 'button-patterns',
+            exportName: 'Primary',
+            width: 400,
+            height: 300,
+            snapshot: '/_storyboard/canvas/images/snapshot-story-abc123.webp?v=456',
+          }}
+          onUpdate={vi.fn()}
+          resizable={false}
+        />
+      )
+
+      const img = wrapper.querySelector('img')
+      expect(img).toBeInTheDocument()
+      fireEvent.error(img)
+      expect(wrapper.querySelector('img')).not.toBeInTheDocument()
+    })
+  })
+})

package/src/canvas/widgets/widgetConfig.js

@@ -34,7 +34,16 @@ function resolveFeature(feature) {
     if (key === 'items' && Array.isArray(val)) {
       resolved[key] = val.map((item) => {
         const r = {}
-        for (const [k, v] of Object.entries(item)) r[k] = resolveVar(v)
+        for (const [k, v] of Object.entries(item)) {
+          // Resolve nested alt object inside items
+          if (k === 'alt' && v && typeof v === 'object') {
+            const altResolved = {}
+            for (const [ak, av] of Object.entries(v)) altResolved[ak] = resolveVar(av)
+            r[k] = altResolved
+          } else {
+            r[k] = resolveVar(v)
+          }
+        }
         return r
       })
     } else if (key === 'alt' && val && typeof val === 'object') {
@@ -103,14 +112,16 @@ export const widgetTypes = buildWidgetTypes()
 
 /**
  * Get the feature list for a widget type.
- * In production, only features with `prod: true` are returned.
+ * In production (or when isLocalDev is false, e.g. ?prodMode simulation),
+ * only features with `prod: true` are returned.
  * In dev, all features are returned.
  * @param {string} type — widget type string
+ * @param {{ isLocalDev?: boolean }} [options]
  * @returns {Array} features array from config (variables resolved), or empty array
  */
-export function getFeatures(type) {
+export function getFeatures(type, { isLocalDev = true } = {}) {
   const features = widgetTypes[type]?.features ?? []
-  if (import.meta.env?.PROD) {
+  if (import.meta.env?.PROD || !isLocalDev) {
     return features.filter(f => f.prod)
   }
   return features
@@ -146,6 +157,6 @@ export function getWidgetMeta(type) {
  */
 export function getMenuWidgetTypes() {
   return Object.entries(widgetTypes)
-    .filter(([type]) => type !== 'link-preview' && type !== 'image' && type !== 'figma-embed')
+    .filter(([type]) => type !== 'link-preview' && type !== 'image' && type !== 'figma-embed' && type !== 'codepen-embed' && type !== 'story')
     .map(([type, def]) => ({ type, label: def.label, icon: def.icon }))
 }

package/src/canvas/widgets/widgetConfig.test.js

@@ -2,21 +2,24 @@ import { describe, expect, it } from 'vitest'
 import { isResizable, getFeatures, getWidgetMeta } from './widgetConfig.js'
 
 describe('isResizable', () => {
-  // Vitest runs with import.meta.env.PROD = true, so prod: false widgets
-  // correctly return false. This tests the production behavior.
-  it('returns false for resize-enabled widgets when prod is false (production env)', () => {
-    expect(isResizable('sticky-note')).toBe(false)
-    expect(isResizable('prototype')).toBe(false)
-    expect(isResizable('figma-embed')).toBe(false)
-    expect(isResizable('image')).toBe(false)
-    expect(isResizable('component')).toBe(false)
-  })
-
-  it('returns false for widget types with resize disabled', () => {
-    expect(isResizable('markdown')).toBe(false)
+  // Vitest runs in dev mode by default (import.meta.env.PROD = false)
+  // In dev mode, all resize-enabled widgets are resizable
+  it('returns true for resize-enabled widgets in dev mode', () => {
+    expect(isResizable('sticky-note')).toBe(true)
+    expect(isResizable('prototype')).toBe(true)
+    expect(isResizable('figma-embed')).toBe(true)
+    expect(isResizable('image')).toBe(true)
+    expect(isResizable('component')).toBe(true)
+  })
+
+  it('returns false for link-preview (resize disabled)', () => {
     expect(isResizable('link-preview')).toBe(false)
   })
 
+  it('returns true for markdown (resize enabled, dev only)', () => {
+    expect(isResizable('markdown')).toBe(true)
+  })
+
   it('returns false for unknown widget types', () => {
     expect(isResizable('nonexistent')).toBe(false)
   })
@@ -32,6 +35,25 @@ describe('getFeatures', () => {
   it('returns empty array for unknown widget types', () => {
     expect(getFeatures('nonexistent')).toEqual([])
   })
+
+  it('returns only prod features when isLocalDev is false', () => {
+    const features = getFeatures('figma-embed', { isLocalDev: false })
+    expect(features.length).toBeGreaterThan(0)
+    expect(features.every(f => f.prod === true)).toBe(true)
+  })
+
+  it('returns all features when isLocalDev is true (default)', () => {
+    const allFeatures = getFeatures('figma-embed')
+    const prodFeatures = getFeatures('figma-embed', { isLocalDev: false })
+    expect(allFeatures.length).toBeGreaterThan(prodFeatures.length)
+  })
+
+  it('includes menu-only prod features when isLocalDev is false', () => {
+    const features = getFeatures('figma-embed', { isLocalDev: false })
+    const menuFeature = features.find(f => f.menu)
+    expect(menuFeature).toBeDefined()
+    expect(menuFeature.prod).toBe(true)
+  })
 })
 
 describe('getWidgetMeta', () => {

package/src/context.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, Suspense, lazy } from 'react'
 import { useParams, useLocation } from 'react-router-dom'
-// Named import seeds the core data index via init() AND provides canvas route data
-import { canvases } from 'virtual:storyboard-data-index'
+// Named import seeds the core data index via init() AND provides canvas/story route data
+import { canvases, canvasAliases, stories } from 'virtual:storyboard-data-index'
 import { loadFlow, flowExists, findRecord, deepMerge, setFlowClass, installBodyClassSync, resolveFlowName, resolveRecordName, isModesEnabled } from '@dfosco/storyboard-core'
 import { StoryboardContext } from './StoryboardContext.js'
 import styles from './FlowError.module.css'
@@ -9,24 +9,77 @@ import styles from './FlowError.module.css'
 export { StoryboardContext }
 
 const CanvasPageLazy = lazy(() => import('./canvas/CanvasPage.jsx'))
+const StoryPageLazy = lazy(() => import('./story/StoryPage.jsx'))
 
 // Build a map from canvas route paths → canvas names at module load time
 const canvasRouteMap = new Map()
+// Build a map from group name → array of { name, route, title } for page selector
+const canvasGroupMap = new Map()
 for (const [name, data] of Object.entries(canvases || {})) {
-  const route = (data?._route || `/${name}`).replace(/\/+$/, '')
+  const route = (data?._route || `/canvas/${name}`).replace(/\/+$/, '')
   canvasRouteMap.set(route, name)
+  const group = data?._group
+  if (group) {
+    if (!canvasGroupMap.has(group)) canvasGroupMap.set(group, [])
+    canvasGroupMap.get(group).push({
+      name,
+      route,
+      title: data?.title || name.split('/').pop(),
+      _canvasMeta: data?._canvasMeta || null,
+    })
+  }
+}
+
+// Build a map from story route paths → story names at module load time
+const storyRouteMap = new Map()
+for (const [name, data] of Object.entries(stories || {})) {
+  if (data?._route) {
+    const route = data._route.replace(/\/+$/, '')
+    storyRouteMap.set(route, name)
+  }
 }
 
 function matchCanvasRoute(pathname) {
-  const normalized = pathname.replace(/\/+$/, '') || '/'
+  const normalized = stripBasePath(pathname)
   return canvasRouteMap.get(normalized) || null
 }
 
+function matchStoryRoute(pathname) {
+  const normalized = stripBasePath(pathname)
+  return storyRouteMap.get(normalized) || null
+}
+
+/**
+ * Strip the app's sub-path prefix (e.g. /storyboard) from the pathname.
+ * React Router's basename strips the branch prefix but not the app name prefix
+ * when the app runs under a nested base path.
+ */
+function stripBasePath(pathname) {
+  let p = pathname.replace(/\/+$/, '') || '/'
+  // BASE_URL includes branch prefix + app path (e.g. /branch--name/storyboard/)
+  // React Router strips the branch prefix but may leave the app sub-path
+  const base = (import.meta.env?.BASE_URL || '/').replace(/\/+$/, '')
+  if (base && base !== '/') {
+    // Extract just the last segment(s) after the branch prefix
+    const withoutBranch = base.replace(/^\/branch--[^/]+/, '')
+    const subPath = withoutBranch.replace(/\/+$/, '')
+    if (subPath && p.startsWith(subPath)) {
+      p = p.slice(subPath.length) || '/'
+    }
+  }
+  return p
+}
+
 function isCanvasPath(pathname) {
-  const normalized = pathname.replace(/\/+$/, '') || '/'
+  const normalized = stripBasePath(pathname)
   return normalized === '/canvas' || normalized.startsWith('/canvas/')
 }
 
+function isStoryPath(pathname) {
+  const normalized = stripBasePath(pathname)
+  return normalized === '/components' || normalized.startsWith('/components/')
+}
+
 /**
  * Derives the top-level prototype name from a pathname.
  * "/Dashboard" → "Dashboard", "/Dashboard/sub" → "Dashboard"
@@ -66,10 +119,17 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
   const params = useParams()
 
   // Canvas route detection — matches current URL against registered canvas routes
-  const canvasName = useMemo(() => matchCanvasRoute(location.pathname), [location.pathname])
+  const canvasId = useMemo(() => matchCanvasRoute(location.pathname), [location.pathname])
   const isMissingCanvasRoute = useMemo(
-    () => isCanvasPath(location.pathname) && !canvasName,
-    [location.pathname, canvasName],
+    () => isCanvasPath(location.pathname) && !canvasId && !matchStoryRoute(location.pathname),
+    [location.pathname, canvasId],
+  )
+
+  // Story route detection — matches current URL against registered story routes
+  const storyName = useMemo(() => matchStoryRoute(location.pathname), [location.pathname])
+  const isMissingStoryRoute = useMemo(
+    () => isStoryPath(location.pathname) && !storyName,
+    [location.pathname, storyName],
   )
 
   const searchParams = new URLSearchParams(location.search)
@@ -77,9 +137,9 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
   const prototypeName = getPrototypeName(location.pathname)
   const pageFlow = getPageFlowName(location.pathname)
 
-  // Resolve flow name with prototype scoping (skip for canvas pages)
+  // Resolve flow name with prototype scoping (skip for canvas/story pages)
   const activeFlowName = useMemo(() => {
-    if (canvasName || isMissingCanvasRoute) return null
+    if (canvasId || isMissingCanvasRoute || storyName || isMissingStoryRoute) return null
     const requested = sceneParam || flowName || sceneName
     if (requested) {
       // Allow fully-scoped flow names from URLs/widgets without re-prefixing
@@ -103,11 +163,32 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     // 4. Global default — or null if no flow exists at all
     if (flowExists('default')) return 'default'
     return null
-  }, [canvasName, isMissingCanvasRoute, sceneParam, flowName, sceneName, prototypeName, pageFlow])
+  }, [canvasId, isMissingCanvasRoute, storyName, isMissingStoryRoute, sceneParam, flowName, sceneName, prototypeName, pageFlow])
 
   // Auto-install body class sync (sb-key--value classes on <body>)
   useEffect(() => installBodyClassSync(), [])
 
+  // Update document.title to reflect the current artifact
+  useEffect(() => {
+    const base = import.meta.env?.BASE_URL || '/'
+    const branchMatch = base.match(/\/branch--([^/]+)/)
+    const branchSuffix = branchMatch ? ` (${branchMatch[1]})` : ''
+
+    let title
+    if (canvasId) {
+      const canvasData = canvases?.[canvasId]
+      const meta = canvasData?._canvasMeta
+      const pageTitle = canvasData?.title || canvasId.split('/').pop()
+      title = (meta?.title || pageTitle) + ' · Storyboard'
+    } else if (prototypeName) {
+      title = prototypeName + ' · Storyboard'
+    } else {
+      title = 'Storyboard'
+    }
+
+    document.title = title + branchSuffix
+  }, [canvasId, prototypeName])
+
   // Mount design modes UI when enabled in storyboard.config.json
   useEffect(() => {
     if (!isModesEnabled()) return
@@ -124,9 +205,9 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     return () => cleanup?.()
   }, [])
 
-  // Skip flow loading for canvas pages and flow-less pages
+  // Skip flow loading for canvas/story pages and flow-less pages
   const { data, error } = useMemo(() => {
-    if (canvasName || isMissingCanvasRoute) return { data: null, error: null }
+    if (canvasId || isMissingCanvasRoute || storyName || isMissingStoryRoute) return { data: null, error: null }
     if (!activeFlowName) return { data: {}, error: null }
     try {
       let flowData = loadFlow(activeFlowName)
@@ -145,10 +226,18 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     } catch (err) {
       return { data: null, error: err.message }
     }
-  }, [canvasName, isMissingCanvasRoute, activeFlowName, recordName, recordParam, params, prototypeName])
+  }, [canvasId, isMissingCanvasRoute, storyName, isMissingStoryRoute, activeFlowName, recordName, recordParam, params, prototypeName])
 
   // Canvas pages get their own rendering path — no flow data needed
-  if (canvasName) {
+  if (canvasId) {
+    const canvasData = canvases?.[canvasId]
+    const group = canvasData?._group
+    // Include the current canvas as a sibling even if it's the only page in its group,
+    // so the PageSelector can render and allow adding new pages.
+    const siblingPages = group
+      ? canvasGroupMap.get(group) || []
+      : [{ name: canvasId, route: canvasData?._route || `/canvas/${canvasId}`, title: canvasData?.title || canvasId.split('/').pop() }]
+    const canvasMeta = canvasData?._canvasMeta || null
     const canvasValue = {
       data: null,
       error: null,
@@ -160,7 +249,26 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     return (
       <StoryboardContext.Provider value={canvasValue}>
         <Suspense fallback={null}>
-          <CanvasPageLazy name={canvasName} />
+          <CanvasPageLazy canvasId={canvasId} siblingPages={siblingPages} canvasMeta={canvasMeta} />
+        </Suspense>
+      </StoryboardContext.Provider>
+    )
+  }
+
+  // Story pages get their own rendering path — no flow data needed
+  if (storyName) {
+    const storyValue = {
+      data: null,
+      error: null,
+      loading: false,
+      flowName: null,
+      sceneName: null,
+      prototypeName: null,
+    }
+    return (
+      <StoryboardContext.Provider value={storyValue}>
+        <Suspense fallback={null}>
+          <StoryPageLazy name={storyName} />
         </Suspense>
       </StoryboardContext.Provider>
     )
@@ -187,6 +295,27 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     )
   }
 
+  if (isMissingStoryRoute) {
+    const currentUrl = `${location.pathname}${location.search}`
+    const truncatedUrl = currentUrl.length > 60
+      ? currentUrl.slice(0, 60) + '…'
+      : currentUrl
+
+    return (
+      <main className={styles.container}>
+        <div className={styles.banner}>
+          <strong>Story not found</strong>
+          No story matches this route.
+        </div>
+        <p className={styles.meta}>
+          Tried to open{' '}
+          <a href={currentUrl} title={currentUrl}>{truncatedUrl}</a>
+        </p>
+        <a className={styles.homeLink} href="/">← Go to index page</a>
+      </main>
+    )
+  }
+
   const value = {
     data,
     error,

package/src/hooks/useSceneData.js

@@ -17,10 +17,12 @@ import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
  *
  * @param {string} [path] - Dot-notation path (e.g. 'user.profile.name').
  *                          Omit to get the entire flow object.
+ * @param {{ optional?: boolean }} [opts] - Pass { optional: true } to suppress
+ *                          the "path not found" warning for optional data.
  * @returns {*} The resolved value. Returns {} if path is missing after loading.
  * @throws If used outside a StoryboardProvider.
  */
-export function useFlowData(path) {
+export function useFlowData(path, opts) {
   const context = useContext(StoryboardContext)
 
   if (context === null) {
@@ -73,7 +75,7 @@ export function useFlowData(path) {
     }
 
     if (sceneValue === undefined) {
-      if (data != null && Object.keys(data).length > 0) {
+      if (!opts?.optional && data != null && Object.keys(data).length > 0) {
         console.warn(`[useFlowData] Path "${path}" not found in flow data.`)
       }
       return {}