@dfosco/storyboard 0.5.0-alpha.0

package/src/core/canvas/identity.js

@@ -0,0 +1,107 @@
+/**
+ * Canvas Identity — path-based canvas ID utilities.
+ *
+ * Canonical canvas IDs are normalized relative paths derived from the file
+ * location. They uniquely identify a canvas even when two canvases share the
+ * same basename in different folders.
+ *
+ * Format examples:
+ *   src/canvas/overview.canvas.jsonl                  → "overview"
+ *   src/canvas/design.folder/overview.canvas.jsonl    → "design/overview"
+ *   src/canvas/design.folder/sub.folder/a.canvas.jsonl → "design/sub/a"
+ *   src/prototypes/Main/board.canvas.jsonl            → "proto:Main/board"
+ *
+ * Canvases under src/canvas/ get plain IDs; those under src/prototypes/ get
+ * a "proto:" prefix so the two namespaces never collide.
+ *
+ * Legacy IDs (bare names like "overview") remain supported as aliases when
+ * they resolve to exactly one canvas.
+ *
+ * @module canvas/identity
+ */
+
+const CANVAS_SUFFIX_RE = /\.canvas\.jsonl$/
+const FOLDER_SUFFIX_RE = /([^/]+)\.folder\//g
+
+/**
+ * Convert a relative file path to a canonical canvas ID.
+ *
+ * @param {string} relPath — path relative to project root
+ * @returns {string} canonical canvas ID
+ */
+export function toCanvasId(relPath) {
+  let p = relPath.replace(/\\/g, '/')
+
+  let prefix = ''
+  if (p.startsWith('src/canvas/')) {
+    p = p.slice('src/canvas/'.length)
+  } else if (p.startsWith('src/prototypes/')) {
+    p = p.slice('src/prototypes/'.length)
+    prefix = 'proto:'
+  }
+
+  // Strip .canvas.jsonl suffix
+  p = p.replace(CANVAS_SUFFIX_RE, '')
+
+  // Normalize .folder segments: "design.folder/" → "design/"
+  p = p.replace(FOLDER_SUFFIX_RE, '$1/')
+
+  // Clean up double slashes and trailing slash
+  p = p.replace(/\/+/g, '/').replace(/\/$/, '')
+
+  return prefix + (p || 'unknown')
+}
+
+/**
+ * Parse a canvas ID into its segments.
+ *
+ * @param {string} id — canonical canvas ID
+ * @returns {{ namespace: 'canvas' | 'prototype', segments: string[], name: string }}
+ */
+export function parseCanvasId(id) {
+  let namespace = 'canvas'
+  let raw = id
+  if (raw.startsWith('proto:')) {
+    namespace = 'prototype'
+    raw = raw.slice('proto:'.length)
+  }
+  const segments = raw.split('/').filter(Boolean)
+  const name = segments[segments.length - 1] || raw
+  return { namespace, segments, name }
+}
+
+/**
+ * Extract the basename from a canvas ID (the last segment).
+ * Useful for backward-compatible lookups.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function canvasIdBasename(id) {
+  return parseCanvasId(id).name
+}
+
+/**
+ * Check whether an ID is a legacy bare name (no path segments, no namespace prefix).
+ *
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function isLegacyCanvasId(id) {
+  return !id.includes('/') && !id.startsWith('proto:')
+}
+
+/**
+ * Known consumers of canvas identity that must be updated when migrating
+ * from basename-only to path-based IDs. This inventory is used by downstream
+ * slices to track migration completeness.
+ */
+export const CANVAS_IDENTITY_CONSUMERS = [
+  'packages/react/src/vite/data-plugin.js — index & HMR payloads',
+  'packages/core/src/canvas/server.js — findCanvasPath() & all API routes',
+  'packages/react/src/context.jsx — canvasRouteMap',
+  'packages/react/src/canvas/CanvasPage.jsx — cross-canvas copy/paste (canvasName/widgetId)',
+  'packages/react/src/canvas/CanvasPage.jsx — viewport persistence keys',
+  'packages/core/src/viewfinder.js — canvas listing',
+  'packages/core/src/rename-watcher/watcher.js — canvas rename route inference',
+]

