@bycrux/editor 0.4.1

package/src/index.ts

@@ -0,0 +1,136 @@
+// @bycrux/editor — public API.
+//
+// The package owns the host-agnostic carousel editor: the editor-facing schema,
+// the adapter/theme contracts, and the host-agnostic PIECES (state, gestures,
+// crop, text, preview, overlays). Hosts (Montaj's UI, Hub clients) import from
+// here and supply an EditorAdapter to drive it.
+
+// ── Schema (single source of truth for project/slide/element shapes) ──────────
+export type {
+  Word,
+  AudioTrack,
+  CaptionSegment,
+  Captions,
+  VisualItem,
+  Asset,
+  ImageElement,
+  OverlayElement,
+  CarouselElement,
+  Slide,
+  EditorProject,
+} from './schema'
+
+// ── Contracts (adapter, theme, render, media, component props) ────────────────
+// Schema types are sourced from './schema' above; here we export only the
+// symbols types.ts itself owns, plus the `Project` alias (= EditorProject) that
+// the ported state/reducer code is typed against.
+export type {
+  Project,
+  OverlayFactory,
+  RenderEvent,
+  RenderOptions,
+  MediaScope,
+  MediaItem,
+  GlobalOverlay,
+  GlobalOverlayProp,
+  VersionEntry,
+  WaveformChunk,
+  EditorAdapter,
+  EditorTheme,
+  EditorSlots,
+  CarouselEditorProps,
+  VideoEditorProps,
+} from './types'
+
+// ── Video editor pure helpers ─────────────────────────────────────────────────
+export {
+  applyCutToTracks,
+  applyCutToItem,
+  collapseGaps,
+  splitAtTime,
+} from './video/cuts'
+export type { Cut } from './video/cuts'
+export { getOverlayDesignCanvas } from './video/design-canvas'
+
+// ── Theme ─────────────────────────────────────────────────────────────────────
+export { defaultMontajTheme, applyTheme } from './theme'
+
+// ── State ───────────────────────────────────────────────────────────────────
+export { useProjectState } from './state/use-project-state'
+export type { Connection, UseProjectState } from './state/use-project-state'
+export { projectReducer } from './state/project-reducer'
+export type { Action, ProjectStatus } from './state/project-reducer'
+export { createMutationQueue } from './state/mutation-queue'
+export type { MutationQueue } from './state/mutation-queue'
+
+// ── Gestures ──────────────────────────────────────────────────────────────────
+export * from './gestures'
+
+// ── Crop ──────────────────────────────────────────────────────────────────────
+export {
+  renderedSourceRect,
+  fractionToWrapperPx,
+  wrapperPxToFraction,
+  applyCropHandleDrag,
+} from './crop/crop-math'
+export type {
+  RenderedRect,
+  CropFraction,
+  WrapperPxRect,
+  CropHandle,
+} from './crop/crop-math'
+export { CanvasCropOverlay } from './crop/CanvasCropOverlay'
+export type { CanvasCropOverlayProps } from './crop/CanvasCropOverlay'
+
+// ── Text ──────────────────────────────────────────────────────────────────────
+export {
+  FONT_OPTIONS,
+  findFontOption,
+  FontFamilyPicker,
+  FontSizePicker,
+} from './text/FontPicker'
+export type { FontOption } from './text/FontPicker'
+export { InlineTextEditor } from './text/InlineTextEditor'
+export type { InlineTextEditorProps } from './text/InlineTextEditor'
+export {
+  HEX_PATTERN,
+  isColorProp,
+  isBold,
+  isItalic,
+  nextCase,
+  isStyleProp,
+  nonColorTextEntries,
+  TextFormattingToolbar,
+} from './text/TextFormattingToolbar'
+export type { TextFormattingToolbarProps } from './text/TextFormattingToolbar'
+
+// ── Preview ─────────────────────────────────────────────────────────────────
+export { OverlayPreview } from './preview/OverlayPreview'
+export type { OverlayPreviewProps } from './preview/OverlayPreview'
+
+// ── Video preview ─────────────────────────────────────────────────────────────
+export { default as PreviewPlayer } from './video/preview/PreviewPlayer'
+export { default as CarouselPreview } from './video/preview/CarouselPreview'
+export { default as OverlayItemsLayer } from './video/preview/OverlayItemsLayer'
+export { useVideoPlayback } from './video/preview/useVideoPlayback'
+export { useDragOverlay } from './video/preview/useDragOverlay'
+export type { Corner, DragType } from './video/preview/useDragOverlay'
+
+// ── Overlays ──────────────────────────────────────────────────────────────────
+export {
+  STANDARD_TEXT_PROPS,
+  getSupportedProps,
+  readPropAsString,
+} from './overlays/contract'
+
+// ── Assembled editors ─────────────────────────────────────────────────────────
+export { default as CarouselEditor } from './carousel/CarouselEditor'
+export { default as VideoEditor } from './video/VideoEditor'
+
+// ── Public carousel sub-components ────────────────────────────────────────────
+// Hosts consume these beyond the assembled editor — Montaj's preview/caption
+// components render SlideCanvas thumbnails and wrap overlays in the boundary.
+export { default as SlideCanvas, resolveAsset } from './carousel/SlideCanvas'
+export { default as OverlayErrorBoundary } from './carousel/OverlayErrorBoundary'
+export { default as ReadOnlySlide } from './carousel/ReadOnlySlide'
+export type { ReadOnlySlideProps } from './carousel/ReadOnlySlide'

