@devbycrux/editor 0.1.0

package/src/types.ts

@@ -0,0 +1,325 @@
+/**
+ * editor-core / types — the host-agnostic boundary for Montaj's carousel
+ * editor.
+ *
+ * The editor module knows nothing about *where* a project lives or *how* it is
+ * transported. The host application (Montaj's own UI, or a Next.js client app
+ * like mission-control) supplies an `EditorAdapter` that implements load / save
+ * / subscribe / render / image-resolution against whatever transport it owns.
+ *
+ * The canonical project/slide/element shapes live in `./schema` (the package's
+ * own editor-facing schema). Internally we alias `EditorProject` to `Project`
+ * so the ported reducer/hook/tests keep their original naming. These names are
+ * re-exported from this module so the package's internal modules can import
+ * them from `../types`; the public barrel (index.ts) sources the schema types
+ * from `./schema` directly to avoid duplicate-export conflicts.
+ */
+import type { ReactElement, ReactNode } from 'react'
+import type {
+  EditorProject as Project,
+  Slide,
+  CarouselElement,
+  ImageElement,
+  OverlayElement,
+} from './schema'
+
+// ── Overlay compiler ─────────────────────────────────────────────────────────
+
+/**
+ * A compiled overlay factory: given the current frame/fps/durationFrames and
+ * the overlay's runtime props, returns a React element (or null on error).
+ * Matches the signature produced by `lib/overlay-eval`'s `compileOverlay`.
+ */
+export type OverlayFactory = (
+  frame: number,
+  fps: number,
+  durationFrames: number,
+  props: Record<string, unknown>,
+) => ReactElement | null
+
+// ── Re-exported canonical carousel types ─────────────────────────────────────
+// schema.ts is the single source of truth. Consumers of editor-core import
+// these from here so the module presents one coherent surface.
+export type { Project, Slide, CarouselElement, ImageElement, OverlayElement }
+
+// ── Render ───────────────────────────────────────────────────────────────────
+
+/**
+ * A single frame of render progress. Discriminated on `type`:
+ *  - 'log'   — a human-readable progress line.
+ *  - 'done'  — terminal success; `outputPath` is the rendered artifact location
+ *              (a host-resolvable path/URL — Montaj returns a workspace path,
+ *              a Hub client may return a media URL).
+ *  - 'error' — terminal failure; `message` describes what went wrong.
+ */
+export type RenderEvent =
+  | { type: 'log'; message: string }
+  | { type: 'done'; outputPath: string }
+  | { type: 'error'; message: string }
+
+/**
+ * Options for a render request. Kept intentionally minimal — Montaj's render
+ * endpoint (`POST /api/projects/:id/render`) takes no body today, so `scale`
+ * is the only forward-looking knob and is optional. Hosts ignore fields they
+ * don't support.
+ */
+export interface RenderOptions {
+  /** Output scale multiplier (1 = native resolution). */
+  scale?: number
+}
+
+// ── Overlay library types ─────────────────────────────────────────────────────
+// Copied verbatim from Montaj's `ui/src/lib/api.ts` so the package owns the
+// shape the editor consumes. A host's overlay-listing endpoints return these;
+// the adapter wraps whatever transport produces them.
+
+/**
+ * A single declared prop on an overlay template. `type` drives the input
+ * control the editor renders; `default` seeds an unset value.
+ */
+export interface GlobalOverlayProp {
+  name: string
+  type: 'string' | 'int' | 'float' | 'bool' | 'color'
+  default?: unknown
+  description?: string
+}
+
+/**
+ * A reusable overlay template the host exposes (global, system, or
+ * profile-scoped). `jsxPath` is the host-resolvable path to the JSX template
+ * the adapter feeds to `compileOverlay`; `group` is an optional UI grouping;
+ * `empty` flags a placeholder group with no concrete overlay yet.
+ */
+export interface GlobalOverlay {
+  name: string
+  description: string
+  props: GlobalOverlayProp[]
+  jsxPath: string
+  group?: string
+  empty?: boolean
+}
+
+// ── Media (optional capability) ───────────────────────────────────────────────
+
+/**
+ * Scope for a media-library query. Grounded in mission-control's
+ * `UseMediaListScope`: media is either project-scoped or drawn from the host's
+ * universal/global library.
+ */
+export type MediaScope =
+  | { kind: 'universal' }
+  | { kind: 'project'; projectId: string }
+
+/**
+ * A minimal media-library item. Hosts may carry more fields, but the editor
+ * only relies on these: an id to reference, a resolvable URL to display, a
+ * MIME content type, and an optional display name.
+ */
+export interface MediaItem {
+  id: string
+  /** A directly displayable URL (presigned, workspace, or otherwise host-resolved). */
+  url: string
+  contentType: string
+  name?: string
+}
+
+// ── Adapter ────────────────────────────────────────────────────────────────
+
+/**
+ * The contract a host implements to drive the editor. All transport,
+ * authentication, and URL-shape concerns live behind this interface; the
+ * editor calls only these methods.
+ *
+ * Generic over the host's concrete project type `P` (constrained to the
+ * editor-facing `Project` = EditorProject). Montaj instantiates it with its
+ * full `Project`; a host with no extra fields gets the default `Project`. This
+ * lets the host's pipeline fields survive load→edit→save round-trips at the
+ * type level without casts.
+ */
+export interface EditorAdapter<P extends Project = Project> {
+  /** Fetch the full project by id. */
+  loadProject(id: string): Promise<P>
+
+  /** Persist the full project. Mirrors Montaj's `PUT /api/projects/:id`. */
+  saveProject(id: string, project: P): Promise<void>
+
+  /**
+   * Subscribe to live project frames (e.g. an SSE stream). `onFrame` is invoked
+   * with each fresh project snapshot. Returns an unsubscribe function the
+   * editor calls on teardown.
+   */
+  subscribe(id: string, onFrame: (project: P) => void): () => void
+
+  /**
+   * Start a render and stream progress as an async iterable of `RenderEvent`s.
+   * The iterable completes after a terminal 'done' or 'error' event.
+   */
+  render(id: string, opts?: RenderOptions): AsyncIterable<RenderEvent>
+
+  /**
+   * Resolve an `ImageElement` to a directly displayable URL. This is the host's
+   * job because the resolution rule differs per host:
+   *  - Montaj returns a workspace/files URL (e.g. `/api/files?path=...`).
+   *  - Hub clients resolve a `mediaId` → presigned URL.
+   * The editor never assumes a URL shape — it always routes through here.
+   */
+  resolveImageSrc(element: ImageElement): string
+
+  /**
+   * Optional: list media available to the editor in the given scope. Hosts
+   * without a media library omit this; the editor must feature-detect it.
+   */
+  listMedia?(scope: MediaScope): Promise<MediaItem[]>
+
+  /**
+   * Compile a JSX overlay template file into an `OverlayFactory`.
+   * The host supplies this because the compilation pipeline (Babel, fetch
+   * strategy, caching) is host-specific. The editor-core preview component
+   * receives it as a prop; nothing inside editor-core imports the host's
+   * compiler directly.
+   */
+  compileOverlay(template: string): Promise<OverlayFactory>
+
+  /**
+   * List the host's global (workspace-wide) overlay templates. The assembled
+   * editor's overlay picker reads these. Maps to Montaj's `GET /api/overlays`.
+   */
+  listGlobalOverlays(): Promise<GlobalOverlay[]>
+
+  /**
+   * List the host's built-in/system overlay templates. Maps to Montaj's
+   * `GET /api/overlays/system`.
+   */
+  listSystemOverlays(): Promise<GlobalOverlay[]>
+
+  /**
+   * Upload a file and return a host-resolvable path/ref. When `projectId` is
+   * given, the host should store it inside the project (so it stays
+   * self-contained); otherwise a shared/upload location is used. Maps to
+   * Montaj's `POST /api/projects/:id/upload-asset` (or `POST /api/upload`).
+   */
+  uploadFile(file: File, projectId?: string): Promise<string>
+
+  /**
+   * Map a host path to a directly fetchable URL. Synchronous because hosts
+   * derive it by string transform (Montaj: `/api/files?path=...`). Distinct
+   * from `resolveImageSrc`, which takes an `ImageElement` and applies element
+   * resolution rules; `fileUrl` is the raw path→URL primitive.
+   */
+  fileUrl(path: string): string
+
+  /**
+   * Optional: list overlay templates scoped to a named profile. Hosts without
+   * profile-scoped overlays omit this. Maps to Montaj's
+   * `GET /api/profiles/:name/overlays`.
+   */
+  listProfileOverlays?(profileName: string): Promise<GlobalOverlay[]>
+
+  /**
+   * Optional: host environment info the editor may surface (e.g. the root
+   * skill path for authoring overlays). Maps to Montaj's `GET /api/info`.
+   */
+  getInfo?(): Promise<{ root_skill_path?: string }>
+
+  /**
+   * Optional: generate an image from a prompt and return its host path. Hosts
+   * without AI image generation omit this; the editor feature-detects it.
+   */
+  generateImage?(prompt: string, projectId: string): Promise<{ path: string }>
+
+  /**
+   * Optional: watch a host file path for changes, invoking `onChange` whenever
+   * the file is rewritten. Returns an unsubscribe function. The editor uses this
+   * to auto-recover an overlay preview when its source is edited on disk. Hosts
+   * without a file-watch transport omit this; the editor simply doesn't watch
+   * (no fallback EventSource). Montaj wires this to its `/api/files/stream` SSE.
+   */
+  watchFile?(path: string, onChange: () => void): () => void
+
+  /**
+   * Optional: resolve the host's default "static text" overlay template — the
+   * one the editor's "+ Text" button seeds. Returns null when the host has no
+   * such template (the editor then hides "+ Text"). Hosts without any system
+   * text overlay omit this entirely. Montaj implements it over
+   * `listSystemOverlays()` + its `static-text` matcher.
+   */
+  getDefaultTextOverlay?(): Promise<GlobalOverlay | null>
+}
+
+// ── Theme ────────────────────────────────────────────────────────────────────
+
+/**
+ * A flat token record describing the editor's visual language. The host passes
+ * one of these (or relies on the Montaj default). `applyTheme` (in theme.ts)
+ * writes these tokens as CSS custom properties so styling stays declarative and
+ * host-overridable.
+ */
+export interface EditorTheme {
+  colors: {
+    /** Outermost canvas/page background. */
+    background: string
+    /** Raised panels, toolbars, inspectors. */
+    surface: string
+    /** Primary interactive/brand accent. */
+    accent: string
+    /** Default text color. */
+    text: string
+    /** Hairline/divider color. */
+    border: string
+    /** Selection outline / active-element highlight. */
+    selection: string
+  }
+  fonts: {
+    sans: string
+    serif?: string
+    display?: string
+  }
+  /** Border-radius scale, smallest → largest. */
+  radii: {
+    sm: string
+    md: string
+    lg: string
+  }
+  /**
+   * Spacing scale keyed by step. Indices follow a 4px-base rhythm (matching
+   * Tailwind's `1`=4px, `2`=8px, …). Values are CSS lengths.
+   */
+  spacing: Record<number, string>
+}
+
+// ── Host-injected UI ──────────────────────────────────────────────────────────
+
+/**
+ * Optional UI the host injects into editor slots — e.g. a "Publish to Hub"
+ * button in the toolbar, or app-specific export controls.
+ */
+export interface EditorSlots {
+  /** Rendered into the editor toolbar's action area. */
+  toolbarActions?: ReactNode
+  /** Rendered into the editor's export/render action area. */
+  exportActions?: ReactNode
+  /** Rendered into the editor's assets/media panel area. */
+  assetsPanel?: ReactNode
+  /**
+   * Rendered in the pending/empty view in place of the default
+   * "Message your agent to start" copy. Hosts use this to surface live agent
+   * progress (Montaj feeds its SSE log line here); absent → default copy shows.
+   */
+  pendingStatus?: ReactNode
+}
+
+// ── Top-level component props ──────────────────────────────────────────────────
+
+/**
+ * Props for the carousel editor component. Controlled shape: the host owns the
+ * `project` and is notified of edits via `onProjectChange`. The adapter drives
+ * transport; theme and slots are optional, and `readOnly` disables mutation.
+ */
+export interface CarouselEditorProps<P extends Project = Project> {
+  project: P
+  adapter: EditorAdapter<P>
+  onProjectChange?: (p: P) => void
+  theme?: EditorTheme
+  slots?: EditorSlots
+  readOnly?: boolean
+}

