@devbycrux/editor 0.1.0

package/src/state/__tests__/use-project-state.test.tsx

@@ -0,0 +1,258 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { useProjectState } from '../use-project-state'
+import type { EditorAdapter, Project, ImageElement, RenderEvent } from '../../types'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function makeProject(overrides: Partial<Project> = {}): Project {
+  return {
+    version: '1',
+    id: 'proj-1',
+    name: 'Test Project',
+    workflow: 'carousel',
+    status: 'draft', // editable so mutations are not gated out
+    editingPrompt: '',
+    settings: { resolution: [1080, 1080] },
+    assets: [],
+    slides: [
+      {
+        id: 'slide-0',
+        base_color: '#ffffff',
+        elements: [
+          { id: 'el-0', type: 'image', src: 'a.png', x: 0, y: 0, w: 100, h: 100, rotation: 0 },
+          {
+            id: 'el-1',
+            type: 'overlay',
+            overlay: { template: 't', props: { text: 'hi' } },
+            frame: 0,
+            x: 0,
+            y: 0,
+            w: 50,
+            h: 50,
+            rotation: 0,
+          },
+        ],
+      },
+    ],
+    ...overrides,
+  }
+}
+
+interface FakeAdapter extends EditorAdapter {
+  emit: (p: Project) => void
+  saveCalls: Array<{ id: string; project: Project }>
+}
+
+function makeFakeAdapter(opts: { failSave?: boolean } = {}): FakeAdapter {
+  let onFrame: ((p: Project) => void) | null = null
+  const saveCalls: Array<{ id: string; project: Project }> = []
+  return {
+    loadProject: vi.fn(async () => makeProject()),
+    saveProject: vi.fn(async (id: string, project: Project) => {
+      saveCalls.push({ id, project })
+      if (opts.failSave) throw new Error('save boom')
+    }),
+    subscribe: (_id: string, cb: (p: Project) => void) => {
+      onFrame = cb
+      return () => { onFrame = null }
+    },
+    render: async function* (): AsyncIterable<RenderEvent> {
+      yield { type: 'done', outputPath: '/out.png' }
+    },
+    resolveImageSrc: (el: ImageElement) => el.src,
+    compileOverlay: vi.fn(async () => () => null),
+    listGlobalOverlays: vi.fn(async () => []),
+    listSystemOverlays: vi.fn(async () => []),
+    uploadFile: vi.fn(async () => '/path'),
+    fileUrl: (path: string) => path,
+    emit: (p: Project) => onFrame?.(p),
+    saveCalls,
+  }
+}
+
+beforeEach(() => { vi.spyOn(console, 'warn').mockImplementation(() => {}) })
+afterEach(() => { vi.restoreAllMocks() })
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('useProjectState — adapter wiring', () => {
+  it('optimistically applies a mutation and persists via adapter.saveProject', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectState(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.updateOverlayProp('slide-0', 'el-1', 'text', 'bye')
+    })
+
+    // Optimistic local state updated.
+    const el = result.current.project.slides![0].elements[1]
+    expect(el.type === 'overlay' && el.overlay.props.text).toBe('bye')
+    // Persisted through the adapter, not a hardcoded fetch.
+    expect(adapter.saveProject).toHaveBeenCalledTimes(1)
+    expect(adapter.saveCalls[0].id).toBe('proj-1')
+  })
+
+  it('rolls back optimistic state and surfaces lastError when saveProject fails', async () => {
+    const adapter = makeFakeAdapter({ failSave: true })
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectState(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.updateOverlayProp('slide-0', 'el-1', 'text', 'bye').catch(() => {})
+    })
+
+    const el = result.current.project.slides![0].elements[1]
+    // Rolled back to original value.
+    expect(el.type === 'overlay' && el.overlay.props.text).toBe('hi')
+    expect(result.current.lastError).toMatch(/save boom/)
+  })
+
+  it('applies SSE frames pushed through adapter.subscribe', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectState(adapter, initial.id, initial))
+
+    const frame = makeProject({ name: 'From Server', status: 'final' })
+    act(() => { adapter.emit(frame) })
+
+    await waitFor(() => {
+      expect(result.current.project.name).toBe('From Server')
+      expect(result.current.connection).toBe('live')
+    })
+  })
+
+  it('undo/redo swap state and re-persist via adapter', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectState(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.setName('Renamed')
+    })
+    expect(result.current.project.name).toBe('Renamed')
+    expect(result.current.canUndo).toBe(true)
+
+    await act(async () => { result.current.undo() })
+    expect(result.current.project.name).toBe('Test Project')
+    expect(result.current.canRedo).toBe(true)
+
+    await act(async () => { result.current.redo() })
+    expect(result.current.project.name).toBe('Renamed')
+
+    // mutate save + undo save + redo save
+    await waitFor(() => expect(adapter.saveProject).toHaveBeenCalledTimes(3))
+  })
+
+  it('commit persists one save after transient gesture mutations', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectState(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.moveElement('slide-0', 'el-0', 10, 20)
+      await result.current.moveElement('slide-0', 'el-0', 30, 40)
+    })
+    // Transient moves do not save.
+    expect(adapter.saveProject).not.toHaveBeenCalled()
+    const moved = result.current.project.slides![0].elements[0]
+    expect(moved.x).toBe(30)
+    expect(moved.y).toBe(40)
+
+    await act(async () => { await result.current.commit() })
+    expect(adapter.saveProject).toHaveBeenCalledTimes(1)
+    expect(result.current.canUndo).toBe(true)
+  })
+
+  it('unsubscribes on unmount', () => {
+    const adapter = makeFakeAdapter()
+    const unsub = vi.fn()
+    adapter.subscribe = (_id, _cb) => unsub
+    const initial = makeProject()
+    const { unmount } = renderHook(() => useProjectState(adapter, initial.id, initial))
+    unmount()
+    expect(unsub).toHaveBeenCalledTimes(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Status gating — slide-CRUD actions are no-ops when project is not editable
+// ---------------------------------------------------------------------------
+
+describe('useProjectState — addSlide is status-gated', () => {
+  it('no-ops addSlide and does not save when project status is "pending"', async () => {
+    const adapter = makeFakeAdapter()
+    // Override loadProject to return a pending project, but we pass initial directly
+    const initial = makeProject({ status: 'pending' })
+    const { result } = renderHook(() => useProjectState(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.addSlide({
+        id: 'slide-new',
+        base_color: '#ff0000',
+        elements: [],
+      })
+    })
+
+    // State must not have gained a slide
+    expect(result.current.project.slides).toHaveLength(initial.slides!.length)
+    // Adapter must not have been asked to save
+    expect(adapter.saveProject).not.toHaveBeenCalled()
+  })
+
+  it('no-ops addSlide when project status is "storyboard_ready"', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject({ status: 'storyboard_ready' })
+    const { result } = renderHook(() => useProjectState(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.addSlide({
+        id: 'slide-new',
+        base_color: '#0000ff',
+        elements: [],
+      })
+    })
+
+    expect(result.current.project.slides).toHaveLength(initial.slides!.length)
+    expect(adapter.saveProject).not.toHaveBeenCalled()
+  })
+
+  it('allows addSlide when project status is "draft"', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject({ status: 'draft' })
+    const { result } = renderHook(() => useProjectState(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.addSlide({
+        id: 'slide-new',
+        base_color: '#00ff00',
+        elements: [],
+      })
+    })
+
+    expect(result.current.project.slides).toHaveLength(initial.slides!.length + 1)
+    expect(adapter.saveProject).toHaveBeenCalledTimes(1)
+  })
+
+  it('allows addSlide when project status is "final"', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject({ status: 'final' })
+    const { result } = renderHook(() => useProjectState(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.addSlide({
+        id: 'slide-new',
+        base_color: '#00ff00',
+        elements: [],
+      })
+    })
+
+    expect(result.current.project.slides).toHaveLength(initial.slides!.length + 1)
+    expect(adapter.saveProject).toHaveBeenCalledTimes(1)
+  })
+})

