@dfosco/storyboard-react 2.1.0 → 2.3.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "type": "module",
   "dependencies": {
-    "@dfosco/storyboard-core": "2.1.0",
+    "@dfosco/storyboard-core": "2.3.0",
     "glob": "^11.0.0",
     "jsonc-parser": "^3.3.1"
   },

package/src/Viewfinder.jsx

@@ -15,12 +15,14 @@ import { useRef, useEffect } from 'react'
  * @param {string} [props.title] - Header title
  * @param {string} [props.subtitle] - Optional subtitle
  * @param {boolean} [props.showThumbnails] - Show thumbnail previews
- * @param {boolean} [props.hideDefaultScene] - Hide the "default" flow
+ * @param {boolean} [props.hideDefaultFlow] - Hide the "default" flow from the "Other flows" section
  */
-export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyboard', subtitle, showThumbnails = false, hideDefaultScene = false }) {
+export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyboard', subtitle, showThumbnails = false, hideDefaultFlow, hideDefaultScene = false }) {
   const containerRef = useRef(null)
   const handleRef = useRef(null)
 
+  const shouldHideDefault = hideDefaultFlow ?? hideDefaultScene
+
   const knownRoutes = Object.keys(pageModules)
     .map(p => p.replace('/src/prototypes/', '').replace('.jsx', ''))
     .filter(n => !n.startsWith('_') && n !== 'index' && n !== 'viewfinder')
@@ -40,7 +42,7 @@ export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyb
         basePath,
         knownRoutes,
         showThumbnails,
-        hideDefaultFlow: hideDefaultScene,
+        hideDefaultFlow: shouldHideDefault,
       })
     })
 
@@ -51,7 +53,7 @@ export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyb
         handleRef.current = null
       }
     }
-  }, [title, subtitle, basePath, showThumbnails, hideDefaultScene])
+  }, [title, subtitle, basePath, showThumbnails, shouldHideDefault])
 
   return <div ref={containerRef} style={{ minHeight: '100vh' }} />
 }

package/src/context.jsx

@@ -32,7 +32,7 @@ function getPageFlowName(pathname) {
 
 /**
  * Provides loaded flow data to the component tree.
- * Reads the flow name from the ?scene= URL param, the flowName prop,
+ * Reads the flow name from the ?flow= URL param (with ?scene= as alias),
  * a matching flow file for the current page, or defaults to "default".
  *
  * Derives the prototype scope from the route and uses it to resolve
@@ -43,7 +43,8 @@ function getPageFlowName(pathname) {
  */
 export default function StoryboardProvider({ flowName, sceneName, recordName, recordParam, children }) {
   const location = useLocation()
-  const sceneParam = new URLSearchParams(location.search).get('scene')
+  const searchParams = new URLSearchParams(location.search)
+  const sceneParam = searchParams.get('flow') || searchParams.get('scene')
   const prototypeName = getPrototypeName(location.pathname)
   const pageFlow = getPageFlowName(location.pathname)
   const params = useParams()

package/src/context.test.jsx

@@ -187,7 +187,18 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('nav')).toHaveTextContent('Home,Repos')
   })
 