package/src/ui/__tests__/button.test.tsx

@@ -0,0 +1,17 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Button } from '../button'
+
+describe('vendored Button', () => {
+  it('renders its children', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument()
+  })
+
+  it('fires onClick when clicked', () => {
+    const onClick = vi.fn()
+    render(<Button onClick={onClick}>Go</Button>)
+    fireEvent.click(screen.getByRole('button', { name: 'Go' }))
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+})

package/src/ui/badge.tsx

@@ -0,0 +1,32 @@
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from './utils'
+
+const badgeVariants = cva(
+  'inline-flex items-center rounded px-2 py-0.5 text-xs font-semibold',
+  {
+    variants: {
+      variant: {
+        pending: 'bg-amber-100 text-amber-700 dark:bg-amber-900/50 dark:text-amber-300',
+        draft:   'bg-blue-100 text-blue-700 dark:bg-blue-900/50 dark:text-blue-300',
+        final:   'bg-emerald-100 text-emerald-700 dark:bg-green-900/50 dark:text-green-300',
+        default: 'bg-gray-100 text-gray-600 dark:bg-gray-700 dark:text-gray-300',
+      },
+    },
+    defaultVariants: { variant: 'default' },
+  },
+)
+
+export interface BadgeProps
+  extends React.HTMLAttributes<HTMLSpanElement>,
+    VariantProps<typeof badgeVariants> {}
+
+export function Badge({ className, variant, ...props }: BadgeProps) {
+  return <span className={cn(badgeVariants({ variant }), className)} {...props} />
+}
+
+export function StatusBadge({ status }: { status: string }) {
+  const variant = ['pending', 'draft', 'final'].includes(status)
+    ? (status as 'pending' | 'draft' | 'final')
+    : 'default'
+  return <Badge variant={variant}>{status}</Badge>
+}

package/src/ui/button.tsx

@@ -0,0 +1,32 @@
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from './utils'
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default:   'bg-blue-600 text-white hover:bg-blue-700',
+        secondary: 'bg-gray-100 text-gray-700 hover:bg-gray-200 dark:bg-gray-700 dark:text-gray-100 dark:hover:bg-gray-600',
+        ghost:     'text-gray-500 hover:bg-gray-100 hover:text-gray-900 dark:text-gray-400 dark:hover:bg-gray-800 dark:hover:text-gray-100',
+        danger:    'bg-red-600 text-white hover:bg-red-700',
+        outline:   'border border-gray-300 dark:border-gray-700 text-gray-700 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800',
+      },
+      size: {
+        default: 'h-9 px-4 py-2',
+        sm:      'h-7 px-3 text-xs',
+        lg:      'h-11 px-6',
+        icon:    'h-9 w-9',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'default' },
+  },
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />
+}

