@bycrux/editor 0.8.9 → 0.10.0

package/package.json

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

package/src/carousel/CarouselEditor.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
-import { RefreshCw, AlertCircle, Download, Info } from 'lucide-react'
+import { RefreshCw, AlertCircle, Download, Info, Undo2, Redo2 } from 'lucide-react'
 import type { Project, Slide, CarouselElement, ImageElement, CarouselEditorProps, OverlayFactory } from '../types'
 import { applyTheme, defaultMontajTheme } from '../theme'
 import { useProjectState } from '../state/use-project-state'
@@ -409,19 +409,39 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
         {/* TOOLBAR ROW: Refresh on the left; host toolbar actions + Render on the
             right. Pinned (shrink-0) above the scrolling canvas area. */}
         <div className="flex-shrink-0 flex items-center justify-between gap-2 px-4 py-3 border-b border-[var(--editor-border)]">
-          <button
-            onClick={handleRefresh}
-            disabled={refreshing}
-            className={`flex items-center gap-2 px-3 py-2 rounded-md border transition-colors ${
-              refreshState === 'err'
-                ? 'text-red-300 border-red-500/40 bg-red-950/60 hover:bg-red-900/70'
-                : 'text-[var(--editor-text)] border-[var(--editor-border)] bg-[var(--editor-surface)]/80 hover:text-[var(--editor-text)] hover:border-[var(--editor-accent)] hover:bg-[var(--editor-surface)]'
-            }`}
-            title={refreshState === 'err' ? 'Refresh failed — check connection' : 'Refresh project'}
-          >
-            {refreshState === 'err' ? <AlertCircle size={18} /> : <RefreshCw size={18} className={refreshing ? 'animate-spin' : ''} />}
-            <span className="text-xs font-medium">Refresh</span>
-          </button>
+          <div className="flex items-center gap-2">
+            <button
+              onClick={handleRefresh}
+              disabled={refreshing}
+              className={`flex items-center gap-2 px-3 py-2 rounded-md border transition-colors ${
+                refreshState === 'err'
+                  ? 'text-red-300 border-red-500/40 bg-red-950/60 hover:bg-red-900/70'
+                  : 'text-[var(--editor-text)] border-[var(--editor-border)] bg-[var(--editor-surface)]/80 hover:text-[var(--editor-text)] hover:border-[var(--editor-accent)] hover:bg-[var(--editor-surface)]'
+              }`}
+              title={refreshState === 'err' ? 'Refresh failed — check connection' : 'Refresh project'}
+            >
+              {refreshState === 'err' ? <AlertCircle size={18} /> : <RefreshCw size={18} className={refreshing ? 'animate-spin' : ''} />}
+              <span className="text-xs font-medium">Refresh</span>
+            </button>
+            <button
+              onClick={() => state.undo()}
+              disabled={!state.canUndo}
+              className="flex items-center justify-center p-2 rounded-md border border-[var(--editor-border)] bg-[var(--editor-surface)]/80 text-[var(--editor-text)] transition-colors hover:border-[var(--editor-accent)] hover:bg-[var(--editor-surface)] disabled:opacity-40 disabled:cursor-not-allowed"
+              title="Undo (Cmd/Ctrl+Z)"
+              aria-label="Undo"
+            >
+              <Undo2 size={18} />
+            </button>
+            <button
+              onClick={() => state.redo()}
+              disabled={!state.canRedo}
+              className="flex items-center justify-center p-2 rounded-md border border-[var(--editor-border)] bg-[var(--editor-surface)]/80 text-[var(--editor-text)] transition-colors hover:border-[var(--editor-accent)] hover:bg-[var(--editor-surface)] disabled:opacity-40 disabled:cursor-not-allowed"
+              title="Redo (Cmd/Ctrl+Shift+Z)"
+              aria-label="Redo"
+            >
+              <Redo2 size={18} />
+            </button>
+          </div>
 
           <div className="flex items-center gap-2">
             {slots?.toolbarActions}

package/src/carousel/SlidePropertyPanel.tsx

@@ -9,7 +9,7 @@ import type {
   GlobalOverlayProp,
   EditorAdapter,
 } from '../types'
