@devbycrux/editor 0.1.0

package/src/preview/__tests__/OverlayPreview.test.tsx

@@ -0,0 +1,169 @@
+/**
+ * editor-core/preview/OverlayPreview — unit tests.
+ *
+ * The overlay compiler is injected via the `compileOverlay` prop so no module
+ * mock is needed. Each test passes its own fake compiler directly.
+ */
+
+import React from 'react'
+import { render, screen, waitFor } from '@testing-library/react'
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest'
+import type { OverlayFactory } from '../../types'
+
+// ── Import component under test ──────────────────────────────────────────────
+
+import { OverlayPreview } from '../OverlayPreview'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Factory that returns a simple div with a test id. */
+const trivialFactory: OverlayFactory = (_frame, _fps, _duration, _props) =>
+  React.createElement('div', { 'data-testid': 'overlay-output' }, 'hello overlay')
+
+/** A compileOverlay prop that always resolves with the given factory. */
+const makeCompiler =
+  (factory: OverlayFactory) =>
+  (_template: string): Promise<OverlayFactory> =>
+    Promise.resolve(factory)
+
+/** A compileOverlay prop that always rejects with the given error. */
+const makeFailingCompiler =
+  (message: string) =>
+  (_template: string): Promise<OverlayFactory> =>
+    Promise.reject(new Error(message))
+
+/** A compileOverlay prop that never resolves (simulates in-flight). */
+const pendingCompiler = (_template: string): Promise<OverlayFactory> =>
+  new Promise(() => {})
+
+const DEFAULT_PROPS = {
+  template: '/path/to/overlay.jsx',
+  props: { text: 'hi' },
+  frame: 0,
+  fps: 30,
+  duration: 60,
+  compileOverlay: makeCompiler(trivialFactory),
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('OverlayPreview', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('shows a loading state while compiling', async () => {
+    render(<OverlayPreview {...DEFAULT_PROPS} compileOverlay={pendingCompiler} />)
+
+    expect(screen.getByRole('status')).toBeInTheDocument()
+  })
+
+  it('renders the factory output when compilation succeeds', async () => {
+    render(<OverlayPreview {...DEFAULT_PROPS} />)
+
+    await waitFor(() =>
+      expect(screen.getByTestId('overlay-output')).toBeInTheDocument(),
+    )
+    expect(screen.getByTestId('overlay-output')).toHaveTextContent('hello overlay')
+  })
+
+  it('passes frame/fps/duration/props to the factory', async () => {
+    const factorySpy = vi.fn(trivialFactory)
+
+    render(
+      <OverlayPreview
+        template="/t.jsx"
+        props={{ color: 'red' }}
+        frame={12}
+        fps={24}
+        duration={90}
+        compileOverlay={makeCompiler(factorySpy)}
+      />,
+    )
+
+    await waitFor(() => expect(factorySpy).toHaveBeenCalled())
+    expect(factorySpy).toHaveBeenCalledWith(12, 24, 90, expect.objectContaining({ color: 'red' }))
+  })
+
+  it('surfaces an error badge when compileOverlay rejects', async () => {
+    render(
+      <OverlayPreview
+        {...DEFAULT_PROPS}
+        compileOverlay={makeFailingCompiler('bad JSX syntax')}
+      />,
+    )
+
+    await waitFor(() =>
+      expect(screen.getByRole('alert')).toBeInTheDocument(),
+    )
+    const alert = screen.getByRole('alert')
+    expect(alert).toBeInTheDocument()
+  })
+
+  it('surfaces an error badge when the factory throws at render time', async () => {
+    const throwingFactory: OverlayFactory = () => {
+      throw new Error('runtime render error')
+    }
+
+    render(
+      <OverlayPreview
+        {...DEFAULT_PROPS}
+        compileOverlay={makeCompiler(throwingFactory)}
+      />,
+    )
+
+    await waitFor(() =>
+      expect(screen.getByRole('alert')).toBeInTheDocument(),
+    )
+  })
+
+  it('re-compiles when template changes', async () => {
+    const factory1: OverlayFactory = () =>
+      React.createElement('div', { 'data-testid': 'v1' }, 'v1')
+    const factory2: OverlayFactory = () =>
+      React.createElement('div', { 'data-testid': 'v2' }, 'v2')
+
+    const compilerSpy = vi.fn()
+    compilerSpy.mockResolvedValueOnce(factory1).mockResolvedValueOnce(factory2)
+
+    const { rerender } = render(
+      <OverlayPreview {...DEFAULT_PROPS} template="/overlay-v1.jsx" compileOverlay={compilerSpy} />,
+    )
+    await waitFor(() => expect(screen.getByTestId('v1')).toBeInTheDocument())
+
+    rerender(<OverlayPreview {...DEFAULT_PROPS} template="/overlay-v2.jsx" compileOverlay={compilerSpy} />)
+    await waitFor(() => expect(screen.getByTestId('v2')).toBeInTheDocument())
+
+    expect(compilerSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('accepts a custom loading node', async () => {
+    render(
+      <OverlayPreview
+        {...DEFAULT_PROPS}
+        compileOverlay={pendingCompiler}
+        loading={<div data-testid="custom-loading">Loading…</div>}
+      />,
+    )
+
+    expect(screen.getByTestId('custom-loading')).toBeInTheDocument()
+  })
+
+  it('accepts a custom errorState node', async () => {
+    render(
+      <OverlayPreview
+        {...DEFAULT_PROPS}
+        compileOverlay={makeFailingCompiler('boom')}
+        errorState={<div data-testid="custom-error">Error!</div>}
+      />,
+    )
+
+    await waitFor(() =>
+      expect(screen.getByTestId('custom-error')).toBeInTheDocument(),
+    )
+  })
+})

package/src/schema.ts

@@ -0,0 +1,194 @@
+// Editor-facing schema for the @devbycrux/editor package.
+//
+// These types describe the slice of a Montaj project the carousel editor reads
+// and writes. They are intentionally self-contained: the package owns no
+// pipeline/agent types and depends on nothing from Montaj. The host app
+// (Montaj, Hub, …) extends EditorProject with its own pipeline fields.
+
+export interface Word {
+  word: string
+  start: number
+  end: number
+}
+
+export interface AudioTrack {
+  id: string
+  type?: 'voiceover' | 'music' | 'sfx' | 'audio'
+  src: string
+  start: number          // position on project timeline (seconds)
+  end: number
+  volume?: number        // 0.0–2.0, default 1.0
+  inPoint?: number       // offset into source file (seconds)
+  outPoint?: number      // end offset in source file (seconds)
+  label?: string         // display name, defaults to filename
+  muted?: boolean
+  ducking?: {
+    enabled: boolean
+    depth?: number       // dB, default -12
+    attack?: number      // seconds, default 0.3
+    release?: number     // seconds, default 0.5
+  }
+  fadeIn?: number          // fade-in duration in seconds (0 = no fade)
+  fadeOut?: number         // fade-out duration in seconds (0 = no fade)
+  sourceDuration?: number  // intrinsic duration of the source file in seconds
+  lane?: number            // visual grouping — tracks sharing a lane render in the same row
+}
+
+export interface CaptionSegment {
+  id?: string
+  text: string
+  start: number
+  end: number
+  words?: Word[]
+}
+
+export interface Captions {
+  style: 'word-by-word' | 'pop' | 'karaoke' | 'subtitle'
+  segments: CaptionSegment[]
+  // ffmpeg-drawtext render params — ignored by JSX preview, used by render.js ffmpeg branch
+  position?: 'center' | 'top-left' | 'bottom-left'
+  color?: string
+  fontsize?: number
+  bgColor?: string
+}
+
+export interface VisualItem {
+  id: string
+  type: 'overlay' | 'image' | 'video'
+  src?: string
+  start: number
+  end: number
+  sourceDuration?: number     // video type only — used for right-edge drag guard
+  inPoint?: number            // video type only
+  outPoint?: number           // video type only
+  loop?: boolean              // video type only — loop source clip within project window
+  transition?: { type: string; duration: number }  // video type only — transition into next clip
+  offsetX?: number
+  offsetY?: number
+  scale?: number
+  opacity?: number        // 0.0–1.0
+  fit?: 'cover' | 'contain' | 'fill'  // image type only — how the source fills its box. Default 'cover' (AR-preserving fill+crop). 'contain' letterboxes; 'fill' is legacy stretch (no AR).
+  volume?: number         // video audio level 0.0–2.0, default 1.0 (ignored for images)
+  rotation?: number       // degrees, clockwise
+  opaque?: boolean        // legacy boolean kept for old overlay items
+  props?: Record<string, unknown>  // overlay type only
+  googleFonts?: string[]  // overlay type only — Google Fonts family specs (e.g. ["Syne:wght@800"])
+  remove_bg?: boolean     // video type only
+  nobg_src?: string         // video type only — ProRes 4444 .mov for final render
+  nobg_preview_src?: string // video type only — VP9 WebM with alpha for browser preview
+  muted?: boolean         // video type only — suppress audio in preview and render
+  generation?: {            // ai_video only — frozen provenance from Kling generation
+    // Single-shot fields (present when multiShot is falsy).
+    sceneId?: string
+    prompt?: string
+    refImages?: string[]
+    duration?: number
+    // Shared fields.
+    provider?: string
+    model?: string
+    attempts?: Array<{ ts: string; prompt: string; src: string }>
+    eval?: {
+      pass: boolean
+      scores: Record<string, number>
+      attempt: number
+    }
+    // Multi-shot / batched fields. When multiShot is true, the clip represents a
+    // batch of up to 6 scenes generated in ONE Kling call. The outer sceneId/
+    // prompt/refImages fields are replaced by batchShots[] which carries the
+    // per-scene mapping inside the concatenated output video.
+    multiShot?: boolean
+    shotType?: 'customize' | 'intelligence'
+    batchShots?: Array<{
+      sceneId: string
+      index: number          // 1-based, matches Kling's multi_prompt[].index
+      prompt: string         // combined prompt for this shot (styleAnchor + scene prose + tokens)
+      start: number          // shot start, seconds, RELATIVE to the batch clip
+      end: number            // shot end, seconds, RELATIVE to the batch clip
+      duration: number
+    }>
+  }
+  // Legacy fields for old text overlay items (pre-schema migration)
+  position?: string
+  text?: string
+}
+
+export interface Asset {
+  id: string
+  src: string
+  type: 'image'
+  name?: string
+}
+
+// ── Carousel types ─────────────────────────────────────────────────────────
+export interface ImageElement {
+  id: string
+  type: 'image'
+  src: string
+  x: number
+  y: number
+  w: number
+  h: number
+  rotation: number
+  /**
+   * Optional non-destructive crop expressed as a sub-rectangle of the source
+   * image in 0–1 fractions. The editor (mission-control) is the sole enforcer
+   * of the aspect-lock invariant (crop pixel aspect == element pixel aspect);
+   * the server validates only bounds. The renderer's object-fit: cover acts as
+   * a graceful-degradation safety net when the invariant is violated by a
+   * manual project.json edit. Absent = no crop = current behavior.
+   */
+  crop?: { x: number; y: number; w: number; h: number }
+  /**
+   * Optional passthrough field used by host apps (e.g. Hub) to link this
+   * image element to an external media record. Montaj preserves the value
+   * through load→save round-trips but never interprets it; the host app's
+   * adapter (e.g. resolveImageSrc) is responsible for resolving the actual URL.
+   */
+  mediaId?: string
+}
+
+export interface OverlayElement {
+  id: string
+  type: 'overlay'
+  overlay: { template: string; props: Record<string, unknown> }
+  frame: number
+  x: number
+  y: number
+  w: number
+  h: number
+  rotation: number
+}
+
+export type CarouselElement = ImageElement | OverlayElement
+
+export interface Slide {
+  id: string
+  base_color: string
+  elements: CarouselElement[]
+}
+
+/**
+ * The editor-facing view of a Montaj project. Captures only the fields the
+ * carousel editor reads or writes. Field types mirror the host Project
+ * interface exactly so that a full host Project is assignable to EditorProject.
+ *
+ * The index signature lets host-only / pipeline fields (workflow, storyboard,
+ * regenQueue, version, …) pass through at the type level without the package
+ * needing to know about them.
+ */
+export interface EditorProject {
+  id: string
+  status: 'pending' | 'storyboard_ready' | 'draft' | 'final'
+  settings: { resolution: [number, number]; fps?: number; brandKit?: string }
+  name?: string | null
+  editingPrompt?: string
+  slides?: Slide[]
+  tracks?: VisualItem[][]
+  captions?: Captions
+  audio?: { tracks: AudioTrack[] }
+  assets?: Asset[]
+  carousel?: { aspect: string }
+  profile?: string
+  // Host-only / pipeline fields pass through at the type level.
+  [key: string]: unknown
+}