package/src/ui/index.ts

@@ -0,0 +1,16 @@
+// Vendored UI primitives — self-contained copies of Montaj's shadcn-style
+// components so the package has no `@/` host dependency. Tailwind classes are
+// preserved verbatim; the host supplies the matching Tailwind theme.
+export { cn } from './utils'
+export { Button } from './button'
+export type { ButtonProps } from './button'
+export { Input } from './input'
+export type { InputProps } from './input'
+export { Label } from './label'
+export { Select } from './select'
+export type { SelectProps } from './select'
+export { Switch } from './switch'
+export { Textarea } from './textarea'
+export type { TextareaProps } from './textarea'
+export { Badge, StatusBadge } from './badge'
+export type { BadgeProps } from './badge'

package/src/ui/input.tsx

@@ -0,0 +1,15 @@
+import { cn } from './utils'
+
+export type InputProps = React.InputHTMLAttributes<HTMLInputElement>
+
+export function Input({ className, ...props }: InputProps) {
+  return (
+    <input
+      className={cn(
+        'flex h-9 w-full rounded-md border border-gray-300 bg-white px-3 py-1 text-sm text-gray-900 placeholder:text-gray-400 focus:outline-none focus:ring-2 focus:ring-blue-500 disabled:opacity-50 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-100 dark:placeholder:text-gray-500',
+        className,
+      )}
+      {...props}
+    />
+  )
+}

