@dfosco/storyboard-core 2.4.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/index.js

@@ -11,7 +11,7 @@ export { init } from './loader.js'
 // Flow, object & record loading
 export { loadFlow, listFlows, flowExists, loadRecord, findRecord, loadObject, deepMerge } from './loader.js'
 // Scoped name resolution
-export { resolveFlowName, resolveRecordName } from './loader.js'
+export { resolveFlowName, resolveRecordName, resolveObjectName } from './loader.js'
 // Prototype metadata
 export { listPrototypes, getPrototypeMetadata } from './loader.js'
 // Folder metadata

package/src/loader.js

@@ -98,27 +98,28 @@ function loadDataFile(name, type) {
  * @param {Set} seen - Tracks visited names to prevent circular refs
  * @returns {*} Resolved data
  */
-function resolveRefs(node, seen = new Set()) {
+function resolveRefs(node, seen = new Set(), scope = null) {
   if (node === null || typeof node !== 'object') return node
   if (Array.isArray(node)) {
-    return node.map((item) => resolveRefs(item, seen))
+    return node.map((item) => resolveRefs(item, seen, scope))
   }
 
   // Handle $ref replacement
   if (node.$ref && typeof node.$ref === 'string') {
     const refName = node.$ref
-    if (seen.has(refName)) {
+    const resolvedRef = scope ? resolveObjectName(scope, refName) : refName
+    if (seen.has(resolvedRef)) {
       throw new Error(`Circular $ref detected: ${refName}`)
     }
-    seen.add(refName)
-    const refData = loadDataFile(refName, 'objects')
-    return resolveRefs(refData, seen)
+    seen.add(resolvedRef)
+    const refData = loadDataFile(resolvedRef, 'objects')
+    return resolveRefs(refData, seen, scope)
   }
 
   // Recurse into object values
   const result = {}
   for (const [key, value] of Object.entries(node)) {
-    result[key] = resolveRefs(value, seen)
+    result[key] = resolveRefs(value, seen, scope)
   }
   return result
 }
@@ -163,6 +164,9 @@ export const sceneExists = flowExists
 export function loadFlow(flowName = 'default') {
   let flowData
 
+  // Extract prototype scope from the flow name (e.g. "Dashboard/default" → "Dashboard")
+  const scope = flowName.includes('/') ? flowName.split('/')[0] : null
+
   try {
     flowData = structuredClone(loadDataFile(flowName, 'flows'))
   } catch {
@@ -184,8 +188,9 @@ export function loadFlow(flowName = 'default') {
     let mergedGlobals = {}
     for (const name of globalNames) {
       try {
-        let globalData = loadDataFile(name)
-        globalData = resolveRefs(globalData)
+        const resolvedName = scope ? resolveObjectName(scope, name) : name
+        let globalData = loadDataFile(resolvedName)
+        globalData = resolveRefs(globalData, new Set(), scope)
         mergedGlobals = deepMerge(mergedGlobals, globalData)
       } catch (err) {
         console.warn(`Failed to load $global: ${name}`, err)
@@ -195,7 +200,7 @@ export function loadFlow(flowName = 'default') {
     flowData = deepMerge(mergedGlobals, flowData)
   }
 
-  flowData = resolveRefs(flowData)
+  flowData = resolveRefs(flowData, new Set(), scope)
 
   // Single clone at the boundary — resolveRefs builds new objects internally,
   // so the index data is safe. Clone here to prevent consumer mutation.
@@ -244,12 +249,13 @@ export function findRecord(recordName, id) {
  * and returns a deep clone.
  *
  * @param {string} objectName - Name of the object file (e.g., "jane-doe")
+ * @param {string|null} [scope] - Optional prototype scope for name resolution
  * @returns {object|Array} Resolved object data
  */
-export function loadObject(objectName) {
-  const data = loadDataFile(objectName, 'objects')
-  const resolved = resolveRefs(structuredClone(data))
-  return resolved
+export function loadObject(objectName, scope) {
+  const resolved = scope ? resolveObjectName(scope, objectName) : objectName
+  const data = loadDataFile(resolved, 'objects')
+  return resolveRefs(structuredClone(data), new Set(), scope)
 }
 
 /**
@@ -287,6 +293,23 @@ export function resolveRecordName(scope, name) {
   return scope ? `${scope}/${name}` : name
 }
 
+/**
+ * Resolve an object name within a prototype scope.
+ * Tries the scoped name first ({scope}/{name}), then falls back to the plain name.
+ *
+ * @param {string|null} scope - Prototype name (e.g. "Dashboard"), or null for global-only
+ * @param {string} name - Object name (e.g. "jane-doe")
+ * @returns {string} The resolved object name that exists in the index
+ */
+export function resolveObjectName(scope, name) {
+  if (scope) {
+    const scoped = `${scope}/${name}`
+    if (dataIndex.objects[scoped] != null) return scoped
+  }
+  if (dataIndex.objects[name] != null) return name
+  return scope ? `${scope}/${name}` : name
+}
+
 /**
  * Returns the names of all registered prototypes.
  * @returns {string[]}

package/src/loader.test.js

@@ -1,4 +1,4 @@
-import { init, loadFlow, listFlows, flowExists, loadScene, listScenes, sceneExists, loadRecord, findRecord, loadObject, deepMerge, resolveFlowName, resolveRecordName, listFolders, getFolderMetadata } from './loader.js'
+import { init, loadFlow, listFlows, flowExists, loadScene, listScenes, sceneExists, loadRecord, findRecord, loadObject, deepMerge, resolveFlowName, resolveRecordName, resolveObjectName, listFolders, getFolderMetadata } from './loader.js'
 
 const makeIndex = () => ({
   flows: {
@@ -383,6 +383,87 @@ describe('resolveRecordName', () => {
   })
 })
 
+describe('resolveObjectName', () => {
+  beforeEach(() => {
+    init({
+      flows: {},
+      objects: {
+        'jane-doe': { name: 'Jane Global' },
+        'Dashboard/jane-doe': { name: 'Jane Dashboard' },
+        'Dashboard/helpers': { util: true },
+      },
+      records: {},
+    })
+  })
+
+  it('returns scoped name when it exists', () => {
+    expect(resolveObjectName('Dashboard', 'jane-doe')).toBe('Dashboard/jane-doe')
+    expect(resolveObjectName('Dashboard', 'helpers')).toBe('Dashboard/helpers')
+  })
+
+  it('falls back to global when scoped does not exist', () => {
+    expect(resolveObjectName('Blog', 'jane-doe')).toBe('jane-doe')
+  })
+
+  it('returns global when scope is null', () => {
+    expect(resolveObjectName(null, 'jane-doe')).toBe('jane-doe')
+  })
+
+  it('returns scoped name for error messages when neither exists', () => {
+    expect(resolveObjectName('Dashboard', 'nonexistent')).toBe('Dashboard/nonexistent')
+  })
+
+  it('returns plain name when scope is null and name does not exist', () => {
+    expect(resolveObjectName(null, 'nonexistent')).toBe('nonexistent')
+  })
+})
+
+describe('scoped object loading', () => {
+  beforeEach(() => {
+    init({
+      flows: {
+        'Dashboard/default': {
+          $global: ['nav'],
+          user: { $ref: 'jane-doe' },
+          heading: 'Dashboard',
+        },
+      },
+      objects: {
+        'jane-doe': { name: 'Jane Global' },
+        nav: { links: ['home'] },
+        'Dashboard/jane-doe': { name: 'Jane Dashboard' },
+        'Dashboard/nav': { links: ['dashboard-home', 'settings'] },
+      },
+      records: {},
+    })
+  })
+
+  it('loadObject with scope resolves scoped object', () => {
+    const obj = loadObject('jane-doe', 'Dashboard')
+    expect(obj.name).toBe('Jane Dashboard')
+  })
+
+  it('loadObject with scope falls back to global', () => {
+    const obj = loadObject('jane-doe', 'Blog')
+    expect(obj.name).toBe('Jane Global')
+  })
+
+  it('loadObject without scope uses global', () => {
+    const obj = loadObject('jane-doe')
+    expect(obj.name).toBe('Jane Global')
+  })
+
+  it('loadFlow resolves $ref with prototype scope', () => {
+    const flow = loadFlow('Dashboard/default')
+    expect(flow.user.name).toBe('Jane Dashboard')
+  })
+
+  it('loadFlow resolves $global with prototype scope', () => {
+    const flow = loadFlow('Dashboard/default')
+    expect(flow.links).toEqual(['dashboard-home', 'settings'])
+  })
+})
+
 describe('error hints for scoped data', () => {
   beforeEach(() => {
     init({

package/src/viewfinder.js

@@ -16,13 +16,17 @@ export function hash(str) {
 /**
  * Resolve the target route path for a flow.
  *
+ * Priority:
  * 1. If flow name matches a known route (case-insensitive), use that route
- * 2. If flow data has a top-level `route`, or `meta.route` / `sceneMeta.route`, use that
- * 3. Fall back to root "/"
+ * 2. If flow data has an explicit top-level `route`, or `meta.route` / `flowMeta.route`, use that
+ * 3. If flow data has `_route` (inferred from file path by Vite plugin), use that
+ * 4. Fall back to root "/"
+ *
+ * Flows with `meta.default: true` targeting a route omit the `?flow=` param.
  *
  * @param {string} flowName
  * @param {string[]} knownRoutes - Array of route names (e.g. ["Dashboard", "Repositories"])
- * @returns {string} Full path with ?flow= param
+ * @returns {string} Full path with optional ?flow= param
  */
 export function resolveFlowRoute(flowName, knownRoutes = []) {
   // Case-insensitive match against known routes
@@ -34,14 +38,22 @@ export function resolveFlowRoute(flowName, knownRoutes = []) {
     }
   }
 
-  // Check for explicit route: top-level `route`, then meta.route, then legacy sceneMeta.route
   try {
     const data = loadFlow(flowName)
-    const route = data?.route || data?.meta?.route || data?.flowMeta?.route || data?.sceneMeta?.route
-    if (route) {
-      const normalized = route.startsWith('/') ? route : `/${route}`
+
+    // Check for explicit route: top-level `route`, then meta.route, then legacy sceneMeta.route
+    const explicitRoute = data?.route || data?.meta?.route || data?.flowMeta?.route || data?.sceneMeta?.route
+    if (explicitRoute) {
+      const normalized = explicitRoute.startsWith('/') ? explicitRoute : `/${explicitRoute}`
+      if (data?.meta?.default === true) return normalized
       return `${normalized}?flow=${encodeURIComponent(flowName)}`
     }
+
+    // Use inferred route from file path (injected by Vite data plugin)
+    if (data?._route) {
+      if (data?.meta?.default === true) return data._route
+      return `${data._route}?flow=${encodeURIComponent(flowName)}`
+    }
   } catch {
     // ignore load errors
   }

package/src/viewfinder.test.js

@@ -12,6 +12,9 @@ const makeIndex = () => ({
     'meta-author': { flowMeta: { author: 'dfosco' }, title: 'With Author' },
     'meta-authors': { flowMeta: { author: ['dfosco', 'heyamie', 'branonconor'] }, title: 'Multi Author' },
     'meta-both': { flowMeta: { route: '/Overview', author: 'octocat' }, title: 'Both' },
+    'inferred-route': { _route: '/Dashboard', title: 'Inferred' },
+    'inferred-default': { _route: '/Settings', meta: { default: true }, title: 'Default Flow' },
+    'explicit-wins': { route: '/Forms', _route: '/Dashboard', title: 'Explicit Wins' },
   },
   objects: {},
   records: {},
@@ -105,6 +108,31 @@ describe('resolveFlowRoute', () => {
     })
     expect(resolveFlowRoute('conflict', [])).toBe('/Forms?flow=conflict')
   })
+
+  it('uses _route when no explicit route exists', () => {
+    expect(resolveFlowRoute('inferred-route', routes)).toBe('/Dashboard?flow=inferred-route')
+  })
+
+  it('prefers explicit route over _route', () => {
+    expect(resolveFlowRoute('explicit-wins', routes)).toBe('/Forms?flow=explicit-wins')
+  })
+
+  it('omits ?flow= when meta.default is true (inferred route)', () => {
+    expect(resolveFlowRoute('inferred-default', routes)).toBe('/Settings')
+  })
+
+  it('omits ?flow= when meta.default is true (explicit route)', () => {
+    init({
+      flows: { 'default-explicit': { route: '/Overview', meta: { default: true } } },
+      objects: {},
+      records: {},
+    })
+    expect(resolveFlowRoute('default-explicit', [])).toBe('/Overview')
+  })
+
+  it('still appends ?flow= when meta.default is absent even with _route', () => {
+    expect(resolveFlowRoute('inferred-route', [])).toBe('/Dashboard?flow=inferred-route')
+  })
 })
 
 describe('getFlowMeta', () => {