@devbycrux/editor 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devbycrux/editor",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "exports": {

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

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest'
+import type {
+  EditorAdapter,
+  RenderEvent,
+  RenderOptions,
+  VersionEntry,
+  WaveformChunk,
+} from '../types'
+import type { EditorProject, ImageElement } from '../schema'
+
+// ── Video adapter contract ────────────────────────────────────────────────────
+// The video editor adds four OPTIONAL adapter methods: listVersionHistory,
+// restoreVersion, getWaveformChunks, clearOverlayCache. This file fails to
+// compile if those methods are mistyped, and verifies that (a) an adapter
+// implementing them type-checks and (b) one omitting them still type-checks.
+
+const project: EditorProject = {
+  version: '1',
+  id: 'p1',
+  status: 'draft' as EditorProject['status'],
+  name: 'Fake',
+  workflow: 'video',
+  editingPrompt: '',
+  settings: { resolution: [1080, 1920] },
+  assets: [],
+  tracks: [[]],
+}
+
+const baseRequired = {
+  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 () => [],
+  listSystemOverlays: async () => [],
+  uploadFile: async (_file: File): Promise<string> => '/path',
+  fileUrl: (path: string): string => path,
+}
+
+// (a) Adapter implementing all four new optional methods.
+function makeVideoAdapter(): EditorAdapter<EditorProject> {
+  return {
+    ...baseRequired,
+    listVersionHistory: async (_id: string): Promise<VersionEntry[]> => [
+      { hash: 'abc', message: 'init', timestamp: '2026-01-01T00:00:00Z' },
+    ],
+    restoreVersion: async (_id: string, _hash: string): Promise<EditorProject> => project,
+    getWaveformChunks: async (
+      _projectId: string,
+      _trackId: string,
+      _trackSrc: string,
+      _chunkDurationS?: number,
+    ): Promise<WaveformChunk[]> => [{ path: '/wf/0.png', start: 0, end: 15 }],
+    clearOverlayCache: (_src?: string): void => {},
+  }
+}
+
+// (b) Adapter omitting the new optional methods. Must still type-check.
+function makeMinimalAdapter(): EditorAdapter<EditorProject> {
+  return { ...baseRequired }
+}
+
+describe('EditorAdapter video methods', () => {
+  it('an adapter implementing the new optional methods type-checks', async () => {
+    const a = makeVideoAdapter()
+    expect(typeof a.listVersionHistory).toBe('function')
+    expect(typeof a.restoreVersion).toBe('function')
+    expect(typeof a.getWaveformChunks).toBe('function')
+    expect(typeof a.clearOverlayCache).toBe('function')
+
+    const versions = await a.listVersionHistory!('p1')
+    expect(versions[0]).toMatchObject({ hash: 'abc', message: 'init' })
+
+    const chunks = await a.getWaveformChunks!('p1', 't1', 'a.mp3', 15)
+    expect(chunks[0]).toMatchObject({ path: '/wf/0.png', start: 0, end: 15 })
+  })
+
+  it('an adapter omitting the new optional methods still type-checks', () => {
+    const a = makeMinimalAdapter()
+    expect(a.listVersionHistory).toBeUndefined()
+    expect(a.restoreVersion).toBeUndefined()
+    expect(a.getWaveformChunks).toBeUndefined()
+    expect(a.clearOverlayCache).toBeUndefined()
+  })
+})

package/src/carousel/CarouselEditor.tsx

