@dfosco/storyboard-react 2.4.0 → 2.6.0

package/package.json

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

package/src/FlowError.module.css

@@ -0,0 +1,30 @@
+.container {
+  padding: 80px 24px 24px 24px;
+  max-width: 700px;
+  margin: 0 auto;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+  font-size: 14px;
+}
+
+.banner {
+  padding: 12px 16px;
+  margin-bottom: 16px;
+  border-radius: 6px;
+  border: 1px solid var(--borderColor-danger-emphasis, #da3633);
+  background-color: var(--bgColor-danger-muted, rgba(248, 81, 73, 0.1));
+  color: var(--fgColor-danger, #f85149);
+}
+
+.banner strong {
+  display: block;
+  margin-bottom: 4px;
+}
+
+.meta {
+  color: var(--fgColor-muted, #9198a1);
+}
+
+.meta a,
+.homeLink {
+  color: var(--fgColor-accent, #4493f8);
+}

package/src/context.jsx

@@ -4,6 +4,7 @@ import { useParams, useLocation } from 'react-router-dom'
 import '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'
 
 export { StoryboardContext }
 
@@ -116,7 +117,24 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
   }
 
   if (error) {
-    return <span style={{ color: 'var(--fgColor-danger, #f85149)' }}>Error loading flow: {error}</span>
+    const currentUrl = `${location.pathname}${location.search}`
+    const truncatedUrl = currentUrl.length > 60
+      ? currentUrl.slice(0, 60) + '…'
+      : currentUrl
+
+    return (
+      <div className={styles.container}>
+        <div className={styles.banner}>
+          <strong>Error loading flow</strong>
+          {error}
+        </div>
+        <p className={styles.meta}>
+          Tried to load{' '}
+          <a href={currentUrl} title={currentUrl}>{truncatedUrl}</a>
+        </p>
+        <a className={styles.homeLink} href="/">← Go to homepage</a>
+      </div>
+    )
   }
 
   return (

package/src/hooks/useObject.js

@@ -1,14 +1,16 @@
-import { useMemo, useSyncExternalStore } from 'react'
-import { loadObject } from '@dfosco/storyboard-core'
+import { useContext, useMemo, useSyncExternalStore } from 'react'
+import { loadObject, resolveObjectName } from '@dfosco/storyboard-core'
 import { getByPath, deepClone, setByPath } from '@dfosco/storyboard-core'
 import { getParam, getAllParams } from '@dfosco/storyboard-core'
 import { isHideMode, getShadow, getAllShadows } from '@dfosco/storyboard-core'
 import { subscribeToHash, getHashSnapshot } from '@dfosco/storyboard-core'
 import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
+import { StoryboardContext } from '../StoryboardContext.js'
 
 /**
  * Load an object data file directly by name, without going through a scene.
  * Supports dot-notation path access and URL hash overrides.
+ * Objects inside prototypes are automatically resolved with prototype scope.
  *
  * Hash override convention: object.{objectName}.{field}=value
  *
@@ -23,13 +25,16 @@ import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
  * // Override via URL hash: #object.jane-doe.name=Alice
  */
 export function useObject(objectName, path) {
+  const context = useContext(StoryboardContext)
+  const prototypeName = context?.prototypeName ?? null
   const hashString = useSyncExternalStore(subscribeToHash, getHashSnapshot)
   const storageString = useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
 
   return useMemo(() => {
+    const resolvedName = resolveObjectName(prototypeName, objectName)
     let data
     try {
-      data = loadObject(objectName)
+      data = loadObject(resolvedName)
     } catch (err) {
       console.error(`[useObject] ${err.message}`)
       return undefined
@@ -39,35 +44,48 @@ export function useObject(objectName, path) {
     const readParam = hidden ? getShadow : getParam
     const readAllParams = hidden ? getAllShadows : getAllParams
 
-    // Apply overrides scoped to this object
-    const prefix = `object.${objectName}.`
+    // Apply overrides scoped to this object.
+    // Check both the resolved (scoped) prefix and the plain (unscoped) prefix
+    // so overrides work whether written with the bare or scoped name.
+    const resolvedPrefix = `object.${resolvedName}.`
+    const plainPrefix = objectName !== resolvedName ? `object.${objectName}.` : null
     const allParams = readAllParams()
-    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) {
       data = deepClone(data)
       for (const key of overrideKeys) {
-        const fieldPath = key.slice(prefix.length)
+        const fieldPath = key.startsWith(resolvedPrefix)
+          ? key.slice(resolvedPrefix.length)
+          : key.slice(plainPrefix.length)
         setByPath(data, fieldPath, allParams[key])
       }
     }
 
     if (!path) return data
 
-    // Exact match for this sub-path override
-    const exactKey = `${prefix}${path}`
-    const exact = readParam(exactKey)
+    // Exact match for this sub-path override (check both prefixes)
+    const exactResolved = `${resolvedPrefix}${path}`
+    const exactPlain = plainPrefix ? `${plainPrefix}${path}` : null
+    const exact = readParam(exactResolved) ?? (exactPlain ? readParam(exactPlain) : null)
     if (exact !== null) return exact
 
     // Child overrides under the sub-path
-    const subPrefix = exactKey + '.'
-    const childKeys = overrideKeys.filter(k => k.startsWith(subPrefix))
+    const subResolved = exactResolved + '.'
+    const subPlain = exactPlain ? exactPlain + '.' : null
+    const childKeys = overrideKeys.filter(k =>
+      k.startsWith(subResolved) || (subPlain && k.startsWith(subPlain))
+    )
     const baseValue = getByPath(data, path)
 
     if (childKeys.length > 0 && baseValue !== undefined) {
       const merged = deepClone(baseValue)
       for (const key of childKeys) {
-        const relativePath = key.slice(subPrefix.length)
+        const relativePath = key.startsWith(subResolved)
+          ? key.slice(subResolved.length)
+          : key.slice(subPlain.length)
         setByPath(merged, relativePath, allParams[key])
       }
       return merged
@@ -79,5 +97,5 @@ export function useObject(objectName, path) {
     }
 
     return baseValue
-  }, [objectName, path, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [objectName, prototypeName, path, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
 }

package/src/vite/data-plugin.js

@@ -11,13 +11,13 @@ const GLOB_PATTERN = '**/*.{flow,scene,object,record,prototype,folder}.{json,jso
 
 /**
  * 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.
+ * Flows, records, and objects inside src/prototypes/{Name}/ get prefixed with
+ * the prototype name (e.g. "Dashboard/default", "Dashboard/helpers").
  * 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/Dashboard/helpers.object.json"→ { name: "Dashboard/helpers", suffix: "object" }
  *      "src/prototypes/X.folder/Dashboard/default.flow.json" → { name: "Dashboard/default", suffix: "flow", folder: "X" }
  */
 function parseDataFile(filePath) {
@@ -57,16 +57,29 @@ function parseDataFile(filePath) {
     return { name, suffix, ext: match[3], folder: folderName }
   }
 
-  // Scope flows and records inside src/prototypes/{Name}/ with a prefix
+  // Scope flows, records, and objects inside src/prototypes/{Name}/ with a prefix
   // (skip .folder/ segments when determining prototype name)
-  if (suffix !== 'object') {
-    const protoMatch = normalized.match(/(?:^|\/)src\/prototypes\/(?:[^/]+\.folder\/)?([^/]+)\//)
-    if (protoMatch) {
-      name = `${protoMatch[1]}/${name}`
+  const protoMatch = normalized.match(/(?:^|\/)src\/prototypes\/(?:[^/]+\.folder\/)?([^/]+)\//)
+  if (protoMatch) {
+    name = `${protoMatch[1]}/${name}`
+  }
+
+  // Infer route for prototype-scoped flows from their file path.
+  // Mirrors the generouted route regex: strip src/prototypes/ and *.folder/ segments.
+  let inferredRoute = null
+  if (suffix === 'flow') {
+    const protoCheck = normalized.match(/(?:^|\/)src\/prototypes\//)
+    if (protoCheck) {
+      const dirPath = normalized.substring(0, normalized.lastIndexOf('/'))
+      inferredRoute = '/' + dirPath
+        .replace(/^.*?src\/prototypes\//, '')
+        .replace(/[^/]*\.folder\//g, '')
+      // Normalize trailing slash and double slashes
+      inferredRoute = inferredRoute.replace(/\/+/g, '/').replace(/\/$/, '') || '/'
     }
   }
 
-  return { name, suffix, ext: match[3] }
+  return { name, suffix, ext: match[3], inferredRoute }
 }
 
 /**
@@ -127,6 +140,7 @@ function buildIndex(root) {
   const index = { flow: {}, object: {}, record: {}, prototype: {}, folder: {} }
   const seen = {} // "name.suffix" → absolute path (for duplicate detection)
   const protoFolders = {} // prototype name → folder name (for injection)
+  const flowRoutes = {} // flow name → inferred route (for _route injection)
 
   for (const relPath of files) {
     const parsed = parseDataFile(relPath)
@@ -136,12 +150,9 @@ function buildIndex(root) {
     const absPath = path.resolve(root, relPath)
 
     if (seen[key]) {
-      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.'
-        : parsed.suffix === 'folder'
+      const hint = parsed.suffix === 'folder'
           ? '  Folder names must be unique across the project.'
-          : '  Flows and records are scoped to their prototype directory.\n' +
+          : '  Flows, records, and objects are scoped to their prototype directory.\n' +
             '  If both files are global (outside src/prototypes/), rename one to avoid the collision.'
 
       throw new Error(
@@ -159,9 +170,58 @@ function buildIndex(root) {
     if (parsed.suffix === 'prototype' && parsed.folder) {
       protoFolders[parsed.name] = parsed.folder
     }
+
+    // Track inferred routes for flows
+    if (parsed.suffix === 'flow' && parsed.inferredRoute) {
+      flowRoutes[parsed.name] = parsed.inferredRoute
+    }
+  }
+
+  return { index, protoFolders, flowRoutes }
+}
+
+/**
+ * Recursively walk a parsed JSON value and replace `${varName}` patterns
+ * in every string value. Only string values are processed — keys, numbers,
+ * booleans, and null are left untouched.
+ */
+function resolveTemplateVars(obj, vars) {
+  if (typeof obj === 'string') {
+    let result = obj
+    for (const [key, value] of Object.entries(vars)) {
+      result = result.replaceAll(`\${${key}}`, value)
+    }
+    return result
   }
+  if (Array.isArray(obj)) return obj.map(item => resolveTemplateVars(item, vars))
+  if (obj !== null && typeof obj === 'object') {
+    const out = {}
+    for (const [key, value] of Object.entries(obj)) {
+      out[key] = resolveTemplateVars(value, vars)
+    }
+    return out
+  }
+  return obj
+}
+
+/**
+ * Compute path-based template variables for a data file.
+ *
+ * - currentDir:      directory of the file, relative to project root
+ * - currentProto:    path to the prototype directory (e.g. src/prototypes/main.folder/Example)
+ * - currentProtoDir: path to the first parent *.folder directory (e.g. src/prototypes/main.folder)
+ */
+function computeTemplateVars(absPath, root) {
+  const relPath = path.relative(root, absPath).replace(/\\/g, '/')
+  const currentDir = path.dirname(relPath).replace(/\\/g, '/')
+
+  const protoMatch = relPath.match(/^(src\/prototypes\/(?:[^/]+\.folder\/)?[^/]+)\//)
+  const currentProto = protoMatch && !protoMatch[1].endsWith('.folder') ? protoMatch[1] : ''
 
-  return { index, protoFolders }
+  const folderMatch = relPath.match(/^(src\/prototypes\/[^/]+\.folder)\//)
+  const currentProtoDir = folderMatch ? folderMatch[1] : ''
+
+  return { currentDir, currentProto, currentProtoDir }
 }
 
 /**
@@ -224,10 +284,11 @@ function readModesConfig(root) {
   return fallback
 }
 
-function generateModule({ index, protoFolders }, root) {
+function generateModule({ index, protoFolders, flowRoutes }, root) {
   const declarations = []
   const INDEX_KEYS = ['flow', 'object', 'record', 'prototype', 'folder']
   const entries = { flow: [], object: [], record: [], prototype: [], folder: [] }
+  const resolvedFlowRoutes = {} // flow name → resolved route (for multi-flow logging)
   let i = 0
 
   for (const suffix of INDEX_KEYS) {
@@ -258,6 +319,35 @@ function generateModule({ index, protoFolders }, root) {
         parsed = { ...parsed, folder: protoFolders[name] }
       }
 
+      // Inject inferred _route into flow data (explicit route takes precedence)
+      if (suffix === 'flow' && flowRoutes[name] && !parsed?.route) {
+        parsed = { ...parsed, _route: flowRoutes[name] }
+      }
+
+      // Track resolved route for multi-flow logging
+      if (suffix === 'flow') {
+        const route = parsed?.route || parsed?._route || null
+        if (route) {
+          resolvedFlowRoutes[name] = { route, isDefault: parsed?.meta?.default === true }
+        }
+      }
+
+      // Resolve template variables (${currentDir}, ${currentProto}, ${currentProtoDir})
+      const templateVars = computeTemplateVars(absPath, root)
+      if (!templateVars.currentProto && raw.includes('${currentProto}')) {
+        console.warn(
+          `[storyboard-data] \${currentProto} used in "${path.relative(root, absPath)}" ` +
+          `but file is not inside a prototype directory. Variable resolves to empty string.`
+        )
+      }
+      if (!templateVars.currentProtoDir && raw.includes('${currentProtoDir}')) {
+        console.warn(
+          `[storyboard-data] \${currentProtoDir} used in "${path.relative(root, absPath)}" ` +
+          `but file is not inside a .folder directory. Variable resolves to empty string.`
+        )
+      }
+      parsed = resolveTemplateVars(parsed, templateVars)
+
       declarations.push(`const ${varName} = ${JSON.stringify(parsed)}`)
       entries[suffix].push(`  ${JSON.stringify(name)}: ${varName}`)
     }
@@ -302,6 +392,26 @@ function generateModule({ index, protoFolders }, root) {
     }
   }
 
+  // Log info when multiple flows target the same route
+  const routeGroups = {}
+  for (const [name, { route, isDefault }] of Object.entries(resolvedFlowRoutes)) {
+    if (!routeGroups[route]) routeGroups[route] = []
+    routeGroups[route].push({ name, isDefault })
+  }
+  for (const [route, flows] of Object.entries(routeGroups)) {
+    if (flows.length > 1) {
+      const labels = flows.map(f => `  - ${f.name}${f.isDefault ? ' (default)' : ''}`).join('\n')
+      console.log(`[storyboard-data] Route "${route}" has ${flows.length} flows:\n${labels}`)
+      const defaults = flows.filter(f => f.isDefault)
+      if (defaults.length > 1) {
+        console.warn(
+          `[storyboard-data] Warning: Route "${route}" has ${defaults.length} flows with meta.default: true.\n` +
+          `  Only one flow per route should be marked as default.`
+        )
+      }
+    }
+  }
+
   return [
     imports.join('\n'),
     '',
@@ -408,3 +518,6 @@ export default function storyboardDataPlugin() {
     },
   }
 }
+
+// Exported for testing
+export { resolveTemplateVars, computeTemplateVars }

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

@@ -1,7 +1,7 @@
 import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
-import storyboardDataPlugin from './data-plugin.js'
+import storyboardDataPlugin, { resolveTemplateVars, computeTemplateVars } from './data-plugin.js'
 
 const RESOLVED_ID = '\0virtual:storyboard-data-index'
 
@@ -99,7 +99,7 @@ describe('storyboardDataPlugin', () => {
     expect(() => plugin.load(RESOLVED_ID)).toThrow(/Duplicate flow "dup"/)
   })
 
-  it('duplicate objects show globally-scoped hint', () => {
+  it('allows same object name in global and prototype without clash', () => {
     mkdirSync(path.join(tmpDir, 'src', 'data'), { recursive: true })
     mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Dashboard'), { recursive: true })
     writeFileSync(
@@ -112,8 +112,32 @@ describe('storyboardDataPlugin', () => {
     )
 
     const plugin = createPlugin()
-    expect(() => plugin.load(RESOLVED_ID)).toThrow(/Duplicate object "user"/)
-    expect(() => plugin.load(RESOLVED_ID)).toThrow(/globally scoped/)
+    const code = plugin.load(RESOLVED_ID)
+
+    // Both should exist without error
+    expect(code).toContain('"user"')
+    expect(code).toContain('"Dashboard/user"')
+    expect(code).toContain('"Global"')
+    expect(code).toContain('"Local"')
+  })
+
+  it('allows same object name in different prototypes without clash', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'A'), { recursive: true })
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'B'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'A', 'nav.object.json'),
+      JSON.stringify({ from: 'A' }),
+    )
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'B', 'nav.object.json'),
+      JSON.stringify({ from: 'B' }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('"A/nav"')
+    expect(code).toContain('"B/nav"')
   })
 
   it('handles JSONC files (with comments)', () => {
@@ -215,7 +239,7 @@ describe('prototype scoping', () => {
     expect(code).toContain('"Global Post"')
   })
 
-  it('does NOT prefix objects inside src/prototypes/{Name}/', () => {
+  it('prefixes objects inside src/prototypes/{Name}/', () => {
     mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Dashboard'), { recursive: true })
     writeFileSync(
       path.join(tmpDir, 'src', 'prototypes', 'Dashboard', 'helpers.object.json'),
@@ -225,9 +249,8 @@ describe('prototype scoping', () => {
     const plugin = createPlugin()
     const code = plugin.load(RESOLVED_ID)
 
-    // Object should be plain "helpers", NOT "Dashboard/helpers"
-    expect(code).toContain('"helpers"')
-    expect(code).not.toContain('"Dashboard/helpers"')
+    // Object should be scoped as "Dashboard/helpers"
+    expect(code).toContain('"Dashboard/helpers"')
   })
 
   it('allows same flow name in different prototypes without clash', () => {
@@ -265,6 +288,123 @@ describe('prototype scoping', () => {
   })
 })
 
+describe('flow route inference', () => {
+  it('injects _route for flows inside src/prototypes/', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Dashboard'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Dashboard', 'default.flow.json'),
+      JSON.stringify({ title: 'Dashboard Flow' }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('"_route":"/Dashboard"')
+  })
+
+  it('injects _route for flows inside .folder/ directories', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'MyFolder.folder', 'Example'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'MyFolder.folder', 'Example', 'basic.flow.json'),
+      JSON.stringify({ title: 'Example Flow' }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    // .folder/ should be stripped from the inferred route
+    expect(code).toContain('"_route":"/Example"')
+    expect(code).not.toContain('MyFolder')
+  })
+
+  it('injects _route with nested path for deeply placed flows', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'App', 'settings'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'App', 'settings', 'prefs.flow.json'),
+      JSON.stringify({ title: 'Settings Prefs' }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('"_route":"/App/settings"')
+  })
+
+  it('does NOT inject _route for global flows outside src/prototypes/', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'data'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'data', 'global.flow.json'),
+      JSON.stringify({ title: 'Global Flow' }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).not.toContain('"_route"')
+  })
+
+  it('does NOT inject _route when flow has explicit route field', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Dashboard'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Dashboard', 'custom.flow.json'),
+      JSON.stringify({ route: '/custom-page', title: 'Custom Route' }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    // Should have the explicit route but NOT _route
+    expect(code).toContain('"route":"/custom-page"')
+    expect(code).not.toContain('"_route"')
+  })
+
+  it('logs info when multiple flows share the same route', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Dashboard'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Dashboard', 'happy.flow.json'),
+      JSON.stringify({ title: 'Happy Path' }),
+    )
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Dashboard', 'error.flow.json'),
+      JSON.stringify({ title: 'Error State' }),
+    )
+
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const plugin = createPlugin()
+    plugin.load(RESOLVED_ID)
+
+    const routeLog = logSpy.mock.calls.find(call =>
+      typeof call[0] === 'string' && call[0].includes('Route "/Dashboard" has 2 flows')
+    )
+    expect(routeLog).toBeTruthy()
+    logSpy.mockRestore()
+  })
+
+  it('warns when multiple flows on same route have meta.default: true', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Dashboard'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Dashboard', 'a.flow.json'),
+      JSON.stringify({ meta: { default: true }, title: 'A' }),
+    )
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Dashboard', 'b.flow.json'),
+      JSON.stringify({ meta: { default: true }, title: 'B' }),
+    )
+
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const plugin = createPlugin()
+    plugin.load(RESOLVED_ID)
+
+    const warnCall = warnSpy.mock.calls.find(call =>
+      typeof call[0] === 'string' && call[0].includes('meta.default: true')
+    )
+    expect(warnCall).toBeTruthy()
+    logSpy.mockRestore()
+    warnSpy.mockRestore()
+  })
+})
+
 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 })
@@ -303,7 +443,7 @@ describe('folder grouping', () => {
     expect(code).toContain('"folder":"MyFolder"')
   })
 
-  it('does NOT prefix objects inside .folder/ directories', () => {
+  it('scopes objects inside .folder/ directories to their prototype', () => {
     mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'X.folder', 'Proto'), { recursive: true })
     writeFileSync(
       path.join(tmpDir, 'src', 'prototypes', 'X.folder', 'Proto', 'helpers.object.json'),
@@ -313,9 +453,9 @@ describe('folder grouping', () => {
     const plugin = createPlugin()
     const code = plugin.load(RESOLVED_ID)
 
-    expect(code).toContain('"helpers"')
+    // Object should be scoped to prototype, not folder
+    expect(code).toContain('"Proto/helpers"')
     expect(code).not.toContain('"X/helpers"')
-    expect(code).not.toContain('"Proto/helpers"')
   })
 
   it('scopes records inside .folder/ directories to their prototype', () => {
@@ -435,3 +575,249 @@ describe('underscore prefix ignoring', () => {
     expect(code).toContain('"Has Underscore"')
   })
 })
+
+describe('resolveTemplateVars', () => {
+  it('replaces variables in a simple string', () => {
+    const result = resolveTemplateVars('/${currentDir}/page', { currentDir: 'src/data' })
+    expect(result).toBe('/src/data/page')
+  })
+
+  it('replaces multiple variables in one string', () => {
+    const result = resolveTemplateVars('${currentProto} in ${currentProtoDir}', {
+      currentProto: 'src/prototypes/main.folder/Example',
+      currentProtoDir: 'src/prototypes/main.folder',
+    })
+    expect(result).toBe('src/prototypes/main.folder/Example in src/prototypes/main.folder')
+  })
+
+  it('replaces variables in nested objects', () => {
+    const input = {
+      nav: { url: '/${currentDir}/page', label: 'Go' },
+      meta: { proto: '${currentProto}' },
+    }
+    const vars = { currentDir: 'src/data', currentProto: 'src/prototypes/App' }
+    const result = resolveTemplateVars(input, vars)
+
+    expect(result.nav.url).toBe('/src/data/page')
+    expect(result.nav.label).toBe('Go')
+    expect(result.meta.proto).toBe('src/prototypes/App')
+  })
+
+  it('replaces variables in arrays', () => {
+    const input = ['/${currentDir}/a', '/${currentDir}/b']
+    const result = resolveTemplateVars(input, { currentDir: 'here' })
+    expect(result).toEqual(['/here/a', '/here/b'])
+  })
+
+  it('replaces variables in deeply nested structures', () => {
+    const input = {
+      items: [
+        { links: [{ url: '/${currentDir}/x' }] },
+      ],
+    }
+    const result = resolveTemplateVars(input, { currentDir: 'deep' })
+    expect(result.items[0].links[0].url).toBe('/deep/x')
+  })
+
+  it('does not modify non-string values', () => {
+    const input = { count: 42, active: true, empty: null }
+    const result = resolveTemplateVars(input, { currentDir: 'test' })
+    expect(result).toEqual({ count: 42, active: true, empty: null })
+  })
+
+  it('returns input unchanged when no variables match', () => {
+    const input = { url: '/static/path', name: 'no vars here' }
+    const result = resolveTemplateVars(input, { currentDir: 'test' })
+    expect(result).toEqual(input)
+  })
+
+  it('leaves unknown variable patterns as-is', () => {
+    const result = resolveTemplateVars('${unknownVar}/path', { currentDir: 'test' })
+    expect(result).toBe('${unknownVar}/path')
+  })
+
+  it('does not mutate the original object', () => {
+    const input = { url: '/${currentDir}/page' }
+    const original = JSON.parse(JSON.stringify(input))
+    resolveTemplateVars(input, { currentDir: 'test' })
+    expect(input).toEqual(original)
+  })
+
+  it('handles empty vars object', () => {
+    const input = { url: '/${currentDir}/page' }
+    const result = resolveTemplateVars(input, {})
+    expect(result.url).toBe('/${currentDir}/page')
+  })
+
+  it('handles multiple occurrences of the same variable', () => {
+    const result = resolveTemplateVars('${currentDir}/${currentDir}', { currentDir: 'x' })
+    expect(result).toBe('x/x')
+  })
+})
+
+describe('computeTemplateVars', () => {
+  it('computes currentDir for a file in src/data/', () => {
+    const root = '/project'
+    const absPath = '/project/src/data/nav.object.json'
+    const vars = computeTemplateVars(absPath, root)
+
+    expect(vars.currentDir).toBe('src/data')
+    expect(vars.currentProto).toBe('')
+    expect(vars.currentProtoDir).toBe('')
+  })
+
+  it('computes all three vars for a file in a prototype inside a folder', () => {
+    const root = '/project'
+    const absPath = '/project/src/prototypes/main.folder/Example/sidenav.object.json'
+    const vars = computeTemplateVars(absPath, root)
+
+    expect(vars.currentDir).toBe('src/prototypes/main.folder/Example')
+    expect(vars.currentProto).toBe('src/prototypes/main.folder/Example')
+    expect(vars.currentProtoDir).toBe('src/prototypes/main.folder')
+  })
+
+  it('computes vars for a file in a subdirectory of a prototype', () => {
+    const root = '/project'
+    const absPath = '/project/src/prototypes/main.folder/Example/data/deep.object.json'
+    const vars = computeTemplateVars(absPath, root)
+
+    expect(vars.currentDir).toBe('src/prototypes/main.folder/Example/data')
+    expect(vars.currentProto).toBe('src/prototypes/main.folder/Example')
+    expect(vars.currentProtoDir).toBe('src/prototypes/main.folder')
+  })
+
+  it('computes vars for a file in a prototype without a folder', () => {
+    const root = '/project'
+    const absPath = '/project/src/prototypes/Dashboard/nav.object.json'
+    const vars = computeTemplateVars(absPath, root)
+
+    expect(vars.currentDir).toBe('src/prototypes/Dashboard')
+    expect(vars.currentProto).toBe('src/prototypes/Dashboard')
+    expect(vars.currentProtoDir).toBe('')
+  })
+
+  it('computes vars for a root-level file', () => {
+    const root = '/project'
+    const absPath = '/project/config.object.json'
+    const vars = computeTemplateVars(absPath, root)
+
+    expect(vars.currentDir).toBe('.')
+    expect(vars.currentProto).toBe('')
+    expect(vars.currentProtoDir).toBe('')
+  })
+
+  it('returns empty currentProto for a file directly inside a .folder (not in a prototype)', () => {
+    const root = '/project'
+    const absPath = '/project/src/prototypes/main.folder/nav.object.json'
+    const vars = computeTemplateVars(absPath, root)
+
+    expect(vars.currentDir).toBe('src/prototypes/main.folder')
+    expect(vars.currentProto).toBe('')
+    expect(vars.currentProtoDir).toBe('src/prototypes/main.folder')
+  })
+})
+
+describe('template variable integration', () => {
+  it('resolves ${currentDir} in object files', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'data'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'data', 'nav.object.json'),
+      JSON.stringify({ url: '/${currentDir}/page' }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('/src/data/page')
+    expect(code).not.toContain('${currentDir}')
+  })
+
+  it('resolves ${currentProto} and ${currentProtoDir} in prototype files', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'App.folder', 'Dashboard'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'App.folder', 'Dashboard', 'nav.object.json'),
+      JSON.stringify({
+        proto: '${currentProto}',
+        folder: '${currentProtoDir}',
+        dir: '${currentDir}',
+      }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('src/prototypes/App.folder/Dashboard')
+    expect(code).toContain('src/prototypes/App.folder')
+    expect(code).not.toContain('${currentProto}')
+    expect(code).not.toContain('${currentProtoDir}')
+    expect(code).not.toContain('${currentDir}')
+  })
+
+  it('resolves variables in flow files', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Example.folder', 'Demo'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Example.folder', 'Demo', 'default.flow.json'),
+      JSON.stringify({
+        nav: [{ label: 'Home', url: '/${currentDir}' }],
+      }),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('/src/prototypes/Example.folder/Demo')
+    expect(code).not.toContain('${currentDir}')
+  })
+
+  it('resolves variables in record files', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Blog'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Blog', 'posts.record.json'),
+      JSON.stringify([
+        { id: '1', link: '/${currentProto}/post/1' },
+      ]),
+    )
+
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('/src/prototypes/Blog/post/1')
+    expect(code).not.toContain('${currentProto}')
+  })
+
+  it('warns when ${currentProto} is used outside a prototype', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'data'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'data', 'nav.object.json'),
+      JSON.stringify({ url: '/${currentProto}/page' }),
+    )
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const plugin = createPlugin()
+    plugin.load(RESOLVED_ID)
+
+    const warnCall = warnSpy.mock.calls.find(call =>
+      typeof call[0] === 'string' && call[0].includes('${currentProto}')
+    )
+    expect(warnCall).toBeTruthy()
+    warnSpy.mockRestore()
+  })
+
+  it('warns when ${currentProtoDir} is used outside a .folder', () => {
+    mkdirSync(path.join(tmpDir, 'src', 'prototypes', 'Dashboard'), { recursive: true })
+    writeFileSync(
+      path.join(tmpDir, 'src', 'prototypes', 'Dashboard', 'nav.object.json'),
+      JSON.stringify({ folder: '${currentProtoDir}' }),
+    )
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const plugin = createPlugin()
+    plugin.load(RESOLVED_ID)
+
+    const warnCall = warnSpy.mock.calls.find(call =>
+      typeof call[0] === 'string' && call[0].includes('${currentProtoDir}')
+    )
+    expect(warnCall).toBeTruthy()
+    warnSpy.mockRestore()
+  })
+})