package/src/lib/google-fonts.ts

@@ -0,0 +1,28 @@
+// Shared Google Fonts loader.
+//
+// Injects a Google Fonts stylesheet <link> for the declared family specs so the
+// editor's preview/render uses the same glyphs and metrics the renderer
+// (bundle.js) fetches. Used by both the video overlay layer and the carousel
+// overlay render path. Resilient by design: a font-load failure must never
+// break the render (we only append a <link>; the browser handles the fetch).
+
+// Track Google Fonts URLs already injected so we don't add the same <link>
+// twice when multiple overlays declare overlapping fonts. Keyed by the full
+// stylesheet URL — the same URL never produces a duplicate fetch from
+// Chromium regardless, but the duplicate <link> tags would still clutter
+// document.head across long editing sessions.
+const __injectedFontUrls = new Set<string>()
+
+export function ensureGoogleFontsLoaded(googleFonts: string[] | undefined): void {
+  if (!googleFonts?.length) return
+  // Match the format bundle.js uses for the render pipeline so preview and
+  // render fetch identical CSS (and identical glyphs / metrics).
+  const url = `https://fonts.googleapis.com/css2?${googleFonts.map((f) => `family=${f}`).join('&')}&display=swap`
+  if (__injectedFontUrls.has(url)) return
+  __injectedFontUrls.add(url)
+  if (typeof document === 'undefined') return
+  const link = document.createElement('link')
+  link.rel = 'stylesheet'
+  link.href = url
+  document.head.appendChild(link)
+}

package/src/overlays/contract.ts

@@ -0,0 +1,41 @@
+import type { OverlayElement } from '../types'
+
+// The 9-prop editable-text contract. Single source of truth on the FE for
+// which prop keys the floating text toolbar knows how to write. Mirrors
+// hub/backend/src/modules/mcp/overlay-contract.ts REQUIRED_PROPS.
+export const STANDARD_TEXT_PROPS: ReadonlySet<string> = new Set([
+  'text', 'fontSize', 'fontFamily', 'fontWeight', 'fontStyle',
+  'color', 'textAlign', 'textTransform', 'bgColor',
+])
+
+/**
+ * Returns the subset of STANDARD_TEXT_PROPS present (non-null) on the
+ * element. Toolbar controls render only when their target prop is in this set.
+ *
+ * Forgiving on value type: numeric values (e.g. `fontSize: 64`) count as
+ * present. The toolbar reads them via String(value) and writes back as
+ * strings — fixing the round-trip silently rather than blocking the operator
+ * with a "this overlay isn't editable" message. Per the resolved product
+ * question, this prefers UX over strictness; non-string values on contract
+ * props are still flagged upstream by hub.write_overlay's validator.
+ */
+export function getSupportedProps(element: OverlayElement): Set<string> {
+  const props = element.overlay.props
+  const supported = new Set<string>()
+  for (const key of STANDARD_TEXT_PROPS) {
+    const value = props[key]
+    if (value !== undefined && value !== null) supported.add(key)
+  }
+  return supported
+}
+
+/**
+ * Read a contract prop's current value as a string, coercing numbers. Used
+ * by the toolbar's read paths so the displayed control value matches what's
+ * on the element regardless of its stored type.
+ */
+export function readPropAsString(element: OverlayElement, key: string): string {
+  const value = element.overlay.props[key]
+  if (value === undefined || value === null) return ''
+  return String(value)
+}

package/src/preview/OverlayPreview.tsx