-  it('reads ?scene= param from location.search', () => {
+  it('reads ?flow= param from location.search', () => {
+    mockUseLocation.mockReturnValue({ pathname: '/whatever', search: '?flow=other', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
+  it('reads ?scene= as alias for ?flow=', () => {
     mockUseLocation.mockReturnValue({ pathname: '/whatever', search: '?scene=other', hash: '' })
 
     render(
@@ -198,6 +209,17 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
   })
 
+  it('prefers ?flow= over ?scene= when both present', () => {
+    mockUseLocation.mockReturnValue({ pathname: '/whatever', search: '?flow=other&scene=default', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
   it('loads prototype flow for sub-pages when no page-specific flow exists', () => {
     init({
       flows: {

package/src/hooks/useRecord.js

@@ -20,15 +20,26 @@ import { StoryboardContext } from '../StoryboardContext.js'
  * - Unknown ids create new entries appended to the array.
  *
  * @param {Array} baseRecords - The original record array (will be deep-cloned)
- * @param {string} recordName - Record collection name (e.g. "posts")
+ * @param {string} resolvedName - Resolved (possibly scoped) record name (e.g. "security/rules")
+ * @param {string} [plainName] - Original unscoped record name (e.g. "rules"). Falls back to resolvedName.
  * @returns {Array} Merged array
  */
-function applyRecordOverrides(baseRecords, recordName) {
+function applyRecordOverrides(baseRecords, resolvedName, plainName) {
   const allParams = isHideMode() ? getAllShadows() : getAllParams()
-  const prefix = `record.${recordName}.`
+
+  // Check both the resolved (scoped) prefix and the plain (unscoped) prefix.
+  // Callers write overrides with the plain name, but the data index resolves
+  // to the scoped name — we need to match both so overrides are not silently
+  // dropped for prototype-scoped records.
+  const resolvedPrefix = `record.${resolvedName}.`
+  const plainPrefix = plainName && plainName !== resolvedName
+    ? `record.${plainName}.`
+    : null
 
   // Collect only the params that target this record
-  const overrideKeys = Object.keys(allParams).filter(k => k.startsWith(prefix))
+  const overrideKeys = Object.keys(allParams).filter(k =>
+    k.startsWith(resolvedPrefix) || (plainPrefix && k.startsWith(plainPrefix))
+  )
   if (overrideKeys.length === 0) return baseRecords
 
   const records = deepClone(baseRecords)
@@ -37,6 +48,8 @@ function applyRecordOverrides(baseRecords, recordName) {
   // key format: record.{name}.{entryId}.{field...}
   const byEntryId = {}
   for (const key of overrideKeys) {
+    // Determine which prefix matched to slice correctly
+    const prefix = key.startsWith(resolvedPrefix) ? resolvedPrefix : plainPrefix
     const rest = key.slice(prefix.length) // "{entryId}.{field...}"
     const dotIdx = rest.indexOf('.')
     if (dotIdx === -1) continue // no field path — skip
@@ -104,7 +117,7 @@ export function useRecord(recordName, paramName = 'id') {
     try {
       const resolvedName = resolveRecordName(prototypeName, recordName)
       const base = loadRecord(resolvedName)
-      const merged = applyRecordOverrides(base, resolvedName)
+      const merged = applyRecordOverrides(base, resolvedName, recordName)
       return merged.find(e => e[paramName] === paramValue) ?? null
     } catch (err) {
       console.error(`[useRecord] ${err.message}`)
@@ -136,7 +149,7 @@ export function useRecords(recordName) {
     try {
       const resolvedName = resolveRecordName(prototypeName, recordName)
       const base = loadRecord(resolvedName)
-      return applyRecordOverrides(base, resolvedName)
+      return applyRecordOverrides(base, resolvedName, recordName)
     } catch (err) {
       console.error(`[useRecords] ${err.message}`)
       return []

package/src/hooks/useRecord.test.js

@@ -1,6 +1,8 @@
+import React from 'react'
 import { renderHook, act } from '@testing-library/react'
 import { seedTestData, TEST_RECORDS } from '../../test-utils.js'
-import { activateHideMode, setShadow } from '@dfosco/storyboard-core'
+import { activateHideMode, setShadow, init } from '@dfosco/storyboard-core'
+import { StoryboardContext } from '../StoryboardContext.js'
 
 vi.mock('react-router-dom', async () => {
   const actual = await vi.importActual('react-router-dom')
@@ -15,6 +17,20 @@ beforeEach(() => {
   useParams.mockReturnValue({})
 })
 
+/**
+ * Create a wrapper that provides StoryboardContext with a prototypeName,
+ * used for testing scoped (prototype-level) records.
+ */
+function createPrototypeWrapper(prototypeName) {
+  return function Wrapper({ children }) {
+    return React.createElement(
+      StoryboardContext.Provider,
+      { value: { data: {}, prototypeName } },
+      children,
+    )
+  }
+}
+
 // ── useRecord ──
 
 describe('useRecord', () => {
@@ -128,3 +144,78 @@ describe('useRecords (hide mode)', () => {
     expect(newPost.title).toBe('New Shadow')
   })
 })
+
+// ── Scoped (prototype) records ──
+
+const SCOPED_RECORDS = {
+  'security/rules': [
+    { id: 'constant-condition', title: 'Constant Condition', state: 'open' },
+    { id: 'unused-var', title: 'Unused Variable', state: 'open' },
+  ],
+}
+
+function seedScopedData() {
+  init({
+    flows: {},
+    objects: {},
+    records: SCOPED_RECORDS,
+  })
+}
+
+describe('useRecords (scoped records)', () => {
+  beforeEach(() => {
+    seedScopedData()
+    window.location.hash = ''
+  })
+
+  it('applies overrides written with the plain (unscoped) record name', () => {
+    // Callers write: record.rules.constant-condition.state=dismissed
+    // Reader resolves to "security/rules" — this was the bug
+    window.location.hash = 'record.rules.constant-condition.state=dismissed'
+
+    const wrapper = createPrototypeWrapper('security')
+    const { result } = renderHook(() => useRecords('rules'), { wrapper })
+
+    const rule = result.current.find(e => e.id === 'constant-condition')
+    expect(rule.state).toBe('dismissed')
+  })
+
+  it('applies overrides written with the resolved (scoped) record name', () => {
+    window.location.hash = 'record.security/rules.constant-condition.state=dismissed'
+
+    const wrapper = createPrototypeWrapper('security')
+    const { result } = renderHook(() => useRecords('rules'), { wrapper })
+
+    const rule = result.current.find(e => e.id === 'constant-condition')
+    expect(rule.state).toBe('dismissed')
+  })
+
+  it('merges overrides from both plain and scoped prefixes', () => {
+    window.location.hash =
+      'record.rules.constant-condition.state=dismissed' +
+      '&record.security/rules.unused-var.state=resolved'
+
+    const wrapper = createPrototypeWrapper('security')
+    const { result } = renderHook(() => useRecords('rules'), { wrapper })
+
+    expect(result.current.find(e => e.id === 'constant-condition').state).toBe('dismissed')
+    expect(result.current.find(e => e.id === 'unused-var').state).toBe('resolved')
+  })
+})
+
+describe('useRecord (scoped records)', () => {
+  beforeEach(() => {
+    seedScopedData()
+    window.location.hash = ''
+    useParams.mockReturnValue({ id: 'constant-condition' })
+  })
+
+  it('applies overrides written with the plain (unscoped) record name', () => {
+    window.location.hash = 'record.rules.constant-condition.state=dismissed'
+
+    const wrapper = createPrototypeWrapper('security')
+    const { result } = renderHook(() => useRecord('rules'), { wrapper })
+
+    expect(result.current.state).toBe('dismissed')
+  })
+})

package/src/hooks/useScene.js

@@ -6,7 +6,7 @@ import { StoryboardContext } from '../StoryboardContext.js'
  *
  * @returns {{ flowName: string, switchFlow: (name: string) => void }}
  *   - flowName    – current active flow (e.g. "default")
- *   - switchFlow  – navigate to a different flow by updating ?scene= param
+ *   - switchFlow  – navigate to a different flow by updating ?flow= param
  */
 export function useFlow() {
   const context = useContext(StoryboardContext)
@@ -16,7 +16,8 @@ export function useFlow() {
 
   const switchFlow = useCallback((name) => {
     const url = new URL(window.location.href)
-    url.searchParams.set('scene', name)
+    url.searchParams.delete('scene')
+    url.searchParams.set('flow', name)
     // Preserve hash params across flow switches
     window.location.href = url.toString()
   }, [])

package/src/vite/data-plugin.js

@@ -7,39 +7,55 @@ import { parse as parseJsonc } from 'jsonc-parser'
 const VIRTUAL_MODULE_ID = 'virtual:storyboard-data-index'
 const RESOLVED_ID = '\0' + VIRTUAL_MODULE_ID
 
-const GLOB_PATTERN = '**/*.{flow,scene,object,record,prototype}.{json,jsonc}'
+const GLOB_PATTERN = '**/*.{flow,scene,object,record,prototype,folder}.{json,jsonc}'
 
 /**
  * Extract the data name and type suffix from a file path.
  * Flows and records inside src/prototypes/{Name}/ get prefixed with the
  * prototype name (e.g. "Dashboard/default"). Objects are never prefixed.
+ * Directories ending in .folder/ are skipped when extracting prototype scope.
  *
  * e.g. "src/data/default.flow.json"                → { name: "default",           suffix: "flow" }
  *      "src/prototypes/Dashboard/default.flow.json" → { name: "Dashboard/default", suffix: "flow" }
  *      "src/prototypes/Dashboard/helpers.object.json"→ { name: "helpers",           suffix: "object" }
+ *      "src/prototypes/X.folder/Dashboard/default.flow.json" → { name: "Dashboard/default", suffix: "flow", folder: "X" }
  */
 function parseDataFile(filePath) {
   const base = path.basename(filePath)
-  const match = base.match(/^(.+)\.(flow|scene|object|record|prototype)\.(jsonc?)$/)
+  const match = base.match(/^(.+)\.(flow|scene|object|record|prototype|folder)\.(jsonc?)$/)
   if (!match) return null
   // Normalize .scene → .flow for backward compatibility
   const suffix = match[2] === 'scene' ? 'flow' : match[2]
   let name = match[1]
 
+  const normalized = filePath.replace(/\\/g, '/')
+
+  // Detect if this file is inside a .folder/ directory
+  const folderDirMatch = normalized.match(/(?:^|\/)src\/prototypes\/([^/]+)\.folder\//)
+  const folderName = folderDirMatch ? folderDirMatch[1] : null
+
+  // Folder metadata files are keyed by their folder directory name (sans .folder suffix)
+  if (suffix === 'folder') {
+    if (folderName) {
+      name = folderName
+    }
+    return { name, suffix, ext: match[3] }
+  }
+
   // Prototype metadata files are keyed by their prototype directory name
+  // (skip .folder/ segments when determining prototype name)
   if (suffix === 'prototype') {
-    const normalized = filePath.replace(/\\/g, '/')
-    const protoMatch = normalized.match(/(?:^|\/)src\/prototypes\/([^/]+)\//)
+    const protoMatch = normalized.match(/(?:^|\/)src\/prototypes\/(?:[^/]+\.folder\/)?([^/]+)\//)
     if (protoMatch) {
       name = protoMatch[1]
     }
-    return { name, suffix, ext: match[3] }
+    return { name, suffix, ext: match[3], folder: folderName }
   }
 
   // Scope flows and records inside src/prototypes/{Name}/ with a prefix
+  // (skip .folder/ segments when determining prototype name)
   if (suffix !== 'object') {
-    const normalized = filePath.replace(/\\/g, '/')
-    const protoMatch = normalized.match(/(?:^|\/)src\/prototypes\/([^/]+)\//)
+    const protoMatch = normalized.match(/(?:^|\/)src\/prototypes\/(?:[^/]+\.folder\/)?([^/]+)\//)
     if (protoMatch) {
       name = `${protoMatch[1]}/${name}`
     }
@@ -65,6 +81,22 @@ function getGitAuthor(root, filePath) {
   }
 }
 
+/**
+ * Look up the most recent commit date for any file in a directory.
+ * Returns an ISO 8601 timestamp, or null if unavailable.
+ */
+function getLastModified(root, dirPath) {
+  try {
+    const result = execSync(
+      `git log -1 --format="%aI" -- "${dirPath}"`,
+      { cwd: root, encoding: 'utf-8', timeout: 5000 },
+    ).trim()
+    return result || null
+  } catch {
+    return null
+  }
+}
+
 /**
  * Scan the repo for all data files, validate uniqueness, return the index.
  */
@@ -72,8 +104,24 @@ function buildIndex(root) {
   const ignore = ['node_modules/**', 'dist/**', '.git/**']
   const files = globSync(GLOB_PATTERN, { cwd: root, ignore, absolute: false })
 
-  const index = { flow: {}, object: {}, record: {}, prototype: {} }
+  // Detect nested .folder/ directories (not supported)
+  // Scan directories directly since empty nested folders have no data files
+  const folderDirs = globSync('src/prototypes/**/*.folder', { cwd: root, ignore, absolute: false })
+  for (const dir of folderDirs) {
+    const normalized = dir.replace(/\\/g, '/')
+    const segments = normalized.split('/').filter(s => s.endsWith('.folder'))
+    if (segments.length > 1) {
+      throw new Error(
+        `[storyboard-data] Nested .folder directories are not supported.\n` +
+        `  Found at: ${dir}\n` +
+        `  Folders can only be one level deep inside src/prototypes/.`
+      )
+    }
+  }
+
+  const index = { flow: {}, object: {}, record: {}, prototype: {}, folder: {} }
   const seen = {} // "name.suffix" → absolute path (for duplicate detection)
+  const protoFolders = {} // prototype name → folder name (for injection)
 
   for (const relPath of files) {
     const parsed = parseDataFile(relPath)
@@ -86,8 +134,10 @@ function buildIndex(root) {
       const hint = parsed.suffix === 'object'
         ? '  Objects are globally scoped — even inside src/prototypes/ they share a single namespace.\n' +
           '  Rename one of the files to avoid the collision.'
-        : '  Flows and records are scoped to their prototype directory.\n' +
-          '  If both files are global (outside src/prototypes/), rename one to avoid the collision.'
+        : parsed.suffix === 'folder'
+          ? '  Folder names must be unique across the project.'
+          : '  Flows and records are scoped to their prototype directory.\n' +
+            '  If both files are global (outside src/prototypes/), rename one to avoid the collision.'
 
       throw new Error(
         `[storyboard-data] Duplicate ${parsed.suffix} "${parsed.name}"\n` +
@@ -99,9 +149,14 @@ function buildIndex(root) {
 
     seen[key] = absPath
     index[parsed.suffix][parsed.name] = absPath
+
+    // Track which folder a prototype belongs to
+    if (parsed.suffix === 'prototype' && parsed.folder) {
+      protoFolders[parsed.name] = parsed.folder
+    }
   }
 
-  return index
+  return { index, protoFolders }
 }
 
 /**
@@ -164,10 +219,10 @@ function readModesConfig(root) {
   return fallback
 }
 
-function generateModule(index, root) {
+function generateModule({ index, protoFolders }, root) {
   const declarations = []
-  const INDEX_KEYS = ['flow', 'object', 'record', 'prototype']
-  const entries = { flow: [], object: [], record: [], prototype: [] }
+  const INDEX_KEYS = ['flow', 'object', 'record', 'prototype', 'folder']
+  const entries = { flow: [], object: [], record: [], prototype: [], folder: [] }
   let i = 0
 
   for (const suffix of INDEX_KEYS) {
@@ -184,13 +239,27 @@ function generateModule(index, root) {
         }
       }
 
+      // Auto-fill lastModified from git history for prototypes
+      if (suffix === 'prototype' && parsed) {
+        const protoDir = path.dirname(absPath)
+        const lastModified = getLastModified(root, protoDir)
+        if (lastModified) {
+          parsed = { ...parsed, lastModified }
+        }
+      }
+
+      // Inject folder association into prototype metadata
+      if (suffix === 'prototype' && protoFolders[name]) {
+        parsed = { ...parsed, folder: protoFolders[name] }
+      }
+
       declarations.push(`const ${varName} = ${JSON.stringify(parsed)}`)
       entries[suffix].push(`  ${JSON.stringify(name)}: ${varName}`)
     }
   }
 
   const imports = [`import { init } from '@dfosco/storyboard-core'`]
-  const initCalls = [`init({ flows, objects, records, prototypes })`]
+  const initCalls = [`init({ flows, objects, records, prototypes, folders })`]
 
   // Feature flags from storyboard.config.json
   const { config } = readConfig(root)
@@ -237,14 +306,15 @@ function generateModule(index, root) {
     `const objects = {\n${entries.object.join(',\n')}\n}`,
     `const records = {\n${entries.record.join(',\n')}\n}`,
     `const prototypes = {\n${entries.prototype.join(',\n')}\n}`,
+    `const folders = {\n${entries.folder.join(',\n')}\n}`,
     '',
     '// Backward-compatible alias',
     'const scenes = flows',
     '',
     initCalls.join('\n'),
     '',
-    `export { flows, scenes, objects, records, prototypes }`,
-    `export const index = { flows, scenes, objects, records, prototypes }`,
+    `export { flows, scenes, objects, records, prototypes, folders }`,
+    `export const index = { flows, scenes, objects, records, prototypes, folders }`,
     `export default index`,
   ].join('\n')
 }
@@ -259,7 +329,7 @@ function generateModule(index, root) {
  */
 export default function storyboardDataPlugin() {
   let root = ''
-  let index = null
+  let buildResult = null
 
   return {
     name: 'storyboard-data',
@@ -283,8 +353,8 @@ export default function storyboardDataPlugin() {
 
     load(id) {
       if (id !== RESOLVED_ID) return null
-      if (!index) index = buildIndex(root)
-      return generateModule(index, root)
+      if (!buildResult) buildResult = buildIndex(root)
+      return generateModule(buildResult, root)
     },
 
     configureServer(server) {
@@ -293,9 +363,11 @@ export default function storyboardDataPlugin() {
 
       const invalidate = (filePath) => {
         const parsed = parseDataFile(filePath)
-        if (!parsed) return
+        // Also invalidate when files are added/removed inside .folder/ directories
+        const inFolder = filePath.replace(/\\/g, '/').includes('.folder/')
+        if (!parsed && !inFolder) return
         // Rebuild index and invalidate virtual module
-        index = null
+        buildResult = null
         const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
         if (mod) {
           server.moduleGraph.invalidateModule(mod)
@@ -308,7 +380,7 @@ export default function storyboardDataPlugin() {
       watcher.add(configPath)
       const invalidateConfig = (filePath) => {
         if (path.resolve(filePath) === configPath) {
-          index = null
+          buildResult = null
           const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
           if (mod) {
             server.moduleGraph.invalidateModule(mod)
@@ -327,7 +399,7 @@ export default function storyboardDataPlugin() {
 
     // Rebuild index on each build start
     buildStart() {
-      index = null
+      buildResult = null
     },
   }
 }

package/src/vite/data-plugin.test.js

@@ -69,13 +69,13 @@ describe('storyboardDataPlugin', () => {
     const code = plugin.load(RESOLVED_ID)
 
     expect(code).toContain("import { init } from '@dfosco/storyboard-core'")
-    expect(code).toContain('init({ flows, objects, records, prototypes })')
+    expect(code).toContain('init({ flows, objects, records, prototypes, folders })')
     expect(code).toContain('"Test"')
     expect(code).toContain('"Jane"')
     expect(code).toContain('"First"')
     // Backward-compat alias
     expect(code).toContain('const scenes = flows')
-    expect(code).toContain('export { flows, scenes, objects, records, prototypes }')
+    expect(code).toContain('export { flows, scenes, objects, records, prototypes, folders }')
   })
 
   it('load returns null for other IDs', () => {
@@ -137,7 +137,7 @@ describe('storyboardDataPlugin', () => {
 
     // .scene.json files should be normalized to the flows category
     expect(code).toContain('"Legacy Scene"')
-    expect(code).toContain('init({ flows, objects, records, prototypes })')
+    expect(code).toContain('init({ flows, objects, records, prototypes, folders })')
   })
 
   it('buildStart resets the index cache', () => {
@@ -264,3 +264,106 @@ describe('prototype scoping', () => {
     expect(code).toContain('flows')
   })
 })
+
+describe('folder grouping', () => {
+  it('discovers .folder.json files and keys them by folder directory name', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Getting Started.folder'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Getting Started.folder', 'getting-started.folder.json'),
+      JSON.stringify({ meta: { title: 'Getting Started', description: 'Intro' } }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('"Getting Started"')
+    expect(code).toContain('"Intro"')
+    expect(code).toContain('folders')
+  })
+
+  it('scopes prototypes inside .folder/ directories correctly', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'MyFolder.folder', 'Dashboard'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'MyFolder.folder', 'Dashboard', 'default.flow.json'),
+      JSON.stringify({ title: 'Dashboard Default' }),
+    )
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'MyFolder.folder', 'Dashboard', 'dashboard.prototype.json'),
+      JSON.stringify({ meta: { title: 'Dashboard' } }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    // Flow should be scoped to prototype, not folder
+    expect(code).toContain('"Dashboard/default"')
+    expect(code).not.toContain('"MyFolder.folder/default"')
+    expect(code).not.toContain('"MyFolder/default"')
+    // Prototype should have folder field injected
+    expect(code).toContain('"folder":"MyFolder"')
+  })
+
+  it('does NOT prefix objects inside .folder/ directories', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'X.folder', 'Proto'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'X.folder', 'Proto', 'helpers.object.json'),
+      JSON.stringify({ util: true }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('"helpers"')
+    expect(code).not.toContain('"X/helpers"')
+    expect(code).not.toContain('"Proto/helpers"')
+  })
+
+  it('scopes records inside .folder/ directories to their prototype', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'X.folder', 'Blog'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'X.folder', 'Blog', 'posts.record.json'),
+      JSON.stringify([{ id: '1', title: 'Post' }]),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('"Blog/posts"')
+    expect(code).not.toContain('"X/posts"')
+  })
+
+  it('allows prototypes with same name in different folders without clash', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'A.folder', 'Settings'), { recursive: true })
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'B.folder', 'Settings'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'A.folder', 'Settings', 'default.flow.json'),
+      JSON.stringify({ from: 'A' }),
+    )
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'B.folder', 'Settings', 'default.flow.json'),
+      JSON.stringify({ from: 'B' }),
+    )
+
+    const plugin = createPlugin()
+    // Same flow name in same prototype name → duplicate collision
+    expect(() => plugin.load(RESOLVED_ID)).toThrow(/Duplicate flow "Settings\/default"/)
+  })
+
+  it('throws on nested .folder/ directories', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Outer.folder', 'Inner.folder', 'Proto'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Outer.folder', 'Inner.folder', 'Proto', 'default.flow.json'),
+      JSON.stringify({ title: 'Nested' }),
+    )
+
+    const plugin = createPlugin()
+    expect(() => plugin.load(RESOLVED_ID)).toThrow(/Nested .folder directories are not supported/)
+  })
+
+  it('throws on empty nested .folder/ directories', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Outer.folder', 'Inner.folder'), { recursive: true })
+
+    const plugin = createPlugin()
+    expect(() => plugin.load(RESOLVED_ID)).toThrow(/Nested .folder directories are not supported/)
+  })
+})