@@ -151,7 +151,7 @@ function isTypingTarget(t: EventTarget | null): boolean {
 
 // ── CarouselEditor ────────────────────────────────────────────────────────────
 
-export default function CarouselEditor<P extends Project = Project>({ project: initialProject, adapter, onProjectChange, theme, slots }: Props<P>) {
+export default function CarouselEditor<P extends Project = Project>({ project: initialProject, adapter, onProjectChange, theme, slots, hiddenElementIds, onToggleElementVisibility, onSelectionChange }: Props<P>) {
   const state = useProjectState(adapter, initialProject.id, initialProject)
   const project = state.project
   const slides = project.slides ?? []
@@ -339,6 +339,12 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
   const selectedSlide = slides.find(s => s.id === selectedSlideId)
   const selectedElement = selectedSlide?.elements.find(el => el.id === selectedElementId)
 
+  // Notify the host of selection changes so it can drive selection-aware chrome
+  // (e.g. a regen action in a toolbar slot). Fires with the element or null.
+  useEffect(() => {
+    onSelectionChange?.(selectedElement ?? null)
+  }, [selectedElement, onSelectionChange])
+
   const [w, h] = project.settings.resolution
   const canvasContainerRef = useRef<HTMLDivElement>(null)
   const [canvasContainerSize, setCanvasContainerSize] = useState<{ w: number; h: number }>({ w: 600, h: 700 })
@@ -387,21 +393,24 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
           <span className="text-xs font-medium">Refresh</span>
         </button>
 
-        <button
-          onClick={handleRender}
-          disabled={rendering || project.status === 'pending' || slides.length === 0}
-          className="absolute top-3 right-3 z-30 flex items-center gap-2 px-3 py-2 rounded-md border border-blue-500/50 bg-blue-600/80 text-white hover:bg-blue-600 hover:border-blue-400 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
-          title={
-            project.status === 'pending'
-              ? 'Wait for the agent to finish before rendering'
-              : slides.length === 0
-              ? 'Add slides before rendering'
-              : 'Render all slides as PNGs'
-          }
-        >
-          <Download size={18} />
-          <span className="text-xs font-medium">{rendering ? 'Starting…' : 'Render'}</span>
-        </button>
+        <div className="absolute top-3 right-3 z-30 flex items-center gap-2">
+          {slots?.toolbarActions}
+          <button
+            onClick={handleRender}
+            disabled={rendering || project.status === 'pending' || slides.length === 0}
+            className="flex items-center gap-2 px-3 py-2 rounded-md border border-blue-500/50 bg-blue-600/80 text-white hover:bg-blue-600 hover:border-blue-400 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
+            title={
+              project.status === 'pending'
+                ? 'Wait for the agent to finish before rendering'
+                : slides.length === 0
+                ? 'Add slides before rendering'
+                : 'Render all slides as PNGs'
+            }
+          >
+            <Download size={18} />
+            <span className="text-xs font-medium">{rendering ? 'Starting…' : 'Render'}</span>
+          </button>
+        </div>
 
         {project.status === 'pending' ? (
           <div className="flex flex-col items-center gap-6 text-center max-w-lg w-full">
@@ -461,6 +470,7 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
                 updateImageCrop={state.updateImageCrop}
                 cropElementId={cropElementId}
                 onExitCrop={() => setCropElementId(null)}
+                hiddenElementIds={hiddenElementIds}
               />
             </div>
             <p className="flex-shrink-0 text-xs text-gray-500 text-center max-w-md">
@@ -505,6 +515,8 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
           onReorderElement={handleReorderElement}
           onEnterCrop={(_slideId, elementId) => { setSelectedElementId(elementId); setCropElementId(elementId) }}
           updateOverlayProp={state.updateOverlayProp}
+          hiddenElementIds={hiddenElementIds}
+          onToggleElementVisibility={onToggleElementVisibility}
         />
         {slots?.assetsPanel && (
           <div className="border-t border-gray-800 flex flex-col overflow-hidden" style={{ minHeight: 180 }}>

package/src/carousel/SlideCanvas.tsx

@@ -106,6 +106,13 @@ interface Props {
   // Crop mode is owned here but the entry trigger lives in the property panel.
   cropElementId?: string | null
   onExitCrop?: () => void
+
+  /**
+   * Editor-only element ids to omit from this canvas (non-persisted). Used by
+   * the host's visibility toggle to hide a scrim/background while positioning
+   * overlays beneath it. Absent → all elements render.
+   */
+  hiddenElementIds?: string[]
 }
 
 export default function SlideCanvas({
@@ -128,9 +135,11 @@ export default function SlideCanvas({
   updateImageCrop,
   cropElementId,
   onExitCrop,
+  hiddenElementIds,
 }: Props) {
   const sid = slideId ?? slide.id
   const resolveSrc = resolveImageSrc ?? ((el: ImageElement) => resolveAssetDefault(el.src))
+  const hiddenSet = hiddenElementIds && hiddenElementIds.length ? new Set(hiddenElementIds) : null
 
   // Refs to each element wrapper so gesture previews can mutate DOM directly.
   const wrapperRefs = useRef<Map<string, HTMLDivElement>>(new Map())
@@ -295,6 +304,7 @@ export default function SlideCanvas({
 
   return (
     <div
+      data-interactive={interactive ? 'true' : undefined}
       style={{
         width: displayW,
         height: displayH,
@@ -353,6 +363,8 @@ export default function SlideCanvas({
         )}
 
         {slide.elements.map((element) => {
+          // Editor-only visibility: omit hidden elements from this canvas.
+          if (hiddenSet?.has(element.id)) return null
           const isSelected = selectedElementId === element.id
           const inCrop = cropState?.elementId === element.id
           const isRotated = (element.rotation ?? 0) !== 0

package/src/carousel/SlidePropertyPanel.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react'
-import { Crop } from 'lucide-react'
+import { Crop, Eye, EyeOff } from 'lucide-react'
 import type {
   Project,
   Slide,
@@ -34,6 +34,37 @@ interface Props {
   updateOverlayProp?: (slideId: string, elementId: string, key: string, value: string) => Promise<void>
   // Adapter supplies overlay-schema listing (global + profile-scoped).
   adapter: EditorAdapter<Project>
+  // Editor-only element visibility (host-owned, non-persisted). When
+  // `onToggleElementVisibility` is supplied, an eye toggle is shown for the
+  // selected element; `hiddenElementIds` reflects the current hidden set.
+  hiddenElementIds?: string[]
+  onToggleElementVisibility?: (elementId: string) => void
+}
+
+// Small eye toggle to hide/show the selected element in the editor preview only
+// (never persisted). Absent host callback → not rendered.
+function HideToggle({
+  elementId,
+  isHidden,
+  onToggle,
+}: {
+  elementId: string
+  isHidden: boolean
+  onToggle?: (elementId: string) => void
+}) {
+  if (!onToggle) return null
+  return (
+    <button
+      type="button"
+      onClick={e => { e.stopPropagation(); onToggle(elementId) }}
+      title={isHidden ? 'Show in editor' : 'Hide from editor'}
+      aria-label={isHidden ? 'Show in editor' : 'Hide from editor'}
+      aria-pressed={isHidden}
+      className="text-gray-500 hover:text-white px-1"
+    >
+      {isHidden ? <EyeOff className="h-3.5 w-3.5" /> : <Eye className="h-3.5 w-3.5" />}
+    </button>
+  )
 }
 
 function numInput(
@@ -146,6 +177,8 @@ export default function SlidePropertyPanel({
   onEnterCrop,
   updateOverlayProp,
   adapter,
+  hiddenElementIds,
+  onToggleElementVisibility,
 }: Props) {
   // Map of jsxPath → GlobalOverlay for overlay prop schemas
   const [overlaySchemas, setOverlaySchemas] = useState<Map<string, GlobalOverlay>>(new Map())
@@ -225,7 +258,12 @@ export default function SlidePropertyPanel({
             <span className="text-xs font-semibold text-gray-400 uppercase tracking-wider">
               {element.type === 'image' ? 'Image' : 'Overlay'}
             </span>
-            <div className="flex gap-1">
+            <div className="flex items-center gap-1">
+              <HideToggle
+                elementId={element.id}
+                isHidden={hiddenElementIds?.includes(element.id) ?? false}
+                onToggle={onToggleElementVisibility}
+              />
               <button
                 onClick={() => onReorderElement(slide.id, element.id, 'forward')}
                 className="text-xs text-gray-500 hover:text-white px-1"

package/src/carousel/__tests__/CarouselEditor.test.tsx

@@ -232,4 +232,56 @@ describe('CarouselEditor — editor-core integration', () => {
     expect(adapter.saveCalls.length).toBe(before)
     document.body.removeChild(input)
   })
+
+  // Visibility toggle: ids in `hiddenElementIds` are omitted from the interactive
+  // canvas (editor-only; the thumbnail and `saveProject` are untouched).
+  it('omits hidden elements from the interactive canvas', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject({
+      slides: [
+        {
+          id: 'slide-0',
+          base_color: '#ffffff',
+          elements: [
+            { id: 'el-a', type: 'image', src: 'a.png', x: 0, y: 0, w: 100, h: 100, rotation: 0 },
+            { id: 'el-b', type: 'image', src: 'b.png', x: 10, y: 10, w: 100, h: 100, rotation: 0 },
+          ],
+        },
+      ],
+    })
+    const { container } = render(
+      <CarouselEditor project={initial} adapter={adapter} onProjectChange={vi.fn()} hiddenElementIds={['el-b']} />,
+    )
+    // Visible element renders in the interactive canvas; hidden one does not.
+    await waitFor(() => expect(container.querySelector('[data-interactive] [data-element-id="el-a"]')).not.toBeNull())
+    expect(container.querySelector('[data-interactive] [data-element-id="el-b"]')).toBeNull()
+  })
+
+  // onSelectionChange fires with the selected element, and with null on deselect.
+  it('fires onSelectionChange on select and deselect', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const onSelectionChange = vi.fn()
+    const { container } = render(
+      <CarouselEditor project={initial} adapter={adapter} onProjectChange={vi.fn()} onSelectionChange={onSelectionChange} />,
+    )
+
+    const lastSelection = () => {
+      const calls = onSelectionChange.mock.calls
+      return calls[calls.length - 1]?.[0]
+    }
+
+    const wrapper = await waitFor(() => findInteractiveWrapper('el-img'))
+    await act(async () => { fireEvent.click(wrapper) })
+    await waitFor(() => {
+      expect(lastSelection()?.id).toBe('el-img')
+    })
+
+    // Click the interactive canvas background to clear selection.
+    const root = container.querySelector('[data-interactive]') as HTMLElement
+    await act(async () => { fireEvent.click(root) })
+    await waitFor(() => {
+      expect(lastSelection()).toBeNull()
+    })
+  })
 })

package/src/index.ts

@@ -33,12 +33,25 @@ export type {
   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'
 
@@ -95,6 +108,14 @@ export type { TextFormattingToolbarProps } from './text/TextFormattingToolbar'
 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,
@@ -102,8 +123,9 @@ export {
   readPropAsString,
 } from './overlays/contract'
 
-// ── Assembled carousel editor ───────────────────────────────────────────────
+// ── 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

package/src/types.ts

@@ -99,6 +99,34 @@ export interface GlobalOverlay {
   empty?: boolean
 }
 
+// ── Version history (optional capability) ─────────────────────────────────────
+
+/**
+ * A single entry in a project's version history. The editor-relevant slice of
+ * Montaj's `ProjectVersion` (ui/src/lib/types/schema.ts): a content-addressed
+ * `hash` to restore by, a human-readable `message`, and a `timestamp`. The
+ * adapter maps the host's richer shape down to this.
+ */
+export interface VersionEntry {
+  hash: string
+  message: string
+  timestamp: string
+}
+
+// ── Waveform chunks (optional capability) ─────────────────────────────────────
+
+/**
+ * One rendered waveform-image chunk for an audio track. `path` is a
+ * host-resolvable image path (route through `fileUrl` to display); `start`/`end`
+ * are source-file seconds the chunk covers. Copied verbatim from Montaj's former
+ * `lib/audio-waveform.ts` so the package owns the shape the timeline consumes.
+ */
+export interface WaveformChunk {
+  path: string
+  start: number
+  end: number
+}
+
 // ── Media (optional capability) ───────────────────────────────────────────────
 
 /**
@@ -244,6 +272,53 @@ export interface EditorAdapter<P extends Project = Project> {
    * `listSystemOverlays()` + its `static-text` matcher.
    */
   getDefaultTextOverlay?(): Promise<GlobalOverlay | null>
+
+  // ── Video editor capabilities (optional) ────────────────────────────────────
+  // Hosts driving the video editor implement these; carousel-only hosts omit
+  // them and the editor feature-detects their absence.
+
+  /**
+   * Optional: list the project's version history, newest-first. Maps to
+   * Montaj's `GET /api/projects/:id/versions`, mapped down to `VersionEntry`.
+   */
+  listVersionHistory?(id: string): Promise<VersionEntry[]>
+
+  /**
+   * Optional: restore the project to a prior version by `hash`, returning the
+   * restored project. Maps to Montaj's
+   * `POST /api/projects/:id/versions/:hash/restore`.
+   */
+  restoreVersion?(id: string, hash: string): Promise<P>
+
+  /**
+   * Optional: produce rendered waveform-image chunks for an audio track. The
+   * editor passes the project id, the track id (used to namespace the output
+   * cache), the track's source path, and an optional chunk duration in seconds.
+   * The host renders/caches the chunks and returns their resolvable paths. Maps
+   * to Montaj's `waveform_image` step.
+   */
+  getWaveformChunks?(
+    projectId: string,
+    trackId: string,
+    trackSrc: string,
+    chunkDurationS?: number,
+  ): Promise<WaveformChunk[]>
+
+  /**
+   * Optional: invalidate the host's compiled-overlay cache. When `src` is given,
+   * only that entry is dropped; hosts may treat a missing `src` as a no-op or a
+   * full clear. Maps to Montaj's `clearOverlayCache` in `lib/overlay-eval`.
+   */
+  clearOverlayCache?(src?: string): void
+
+  /**
+   * Optional: resolve the template identifier that `compileOverlay` should
+   * receive for a given caption style name. The mapping is host-specific —
+   * Montaj uses `/api/caption-template/<style>`; other hosts may differ.
+   * When absent the editor renders no captions (graceful no-op). Hosts without
+   * caption support omit this entirely.
+   */
+  resolveCaptionTemplate?(style: string): string
 }
 
 // ── Theme ────────────────────────────────────────────────────────────────────
@@ -306,6 +381,15 @@ export interface EditorSlots {
    * progress (Montaj feeds its SSE log line here); absent → default copy shows.
    */
   pendingStatus?: ReactNode
+  /**
+   * Rendered in the right sidebar below the version-history panel — in the same
+   * position ReviewView showed "Previous runs". The host supplies the concrete
+   * Montaj run-snapshot list (reading `project.history: RunSnapshot[]` and
+   * offering a "Restore this run" action via `onProjectChange`). The package
+   * never reads `project.history` or `RunSnapshot` — those are host-only types.
+   * Absent → nothing is rendered in that slot.
+   */
+  runHistory?: ReactNode
 }
 
 // ── Top-level component props ──────────────────────────────────────────────────
@@ -322,4 +406,81 @@ export interface CarouselEditorProps<P extends Project = Project> {
   theme?: EditorTheme
   slots?: EditorSlots
   readOnly?: boolean
+  /**
+   * Editor-only set of element ids to hide from the interactive canvas. The host
+   * owns this state; the package never persists it (hidden elements are omitted
+   * from the canvas render only, never from `saveProject`). Lets a host
+   * temporarily hide a scrim/background to position overlays beneath it.
+   */
+  hiddenElementIds?: string[]
+  /**
+   * Invoked when the user toggles the selected element's editor-visibility via
+   * the property-panel eye button. The host updates its hidden-set and reflects
+   * it back through `hiddenElementIds`. Absent → no eye toggle is rendered.
+   */
+  onToggleElementVisibility?: (elementId: string) => void
+  /**
+   * Invoked whenever the selected element changes — with the element, or `null`
+   * when selection clears. Lets a host drive selection-aware chrome (e.g. a
+   * "regenerate image" action in a toolbar slot that targets the current
+   * selection). The package keeps owning selection state.
+   */
+  onSelectionChange?: (element: CarouselElement | null) => void
+}
+
+/**
+ * Props for the video editor component. Mirrors `CarouselEditorProps` —
+ * controlled `project` + `onProjectChange`, adapter-driven transport, optional
+ * theme/slots/readOnly — and adds `onBackToSetup`, the host-supplied callback
+ * the editor invokes when the user leaves the editor for the project's setup
+ * view.
+ */
+export interface VideoEditorProps<P extends Project = Project> {
+  project: P
+  adapter: EditorAdapter<P>
+  onProjectChange?: (p: P) => void
+  theme?: EditorTheme
+  slots?: EditorSlots
+  readOnly?: boolean
+  onBackToSetup?: () => void
+
+  // ── Host-supplied Montaj-specific UI (render-prop seams) ──────────────────
+  // The clip/audio inspector and the subcut-regeneration tool read host-only
+  // fields (regenQueue, storyboard, the host's full Project) the package types
+  // don't know. The editor surfaces them as render-props it threads/renders so
+  // those components can stay host-side; the editor stays Montaj-agnostic.
+
+  /**
+   * Render-prop seam for the host's clip/audio inspector (Montaj's
+   * ClipInspectModal). The editor owns the "which item is being inspected"
+   * state — it derives `ctx.item` from the timeline's `onInspectClip` /
+   * `onInspectAudio` callbacks (a Montaj-agnostic `{ kind, id }` selector, not
+   * a project entity) and passes a close callback. Absent → no inspector.
+   */
+  renderClipInspector?: (ctx: {
+    item: { kind: 'clip' | 'audio'; id: string }
+    onClose: () => void
+  }) => ReactNode
+
+  /**
+   * Render-prop seam for the host's subcut-regeneration tool (Montaj's
+   * SubcutRegenTool). Threaded straight through to the timeline, which owns the
+   * open/close trigger (the per-clip Scissors button). Called with the clip id
+   * and a close callback. Absent → the subcut tool isn't rendered.
+   */
+  renderSubcutRegen?: (ctx: { clipId: string; onClose: () => void }) => ReactNode
+
+  /**
+   * Host-computed gate for the per-clip subcut-regenerate affordance (Montaj:
+   * ai_video projects). Threaded to the timeline. The package never reads
+   * `projectType`.
+   */
+  regenEnabled?: boolean
+
+  /**
+   * Host-computed predicate driving the per-clip "queued" badge (Montaj:
+   * project.regenQueue membership). Threaded to the timeline. The package never
+   * reads `regenQueue`.
+   */
+  isClipQueued?: (itemId: string) => boolean
 }