@dfosco/storyboard-core 4.0.0-beta.2 → 4.0.0-beta.21

package/src/canvas/identity.test.js

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest'
+import { toCanvasId, parseCanvasId, canvasIdBasename, isLegacyCanvasId, CANVAS_IDENTITY_CONSUMERS } from './identity.js'
+
+describe('canvas/identity', () => {
+  describe('toCanvasId', () => {
+    it('strips src/canvas/ prefix and .canvas.jsonl suffix', () => {
+      expect(toCanvasId('src/canvas/overview.canvas.jsonl')).toBe('overview')
+    })
+
+    it('normalizes .folder segments', () => {
+      expect(toCanvasId('src/canvas/design.folder/overview.canvas.jsonl')).toBe('design/overview')
+    })
+
+    it('handles nested folders', () => {
+      expect(toCanvasId('src/canvas/design.folder/sub.folder/a.canvas.jsonl')).toBe('design/sub/a')
+    })
+
+    it('prefixes proto: for src/prototypes/', () => {
+      expect(toCanvasId('src/prototypes/Main/board.canvas.jsonl')).toBe('proto:Main/board')
+    })
+
+    it('handles prototype with .folder', () => {
+      expect(toCanvasId('src/prototypes/main.folder/Example/board.canvas.jsonl')).toBe('proto:main/Example/board')
+    })
+
+    it('normalizes backslashes', () => {
+      expect(toCanvasId('src\\canvas\\design.folder\\overview.canvas.jsonl')).toBe('design/overview')
+    })
+
+    it('returns "unknown" for edge case empty result', () => {
+      expect(toCanvasId('src/canvas/.canvas.jsonl')).toBe('unknown')
+    })
+  })
+
+  describe('parseCanvasId', () => {
+    it('parses a simple name', () => {
+      expect(parseCanvasId('overview')).toEqual({
+        namespace: 'canvas',
+        segments: ['overview'],
+        name: 'overview',
+      })
+    })
+
+    it('parses a folder/name ID', () => {
+      expect(parseCanvasId('design/overview')).toEqual({
+        namespace: 'canvas',
+        segments: ['design', 'overview'],
+        name: 'overview',
+      })
+    })
+
+    it('parses a proto: prefixed ID', () => {
+      expect(parseCanvasId('proto:Main/board')).toEqual({
+        namespace: 'prototype',
+        segments: ['Main', 'board'],
+        name: 'board',
+      })
+    })
+
+    it('parses deeply nested ID', () => {
+      expect(parseCanvasId('design/sub/a')).toEqual({
+        namespace: 'canvas',
+        segments: ['design', 'sub', 'a'],
+        name: 'a',
+      })
+    })
+  })
+
+  describe('canvasIdBasename', () => {
+    it('returns the last segment', () => {
+      expect(canvasIdBasename('design/overview')).toBe('overview')
+      expect(canvasIdBasename('overview')).toBe('overview')
+      expect(canvasIdBasename('proto:Main/board')).toBe('board')
+    })
+  })
+
+  describe('isLegacyCanvasId', () => {
+    it('returns true for bare names', () => {
+      expect(isLegacyCanvasId('overview')).toBe(true)
+    })
+
+    it('returns false for path-based IDs', () => {
+      expect(isLegacyCanvasId('design/overview')).toBe(false)
+    })
+
+    it('returns false for proto: prefixed IDs', () => {
+      expect(isLegacyCanvasId('proto:Main')).toBe(false)
+    })
+  })
+
+  describe('CANVAS_IDENTITY_CONSUMERS', () => {
+    it('is a non-empty array of strings', () => {
+      expect(Array.isArray(CANVAS_IDENTITY_CONSUMERS)).toBe(true)
+      expect(CANVAS_IDENTITY_CONSUMERS.length).toBeGreaterThan(0)
+      for (const entry of CANVAS_IDENTITY_CONSUMERS) {
+        expect(typeof entry).toBe('string')
+      }
+    })
+  })
+})

package/src/canvas/server.js

@@ -15,6 +15,8 @@
  *   POST   /widget   — append a widget_added event
  *   DELETE /widget   — append a widget_removed event
  *   POST   /create   — create a new .canvas.jsonl file