-import { Button, cn, inspectorInputClass } from '../ui'
+import { Button, cn, inspectorInputClass, SwatchInput } from '../ui'
 import { TextFormattingToolbar } from '../text/TextFormattingToolbar'
 
 function parseNumber(v: string): number | null {
@@ -173,40 +173,6 @@ function PropEditor({
   )
 }
 
-// Color control that actually reads as one: a filled rounded swatch (the live
-// value) sitting next to the hex string, the whole row clickable to open the
-// native color picker. The transparent <input type="color"> overlays the
-// swatch so the OS picker anchors there.
-function SwatchInput({
-  value,
-  onChange,
-  ariaLabel,
-}: {
-  value: string
-  onChange: (v: string) => void
-  ariaLabel: string
-}) {
-  return (
-    <div className="flex items-center gap-2.5">
-      <label className="relative h-7 w-7 shrink-0 cursor-pointer">
-        <span
-          className="block h-full w-full rounded-md border border-[var(--editor-border)] shadow-sm"
-          style={{ backgroundColor: value }}
-          aria-hidden
-        />
-        <input
-          type="color"
-          value={value}
-          onChange={e => onChange(e.target.value)}
-          className="absolute inset-0 h-full w-full cursor-pointer opacity-0"
-          aria-label={ariaLabel}
-        />
-      </label>
-      <span className="font-mono text-sm uppercase text-[var(--editor-text)]/80">{value}</span>
-    </div>
-  )
-}
-
 export default function SlidePropertyPanel({
   project,
   slide,

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/schema.ts

@@ -45,12 +45,20 @@ export interface CaptionSegment {
 export interface Captions {
   style: 'word-by-word' | 'pop' | 'karaoke' | 'subtitle' | 'highlight-box' | 'outline' | 'clean'
   segments: CaptionSegment[]
-  // ffmpeg-drawtext render params — ignored by JSX preview, used by render.js ffmpeg branch
+  // `color` and `fontsize` are read by BOTH paths: the JSX browser preview /
+  // Puppeteer render (spread into the caption template props; `fontsize`→`fontSize`)
+  // and the ffmpeg-drawtext render branch. `position` and `bgColor` are consumed
+  // only by the ffmpeg-drawtext branch and ignored by the JSX preview.
   position?: 'center' | 'top-left' | 'bottom-left'
-  color?: string
+  color?: string          // base caption text color
   fontsize?: number
   bgColor?: string
-  accentColor?: string    // active-word/box accent color — highlight-box, outline
+  // Per-style accent color fields, each read by the matching JSX caption template.
+  // A single UI control writes whichever one the active style uses (see TranscriptPanel).
+  accentColor?: string    // active-word/box accent — highlight-box, outline
+  highlightColor?: string // active word — karaoke
+  activeColor?: string    // active word — pop
+  backgroundColor?: string// text box background — subtitle
   googleFonts?: string[]  // Google Fonts family specs for the caption template (e.g. ["Figtree:wght@700"])
 }
 

package/src/ui/SwatchInput.tsx

@@ -0,0 +1,57 @@
+import { cn } from './utils'
+
+// Color control that actually reads as one: a filled rounded swatch (the live
+// value) with the native <input type="color"> overlaid transparently so the OS
+// picker anchors on the swatch. Optionally shows the hex string beside it.
+//
+// `onChange` fires live on every pick (drive a cheap preview). `onCommit`, if
+// given, fires on blur (when the OS picker closes) — use it to persist once
+// instead of on every intermediate value, mirroring a slider's drag→commit.
+export interface SwatchInputProps {
+  value: string
+  onChange: (v: string) => void
+  /** Fired on blur (picker closed) — for callers that preview live via onChange
+   *  and persist only on commit. Omit to treat every onChange as final. */
+  onCommit?: (v: string) => void
+  ariaLabel: string
+  /** Render the hex string next to the swatch. Default true. */
+  showValue?: boolean
+  /** Swatch size. `sm` (h-5) suits compact toolbars; `md` (h-7) is the default. */
+  size?: 'sm' | 'md'
+  /** Tooltip on the row. */
+  title?: string
+}
+
+export function SwatchInput({
+  value,
+  onChange,
+  onCommit,
+  ariaLabel,
+  showValue = true,
+  size = 'md',
+  title,
+}: SwatchInputProps) {
+  const box = size === 'sm' ? 'h-5 w-5' : 'h-7 w-7'
+  return (
+    <div className="flex items-center gap-2.5" title={title}>
+      <label className={cn('relative shrink-0 cursor-pointer', box)}>
+        <span
+          className="block h-full w-full rounded-md border border-[var(--editor-border)] shadow-sm"
+          style={{ backgroundColor: value }}
+          aria-hidden
+        />
+        <input
+          type="color"
+          value={value}
+          onChange={e => onChange(e.target.value)}
+          onBlur={e => onCommit?.(e.target.value)}
+          className="absolute inset-0 h-full w-full cursor-pointer opacity-0"
+          aria-label={ariaLabel}
+        />
+      </label>
+      {showValue && (
+        <span className="font-mono text-sm uppercase text-[var(--editor-text)]/80">{value}</span>
+      )}
+    </div>
+  )
+}

package/src/ui/index.ts

@@ -9,6 +9,8 @@ export type { InputProps } from './input'
 export { Label } from './label'
 export { Select } from './select'
 export type { SelectProps } from './select'
+export { SwatchInput } from './SwatchInput'
+export type { SwatchInputProps } from './SwatchInput'
 export { Switch } from './switch'
 export { Textarea } from './textarea'
 export type { TextareaProps } from './textarea'

package/src/video/VideoEditor.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { Crop, Info, Magnet } 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}
@@ -475,6 +534,15 @@ function ReviewSurface<P extends Project>({
           >
             <Info size={12} />
           </button>
+          <button
+            onClick={handleUndo}
+            disabled={!canUndo}
+            title="Undo (Cmd/Ctrl+Z)"
+            aria-label="Undo"
+            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)] disabled:opacity-30 disabled:cursor-not-allowed"
+          >
+            <Undo2 size={12} />
+          </button>
           <button
             onClick={() => handleSplit()}
             title="Split at playhead (S) — selected item or all clips"
@@ -515,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 && (
@@ -530,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}
@@ -661,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)
+}