package/src/state/mutation-queue.ts

@@ -0,0 +1,62 @@
+/**
+ * editor-core / state / mutation-queue — serialises async mutations.
+ *
+ * Ported from mission-control's inline `createMutationQueue`
+ * (src/app/admin/projects/hooks/project-reducer.ts). Extracted into its own
+ * module here so the optimistic project-state hook and the reducer stay
+ * separable.
+ *
+ * The queue guarantees that enqueued functions START in submission order
+ * (each waits for the previous to settle), while preserving the caller's own
+ * rejection handling on the returned promise. `onceDrained` lets the SSE
+ * handler defer applying server echoes until in-flight PUTs have all settled.
+ */
+export interface MutationQueue {
+  /** Enqueue an async op; it starts only after all prior ops have settled. */
+  enqueue<T>(fn: () => Promise<T>): Promise<T>
+  /** True while one or more ops are in flight. */
+  isPending(): boolean
+  /**
+   * Run `cb` the next time the queue transitions busy → idle. If already idle,
+   * `cb` runs on the next microtask. Last-writer-wins: only the most recent
+   * caller is notified, so a burst of SSE frames coalesces into one dispatch.
+   */
+  onceDrained(cb: () => void): void
+}
+
+export function createMutationQueue(): MutationQueue {
+  let tail: Promise<unknown> = Promise.resolve()
+  let pending = 0
+  let onDrain: (() => void) | null = null
+  return {
+    enqueue<T>(fn: () => Promise<T>): Promise<T> {
+      pending++
+      const next = tail.catch(() => undefined).then(() => fn())
+      // Chain the decrement onto the swallowed `tail`, NOT onto `next`. The
+      // caller's rejection handling lives on `next`; adding a .finally() to
+      // `next` here would create a parallel promise chain that also receives
+      // the rejection — with no handler attached, that surfaces as an
+      // unhandled-rejection warning. Folding the decrement into `tail`
+      // preserves single-handler semantics for the caller.
+      tail = next.catch(() => undefined).then(() => {
+        pending--
+        if (pending === 0 && onDrain) {
+          const cb = onDrain
+          onDrain = null
+          cb()
+        }
+      })
+      return next
+    },
+    isPending(): boolean {
+      return pending > 0
+    },
+    onceDrained(cb: () => void): void {
+      if (pending === 0) {
+        Promise.resolve().then(cb)
+        return
+      }
+      onDrain = cb
+    },
+  }
+}