+ *   GET    /stories  — list all .story.{jsx,tsx} files with exports
+ *   POST   /create-story — scaffold a new .story.{jsx,tsx} file
  *   POST   /image    — upload a pasted image to src/canvas/images/
  *   GET    /images/* — serve an image file from src/canvas/images/
  *   POST   /image/toggle-private — toggle _prefix on image filename
@@ -24,6 +26,31 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { Buffer } from 'node:buffer'
 import { materializeFromText, serializeEvent } from './materializer.js'
+import { toCanvasId, parseCanvasId } from './identity.js'
+
+/**
+ * Scan src/canvas/ for directories containing .meta.json files.
+ * Returns an object keyed by directory name (without .folder suffix).
+ */
+function findCanvasMeta(root) {
+  const canvasDir = path.join(root, 'src', 'canvas')
+  const groups = {}
+  if (!fs.existsSync(canvasDir)) return groups
+
+  const entries = fs.readdirSync(canvasDir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const dirName = entry.name.replace(/\.folder$/, '')
+    const metaPath = path.join(canvasDir, entry.name, `${dirName}.meta.json`)
+    if (fs.existsSync(metaPath)) {
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'))
+        groups[dirName] = meta
+      } catch { /* skip invalid meta */ }
+    }
+  }
+  return groups
+}
 
 /**
  * Recursively find all .canvas.jsonl files in the project.
@@ -52,17 +79,82 @@ function findCanvasFiles(root) {
 }
 
 /**
- * Find a canvas JSONL file by name.
+ * Recursively find all .story.{jsx,tsx} files in routable directories
+ * (src/canvas/ and src/components/) and extract their named exports.
+ */
+function findStoryFiles(root) {
+  const results = []
+  const ignore = new Set(['node_modules', 'dist', '.git', '.worktrees'])
+  const ROUTABLE_DIRS = ['src/canvas', 'src/components']
+
+  function walk(dir, rel) {
+    let entries
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      if (ignore.has(entry.name)) continue
+      if (entry.name.startsWith('_')) continue
+      const fullPath = path.join(dir, entry.name)
+      const relPath = rel ? `${rel}/${entry.name}` : entry.name
+      if (entry.isDirectory()) {
+        walk(fullPath, relPath)
+      } else if (/\.story\.(jsx|tsx)$/.test(entry.name)) {
+        const name = entry.name.replace(/\.story\.(jsx|tsx)$/, '')
+        const exports = parseExportNames(fullPath)
+        results.push({ name, path: relPath, exports })
+      }
+    }
+  }
+
+  for (const dir of ROUTABLE_DIRS) {
+    const absDir = path.join(root, dir)
+    if (fs.existsSync(absDir)) {
+      walk(absDir, dir)
+    }
+  }
+  return results
+}
+
+/**
+ * Parse named function/const exports from a JSX/TSX file.
  */