package/src/ui/label.tsx

@@ -0,0 +1,10 @@
+import { cn } from './utils'
+
+export function Label({ className, ...props }: React.LabelHTMLAttributes<HTMLLabelElement>) {
+  return (
+    <label
+      className={cn('text-xs font-medium text-gray-400 leading-none', className)}
+      {...props}
+    />
+  )
+}

package/src/ui/select.tsx

@@ -0,0 +1,23 @@
+import { cn } from './utils'
+
+export interface SelectProps extends React.SelectHTMLAttributes<HTMLSelectElement> {
+  options: Array<{ value: string; label: string }>
+}
+
+export function Select({ className, options, ...props }: SelectProps) {
+  return (
+    <select
+      className={cn(
+        'flex h-9 w-full rounded-md border border-gray-300 bg-white px-3 py-1 text-sm text-gray-900 focus:outline-none focus:ring-2 focus:ring-blue-500 disabled:opacity-50 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-100',
+        className,
+      )}
+      {...props}
+    >
+      {options.map((o) => (
+        <option key={o.value} value={o.value}>
+          {o.label}
+        </option>
+      ))}
+    </select>
+  )
+}

package/src/ui/switch.tsx

@@ -0,0 +1,31 @@
+import { cn } from './utils'
+
+interface SwitchProps {
+  checked: boolean
+  onCheckedChange: (v: boolean) => void
+  className?: string
+  disabled?: boolean
+}
+
+export function Switch({ checked, onCheckedChange, className, disabled }: SwitchProps) {
+  return (
+    <button
+      role="switch"
+      aria-checked={checked}
+      disabled={disabled}
+      onClick={() => onCheckedChange(!checked)}
+      className={cn(
+        'relative inline-flex h-5 w-9 items-center rounded-full transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 disabled:opacity-50',
+        checked ? 'bg-blue-600' : 'bg-gray-300 dark:bg-gray-700',
+        className,
+      )}
+    >
+      <span
+        className={cn(
+          'inline-block h-3.5 w-3.5 rounded-full bg-white shadow transition-transform',
+          checked ? 'translate-x-4' : 'translate-x-1',
+        )}
+      />
+    </button>
+  )
+}

package/src/ui/textarea.tsx

@@ -0,0 +1,15 @@
+import { cn } from './utils'
+
+export type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement>
+
+export function Textarea({ className, ...props }: TextareaProps) {
+  return (
+    <textarea
+      className={cn(
+        'flex w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 placeholder:text-gray-400 focus:outline-none focus:ring-2 focus:ring-blue-500 disabled:opacity-50 resize-none dark:border-gray-700 dark:bg-gray-800 dark:text-gray-100 dark:placeholder:text-gray-500',
+        className,
+      )}
+      {...props}
+    />
+  )
+}

package/src/ui/utils.ts

@@ -0,0 +1,7 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/** Merge conditional class names, de-duplicating Tailwind conflicts. */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}