package/src/state/project-reducer.ts

@@ -0,0 +1,328 @@
+/**
+ * editor-core / state / project-reducer — pure reducer over a carousel Project.
+ *
+ * Ported faithfully from mission-control's
+ * `src/app/admin/projects/hooks/project-reducer.ts`, adapted to import the
+ * canonical Project/Slide/CarouselElement/ImageElement/OverlayElement types
+ * from editor-core (which re-exports Montaj's `lib/types/schema.ts`) rather
+ * than from a hand-mirrored `montaj.ts`.
+ *
+ * All action types and snapshot semantics are preserved. The reducer is pure —
+ * it never touches transport; persistence is the hook's job via the adapter.
+ */
+import type {
+  Project,
+  Slide,
+  ImageElement,
+  CarouselElement,
+} from '../types'
+
+// The reducer/Action are generic over the host's concrete project type `P`,
+// constrained to the editor-facing `Project` (= EditorProject) slice. A host can
+// pass its full project (e.g. Montaj's `Project` with pipeline fields) and get
+// the same concrete type back: every reducer branch spreads `state`, so host-
+// only fields round-trip at both the type level and at runtime. The editor only
+// ever reads/writes the editor-facing fields.
+
+// Status values from the editor-facing schema. Duplicated as a value here so
+// the hook can gate edits without importing the host's project types directly.
+export type ProjectStatus = Project['status']
+
+// ---------------------------------------------------------------------------
+// Action discriminated union
+// ---------------------------------------------------------------------------
+
+export type Action<P extends Project = Project> =
+  | { type: 'sse'; project: P }
+  | { type: 'updateOverlayProp'; slideId: string; elementId: string; key: string; value: string }
+  | { type: 'setStatus'; status: ProjectStatus }
+  | { type: 'setName'; name: string }
+  | { type: 'rollback'; snapshot: P }
+  | { type: 'moveElement'; slideId: string; elementId: string; x: number; y: number }
+  | { type: 'resizeElement'; slideId: string; elementId: string; x: number; y: number; w: number; h: number }
+  | { type: 'rotateElement'; slideId: string; elementId: string; rotation: number }
+  | { type: 'addElement'; slideId: string; element: CarouselElement }
+  | { type: 'removeElement'; slideId: string; elementId: string }
+  | { type: 'updateImageCrop'; slideId: string; elementId: string; crop: ImageElement['crop'] }
+  // Slide-level structural actions. Added for the Montaj-native editor, which —
+  // unlike mission-control's element-only inspector — owns full slide CRUD.
+  | { type: 'addSlide'; slide: Slide; afterSlideId?: string }
+  | { type: 'removeSlide'; slideId: string }
+  | { type: 'duplicateSlide'; slideId: string; newSlide: Slide }
+  | { type: 'reorderSlides'; fromIndex: number; toIndex: number }
+  | { type: 'updateSlide'; slideId: string; patch: Partial<Slide> }
+  // Element structural actions the editor needs beyond add/remove.
+  | { type: 'duplicateElement'; slideId: string; elementId: string; newElement: CarouselElement }
+  | { type: 'reorderElement'; slideId: string; elementId: string; direction: 'forward' | 'backward' }
+  | { type: 'setOverlayFrame'; slideId: string; elementId: string; frame: number }
+
+// ---------------------------------------------------------------------------
+// SSE merge helpers
+// ---------------------------------------------------------------------------
+
+// Structural equality. Used to decide whether to reuse a previous reference
+// in the SSE merge. Tree shape (project.json) is small, no cycles, no
+// special types — a recursive walk is fine and short-circuits early on mismatch.
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (typeof a !== typeof b) return false
+  if (a === null || b === null) return false
+  if (typeof a !== 'object') return false
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false
+    }
+    return true
+  }
+  if (Array.isArray(b)) return false
+  // Compare objects treating `undefined`-valued properties as absent. Required
+  // because the reducer writes `{...el, crop: undefined}` to clear a field,
+  // but the SSE echo round-trip serialises through Montaj's `json.dumps`,
+  // which drops undefined-valued keys. Without this normalisation, the
+  // identity short-circuit in mergeProject silently misses on every echo
+  // following an image resize.
+  const ao = a as Record<string, unknown>
+  const bo = b as Record<string, unknown>
+  const keys = new Set<string>()
+  for (const k of Object.keys(ao)) if (ao[k] !== undefined) keys.add(k)
+  for (const k of Object.keys(bo)) if (bo[k] !== undefined) keys.add(k)
+  for (const k of keys) {
+    if (!deepEqual(ao[k], bo[k])) return false
+  }
+  return true
+}
+
+function mergeElement(prev: CarouselElement, next: CarouselElement): CarouselElement {
+  return deepEqual(prev, next) ? prev : next
+}
+
+function mergeSlide(prev: Slide, next: Slide): Slide {
+  if (deepEqual(prev, next)) return prev
+  const prevElsById = new Map(prev.elements.map((e) => [e.id, e]))
+  let elementsChanged = next.elements.length !== prev.elements.length
+  const mergedElements = next.elements.map((nextEl, i): CarouselElement => {
+    const prevEl = prevElsById.get(nextEl.id)
+    if (!prevEl) { elementsChanged = true; return nextEl }
+    const merged = mergeElement(prevEl, nextEl)
+    if (merged !== prev.elements[i]) elementsChanged = true
+    return merged
+  })
+  return {
+    ...next,
+    elements: elementsChanged ? mergedElements : prev.elements,
+  }
+}
+
+function mergeProject<P extends Project>(prev: P, next: P): P {
+  if (prev === next || deepEqual(prev, next)) return prev
+  const prevSlides = prev.slides ?? []
+  const nextSlides = next.slides ?? []
+  const prevSlidesById = new Map(prevSlides.map((s) => [s.id, s]))
+  let slidesChanged = nextSlides.length !== prevSlides.length
+  const mergedSlides = nextSlides.map((nextSlide, i): Slide => {
+    const prevSlide = prevSlidesById.get(nextSlide.id)
+    if (!prevSlide) { slidesChanged = true; return nextSlide }
+    const merged = mergeSlide(prevSlide, nextSlide)
+    if (merged !== prevSlides[i]) slidesChanged = true
+    return merged
+  })
+  return {
+    ...next,
+    slides: slidesChanged ? mergedSlides : prevSlides,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pure reducer
+// ---------------------------------------------------------------------------
+
+export function projectReducer<P extends Project>(state: P, action: Action<P>): P {
+  switch (action.type) {
+    case 'sse':
+      return mergeProject(state, action.project)
+
+    case 'updateOverlayProp': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        const elements = slide.elements.map((el): CarouselElement => {
+          if (el.id !== action.elementId) return el
+          if (el.type !== 'overlay') return el
+          return {
+            ...el,
+            overlay: {
+              ...el.overlay,
+              props: {
+                ...el.overlay.props,
+                [action.key]: action.value,
+              },
+            },
+          }
+        })
+        return { ...slide, elements }
+      })
+      return { ...state, slides }
+    }
+
+    case 'setStatus':
+      return { ...state, status: action.status }
+
+    case 'setName':
+      return { ...state, name: action.name }
+
+    case 'rollback':
+      return action.snapshot
+
+    case 'moveElement': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        const elements = slide.elements.map((el): CarouselElement => {
+          if (el.id !== action.elementId) return el
+          return { ...el, x: action.x, y: action.y }
+        })
+        return { ...slide, elements }
+      })
+      return { ...state, slides }
+    }
+
+    case 'resizeElement': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        const elements = slide.elements.map((el): CarouselElement => {
+          if (el.id !== action.elementId) return el
+          return { ...el, x: action.x, y: action.y, w: action.w, h: action.h }
+        })
+        return { ...slide, elements }
+      })
+      return { ...state, slides }
+    }
+
+    case 'rotateElement': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        const elements = slide.elements.map((el): CarouselElement => {
+          if (el.id !== action.elementId) return el
+          return { ...el, rotation: action.rotation }
+        })
+        return { ...slide, elements }
+      })
+      return { ...state, slides }
+    }
+
+    case 'addElement': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        return { ...slide, elements: [...slide.elements, action.element] }
+      })
+      return { ...state, slides }
+    }
+
+    case 'removeElement': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        return { ...slide, elements: slide.elements.filter((el) => el.id !== action.elementId) }
+      })
+      return { ...state, slides }
+    }
+
+    case 'updateImageCrop': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        const elements = slide.elements.map((el): CarouselElement => {
+          if (el.id !== action.elementId) return el
+          if (el.type !== 'image') return el
+          return { ...el, crop: action.crop }
+        })
+        return { ...slide, elements }
+      })
+      return { ...state, slides }
+    }
+
+    case 'addSlide': {
+      const slides = [...(state.slides ?? [])]
+      if (action.afterSlideId) {
+        const idx = slides.findIndex((s) => s.id === action.afterSlideId)
+        if (idx >= 0) slides.splice(idx + 1, 0, action.slide)
+        else slides.push(action.slide)
+      } else {
+        slides.push(action.slide)
+      }
+      return { ...state, slides }
+    }
+
+    case 'removeSlide': {
+      const slides = (state.slides ?? []).filter((s) => s.id !== action.slideId)
+      return { ...state, slides }
+    }
+
+    case 'duplicateSlide': {
+      const slides = [...(state.slides ?? [])]
+      const idx = slides.findIndex((s) => s.id === action.slideId)
+      if (idx < 0) return state
+      slides.splice(idx + 1, 0, action.newSlide)
+      return { ...state, slides }
+    }
+
+    case 'reorderSlides': {
+      const slides = [...(state.slides ?? [])]
+      if (
+        action.fromIndex < 0 || action.fromIndex >= slides.length ||
+        action.toIndex < 0 || action.toIndex >= slides.length
+      ) {
+        return state
+      }
+      const [moved] = slides.splice(action.fromIndex, 1)
+      slides.splice(action.toIndex, 0, moved)
+      return { ...state, slides }
+    }
+
+    case 'updateSlide': {
+      const slides = (state.slides ?? []).map((slide): Slide =>
+        slide.id === action.slideId ? { ...slide, ...action.patch } : slide,
+      )
+      return { ...state, slides }
+    }
+
+    case 'duplicateElement': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        const idx = slide.elements.findIndex((el) => el.id === action.elementId)
+        if (idx < 0) return slide
+        const elements = [
+          ...slide.elements.slice(0, idx + 1),
+          action.newElement,
+          ...slide.elements.slice(idx + 1),
+        ]
+        return { ...slide, elements }
+      })
+      return { ...state, slides }
+    }
+
+    case 'reorderElement': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        const elements = [...slide.elements]
+        const idx = elements.findIndex((el) => el.id === action.elementId)
+        if (idx < 0) return slide
+        const swapIdx = action.direction === 'forward' ? idx + 1 : idx - 1
+        if (swapIdx < 0 || swapIdx >= elements.length) return slide
+        ;[elements[idx], elements[swapIdx]] = [elements[swapIdx], elements[idx]]
+        return { ...slide, elements }
+      })
+      return { ...state, slides }
+    }
+
+    case 'setOverlayFrame': {
+      const slides = (state.slides ?? []).map((slide): Slide => {
+        if (slide.id !== action.slideId) return slide
+        const elements = slide.elements.map((el): CarouselElement => {
+          if (el.id !== action.elementId) return el
+          if (el.type !== 'overlay') return el
+          return { ...el, frame: action.frame }
+        })
+        return { ...slide, elements }
+      })
+      return { ...state, slides }
+    }
+  }
+}