-function findCanvasPath(root, name) {
+function parseExportNames(filePath) {
+  try {
+    const src = fs.readFileSync(filePath, 'utf-8')
+    const names = []
+    const re = /export\s+(?:function|const|class)\s+([A-Z]\w*)/g
+    let m
+    while ((m = re.exec(src)) !== null) names.push(m[1])
+    return names
+  } catch { return [] }
+}
+
+/**
+ * Find a canvas JSONL file by canonical ID or legacy basename.
+ * Path-based ID is tried first. Basename fallback only works when it
+ * resolves to exactly one file — ambiguous names return null.
+ */
+function findCanvasPath(root, nameOrId) {
   const files = findCanvasFiles(root)
+
+  // Try matching by canonical ID first
+  for (const file of files) {
+    const id = toCanvasId(file)
+    if (id === nameOrId) {
+      return path.resolve(root, file)
+    }
+  }
+
+  // Fallback: match by basename (legacy). Only if unique.
+  const basenameMatches = []
   for (const file of files) {
     const base = path.basename(file)
     const match = base.match(/^(.+)\.canvas\.jsonl$/)
-    if (match && match[1] === name) {
-      return path.resolve(root, file)
+    if (match && match[1] === nameOrId) {
+      basenameMatches.push(path.resolve(root, file))
     }
   }
+
+  if (basenameMatches.length === 1) return basenameMatches[0]
   return null
 }
 
@@ -117,9 +209,20 @@ export function createCanvasHandler(ctx) {
       let folders = []
       try {
         if (fs.existsSync(canvasDir)) {
-          folders = fs.readdirSync(canvasDir, { withFileTypes: true })
+          const entries = fs.readdirSync(canvasDir, { withFileTypes: true })
+          // .folder directories (existing behavior)
+          const folderDirs = entries
             .filter((d) => d.isDirectory() && d.name.endsWith('.folder'))
             .map((d) => d.name.replace('.folder', ''))
+          // Plain directories containing .canvas.jsonl files
+          const plainDirs = entries
+            .filter((d) => {
+              if (!d.isDirectory() || d.name.endsWith('.folder') || d.name.startsWith('_')) return false
+              const files = fs.readdirSync(path.join(canvasDir, d.name))
+              return files.some((f) => f.endsWith('.canvas.jsonl'))
+            })
+            .map((d) => d.name)
+          folders = [...folderDirs, ...plainDirs]
         }
       } catch { /* empty */ }
       sendJson(res, 200, { folders })
@@ -141,7 +244,17 @@ export function createCanvasHandler(ctx) {
       }
       try {
         const data = readCanvas(filePath)
-        sendJson(res, 200, data)
+        const widgetFilter = url.searchParams.get('widget')
+        if (widgetFilter) {
+          const widget = (data.widgets || []).find((w) => w.id === widgetFilter)
+          if (!widget) {
+            sendJson(res, 404, { error: `Widget "${widgetFilter}" not found in canvas "${name}"` })
+            return
+          }
+          sendJson(res, 200, { ...data, widgets: [widget] })
+        } else {
+          sendJson(res, 200, data)
+        }
       } catch (err) {
         sendJson(res, 500, { error: `Failed to read canvas: ${err.message}` })
       }
@@ -152,22 +265,25 @@ export function createCanvasHandler(ctx) {
     if (routePath === '/list' && method === 'GET') {
       const files = findCanvasFiles(root)
       const canvases = files.map((file) => {
-        const base = path.basename(file)
-        const match = base.match(/^(.+)\.canvas\.jsonl$/)
-        if (!match) return null
+        const id = toCanvasId(file)
+        if (!id) return null
+        const { segments } = parseCanvasId(id)
+        const group = segments.length > 1 ? segments.slice(0, -1).join('/') : null
         try {
           const data = readCanvas(path.resolve(root, file))
           return {
-            name: match[1],
-            title: data.title || match[1],
+            name: id,
+            title: data.title || segments[segments.length - 1],
             path: file,
             widgetCount: (data.widgets || []).length + (data.sources || []).length,
+            group,
           }
         } catch {
-          return { name: match[1], title: match[1], path: file, widgetCount: 0 }
+          return { name: id, title: segments[segments.length - 1], path: file, widgetCount: 0, group }
         }
       }).filter(Boolean)
-      sendJson(res, 200, { canvases })
+      const groups = findCanvasMeta(root)
+      sendJson(res, 200, { canvases, groups })
       return
     }
 
@@ -296,6 +412,8 @@ export function createCanvasHandler(ctx) {
         title,
         folder,
         author,
+        description,
+        meta,
         grid = true,
         gridSize = 24,
         colorMode = 'auto',
@@ -325,12 +443,30 @@ export function createCanvasHandler(ctx) {
       let targetDir = canvasDir
 
       if (folder) {
-        const folderDir = path.join(canvasDir, `${folder}.folder`)
-        if (!fs.existsSync(folderDir)) {
-          sendJson(res, 400, { error: `Folder "${folder}" does not exist` })
-          return
+        const dotFolderDir = path.join(canvasDir, `${folder}.folder`)
+        const plainDir = path.join(canvasDir, folder)
+
+        if (fs.existsSync(dotFolderDir)) {
+          // Existing .folder/ directory
+          targetDir = dotFolderDir
+        } else if (fs.existsSync(plainDir) && fs.statSync(plainDir).isDirectory()) {
+          // Existing plain directory
+          targetDir = plainDir
+        } else {
+          // Create new plain directory
+          try {
+            fs.mkdirSync(plainDir, { recursive: true })
+            // Write .meta.json if meta was provided
+            if (meta && typeof meta === 'object') {
+              const metaPath = path.join(plainDir, `${folder}.meta.json`)
+              fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n', 'utf-8')
+            }
+          } catch (err) {
+            sendJson(res, 500, { error: `Failed to create directory: ${err.message}` })
+            return
+          }
+          targetDir = plainDir
         }
-        targetDir = folderDir
       }
 
       const canvasPath = path.join(targetDir, `${kebab}.canvas.jsonl`)
@@ -353,6 +489,10 @@ export function createCanvasHandler(ctx) {
         creationEvent.author = author
       }
 
+      if (description) {
+        creationEvent.description = description
+      }
+
       if (includeJsx) {
         creationEvent.jsx = `${kebab}.canvas.jsx`
       }
@@ -361,11 +501,14 @@ export function createCanvasHandler(ctx) {
         fs.mkdirSync(targetDir, { recursive: true })
         writeNewCanvas(canvasPath, creationEvent)
 
+        const relPath = path.relative(root, canvasPath).replace(/\\/g, '/')
+        const canonicalName = toCanvasId(relPath) || kebab
+
         const result = {
           success: true,
-          name: kebab,
-          path: path.relative(root, canvasPath),
-          route: `/canvas/${kebab}`,
+          name: canonicalName,
+          path: relPath,
+          route: `/canvas/${canonicalName}`,
         }
 
         // Optionally create starter JSX file
@@ -397,14 +540,124 @@ export function ${componentName}Example() {
       return
     }
 
+    // ── Story routes ──────────────────────────────────────────────────
+
+    // GET /stories — list all .story.{jsx,tsx} files with their exports
+    if (routePath === '/stories' && method === 'GET') {
+      try {
+        const storyFiles = findStoryFiles(root)
+        sendJson(res, 200, { stories: storyFiles })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to list stories: ${err.message}` })
+      }
+      return
+    }
+
+    // POST /create-story — scaffold a new .story.jsx/.tsx file
+    if (routePath === '/create-story' && method === 'POST') {
+      const { name, location, format = 'jsx', canvasName: storyCanvasName } = body
+
+      if (!name || typeof name !== 'string') {
+        sendJson(res, 400, { error: 'Component name is required' })
+        return
+      }
+
+      const kebab = name
+        .replace(/[^a-zA-Z0-9\s_-]/g, '')
+        .trim()
+        .replace(/[\s_]+/g, '-')
+        .toLowerCase()
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+
+      if (!kebab) {
+        sendJson(res, 400, { error: 'Name must contain at least one alphanumeric character' })
+        return
+      }
+
+      const ext = format === 'tsx' ? 'tsx' : 'jsx'
+
+      // Resolve target directory from location + canvas name
+      let targetDir
+      if (location === 'components') {
+        targetDir = path.join(root, 'src', 'components')
+      } else if (storyCanvasName) {
+        const canvasPath = findCanvasPath(root, storyCanvasName)
+        targetDir = canvasPath ? path.dirname(canvasPath) : path.join(root, 'src', 'canvas')
+      } else {
+        targetDir = path.join(root, 'src', 'canvas')
+      }
+
+      const storyPath = path.join(targetDir, `${kebab}.story.${ext}`)
+      if (fs.existsSync(storyPath)) {
+        sendJson(res, 409, { error: `Story "${kebab}.story.${ext}" already exists at ${path.relative(root, targetDir)}` })
+        return
+      }
+
+      // Check for duplicate story name anywhere in the project (Vite data plugin
+      // enforces global uniqueness and would fail the build on duplicates)
+      const existing = findStoryFiles(root)
+      if (existing.some(s => s.name === kebab)) {
+        sendJson(res, 409, { error: `A story named "${kebab}" already exists in the project` })
+        return
+      }
+
+      const componentName = kebab.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('')
+      const content = `/**
+ * ${componentName} component stories.
+ * Each named export becomes a draggable widget on the canvas.
+ */
+
+export function Default() {
+  return (
+    <div style={{ padding: '1.5rem', minWidth: 200 }}>
+      <h3>${componentName}</h3>
+      <p>Edit this file to build your component.</p>
+    </div>
+  )
+}
+`
+
+      try {
+        fs.mkdirSync(targetDir, { recursive: true })
+        fs.writeFileSync(storyPath, content, 'utf-8')
+
+        const relPath = path.relative(root, storyPath)
+        sendJson(res, 201, {
+          success: true,
+          name: kebab,
+          path: relPath,
+          storyId: kebab,
+        })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to create story: ${err.message}` })
+      }
+      return
+    }
+
     // ── Image routes ──────────────────────────────────────────────────
 
-    const imagesDir = path.join(root, 'src', 'canvas', 'images')
+    const imagesDir = path.join(root, 'assets', 'canvas', 'images')
+    const snapshotsDir = path.join(root, 'assets', 'canvas', 'snapshots')
 
     const MIME_TO_EXT = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' }
     const EXT_TO_MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' }
     const MAX_IMAGE_SIZE = 5 * 1024 * 1024 // 5 MB
 
+    // Resolve which directory to write to based on canvasName prefix
+    function resolveWriteDir(canvasName) {
+      return canvasName && canvasName.startsWith('snapshot-') ? snapshotsDir : imagesDir
+    }
+
+    // Resolve a filename to its on-disk path (check snapshots first, then images)
+    function resolveImagePath(filename) {
+      const snapshotPath = path.join(snapshotsDir, filename)
+      if (fs.existsSync(snapshotPath)) return snapshotPath
+      const imagePath = path.join(imagesDir, filename)
+      if (fs.existsSync(imagePath)) return imagePath
+      return null
+    }
+
     // POST /image — upload a pasted image (base64 data URL)
     if (routePath === '/image' && method === 'POST') {
       const { dataUrl, canvasName } = body
@@ -438,12 +691,13 @@ export function ${componentName}Example() {
       const now = new Date()
       const pad = (n) => String(n).padStart(2, '0')
       const dateStr = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}--${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`
-      const prefix = canvasName ? `${canvasName}--` : ''
+      const prefix = canvasName ? `${canvasName.replace(/[\/:]/g, '--')}--` : ''
       const filename = `${prefix}${dateStr}.${ext}`
+      const targetDir = resolveWriteDir(canvasName)
 
       try {
-        fs.mkdirSync(imagesDir, { recursive: true })
-        fs.writeFileSync(path.join(imagesDir, filename), buffer)
+        fs.mkdirSync(targetDir, { recursive: true })
+        fs.writeFileSync(path.join(targetDir, filename), buffer)
         sendJson(res, 201, { success: true, filename })
       } catch (err) {
         sendJson(res, 500, { error: `Failed to save image: ${err.message}` })
@@ -461,8 +715,8 @@ export function ${componentName}Example() {
         return
       }
 
-      const filePath = path.join(imagesDir, filename)
-      if (!fs.existsSync(filePath)) {
+      const filePath = resolveImagePath(filename)
+      if (!filePath) {
         sendJson(res, 404, { error: 'Image not found' })
         return
       }
@@ -500,13 +754,13 @@ export function ${componentName}Example() {
 
       const isPrivate = filename.startsWith('_')
       const newFilename = isPrivate ? filename.slice(1) : `_${filename}`
-      const oldPath = path.join(imagesDir, filename)
-      const newPath = path.join(imagesDir, newFilename)
-
-      if (!fs.existsSync(oldPath)) {
+      const oldPath = resolveImagePath(filename)
+      if (!oldPath) {
         sendJson(res, 404, { error: 'Image not found' })
         return
       }
+      const parentDir = path.dirname(oldPath)
+      const newPath = path.join(parentDir, newFilename)
 
       try {
         fs.renameSync(oldPath, newPath)

package/src/canvasConfig.js

@@ -0,0 +1,56 @@
+/**
+ * Canvas Config — project-level overrides for canvas behavior.
+ *
+ * Client repos use the "canvas" key in storyboard.config.json to customize
+ * canvas paste rules and other canvas-level settings.
+ *
+ *   {
+ *     "canvas": {
+ *       "pasteRules": [
+ *         { "pattern": "youtube\\.com/watch", "type": "link-preview", "props": { "url": "$url" } }
+ *       ]
+ *     }
+ *   }
+ *
+ * Framework-agnostic (zero npm dependencies).
+ */
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+let _pasteRules = []
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize canvas config from storyboard.config.json's "canvas" key.
+ * Called by mountStoryboardCore.
+ *
+ * @param {{ pasteRules?: object[] }} [config]
+ */
+export function initCanvasConfig(config = {}) {
+  _pasteRules = Array.isArray(config.pasteRules) ? config.pasteRules : []
+}
+
+/**
+ * Get the configured paste rules (raw config objects).
+ *
+ * @returns {object[]}
+ */
+export function getPasteRules() {
+  return _pasteRules
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset all internal state. Only for use in tests.
+ */
+export function _resetCanvasConfig() {
+  _pasteRules = []
+}

package/src/canvasConfig.test.js

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { initCanvasConfig, getPasteRules, _resetCanvasConfig } from './canvasConfig.js'
+
+describe('canvasConfig', () => {
+  beforeEach(() => {
+    _resetCanvasConfig()
+  })
+
+  it('returns empty array by default', () => {
+    expect(getPasteRules()).toEqual([])
+  })
+
+  it('stores paste rules from config', () => {
+    const rules = [
+      { pattern: 'youtube\\.com', type: 'link-preview', props: { url: '$url' } },
+    ]
+    initCanvasConfig({ pasteRules: rules })
+    expect(getPasteRules()).toEqual(rules)
+  })
+
+  it('handles missing pasteRules gracefully', () => {
+    initCanvasConfig({})
+    expect(getPasteRules()).toEqual([])
+  })
+
+  it('handles undefined config', () => {
+    initCanvasConfig()
+    expect(getPasteRules()).toEqual([])
+  })
+
+  it('handles non-array pasteRules', () => {
+    initCanvasConfig({ pasteRules: 'not-an-array' })
+    expect(getPasteRules()).toEqual([])
+  })
+
+  it('resets on _resetCanvasConfig', () => {
+    initCanvasConfig({ pasteRules: [{ pattern: '.', type: 'test' }] })
+    expect(getPasteRules()).toHaveLength(1)
+    _resetCanvasConfig()
+    expect(getPasteRules()).toEqual([])
+  })
+})