@dfosco/storyboard-core 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "2.5.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({