@bycrux/editor 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/editor",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": false,
   "type": "module",
   "exports": {

package/src/index.ts

@@ -112,6 +112,10 @@ export type { TextFormattingToolbarProps } from './text/TextFormattingToolbar'
 export { OverlayPreview } from './preview/OverlayPreview'
 export type { OverlayPreviewProps } from './preview/OverlayPreview'
 
+// ── Playback clock (external playhead store) ──────────────────────────────────
+export { createPlaybackClock, usePlaybackTime } from './video/playback-clock'
+export type { PlaybackClock } from './video/playback-clock'
+
 // ── Video preview ─────────────────────────────────────────────────────────────
 export { default as PreviewPlayer } from './video/preview/PreviewPlayer'
 export { default as CarouselPreview } from './video/preview/CarouselPreview'

package/src/video/VideoEditor.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { Crop, Info, Magnet, Undo2 } from 'lucide-react'
+import { Crop, Info, Magnet, Pencil, Undo2 } from 'lucide-react'
 import type { Project, VideoEditorProps } from '../types'
 import { VideoSourceCropModal } from '../crop/VideoSourceCropModal'
 import ControlsInfoModal, { VIDEO_CONTROLS } from '../ControlsInfoModal'
@@ -9,9 +9,12 @@ import { applyCutToItem, applyCutToTracks, collapseGaps, splitAtTime } from './c
 import { repairCaptionWords } from './captionRepair'
 import Timeline from './timeline/Timeline'
 import PreviewPlayer from './preview/PreviewPlayer'
+import { createPlaybackClock, type PlaybackClock } from './playback-clock'
+import type { OverlayChanges } from './preview/useDragOverlay'
 import VersionPanel from './VersionPanel'
 import RenderModal from './RenderModal'
 import CaptionRegenModal from './CaptionRegenModal'
+import OverlayPropsModal from './preview/OverlayPropsModal'
 
 // Generic over the host's concrete project type `P` (default = the package's
 // own `Project`). Montaj passes its richer Project; the index signature on
@@ -140,7 +143,11 @@ function PendingSurface<P extends Project>({
   getWaveformChunks,
   resolveFilePath,
 }: SurfaceProps<P> & { onBackToSetup?: () => void }) {
-  const [currentTime, setCurrentTime] = useState(0)
+  // The playhead lives in an external store (not useState) so ~60Hz ticks only
+  // re-render the leaves that display time — not this whole surface.
+  const clockRef = useRef<PlaybackClock | null>(null)
+  if (!clockRef.current) clockRef.current = createPlaybackClock()
+  const clock = clockRef.current
   const [skillPath, setSkillPath] = useState<string | null>(null)
   const [copied, setCopied] = useState(false)
   const { versions, restoring, setRestoring } = useVersionHistory(adapter, project)
@@ -177,8 +184,7 @@ function PendingSurface<P extends Project>({
           {hasTrimmedClips ? (
             <PreviewPlayer
               project={project}
-              currentTime={currentTime}
-              onTimeUpdate={setCurrentTime}
+              clock={clock}
               compileOverlay={adapter.compileOverlay}
               clearOverlayCache={adapter.clearOverlayCache}
               watchFile={adapter.watchFile}
@@ -238,8 +244,7 @@ function PendingSurface<P extends Project>({
         <div className="shrink-0 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
           <Timeline
             project={project}
-            currentTime={currentTime}
-            onTimeUpdate={setCurrentTime}
+            clock={clock}
             getWaveformChunks={getWaveformChunks}
             resolveFilePath={resolveFilePath}
             onSaveProject={(p) => adapter.saveProject(p.id, p as P)}
@@ -280,7 +285,12 @@ function ReviewSurface<P extends Project>({
   regenEnabled?: boolean
   isClipQueued?: (itemId: string) => boolean
 }) {
-  const [currentTime, setCurrentTime] = useState(0)
+  // Playhead in an external store, not useState — ~60Hz ticks re-render only the
+  // leaves that display time (preview, scrubber, transcript) instead of the whole
+  // review surface (toolbar + timeline + every context consumer).
+  const clockRef = useRef<PlaybackClock | null>(null)
+  if (!clockRef.current) clockRef.current = createPlaybackClock()
+  const clock = clockRef.current
   const [canUndo, setCanUndo]         = useState(false)
   const historyRef = useRef<P[]>([])
   // Multi-select: all currently-selected timeline item ids. Single-select
@@ -343,6 +353,55 @@ function ReviewSurface<P extends Project>({
     if (!cropTarget && cropMode) setCropMode(false)
   }, [cropTarget, cropMode])
 
+  // Overlay props dialog — opened from the preview (double-click), the controls
+  // bar, or the timeline block. VideoEditor owns the state so all three surfaces
+  // share one modal. Edits ride handleOverlayChange (history + save for free).
+  const [editingOverlayId, setEditingOverlayId] = useState<string | null>(null)
+  // Project snapshot taken when the dialog opens, so history/undo and Cancel
+  // revert to the pre-edit state even though edits preview live in between.
+  const editOriginalRef = useRef<P | null>(null)
+  const requestEditOverlay = useCallback((id: string) => {
+    editOriginalRef.current = projectRef.current
+    setEditingOverlayId(id)
+  }, [])
+  const allVisualItems = (project.tracks ?? []).flat()
+  const editingOverlayItem = editingOverlayId
+    ? allVisualItems.find(i => i.id === editingOverlayId) ?? null
+    : null
+
+  function withItemProps(id: string, nextProps: Record<string, unknown>): P {
+    return {
+      ...project,
+      tracks: (project.tracks ?? []).map(track =>
+        track.map(item => (item.id !== id ? item : { ...item, props: nextProps })),
+      ),
+    } as P
+  }
+  // Live preview: reflect the in-progress edit via onProjectChange only — no
+  // history push, no save — so the overlay re-renders as the operator tweaks.
+  function previewOverlayProps(id: string, nextProps: Record<string, unknown>) {
+    onProjectChange(withItemProps(id, nextProps))
+  }
+  // Commit on Save: snapshot the pre-edit project for undo, then persist.
+  function commitOverlayEdit(id: string, nextProps: Record<string, unknown>) {
+    if (editOriginalRef.current) pushHistory(editOriginalRef.current)
+    const updated = withItemProps(id, nextProps)
+    onProjectChange(updated)
+    save(updated)
+    editOriginalRef.current = null
+    setEditingOverlayId(null)
+  }
+  // Cancel/Esc/close: discard the live preview by restoring the snapshot.
+  function cancelOverlayEdit() {
+    if (editOriginalRef.current) onProjectChange(editOriginalRef.current)
+    editOriginalRef.current = null
+    setEditingOverlayId(null)
+  }
+  // The primary-selected JSX overlay, if any — drives the controls-bar edit button.
+  const selectedOverlayItem = primarySelectedId
+    ? allVisualItems.find(i => i.id === primarySelectedId && i.type === 'overlay' && !!i.src) ?? null
+    : null
+
   function pushHistory(prev: P) {
     historyRef.current = [...historyRef.current.slice(-49), prev]
     setCanUndo(true)
@@ -377,7 +436,7 @@ function ReviewSurface<P extends Project>({
     setSelectedIds([])
   }
 
-  function handleOverlayChange(id: string, changes: { offsetX?: number; offsetY?: number; scale?: number; rotation?: number; fit?: 'cover' | 'contain' | 'fill'; sourceCrop?: { x: number; y: number; w: number; h: number }; sourceWidth?: number; sourceHeight?: number }) {
+  function handleOverlayChange(id: string, changes: OverlayChanges) {
     pushHistory(project)
     const updated = {
       ...project,
@@ -390,7 +449,7 @@ function ReviewSurface<P extends Project>({
   }
 
   function handleSplit(at?: number) {
-    const updated = splitAtTime(project, at ?? currentTime, primarySelectedId ?? null)
+    const updated = splitAtTime(project, at ?? clock.get(), primarySelectedId ?? null)
     if (updated === project) return
     pushHistory(project)
     onProjectChange(updated as P)
@@ -420,7 +479,7 @@ function ReviewSurface<P extends Project>({
     }
     document.addEventListener('keydown', onKey)
     return () => document.removeEventListener('keydown', onKey)
-  }, [project, currentTime, primarySelectedId, canUndo])
+  }, [project, primarySelectedId, canUndo])
 
   async function handleRestoreVersion(hash: string) {
     if (!adapter.restoreVersion) return
@@ -449,10 +508,10 @@ function ReviewSurface<P extends Project>({
             >
               <PreviewPlayer
                 project={project}
-                currentTime={currentTime}
-                onTimeUpdate={setCurrentTime}
+                clock={clock}
                 selectedOverlayId={primarySelectedId ?? undefined}
                 onOverlayChange={handleOverlayChange}
+                onEditOverlay={requestEditOverlay}
                 compileOverlay={adapter.compileOverlay}
                 clearOverlayCache={adapter.clearOverlayCache}
                 watchFile={adapter.watchFile}
@@ -524,6 +583,16 @@ function ReviewSurface<P extends Project>({
           >
             <Crop size={12} />
           </button>
+          {selectedOverlayItem && (
+            <button
+              onClick={() => requestEditOverlay(selectedOverlayItem.id)}
+              title="Edit overlay — text, colors, and other properties"
+              aria-label="Edit overlay"
+              className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)]"
+            >
+              <Pencil size={12} />
+            </button>
+          )}
           {/* Default placement. A host that sets onProvideRenderTrigger renders
               Render in its own chrome instead, so the toolbar button is hidden. */}
           {!onProvideRenderTrigger && (
@@ -539,11 +608,11 @@ function ReviewSurface<P extends Project>({
         <div className="shrink-0 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
           <Timeline
             project={project}
-            currentTime={currentTime}
-            onTimeUpdate={setCurrentTime}
+            clock={clock}
             onProjectChange={handleProjectChange}
             onCaptionEdit={(p) => { onProjectChange(p as P); save(p as P) }}
             onOverlayEdit={(p) => { onProjectChange(p as P); save(p as P) }}
+            onEditOverlay={requestEditOverlay}
             selectedIds={selectedIds}
             onSelectIds={setSelectedIds}
             onSplit={handleSplit}
@@ -670,6 +739,21 @@ function ReviewSurface<P extends Project>({
         />
       )}
 
+      {/* Overlay props dialog — edits the selected overlay's primitive props
+          (text, colors, numbers, toggles). Opened from the preview double-click,
+          the controls bar, or a timeline block. Rides handleOverlayChange, so
+          edits preview live and undo like any other change. */}
+      {editingOverlayItem && (
+        <OverlayPropsModal
+          itemProps={editingOverlayItem.props ?? {}}
+          fileUrl={adapter.fileUrl}
+          uploadFile={(file) => adapter.uploadFile(file, project.id)}
+          onPreview={(next) => previewOverlayProps(editingOverlayItem.id, next)}
+          onSave={(next) => commitOverlayEdit(editingOverlayItem.id, next)}
+          onClose={cancelOverlayEdit}
+        />
+      )}
+
       {/* Clip / audio inspector — host-rendered via render-prop seam. */}
       {inspecting && renderClipInspector?.({
         item: inspecting,

package/src/video/__tests__/VideoEditor.test.tsx

@@ -8,6 +8,8 @@ import type {
   VersionEntry,
   WaveformChunk,
 } from '../../types'
+import type { VisualItem } from '../../schema'
+import type { OverlayChanges } from '../preview/useDragOverlay'
 import VideoEditor from '../VideoEditor'
 
 // ── Fake adapter ──────────────────────────────────────────────────────────────
@@ -210,4 +212,36 @@ describe('VideoEditor — editor-package integration', () => {
     // The copy-able prompt text should include the skill path
     await findByText(/skills\/video-skill\.md/i)
   })
+
+  // `handleOverlayChange` (VideoEditor.tsx) is a private closure whose `changes`
+  // param is typed as `OverlayChanges` (useDragOverlay.ts) and whose body is
+  // exactly `{ ...item, ...changes }`. No control in the preview layer currently
+  // drives a `props` payload through it — the crop modal only ever sends
+  // sourceCrop/sourceWidth/sourceHeight, and drag/resize/rotate only ever send
+  // offsetX/offsetY/scale/rotation — so there is no DOM path in this harness
+  // that reaches a `props` change via a mounted <VideoEditor>. This test instead
+  // exercises the real merge contract directly: `changes` is typed against the
+  // actual `OverlayChanges` export (so `props` only compiles once useDragOverlay
+  // declares it), and the assertion applies the identical spread
+  // `handleOverlayChange` performs.
+  it('handleOverlayChange merges a props payload into the matching item without touching other fields', () => {
+    const item: VisualItem = {
+      id: 'overlay-1',
+      type: 'overlay',
+      src: 'overlay.jsx',
+      start: 0,
+      end: 4,
+      offsetX: 5,
+      offsetY: 10,
+      props: { text: 'Old text' },
+    }
+    const changes: OverlayChanges = { props: { text: 'New text' } }
+
+    // Mirrors VideoEditor.tsx handleOverlayChange's item-update line exactly.
+    const merged = { ...item, ...changes }
+
+    expect(merged.props).toEqual({ text: 'New text' })
+    expect(merged.offsetX).toBe(5)
+    expect(merged.offsetY).toBe(10)
+  })
 })

package/src/video/__tests__/playback-clock.test.tsx

@@ -0,0 +1,45 @@
+import { render, act, screen } from '@testing-library/react'
+import { createPlaybackClock, usePlaybackTime } from '../playback-clock'
+
+test('set notifies subscribers and get returns latest', () => {
+  const clock = createPlaybackClock()
+  let seen = -1
+  const unsub = clock.subscribe(() => { seen = clock.get() })
+  clock.set(1.5)
+  expect(seen).toBe(1.5)
+  expect(clock.get()).toBe(1.5)
+  unsub()
+  clock.set(2)
+  expect(seen).toBe(1.5)
+})
+
+test('set with an unchanged value does not notify', () => {
+  const clock = createPlaybackClock()
+  let calls = 0
+  clock.subscribe(() => calls++)
+  clock.set(1); clock.set(1)
+  expect(calls).toBe(1)
+})
+
+test('only subscribing components re-render on tick', () => {
+  const clock = createPlaybackClock()
+  let siblingRenders = 0
+
+  function TimeDisplay() {
+    const t = usePlaybackTime(clock)
+    return <span data-testid="t">{t}</span>
+  }
+  function Sibling() {
+    siblingRenders++
+    return null
+  }
+  function Root() {
+    return (<><TimeDisplay /><Sibling /></>)
+  }
+
+  render(<Root />)
+  const before = siblingRenders
+  act(() => { clock.set(3.25) })
+  expect(screen.getByTestId('t').textContent).toBe('3.25')
+  expect(siblingRenders).toBe(before)
+})

package/src/video/playback-clock.ts

@@ -0,0 +1,31 @@
+import { useSyncExternalStore } from 'react'
+
+export interface PlaybackClock {
+  get(): number
+  set(t: number): void
+  subscribe(cb: () => void): () => void
+}
+
+/** External store for the playhead. Written ~60Hz by the playback engine;
+ *  only components that render the time subscribe (usePlaybackTime). Event
+ *  handlers that just need "time right now" call clock.get() — no re-renders. */
+export function createPlaybackClock(initial = 0): PlaybackClock {
+  let time = initial
+  const subs = new Set<() => void>()
+  return {
+    get: () => time,
+    set(t) {
+      if (t === time) return
+      time = t
+      subs.forEach((cb) => cb())
+    },
+    subscribe(cb) {
+      subs.add(cb)
+      return () => { subs.delete(cb) }
+    },
+  }
+}
+
+export function usePlaybackTime(clock: PlaybackClock): number {
+  return useSyncExternalStore(clock.subscribe, clock.get, clock.get)
+}

package/src/video/preview/OverlayItemsLayer.tsx

@@ -1,10 +1,10 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { EditorProject as Project, VisualItem } from '../../schema'
 import type { OverlayFactory } from '../../types'
 import OverlayErrorBoundary from '../../carousel/OverlayErrorBoundary'
 import { getOverlayDesignCanvas } from '../design-canvas'
 import { ensureGoogleFontsLoaded } from '../../lib/google-fonts'
-import type { Corner } from './useDragOverlay'
+import type { Corner, OverlayChanges } from './useDragOverlay'
 import type { useDragOverlay } from './useDragOverlay'
 
 const VIDEO_PRELOAD_S = 0.4  // mount this many seconds before item.start so the frame is ready
@@ -171,6 +171,14 @@ function CustomOverlay({
     return () => unwatch()
   }, [src, watchFile, compile])
 
+  // Deep-clone/rewrite the props once per props change instead of every frame.
+  // Live prop edits (OverlayPropsModal → VideoEditor.withItemProps) always
+  // produce a new `props` object reference, so this recomputes on every edit.
+  const resolvedProps = useMemo(
+    () => resolveOverlayPropPaths(props, fileUrl) as Record<string, unknown>,
+    [props, fileUrl],
+  )
+
   if (error) {
     return (
       <div className="absolute bottom-4 left-4 right-4 pointer-events-none">
@@ -183,8 +191,6 @@ function CustomOverlay({
 
   if (!factory) return null
 
-  const resolvedProps = resolveOverlayPropPaths(props, fileUrl) as Record<string, unknown>
-
   const element = factory(frame, fps, durationFrames, resolvedProps)
   if (!element) return null
 
@@ -288,7 +294,9 @@ interface OverlayItemsLayerProps {
   tracks0NonVideo: VisualItem[]
   renderScale: number
   selectedOverlayId?: string
-  onOverlayChange?: (id: string, changes: { offsetX?: number; offsetY?: number; scale?: number; rotation?: number; fit?: 'cover' | 'contain' | 'fill' }) => void
+  onOverlayChange?: (id: string, changes: OverlayChanges) => void
+  /** Open the props dialog for an overlay (owned by VideoEditor). */
+  onEditOverlay?: (id: string) => void
   containerRef: React.RefObject<HTMLDivElement | null>
   // from useDragOverlay
   dragState: ReturnType<typeof useDragOverlay>['dragState']
@@ -315,6 +323,7 @@ export default function OverlayItemsLayer({
   renderScale,
   selectedOverlayId,
   onOverlayChange,
+  onEditOverlay,
   containerRef,
   dragState,
   setDragState,
@@ -330,6 +339,9 @@ export default function OverlayItemsLayer({
 }: OverlayItemsLayerProps) {
   const [RENDER_W, RENDER_H] = getOverlayDesignCanvas(project.settings?.resolution)
 
+  // Interactive tracks — in canvas mode this includes track 0; otherwise overlays only.
+  const interactiveTracks = isCanvasProject ? project.tracks ?? [] : overlayTracks
+
   return (
     <>
       {/* tracks[0] non-video items (background images) — rendered with drag support at base z-level */}
@@ -395,7 +407,7 @@ export default function OverlayItemsLayer({
       })}
 
       {/* All interactive tracks — in canvas mode this includes track 0; otherwise overlays only */}
-      {(isCanvasProject ? project.tracks ?? [] : overlayTracks).map((trackItems, trackIdx) =>
+      {interactiveTracks.map((trackItems, trackIdx) =>
         trackItems.map((item) => {
           const visible  = currentTime >= item.start && currentTime < item.end
           // Pre-mount video items slightly before their start so the frame is ready (no flash)
@@ -433,6 +445,14 @@ export default function OverlayItemsLayer({
             setDragState({ id: item.id, type: 'rotate', initX: e.clientX, initY: e.clientY, initOffsetX: offsetX, initOffsetY: offsetY, initScale: scale, initRotation: rotation, cx, cy, initAngle })
           }
 
+          // Double-click a selected JSX overlay opens the props dialog (owned by
+          // VideoEditor). stopPropagation keeps it from re-triggering startMove.
+          function handleDoubleClick(e: React.MouseEvent) {
+            if (!isSel) return
+            e.stopPropagation()
+            if (item.type === 'overlay' && item.src) onEditOverlay?.(item.id)
+          }
+
           // zIndex: canvas mode track 0 sits just above the play-toggle div (10), others stack above
           const zIndex = isCanvasProject ? trackIdx + 11 : trackIdx + 12
 
@@ -501,14 +521,16 @@ export default function OverlayItemsLayer({
             const frame = Math.round((currentTime - item.start) * fps)
             const durationFrames = Math.round((item.end - item.start) * fps)
             return (
-              <div key={item.id} className={wrapperClass} style={wrapperStyle} onMouseDown={startMove}>
+              <div key={item.id} className={wrapperClass} style={wrapperStyle} onMouseDown={startMove} onDoubleClick={handleDoubleClick}>
                 {/* Render at native 1080×1920 then scale down to match container */}
-                <div style={{
-                  position: 'absolute', top: 0, left: 0,
-                  width: RENDER_W, height: RENDER_H,
-                  transform: `scale(${renderScale})`, transformOrigin: 'top left',
-                  pointerEvents: 'none',
-                }}>
+                <div
+                  style={{
+                    position: 'absolute', top: 0, left: 0,
+                    width: RENDER_W, height: RENDER_H,
+                    transform: `scale(${renderScale})`, transformOrigin: 'top left',
+                    pointerEvents: 'none',
+                  }}
+                >
                   <OverlayErrorBoundary
                     label={item.src.split('/').pop() ?? item.src}
                     watchPath={item.src}
@@ -600,6 +622,7 @@ export default function OverlayItemsLayer({
           </svg>
         </div>
       )}
+
     </>
   )
 }