@devbycrux/editor 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+# @devbycrux/editor
+
+Host-agnostic carousel editor for the ByCrux platform. Ships raw TypeScript/TSX source — the consuming application is responsible for transpilation.
+
+The package owns:
+- The editor-facing project/slide/element schema (`./schema`)
+- The `EditorAdapter` and `EditorTheme` contracts
+- All editor UI components (carousel editor, crop, text formatting, overlay preview)
+- State management (reducer + mutation queue + `useProjectState`)
+
+**Video editing is not yet included** — that is a future phase. Today the package covers carousel slides only.
+
+---
+
+## Install
+
+The package is published publicly to the npm registry under the `@devbycrux` org.
+
+```bash
+npm install @devbycrux/editor
+```
+
+---
+
+## Required consumer configuration
+
+The package ships raw source and uses Tailwind utility classes internally. Consumers must configure three things.
+
+### 1. Tailwind content glob
+
+Add the package source to your Tailwind `content` array so utility classes are not purged:
+
+```ts
+// tailwind.config.ts
+export default {
+  content: [
+    './src/**/*.{ts,tsx}',
+    'node_modules/@devbycrux/editor/src/**/*.{ts,tsx}', // required
+  ],
+  // ...
+}
+```
+
+### 2. React deduplication (Vite)
+
+The package lists `react` and `react-dom` as peer dependencies. In a Vite project, deduplicate them to guarantee a single React instance:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  resolve: {
+    dedupe: ['react', 'react-dom'],
+  },
+  optimizeDeps: {
+    include: ['@devbycrux/editor'],
+  },
+})
+```
+
+### 3. Next.js transpilePackages
+
+For Next.js consumers, add the package to `transpilePackages` so Next's compiler handles the raw TypeScript source:
+
+```ts
+// next.config.ts
+const nextConfig = {
+  transpilePackages: ['@devbycrux/editor'],
+}
+export default nextConfig
+```
+
+---
+
+## Usage
+
+### Implementing an EditorAdapter
+
+The editor is host-agnostic. You supply an `EditorAdapter` that wires up your transport, auth, and URL resolution. The interface is generic over your concrete project type `P extends EditorProject`, so host-specific fields survive load→edit→save round-trips at the type level.
+
+**Required methods:**
+
+| Method | Description |
+|---|---|
+| `loadProject(id)` | Fetch the full project by id |
+| `saveProject(id, project)` | Persist the full project |
+| `subscribe(id, onFrame)` | Subscribe to live project frames (e.g. SSE); returns unsubscribe |
+| `render(id, opts?)` | Start a render; returns `AsyncIterable<RenderEvent>` |
+| `resolveImageSrc(element)` | Map an `ImageElement` to a displayable URL |
+| `compileOverlay(template)` | Compile a JSX overlay template → `OverlayFactory`; host-supplied (editor carries no overlay runtime / Three.js) |
+| `listGlobalOverlays()` | List workspace-wide overlay templates |
+| `listSystemOverlays()` | List built-in/system overlay templates |
+| `uploadFile(file, projectId?)` | Upload a file; returns a host-resolvable path |
+| `fileUrl(path)` | Map a raw host path to a fetchable URL (synchronous) |
+
+**Optional methods:**
+
+| Method | Description |
+|---|---|
+| `listMedia?(scope)` | List media items in the given scope (`universal` or `project`) |
+| `listProfileOverlays?(profileName)` | List overlay templates scoped to a named profile |
+| `getInfo?()` | Return host environment info (e.g. `root_skill_path`) |
+| `generateImage?(prompt, projectId)` | AI image generation; editor feature-detects presence |
+
+### Rendering the editor
+
+```tsx
+import { CarouselEditor } from '@devbycrux/editor'
+import type { EditorAdapter, EditorProject } from '@devbycrux/editor'
+
+// Your adapter wired to your host's transport
+const adapter: EditorAdapter = { /* ... */ }
+
+function MyEditorPage() {
+  const [project, setProject] = useState<EditorProject | null>(null)
+
+  return project ? (
+    <CarouselEditor
+      project={project}
+      adapter={adapter}
+      onProjectChange={setProject}
+      theme={myTheme}   // optional — defaults to Montaj dark theme
+      slots={mySlots}   // optional — inject host UI into editor slots
+    />
+  ) : null
+}
+```
+
+### EditorSlots
+
+The `slots` prop lets you inject host-specific UI into named regions inside the assembled editor:
+
+| Slot | Where it renders |
+|---|---|
+| `toolbarActions` | Editor toolbar action area |
+| `exportActions` | Export / render action area |
+| `assetsPanel` | Assets / media panel area |
+| `pendingStatus` | Pending/empty view; replaces default "Message your agent" copy (e.g. live agent progress) |
+
+### Generic project type
+
+If your host carries fields beyond `EditorProject`, pass your richer type through the generic:
+
+```ts
+interface MyProject extends EditorProject {
+  pipelineId: string
+  tenantId: string
+}
+
+const adapter: EditorAdapter<MyProject> = { /* ... */ }
+
+<CarouselEditor<MyProject>
+  project={myProject}
+  adapter={adapter}
+  onProjectChange={setMyProject}
+/>
+```
+
+Your extra fields survive the edit cycle without casts.
+
+---
+
+## Notes
+
+- `compileOverlay` is **always host-supplied**. The package carries no overlay runtime, no Three.js, and no Babel compiler. Montaj provides its own `lib/overlay-eval` implementation; Hub-side consumers will supply their own.
+- The `./schema` export (`import ... from '@devbycrux/editor/schema'`) is the single source of truth for project/slide/element shapes and can be imported independently of the React components.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@devbycrux/editor",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./schema": "./src/schema.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "class-variance-authority": "^0.7",
+    "clsx": "^2",
+    "lucide-react": "^0.400",
+    "tailwind-merge": "^2"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6",
+    "@testing-library/react": "^16",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^4",
+    "eslint": "^9",
+    "jsdom": "^26",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5",
+    "typescript-eslint": "^8.61.1",
+    "vitest": "^2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/adapter-contract.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect } from 'vitest'
+import type {
+  EditorAdapter,
+  RenderEvent,
+  RenderOptions,
+  MediaItem,
+  MediaScope,
+  GlobalOverlay,
+} from '../types'
+import type { EditorProject, ImageElement } from '../schema'
+
+// ── Full adapter contract ─────────────────────────────────────────────────────
+// A fake object implementing the FULL EditorAdapter<EditorProject> — every
+// required method, including the ones T4 adds — must type-check. This file
+// fails to compile if a required method is missing or mistyped.
+
+const project: EditorProject = {
+  version: '1',
+  id: 'p1',
+  status: 'draft' as EditorProject['status'],
+  name: 'Fake',
+  workflow: 'carousel',
+  editingPrompt: '',
+  settings: { resolution: [1080, 1080] },
+  assets: [],
+  slides: [],
+}
+
+const overlay: GlobalOverlay = {
+  name: 'caption',
+  description: 'A caption overlay',
+  props: [
+    { name: 'text', type: 'string', default: '', description: 'caption text' },
+    { name: 'color', type: 'color', default: '#fff' },
+  ],
+  jsxPath: '/overlays/caption.jsx',
+}
+
+// (a) FULL adapter: every required method present, optional ones present too.
+function makeFullAdapter(): EditorAdapter<EditorProject> {
+  return {
+    loadProject: async (_id: string): Promise<EditorProject> => project,
+    saveProject: async (_id: string, _p: EditorProject): Promise<void> => {},
+    subscribe: (_id: string, _onFrame: (p: EditorProject) => void): (() => void) =>
+      () => {},
+    render: async function* (
+      _id: string,
+      _opts?: RenderOptions,
+    ): AsyncIterable<RenderEvent> {
+      yield { type: 'done', outputPath: '/out/p1.mp4' }
+    },
+    resolveImageSrc: (el: ImageElement): string => el.src,
+    compileOverlay: async (_template: string) => () => null,
+    // New REQUIRED methods (T4).
+    listGlobalOverlays: async (): Promise<GlobalOverlay[]> => [overlay],
+    listSystemOverlays: async (): Promise<GlobalOverlay[]> => [],
+    uploadFile: async (_file: File, _projectId?: string): Promise<string> => '/path',
+    fileUrl: (path: string): string => `/api/files?path=${encodeURIComponent(path)}`,
+    // Optional methods present.
+    listMedia: async (_scope: MediaScope): Promise<MediaItem[]> => [],
+    listProfileOverlays: async (_profileName: string): Promise<GlobalOverlay[]> => [],
+    getInfo: async (): Promise<{ root_skill_path?: string }> => ({}),
+    generateImage: async (_prompt: string, _projectId: string): Promise<{ path: string }> => ({
+      path: '/gen.png',
+    }),
+  }
+}
+
+// (b) Minimal adapter: only required methods; optional ones omitted. Must still
+// type-check.
+function makeMinimalAdapter(): EditorAdapter<EditorProject> {
+  return {
+    loadProject: async (_id: string): Promise<EditorProject> => project,
+    saveProject: async (_id: string, _p: EditorProject): Promise<void> => {},
+    subscribe: (_id: string, _onFrame: (p: EditorProject) => void): (() => void) =>
+      () => {},
+    render: async function* (
+      _id: string,
+      _opts?: RenderOptions,
+    ): AsyncIterable<RenderEvent> {
+      yield { type: 'done', outputPath: '/out/p1.mp4' }
+    },
+    resolveImageSrc: (el: ImageElement): string => el.src,
+    compileOverlay: async (_template: string) => () => null,
+    listGlobalOverlays: async (): Promise<GlobalOverlay[]> => [],
+    listSystemOverlays: async (): Promise<GlobalOverlay[]> => [],
+    uploadFile: async (_file: File): Promise<string> => '/path',
+    fileUrl: (path: string): string => path,
+  }
+}
+
+describe('EditorAdapter full contract', () => {
+  it('a full adapter implements every required + optional method', () => {
+    const a = makeFullAdapter()
+    expect(typeof a.listGlobalOverlays).toBe('function')
+    expect(typeof a.listSystemOverlays).toBe('function')
+    expect(typeof a.uploadFile).toBe('function')
+    expect(typeof a.fileUrl).toBe('function')
+    expect(typeof a.listProfileOverlays).toBe('function')
+    expect(typeof a.getInfo).toBe('function')
+    expect(typeof a.generateImage).toBe('function')
+  })
+
+  it('a minimal adapter omits the optional methods and still type-checks', () => {
+    const a = makeMinimalAdapter()
+    expect(a.listProfileOverlays).toBeUndefined()
+    expect(a.getInfo).toBeUndefined()
+    expect(a.generateImage).toBeUndefined()
+    expect(typeof a.listGlobalOverlays).toBe('function')
+  })
+
+  it('listGlobalOverlays resolves to GlobalOverlay[]', async () => {
+    const a = makeFullAdapter()
+    const overlays = await a.listGlobalOverlays()
+    expect(overlays[0].name).toBe('caption')
+    expect(overlays[0].props[0].type).toBe('string')
+  })
+
+  it('fileUrl maps a path to a string url', () => {
+    const a = makeFullAdapter()
+    expect(a.fileUrl('/ws/p1/x.png')).toContain('/api/files?path=')
+  })
+})

package/src/__tests__/adapter.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest'
+import type {
+  EditorAdapter,
+  RenderEvent,
+  RenderOptions,
+  MediaItem,
+  MediaScope,
+} from '../types'
+import type { Project, ImageElement } from '../types'
+import { defaultMontajTheme, applyTheme } from '../theme'
+
+// ── (a) A fake adapter literal must satisfy the EditorAdapter interface ──────
+// This test is purely structural: it type-checks at build time. The runtime
+// assertions below also exercise the methods to keep the fake honest.
+function makeFakeAdapter(): EditorAdapter {
+  const project: Project = {
+    version: '1',
+    id: 'p1',
+    status: 'draft' as Project['status'],
+    name: 'Fake',
+    workflow: 'carousel',
+    editingPrompt: '',
+    settings: { resolution: [1080, 1080] },
+    assets: [],
+    slides: [],
+  }
+
+  return {
+    loadProject: async (_id: string): Promise<Project> => project,
+    saveProject: async (_id: string, _project: Project): Promise<void> => {},
+    subscribe: (_id: string, _onFrame: (p: Project) => void): (() => void) => {
+      return () => {}
+    },
+    render: async function* (
+      _id: string,
+      _opts?: RenderOptions,
+    ): AsyncIterable<RenderEvent> {
+      yield { type: 'log', message: 'starting' }
+      yield { type: 'done', outputPath: '/out/p1.mp4' }
+    },
+    // (b) Montaj-style resolver: returns a workspace/files URL string.
+    resolveImageSrc: (element: ImageElement): string =>
+      `/api/files?path=${encodeURIComponent(element.src)}`,
+    // Optional method present.
+    listMedia: async (_scope: MediaScope): Promise<MediaItem[]> => [],
+    compileOverlay: async (_template: string) => () => null,
+    // Required contract methods.
+    listGlobalOverlays: async () => [],
+    listSystemOverlays: async () => [],
+    uploadFile: async (_file: File, _projectId?: string) => '/path',
+    fileUrl: (path: string) => path,
+  }
+}
+
+describe('EditorAdapter', () => {
+  it('a fake adapter literal satisfies the interface', () => {
+    const adapter = makeFakeAdapter()
+    expect(typeof adapter.loadProject).toBe('function')
+    expect(typeof adapter.saveProject).toBe('function')
+    expect(typeof adapter.subscribe).toBe('function')
+    expect(typeof adapter.render).toBe('function')
+    expect(typeof adapter.resolveImageSrc).toBe('function')
+  })
+
+  it('subscribe returns an unsubscribe function', () => {
+    const adapter = makeFakeAdapter()
+    const unsub = adapter.subscribe('p1', () => {})
+    expect(typeof unsub).toBe('function')
+    // Calling it must not throw.
+    unsub()
+  })
+
+  it('loadProject resolves to a Project', async () => {
+    const adapter = makeFakeAdapter()
+    const p = await adapter.loadProject('p1')
+    expect(p.id).toBe('p1')
+  })
+
+  // (b) resolveImageSrc: both a workspace path string and an https presigned
+  // URL must satisfy the same signature (string in, string out).
+  it('resolveImageSrc supports a Montaj workspace path resolver', () => {
+    const montajResolver: EditorAdapter['resolveImageSrc'] = (el) =>
+      `/api/files?path=${encodeURIComponent(el.src)}`
+    const el: ImageElement = {
+      id: 'img1',
+      type: 'image',
+      src: '/workspace/p1/photo.jpg',
+      x: 0,
+      y: 0,
+      w: 100,
+      h: 100,
+      rotation: 0,
+    }
+    const out = montajResolver(el)
+    expect(out.startsWith('/api/files?path=')).toBe(true)
+  })
+
+  it('resolveImageSrc supports a Hub presigned-URL resolver', () => {
+    const presigned = 'https://bucket.s3.amazonaws.com/media/abc?X-Amz-Signature=xyz'
+    const hubResolver: EditorAdapter['resolveImageSrc'] = (_el) => presigned
+    const el: ImageElement = {
+      id: 'img2',
+      type: 'image',
+      src: 'mediaId:abc',
+      x: 0,
+      y: 0,
+      w: 100,
+      h: 100,
+      rotation: 0,
+    }
+    const out = hubResolver(el)
+    expect(out.startsWith('https://')).toBe(true)
+  })
+})
+
+// ── (d) RenderEvent union must narrow correctly per discriminant ─────────────
+describe('RenderEvent discriminated union', () => {
+  function describeEvent(e: RenderEvent): string {
+    switch (e.type) {
+      case 'log':
+        return e.message
+      case 'done':
+        return e.outputPath
+      case 'error':
+        return e.message
+    }
+  }
+
+  it('narrows on the `type` discriminant', () => {
+    expect(describeEvent({ type: 'log', message: 'hi' })).toBe('hi')
+    expect(describeEvent({ type: 'done', outputPath: '/o.mp4' })).toBe('/o.mp4')
+    expect(describeEvent({ type: 'error', message: 'boom' })).toBe('boom')
+  })
+})
+
+// ── (c) applyTheme writes the expected CSS custom properties onto an element ─
+describe('applyTheme', () => {
+  it('writes editor CSS vars onto a div', () => {
+    const el = document.createElement('div')
+    applyTheme(el, defaultMontajTheme)
+
+    expect(el.style.getPropertyValue('--editor-bg')).toBe(
+      defaultMontajTheme.colors.background,
+    )
+    expect(el.style.getPropertyValue('--editor-surface')).toBe(
+      defaultMontajTheme.colors.surface,
+    )
+    expect(el.style.getPropertyValue('--editor-accent')).toBe(
+      defaultMontajTheme.colors.accent,
+    )
+    expect(el.style.getPropertyValue('--editor-text')).toBe(
+      defaultMontajTheme.colors.text,
+    )
+    expect(el.style.getPropertyValue('--editor-border')).toBe(
+      defaultMontajTheme.colors.border,
+    )
+    expect(el.style.getPropertyValue('--editor-selection')).toBe(
+      defaultMontajTheme.colors.selection,
+    )
+    expect(el.style.getPropertyValue('--editor-font-sans')).toBe(
+      defaultMontajTheme.fonts.sans,
+    )
+  })
+
+  it('writes serif/display font vars only when present', () => {
+    const el = document.createElement('div')
+    applyTheme(el, {
+      ...defaultMontajTheme,
+      fonts: { sans: 'Inter' },
+    })
+    expect(el.style.getPropertyValue('--editor-font-serif')).toBe('')
+    expect(el.style.getPropertyValue('--editor-font-display')).toBe('')
+  })
+
+  it('writes radii and spacing scale vars', () => {
+    const el = document.createElement('div')
+    applyTheme(el, defaultMontajTheme)
+    expect(el.style.getPropertyValue('--editor-radius-md')).toBe(
+      defaultMontajTheme.radii.md,
+    )
+    expect(el.style.getPropertyValue('--editor-space-2')).toBe(
+      defaultMontajTheme.spacing[2],
+    )
+  })
+})

package/src/__tests__/schema.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest'
+import type {
+  EditorProject,
+  ImageElement,
+  OverlayElement,
+  Slide,
+} from '../schema'
+
+// Compile-time assignability helper: if the argument doesn't satisfy T,
+// this fails to type-check (and thus fails `tsc`/build, which vitest runs through).
+function expectAssignable<T>(value: T): T {
+  return value
+}
+
+describe('editor schema', () => {
+  it('accepts an object with the editor-facing fields as EditorProject', () => {
+    const project: EditorProject = {
+      id: 'p1',
+      status: 'draft',
+      settings: { resolution: [1080, 1080], fps: 30 },
+      name: 'My carousel',
+      editingPrompt: 'make it pop',
+      slides: [],
+      captions: { style: 'subtitle', segments: [] },
+      assets: [],
+      carousel: { aspect: 'square' },
+      profile: 'default',
+    }
+    expectAssignable<EditorProject>(project)
+    expect(project.id).toBe('p1')
+    expect(project.status).toBe('draft')
+  })
+
+  it('allows a minimal EditorProject (only required fields)', () => {
+    const minimal: EditorProject = {
+      id: 'p2',
+      status: 'pending',
+      settings: { resolution: [1920, 1080] },
+    }
+    // Index signature lets host-only fields pass through.
+    minimal.hostOnlyField = { anything: true }
+    expectAssignable<EditorProject>(minimal)
+    expect(minimal.settings.resolution).toEqual([1920, 1080])
+  })
+
+  it('type-checks an ImageElement with and without a mediaId', () => {
+    const withMedia: ImageElement = {
+      id: 'img1',
+      type: 'image',
+      src: 'media://1',
+      x: 0,
+      y: 0,
+      w: 100,
+      h: 100,
+      rotation: 0,
+      mediaId: 'media-123',
+    }
+    const withoutMedia: ImageElement = {
+      id: 'img2',
+      type: 'image',
+      src: 'https://example.com/a.png',
+      x: 10,
+      y: 10,
+      w: 50,
+      h: 50,
+      rotation: 0,
+    }
+    expectAssignable<ImageElement>(withMedia)
+    expectAssignable<ImageElement>(withoutMedia)
+    expect(withMedia.mediaId).toBe('media-123')
+    expect(withoutMedia.mediaId).toBeUndefined()
+  })
+
+  it('type-checks a Slide with mixed image + overlay elements', () => {
+    const image: ImageElement = {
+      id: 'img',
+      type: 'image',
+      src: 's',
+      x: 0,
+      y: 0,
+      w: 1,
+      h: 1,
+      rotation: 0,
+    }
+    const overlay: OverlayElement = {
+      id: 'ov',
+      type: 'overlay',
+      overlay: { template: 'title', props: { text: 'hi' } },
+      frame: 0,
+      x: 0,
+      y: 0,
+      w: 1,
+      h: 1,
+      rotation: 0,
+    }
+    const slide: Slide = {
+      id: 's1',
+      base_color: '#000000',
+      elements: [image, overlay],
+    }
+    expectAssignable<Slide>(slide)
+    expect(slide.elements).toHaveLength(2)
+  })
+})