@@ -0,0 +1,196 @@
+/**
+ * editor-core/preview/OverlayPreview
+ *
+ * Host-agnostic React component that compiles and renders a JSX overlay
+ * template. The overlay compiler is injected via the `compileOverlay` prop so
+ * this component has no dependency on any host module (no import from
+ * '@/lib/overlay-eval'). The host wires in the compiler from its adapter.
+ *
+ * States:
+ *   - Compiling  → `loading` node (default: spinner with role="status").
+ *   - Compile or runtime error → `errorState` node (default: red badge with role="alert").
+ *   - Success    → factory output element.
+ */
+
+import React, { useEffect, useState } from 'react'
+import type { OverlayFactory } from '../types'
+
+// ── Defaults ─────────────────────────────────────────────────────────────────
+
+function DefaultSpinner(): React.ReactElement {
+  return (
+    <div
+      role="status"
+      aria-label="Loading overlay"
+      style={{
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        color: 'rgba(255, 255, 255, 0.65)',
+      }}
+    >
+      <svg
+        width="36"
+        height="36"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+      >
+        <g>
+          <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+          <animateTransform
+            attributeName="transform"
+            type="rotate"
+            from="0 12 12"
+            to="360 12 12"
+            dur="0.9s"
+            repeatCount="indefinite"
+          />
+        </g>
+      </svg>
+    </div>
+  )
+}
+
+function DefaultErrorState(): React.ReactElement {
+  return (
+    <div
+      role="alert"
+      style={{
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 16,
+      }}
+    >
+      <div
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 6,
+          padding: '4px 10px',
+          borderRadius: 6,
+          background: 'rgba(220, 38, 38, 0.15)',
+          color: 'rgb(220, 38, 38)',
+          fontSize: 12,
+          fontFamily: 'system-ui, -apple-system, sans-serif',
+          fontWeight: 500,
+        }}
+      >
+        <svg
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <circle cx="12" cy="12" r="10" />
+          <line x1="12" y1="8" x2="12" y2="12" />
+          <line x1="12" y1="16" x2="12.01" y2="16" />
+        </svg>
+        <span>overlay error</span>
+      </div>
+    </div>
+  )
+}
+
+// ── Props ─────────────────────────────────────────────────────────────────────
+
+export interface OverlayPreviewProps {
+  /**
+   * Host-supplied compiler. Receives a template path and returns a compiled
+   * OverlayFactory. Injected from the adapter so editor-core never imports
+   * the host's overlay-eval module directly.
+   */
+  compileOverlay: (template: string) => Promise<OverlayFactory>
+
+  /**
+   * Path to the overlay template file. Passed to the injected compileOverlay.
+   * Matches OverlayElement.overlay.template from Montaj's schema.
+   */
+  template: string
+
+  /**
+   * Runtime props forwarded to the overlay factory.
+   * Matches OverlayElement.overlay.props.
+   */
+  props: Record<string, unknown>
+
+  /**
+   * Frame number to render. Matches OverlayElement.frame or the caller's
+   * scrubber position.
+   */
+  frame: number
+
+  /** Frames per second. Passed to the factory alongside frame. */
+  fps: number
+
+  /**
+   * Duration in frames. Passed to the factory as `durationFrames`.
+   * Mirrors how SlideCanvas derives duration from element.overlay.props.duration.
+   */
+  duration: number
+
+  /** Shown while compileOverlay is in-flight. Default: spinner. */
+  loading?: React.ReactNode
+
+  /** Shown on compile error or factory runtime error. Default: red badge. */
+  errorState?: React.ReactNode
+}
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+export function OverlayPreview({
+  compileOverlay,
+  template,
+  props,
+  frame,
+  fps,
+  duration,
+  loading,
+  errorState,
+}: OverlayPreviewProps): React.ReactElement {
+  const [factory, setFactory] = useState<OverlayFactory | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    // Reset state when template changes so the loading spinner re-appears.
+    setFactory(null)
+    setError(null)
+
+    compileOverlay(template)
+      .then((f) => {
+        if (!cancelled) setFactory(() => f)
+      })
+      .catch((e) => {
+        if (!cancelled) setError(e instanceof Error ? e : new Error(String(e)))
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [template])
+
+  const loadingNode = loading ?? <DefaultSpinner />
+  const errorNode = errorState ?? <DefaultErrorState />
+
+  if (error) return <>{errorNode}</>
+  if (!factory) return <>{loadingNode}</>
+
+  try {
+    const out = factory(frame, fps, duration, props)
+    return out ?? <>{errorNode}</>
+  } catch {
+    return <>{errorNode}</>
+  }
+}

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(),
+    )
+  })
+})