@devbycrux/editor 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devbycrux/editor",
-  "version": "0.1.0",
+  "version": "0.2.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/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 ──────────────────────────────────────────────────
@@ -323,3 +407,60 @@ export interface CarouselEditorProps<P extends Project = Project> {
   slots?: EditorSlots
   readOnly?: boolean
 }
+
+/**
+ * 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
+}

package/src/video/RenderModal.tsx

@@ -0,0 +1,252 @@
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import type { EditorAdapter, Project } from '../types'
+
+interface RenderModalProps<P extends Project = Project> {
+  projectId: string
+  /** Adapter driving the render stream + file-URL resolution. */
+  adapter: EditorAdapter<P>
+  /** Fired when the modal closes from a finished or errored state (post-render).
+   *  Callers can use this to navigate away or refresh project state. */
+  onClose: () => void
+  /** Fired when the user cancels an in-progress render via the Cancel button.
+   *  Distinct from onClose so callers can dismiss the modal without navigating
+   *  away from the editor — the project is unchanged and the user is likely
+   *  about to keep editing. Defaults to onClose if not provided (back-compat). */
+  onCancel?: () => void
+  /** Host-supplied export controls (e.g. a "Download all (.zip)" link) rendered
+   *  in the done state's action area, mirroring the carousel render modal. */
+  exportActions?: ReactNode
+}
+
+function basename(p: string) { return p.split('/').pop() ?? p }
+
+function LogLine({ text }: { text: string }) {
+  const t = text.replace(/^\[montaj render\]\s*/, '')
+  let color = 'text-gray-400'
+  if (/ready|complete|done|encoded|assembled/i.test(t))  color = 'text-green-400'
+  else if (/rendering|bundling|launching|browsers/i.test(t)) color = 'text-sky-400'
+  else if (/trimming|building|composing/i.test(t))       color = 'text-amber-400'
+  else if (/frame\s+\d+\/\d+/i.test(t))                  color = 'text-gray-500'
+  else if (/error|fail|warn/i.test(t))                   color = 'text-red-400'
+
+  const prefix = text.startsWith('[montaj render]')
+    ? <span className="text-gray-600">[render] </span>
+    : null
+
+  return (
+    <span className={`leading-relaxed whitespace-pre-wrap break-all ${color}`}>
+      {prefix}{t}
+    </span>
+  )
+}
+
+export default function RenderModal<P extends Project = Project>({ projectId, adapter, onClose, onCancel, exportActions }: RenderModalProps<P>) {
+  const [logs, setLogs]         = useState<string[]>([])
+  const [status, setStatus]     = useState<'running' | 'done' | 'error'>('running')
+  const [outputPath, setOutput] = useState<string | null>(null)
+  const [errorMsg, setError]    = useState<string | null>(null)
+  const logRef                  = useRef<HTMLDivElement>(null)
+  const cancelledRef            = useRef(false)
+  const unmountedRef            = useRef(false)
+  const cleanupTimerRef         = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    // React StrictMode in dev fires mount → cleanup → mount synchronously to
+    // catch effects that aren't idempotent. Triggering a render is the textbook
+    // non-idempotent effect (spawns a subprocess), so we have to handle it
+    // explicitly: defer the teardown in cleanup, and if the next mount fires
+    // within the same tick, rescue the pending teardown.
+    //
+    // Without this, every render in dev would consume two render streams against
+    // the same workspace, racing on segment files and producing corrupted output
+    // — the bug we tracked down.
+    if (cleanupTimerRef.current !== null) {
+      clearTimeout(cleanupTimerRef.current)
+      cleanupTimerRef.current = null
+      unmountedRef.current = false
+      cancelledRef.current = false
+      return scheduleCleanup
+    }
+
+    unmountedRef.current = false
+    cancelledRef.current = false
+
+    void (async () => {
+      try {
+        for await (const ev of adapter.render(projectId)) {
+          if (unmountedRef.current || cancelledRef.current) break
+          if (ev.type === 'log') {
+            setLogs(l => [...l, ev.message])
+          } else if (ev.type === 'done') {
+            setOutput(ev.outputPath)
+            setStatus('done')
+          } else {
+            setError(ev.message)
+            setStatus('error')
+          }
+        }
+      } catch (e) {
+        if (!unmountedRef.current && !cancelledRef.current) {
+          setError(e instanceof Error ? e.message : String(e))
+          setStatus('error')
+        }
+      }
+    })()
+
+    return scheduleCleanup
+
+    function scheduleCleanup() {
+      // Defer the actual teardown. StrictMode's transient unmount fires before
+      // the next mount; setTimeout(0) puts the teardown after both, giving the
+      // next mount a chance to clearTimeout it. On real unmount the timer fires
+      // and the render stream is abandoned for real.
+      cleanupTimerRef.current = setTimeout(() => {
+        cleanupTimerRef.current = null
+        unmountedRef.current = true
+      }, 0)
+    }
+  }, [projectId, adapter])
+
+  // Auto-scroll logs
+  useEffect(() => {
+    if (logRef.current) logRef.current.scrollTop = logRef.current.scrollHeight
+  }, [logs])
+
+  // Escape to close only when done/error
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && status !== 'running') onClose()
+    }
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  }, [status, onClose])
+
+  function handleCancel() {
+    cancelledRef.current = true
+    // Use onCancel when provided so the host can dismiss without navigating
+    // (cancelling an in-progress render shouldn't yank the user away from
+    // their editor). Falls back to onClose for back-compat with callers that
+    // haven't been updated.
+    ;(onCancel ?? onClose)()
+  }
+
+  if (status === 'done' && outputPath) {
+    return (
+      <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/90 backdrop-blur-md">
+        <div className="w-[96vw] h-[96vh] bg-gray-950 border border-gray-800 rounded-2xl shadow-2xl flex overflow-hidden">
+
+          {/* Left — video */}
+          <div className="flex-1 bg-black flex items-center justify-center overflow-hidden">
+            <video
+              src={adapter.fileUrl(outputPath)}
+              controls
+              autoPlay
+              playsInline
+              className="h-full w-full object-contain"
+            />
+          </div>
+
+          {/* Right — info panel */}
+          <div className="w-72 shrink-0 flex flex-col border-l border-gray-800">
+            <div className="flex items-center justify-between px-5 py-4 border-b border-gray-800">
+              <div className="flex items-center gap-2.5">
+                <span className="w-2 h-2 rounded-full bg-green-400" />
+                <div>
+                  <p className="text-sm font-semibold text-white">Render complete</p>
+                  <p className="text-xs text-gray-400">Your video is ready.</p>
+                </div>
+              </div>
+              <button onClick={onClose} className="text-gray-500 hover:text-white transition-colors text-lg leading-none">×</button>
+            </div>
+
+            <div className="flex flex-col gap-3 p-5 flex-1">
+              <p className="text-xs font-mono text-gray-500 break-all leading-relaxed">{outputPath}</p>
+              {/* Host-supplied export controls (e.g. download-all .zip). */}
+              {exportActions}
+              <a
+                href={adapter.fileUrl(outputPath)}
+                download={basename(outputPath)}
+                className="w-full text-center text-sm px-4 py-2.5 rounded-lg bg-green-800/60 border border-green-700 text-green-200 hover:bg-green-700/60 transition-colors font-medium"
+              >
+                Download
+              </a>
+              <button
+                onClick={onClose}
+                className="w-full text-center text-sm px-4 py-2.5 rounded-lg bg-gray-800 border border-gray-700 text-gray-300 hover:bg-gray-700 transition-colors"
+              >
+                Close
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm">
+      <div className="w-full max-w-3xl bg-gray-900 border border-gray-700 rounded-xl shadow-2xl flex flex-col overflow-hidden">
+
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 py-4 border-b border-gray-800">
+          <div className="flex items-center gap-2.5">
+            {status === 'running' && <span className="w-2 h-2 rounded-full bg-amber-400 animate-pulse" />}
+            {status === 'error'   && <span className="w-2 h-2 rounded-full bg-red-400" />}
+            <div className="flex flex-col gap-0.5">
+              <h2 className="text-sm font-semibold text-white">
+                {status === 'running' ? 'Rendering…' : 'Render failed'}
+              </h2>
+            </div>
+          </div>
+          {status !== 'running' && (
+            <button onClick={onClose} className="text-gray-500 hover:text-white transition-colors text-lg leading-none">×</button>
+          )}
+        </div>
+
+        {/* Log output */}
+        <div className="relative">
+          <button
+            onClick={() => navigator.clipboard.writeText(logs.join('\n') + (errorMsg ? '\n' + errorMsg : ''))}
+            className="absolute top-2 right-2 z-10 text-[10px] px-2 py-0.5 rounded bg-gray-800 border border-gray-700 text-gray-400 hover:text-white hover:border-gray-500 transition-colors"
+            title="Copy logs"
+          >
+            Copy
+          </button>
+          <div
+            ref={logRef}
+            className="h-96 overflow-y-auto px-4 py-3 font-mono text-[11px] text-gray-300 bg-gray-950 flex flex-col gap-0.5"
+          >
+            {logs.length === 0 && status === 'running' && (
+              <span className="text-gray-600 italic">Starting render engine…</span>
+            )}
+            {logs.map((line, i) => (
+              <LogLine key={i} text={line} />
+            ))}
+            {status === 'error' && errorMsg && (
+              <span className="text-red-400 mt-1">{errorMsg}</span>
+            )}
+          </div>
+        </div>
+
+        {/* Footer */}
+        <div className="flex items-center justify-end gap-2 px-5 py-3 border-t border-gray-800">
+          {status === 'running' ? (
+            <button
+              onClick={handleCancel}
+              className="text-sm px-4 py-1.5 rounded-md bg-gray-800 border border-gray-700 text-gray-300 hover:bg-red-900/40 hover:border-red-700 hover:text-red-300 transition-colors"
+            >
+              Cancel
+            </button>
+          ) : (
+            <button
+              onClick={onClose}
+              className="text-sm px-4 py-1.5 rounded-md bg-gray-800 border border-gray-700 text-white hover:bg-gray-700 transition-colors"
+            >
+              Close
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/video/VersionPanel.tsx

@@ -0,0 +1,83 @@
+import { useState } from 'react'
+import type { VersionEntry } from '../types'
+
+// VersionPanel reads only the editor-relevant slice of a version — hash,
+// message, timestamp — which is exactly `VersionEntry`. Aliased to the panel's
+// original `ProjectVersion` name so the ported parse/dedup logic is untouched.
+type ProjectVersion = VersionEntry
+
+function formatTime(iso: string): string {
+  const d = new Date(iso)
+  return d.toLocaleString(undefined, { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' })
+}
+
+function parseVersion(v: ProjectVersion): { run: number; label: string } {
+  const m = v.message.match(/run (\d+) — (.+)/)
+  return m ? { run: parseInt(m[1]), label: m[2] } : { run: 0, label: v.message }
+}
+
+function dedupeVersions(versions: ProjectVersion[]): ProjectVersion[] {
+  const nonInit = versions.filter(v => parseVersion(v).run > 0)
+  const byRun = new Map<number, ProjectVersion>()
+  for (const v of nonInit) {
+    const { run, label } = parseVersion(v)
+    const existing = byRun.get(run)
+    const isDefault = label === 'draft' || label === 'final' || label === 'pending'
+    if (!existing) { byRun.set(run, v); continue }
+    const { label: existingLabel } = parseVersion(existing)
+    const existingIsDefault = existingLabel === 'draft' || existingLabel === 'final' || existingLabel === 'pending'
+    if (existingIsDefault && !isDefault) byRun.set(run, v)
+  }
+  return [...byRun.values()].sort((a, b) => parseVersion(b).run - parseVersion(a).run)
+}
+
+interface VersionPanelProps {
+  versions: ProjectVersion[]
+  restoring: string | null
+  onRestore: (hash: string) => void
+}
+
+export default function VersionPanel({ versions, restoring, onRestore }: VersionPanelProps) {
+  const [open, setOpen] = useState(true)
+  const deduped = dedupeVersions(versions)
+
+  return (
+    <div className="shrink-0 border-b border-gray-200 dark:border-gray-800 flex flex-col overflow-hidden" style={{ maxHeight: open ? 224 : 0, transition: 'max-height 0.15s ease' }}>
+      <button
+        onClick={() => setOpen(o => !o)}
+        className="flex items-center justify-between px-3 py-2 border-b border-gray-200 dark:border-gray-800 hover:bg-gray-100 dark:hover:bg-gray-900 transition-colors w-full text-left"
+      >
+        <span className="text-xs font-medium text-gray-400 uppercase tracking-wide">Versions</span>
+        <span className="text-gray-600 text-[10px]">{open ? '▲' : '▼'}</span>
+      </button>
+      <div className="overflow-y-auto p-2 flex flex-col gap-1.5">
+        {deduped.length === 0 ? (
+          <p className="text-xs text-gray-600 text-center mt-2 px-1 leading-relaxed">No saved versions yet.</p>
+        ) : deduped.map(v => {
+          const { run, label } = parseVersion(v)
+          const isDefault = label === 'draft' || label === 'final' || label === 'pending'
+          return (
+            <div key={v.hash} className="rounded border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-2 flex flex-col gap-1">
+              <div className="flex items-center gap-1.5">
+                <span className="text-[10px] text-gray-500 dark:text-gray-600 shrink-0">Run {run}</span>
+                {isDefault ? (
+                  <span className="text-[10px] text-gray-500 capitalize">{label}</span>
+                ) : (
+                  <span className="text-xs font-medium text-gray-700 dark:text-gray-200 truncate capitalize" title={label}>{label}</span>
+                )}
+              </div>
+              <span className="text-[10px] text-gray-600">{formatTime(v.timestamp)}</span>
+              <button
+                onClick={() => onRestore(v.hash)}
+                disabled={restoring === v.hash}
+                className="text-[10px] text-blue-500 hover:text-blue-400 text-left transition-colors disabled:opacity-40"
+              >
+                {restoring === v.hash ? 'Restoring…' : 'Restore →'}
+              </button>
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}