package/src/core/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/core/canvas/materializer.js

@@ -0,0 +1,259 @@
+/**
+ * Canvas JSONL Materializer
+ *
+ * Pure, framework-agnostic module that replays a stream of canvas events
+ * into a materialized canvas state object. Zero dependencies.
+ *
+ * Event types:
+ *   canvas_created   — full initial state (first line)
+ *   widget_added     — append a widget
+ *   widget_updated   — patch widget props
+ *   widget_moved     — update widget position
+ *   widget_removed   — remove a widget by id
+ *   settings_updated — patch canvas-level settings
+ *   source_updated   — replace the sources array
+ *   widgets_replaced — replace the entire widgets array (bulk update)
+ *   connector_added  — append a connector between two widgets
+ *   connector_removed — remove a connector by id
+ *   connectors_replaced — replace the entire connectors array (bulk update, used by undo/redo)
+ */
+
+/**
+ * Split a text blob into top-level JSON object snippets.
+ * Supports strict JSONL and accidentally concatenated objects.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function splitJsonObjects(text) {
+  const chunks = []
+  let start = -1
+  let depth = 0
+  let inString = false
+  let escaped = false
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+
+    if (inString) {
+      if (escaped) {
+        escaped = false
+      } else if (ch === '\\') {
+        escaped = true
+      } else if (ch === '"') {
+        inString = false
+      }
+      continue
+    }
+
+    if (ch === '"') {
+      inString = true
+      continue
+    }
+
+    if (ch === '{') {
+      if (depth === 0) start = i
+      depth++
+      continue
+    }
+
+    if (ch === '}') {
+      if (depth > 0) depth--
+      if (depth === 0 && start >= 0) {
+        chunks.push(text.slice(start, i + 1))
+        start = -1
+      }
+    }
+  }
+
+  return chunks
+}
+
+/**
+ * Parse canvas event text into an array of event objects.
+ * Blank lines and malformed JSON snippets are skipped.
+ *
+ * @param {string} text - Raw canvas event file contents
+ * @returns {object[]} Parsed event objects
+ */
+export function parseCanvasJsonl(text) {
+  const events = []
+  for (const snippet of splitJsonObjects(text || '')) {
+    try {
+      events.push(JSON.parse(snippet))
+    } catch {
+      // Skip malformed snippets
+    }
+  }
+  return events
+}
+
+/**
+ * Materialize a canvas state from an ordered array of events.
+ *
+ * @param {object[]} events - Array of event objects (first should be canvas_created)
+ * @returns {object} Materialized canvas state
+ */
+export function materialize(events) {
+  let state = {}
+
+  for (const evt of events) {
+    switch (evt.event) {
+      case 'canvas_created': {
+        // Strip event metadata, keep everything else as initial state
+        const initial = { ...evt }
+        delete initial.event
+        delete initial.timestamp
+        if (!initial.connectors) initial.connectors = []
+        state = initial
+        break
+      }
+
+      case 'widget_added': {
+        if (!state.widgets) state.widgets = []
+        state.widgets = [...state.widgets, evt.widget]
+        break
+      }
+
+      case 'widget_updated': {
+        state.widgets = (state.widgets || []).map((w) =>
+          w.id === evt.widgetId
+            ? { ...w, props: { ...w.props, ...evt.props } }
+            : w,
+        )
+        break
+      }
+
+      case 'widget_moved': {
+        state.widgets = (state.widgets || []).map((w) =>
+          w.id === evt.widgetId ? { ...w, position: evt.position } : w,
+        )
+        break
+      }
+
+      case 'widget_removed': {
+        state.widgets = (state.widgets || []).filter(
+          (w) => w.id !== evt.widgetId,
+        )
+        // Cascade: remove connectors referencing the deleted widget
+        if (state.connectors?.length) {
+          state.connectors = state.connectors.filter(
+            (c) => c.start.widgetId !== evt.widgetId && c.end.widgetId !== evt.widgetId,
+          )
+        }
+        break
+      }
+
+      case 'settings_updated': {
+        if (evt.settings) {
+          const { ...rest } = state
+          Object.assign(rest, evt.settings)
+          state = rest
+        }
+        break
+      }
+
+      case 'source_updated': {
+        state.sources = evt.sources
+        break
+      }
+
+      case 'widgets_replaced': {
+        state.widgets = evt.widgets
+        // Orphan cleanup: remove connectors referencing deleted widgets
+        if (state.connectors?.length) {
+          const widgetIds = new Set((state.widgets || []).map((w) => w.id))
+          state.connectors = state.connectors.filter(
+            (c) => widgetIds.has(c.start.widgetId) && widgetIds.has(c.end.widgetId),
+          )
+        }
+        break
+      }
+
+      case 'connector_added': {
+        if (!state.connectors) state.connectors = []
+        state.connectors = [...state.connectors, evt.connector]
+        break
+      }
+
+      case 'connector_removed': {
+        state.connectors = (state.connectors || []).filter(
+          (c) => c.id !== evt.connectorId,
+        )
+        break
+      }
+
+      case 'connectors_replaced': {
+        state.connectors = evt.connectors || []
+        break
+      }
+
+      case 'connector_updated': {
+        state.connectors = (state.connectors || []).map((c) => {
+          if (c.id !== evt.connectorId) return c
+          const { startAnchor, endAnchor, meta, ...rest } = evt.updates || {}
+          // Deep-merge meta so per-widget messaging settings accumulate
+          const mergedMeta = { ...(c.meta || {}), ...(meta || {}) }
+          if (meta?.messaging) {
+            mergedMeta.messaging = { ...(c.meta?.messaging || {}), ...meta.messaging }
+          }
+          // Clear messagingMode if explicitly set to null (switching from two-way to per-widget)
+          if (meta && meta.messagingMode === null) {
+            delete mergedMeta.messagingMode
+          }
+          // Apply anchor updates if provided, preserving widget connections
+          const start = startAnchor
+            ? { ...c.start, anchor: startAnchor }
+            : c.start
+          const end = endAnchor
+            ? { ...c.end, anchor: endAnchor }
+            : c.end
+          return { ...c, ...rest, meta: mergedMeta, id: c.id, start, end }
+        })
+        break
+      }
+
+      // Unknown events are silently ignored (forward compatibility)
+    }
+  }
+
+  // Derive connectorIds on widgets from the connectors array
+  if (state.connectors?.length && state.widgets?.length) {
+    // Build a map: widgetId → Set of connectorIds
+    const widgetConnMap = new Map()
+    for (const conn of state.connectors) {
+      for (const endpoint of [conn.start, conn.end]) {
+        if (!widgetConnMap.has(endpoint.widgetId)) {
+          widgetConnMap.set(endpoint.widgetId, new Set())
+        }
+        widgetConnMap.get(endpoint.widgetId).add(conn.id)
+      }
+    }
+    state.widgets = state.widgets.map((w) => {
+      const ids = widgetConnMap.get(w.id)
+      return ids ? { ...w, connectorIds: [...ids] } : w
+    })
+  }
+
+  return state
+}
+
+/**
+ * Convenience: parse JSONL text and materialize in one step.
+ *
+ * @param {string} text - Raw JSONL file contents
+ * @returns {object} Materialized canvas state
+ */
+export function materializeFromText(text) {
+  return materialize(parseCanvasJsonl(text))
+}
+
+/**
+ * Serialize a single event object to a JSONL line (no trailing newline).
+ *
+ * @param {object} event - Event object
+ * @returns {string} Single-line JSON string
+ */
+export function serializeEvent(event) {
+  return JSON.stringify(event)
+}