@bycrux/editor 0.11.0 → 0.11.2

package/package.json

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

package/src/schema.ts

@@ -46,6 +46,13 @@ export interface CaptionSegment {
   // transform, not a font-size change, so it scales the background box and
   // text stroke too and does NOT re-wrap the text. Default 1.
   scale?: number
+  // Per-segment override of the track-level `Captions.color` (base text color
+  // only — not the per-style accent fields below). CSS color (hex or named).
+  // Absent → inherits the track-level color → the template's own default.
+  // Honored only by the JSX browser preview / Puppeteer render path; the
+  // ffmpeg `drawtext` render branch has no per-segment concept and keeps
+  // reading only the track-level `color`.
+  color?: string
 }
 
 export interface Captions {

package/src/video/__tests__/captionSnap.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Centre/middle snap for the caption move gesture.
+ *
+ * Regression: the first implementation of `captionDragGeometry` translated the
+ * segment with no snapping at all, so captions were the only draggable thing in
+ * the preview that would not settle on the frame's centre line — overlays did,
+ * captions did not. Edge snap remains deliberately absent (its geometry does
+ * not transfer to a content-sized anchor box); only centre/middle is expected.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  captionDragGeometry,
+  captionDragPatch,
+  CAPTION_SNAP_THRESHOLD,
+  type CaptionDragState,
+  type CaptionFrameMetrics,
+} from '../preview/captionDragState'
+
+// previewScale 1 with a 1080x1920 design frame: 1 screen px == 1 design px, so
+// a dx of 10.8px is exactly 1% of frame width.
+const METRICS: CaptionFrameMetrics = { previewScale: 1, renderW: 1080, renderH: 1920 }
+const PX_PER_PCT_X = 1080 / 100
+const PX_PER_PCT_Y = 1920 / 100
+
+function move(initOffsetX: number, initOffsetY: number): CaptionDragState {
+  return {
+    id: 'cap-1', type: 'move',
+    initX: 0, initY: 0,
+    initOffsetX, initOffsetY, initScale: 1,
+  }
+}
+
+describe('captionDragGeometry — centre/middle snap', () => {
+  it('snaps offsetX to exactly 0 inside the threshold', () => {
+    // Start 5% left of centre, drag right to land 1% past centre (inside 2.5%).
+    const g = captionDragGeometry(move(-5, 40), 6 * PX_PER_PCT_X, 0, METRICS)
+    expect(g.offsetX).toBe(0)
+    expect(g.snapX).toBe(true)
+  })
+
+  it('snaps offsetY to exactly 0 inside the threshold', () => {
+    const g = captionDragGeometry(move(40, -5), 0, 6 * PX_PER_PCT_Y, METRICS)
+    expect(g.offsetY).toBe(0)
+    expect(g.snapY).toBe(true)
+  })
+
+  it('snaps both axes at once when dragged through the centre point', () => {
+    const g = captionDragGeometry(move(-1, -1), PX_PER_PCT_X, PX_PER_PCT_Y, METRICS)
+    expect(g).toMatchObject({ offsetX: 0, offsetY: 0, snapX: true, snapY: true })
+  })
+
+  it('does NOT snap outside the threshold — the raw offset is preserved', () => {
+    // Land 4% right of centre: outside 2.5%, so no snap and no rounding.
+    const g = captionDragGeometry(move(0, 40), 4 * PX_PER_PCT_X, 0, METRICS)
+    expect(g.offsetX).toBeCloseTo(4, 6)
+    expect(g.snapX).toBe(false)
+  })
+
+  it('uses the same threshold as the overlay hook', () => {
+    // Just inside snaps, just outside does not — pinning the boundary so the
+    // two gestures cannot drift apart.
+    const inside  = captionDragGeometry(move(0, 40), (CAPTION_SNAP_THRESHOLD - 0.1) * PX_PER_PCT_X, 0, METRICS)
+    const outside = captionDragGeometry(move(0, 40), (CAPTION_SNAP_THRESHOLD + 0.1) * PX_PER_PCT_X, 0, METRICS)
+    expect(inside.snapX).toBe(true)
+    expect(outside.snapX).toBe(false)
+  })
+
+  it('commits the snapped value, not the raw pointer position', () => {
+    const d = move(-5, 40)
+    const g = captionDragGeometry(d, 6 * PX_PER_PCT_X, 0, METRICS)
+    expect(captionDragPatch(d, g)).toEqual({ offsetX: 0, offsetY: g.offsetY })
+  })
+
+  it('leaves resize gestures unsnapped and untouched', () => {
+    const d: CaptionDragState = {
+      id: 'cap-1', type: 'resize-se',
+      initX: 0, initY: 0, initOffsetX: 1, initOffsetY: 1, initScale: 1,
+    }
+    const g = captionDragGeometry(d, 20, 20, METRICS)
+    // A resize must never move the segment, and must not report a snap.
+    expect(g.offsetX).toBe(1)
+    expect(g.offsetY).toBe(1)
+    expect(g.snapX).toBeUndefined()
+    expect(g.snapY).toBeUndefined()
+    expect(captionDragPatch(d, g)).toEqual({ scale: g.scale })
+  })
+})

package/src/video/preview/CaptionPreview.tsx

@@ -345,6 +345,18 @@ export default function CaptionPreview({
         )}
       </OverlayErrorBoundary>
 
+      {/* Centre/middle snap guides. Same amber hairlines, same z 50, and the
+          same `drag.type === 'move'` gate the overlay layer uses, so a snapped
+          caption reads identically to a snapped overlay. Only the centre pair
+          exists here — caption edge snap is deliberately not implemented (its
+          geometry does not transfer; see captionDragState.ts). */}
+      {drag?.type === 'move' && live?.snapX && (
+        <div className="absolute top-0 bottom-0 left-1/2 w-px bg-amber-400 pointer-events-none" style={{ zIndex: 50 }} />
+      )}
+      {drag?.type === 'move' && live?.snapY && (
+        <div className="absolute left-0 right-0 top-1/2 h-px bg-amber-400 pointer-events-none" style={{ zIndex: 50 }} />
+      )}
+
       {/* Selection box — the only interactive part of the caption layer. z 50
           matches the overlay selection handles (see the layering note above);
           the wrapper stays click-through so only the box itself catches events. */}

package/src/video/preview/__tests__/captionDragState.test.ts

@@ -93,9 +93,14 @@ describe('captionDragGeometry — move', () => {
   })
 
   it('is a no-op at the starting pointer position', () => {
+    // 12/34 are both well outside the centre-snap radius, so the geometry is
+    // the untouched starting offsets. The move branch also reports whether each
+    // axis is currently snapped (see captionSnap.test.ts) — asserted here as
+    // false so this stays a genuine no-op check rather than an assertion about
+    // the return shape.
     const d = drag({ initOffsetX: 12, initOffsetY: 34, initScale: 1.5 })
     expect(captionDragGeometry(d, d.initX, d.initY, metrics(540)))
-      .toEqual({ offsetX: 12, offsetY: 34, scale: 1.5 })
+      .toEqual({ offsetX: 12, offsetY: 34, scale: 1.5, snapX: false, snapY: false })
   })
 })
 

package/src/video/preview/captionDragState.ts

@@ -60,8 +60,18 @@ export interface CaptionGeometry {
   offsetX: number
   offsetY: number
   scale: number
+  /** True while the move gesture is snapped to the frame's horizontal centre. */
+  snapX?: boolean
+  /** True while the move gesture is snapped to the frame's vertical middle. */
+  snapY?: boolean
 }
 
+/**
+ * Centre/middle snap radius, in percent of frame. Matches `SNAP_THRESHOLD` in
+ * `useDragOverlay` so dragging a caption and dragging an overlay feel the same.
+ */
+export const CAPTION_SNAP_THRESHOLD = 2.5
+
 /**
  * The preview's design-resolution mapping.
  *
@@ -145,7 +155,23 @@ export function captionDragGeometry(
   const { dx, dy } = screenDeltaToFramePercent(clientX - drag.initX, clientY - drag.initY, metrics)
 
   if (drag.type === 'move') {
-    return { offsetX: drag.initOffsetX + dx, offsetY: drag.initOffsetY + dy, scale: drag.initScale }
+    // Centre/middle snap. Unlike the overlay hook's EDGE snap — whose
+    // `(0.5 - s/2) * 100` geometry genuinely does not transfer to a caption's
+    // content-sized anchor box (see the file header) — the centre snap is
+    // geometry-independent: offsetX 0 is the frame's horizontal centre and
+    // offsetY 0 its vertical middle, for a caption exactly as for an overlay.
+    // Same threshold as useDragOverlay so both gestures feel identical.
+    const rawX = drag.initOffsetX + dx
+    const rawY = drag.initOffsetY + dy
+    const snapX = Math.abs(rawX) < CAPTION_SNAP_THRESHOLD
+    const snapY = Math.abs(rawY) < CAPTION_SNAP_THRESHOLD
+    return {
+      offsetX: snapX ? 0 : rawX,
+      offsetY: snapY ? 0 : rawY,
+      scale: drag.initScale,
+      snapX,
+      snapY,
+    }
   }
 
   // Resize from a corner: project the pointer delta onto the corner's outward

package/src/video/timeline/Timeline.tsx

@@ -410,6 +410,8 @@ export default function Timeline({ project, clock, onProjectChange, onCaptionEdi
         onProjectChange={onProjectChange}
         onExpand={() => setTranscriptModalOpen(true)}
         onRegenerateCaptions={onRegenerateCaptions}
+        selectedCaptionId={selectedCaptionId}
+        onCaptionSegmentChange={onCaptionSegmentChange}
       />
 
       {/* ── Transcript modal ── */}

package/src/video/timeline/TranscriptPanel.tsx

@@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react'
 import type { Project } from '../../types'
 import { formatTime } from './utils'
 import { EditableSegment } from './EditableSegment'
-import { makeCaptionEdit } from './makeCaptionEdit'
+import { makeCaptionEdit, type CaptionEditPatch } from './makeCaptionEdit'
 import { SwatchInput } from '../../ui'
 
 // Each caption style reads a different accent-color prop in its render template
@@ -35,9 +35,18 @@ interface TranscriptPanelProps {
   /** Opens the caption-regeneration modal. Provided only when the host adapter
    *  supports `generateCaptions`; absent → the "Regenerate" button is hidden. */
   onRegenerateCaptions?: () => void
+  /** Selected caption segment id (shared with the preview's selection box —
+   *  see CaptionPreview/CaptionTrackRow). When set and it resolves to a real
+   *  segment, the base color swatch below targets that segment's `color`
+   *  instead of the track-level `color`. */
+  selectedCaptionId?: string | null
+  /** Commit a single-segment patch — the same channel CaptionTrackRow's
+   *  edge-drag and text edits use (see makeCaptionEdit.ts). Used here as the
+   *  per-segment color swatch's commit path. */
+  onCaptionSegmentChange?: (segmentId: string, patch: CaptionEditPatch) => void
 }
 
-export default function TranscriptPanel({ project, captionTrack, currentTime, onCaptionEdit, onProjectChange, onExpand, onRegenerateCaptions }: TranscriptPanelProps) {
+export default function TranscriptPanel({ project, captionTrack, currentTime, onCaptionEdit, onProjectChange, onExpand, onRegenerateCaptions, selectedCaptionId, onCaptionSegmentChange }: TranscriptPanelProps) {
   const segs = captionTrack?.segments ?? []
   const [confirmRemove, setConfirmRemove] = useState(false)
   const removeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
@@ -132,16 +141,48 @@ export default function TranscriptPanel({ project, captionTrack, currentTime, on
               if (!project.captions) return
               onCaptionEdit?.({ ...project, captions: { ...project.captions, ...patch } })
             }
+
+            // Per-segment color: when a real segment is selected, the base
+            // swatch below targets ITS color instead of the track's. Live
+            // preview still flows through `onProjectChange` — a locally
+            // patched project, exactly the channel every other control on
+            // this panel already uses for live preview — but the commit
+            // goes through `onCaptionSegmentChange`, the single-segment
+            // patch channel (see makeCaptionEdit.ts), instead of rewriting
+            // the whole captions object through `onCaptionEdit`. Each is
+            // fired from exactly one of SwatchInput's onChange/onCommit, so
+            // (as with the track-level swatch above) one gesture produces
+            // exactly one commit — never both channels for the same value.
+            const selectedSeg = selectedCaptionId
+              ? segs.find(s => s.id === selectedCaptionId)
+              : undefined
+            const liveSegColor = (v: string) => {
+              if (!project.captions || !selectedSeg) return
+              onProjectChange?.({
+                ...project,
+                captions: {
+                  ...project.captions,
+                  segments: project.captions.segments.map(s =>
+                    s.id === selectedSeg.id ? { ...s, color: v } : s,
+                  ),
+                },
+              })
+            }
+            const commitSegColor = (v: string) => {
+              if (!selectedSeg) return
+              onCaptionSegmentChange?.(selectedSeg.id!, { color: v })
+            }
+
             return (
               <div className="flex items-center gap-1.5">
                 <SwatchInput
                   size="sm"
                   showValue={false}
-                  title="Caption text color"
-                  ariaLabel="Caption text color"
-                  value={toHex(captionTrack.color, '#ffffff')}
-                  onChange={v => live({ color: v })}
-                  onCommit={v => commit({ color: v })}
+                  title={selectedSeg ? 'Selected segment text color' : 'Caption text color'}
+                  ariaLabel={selectedSeg ? 'Selected segment text color' : 'Caption text color'}
+                  value={toHex(selectedSeg ? (selectedSeg.color ?? captionTrack.color) : captionTrack.color, '#ffffff')}
+                  onChange={v => selectedSeg ? liveSegColor(v) : live({ color: v })}
+                  onCommit={v => selectedSeg ? commitSegColor(v) : commit({ color: v })}
                 />
                 {accent && (
                   <SwatchInput

package/src/video/timeline/__tests__/TranscriptPanel.test.tsx

@@ -10,9 +10,14 @@ function makeProject(style: Captions['style'], extra: Partial<Captions> = {}): P
   return { id: 'p1', captions: { style, segments: [], ...extra } } as unknown as Project
 }
 
-function renderPanel(style: Captions['style'], extra: Partial<Captions> = {}) {
+function renderPanel(
+  style: Captions['style'],
+  extra: Partial<Captions> = {},
+  opts: { selectedCaptionId?: string | null } = {},
+) {
   const onCaptionEdit = vi.fn()
   const onProjectChange = vi.fn()
+  const onCaptionSegmentChange = vi.fn()
   const project = makeProject(style, extra)
   render(
     <TranscriptPanel
@@ -21,10 +26,12 @@ function renderPanel(style: Captions['style'], extra: Partial<Captions> = {}) {
       currentTime={0}
       onCaptionEdit={onCaptionEdit}
       onProjectChange={onProjectChange}
+      onCaptionSegmentChange={onCaptionSegmentChange}
+      selectedCaptionId={opts.selectedCaptionId ?? null}
       onExpand={() => {}}
     />,
   )
-  return { onCaptionEdit, onProjectChange }
+  return { onCaptionEdit, onProjectChange, onCaptionSegmentChange }
 }
 
 describe('TranscriptPanel caption color controls', () => {
@@ -84,6 +91,76 @@ describe('TranscriptPanel caption color controls', () => {
   })
 })
 
+describe('TranscriptPanel per-segment caption color', () => {
+  it('no selection: base swatch is unchanged — still previews/commits the track-level color', () => {
+    const { onCaptionEdit, onProjectChange } = renderPanel('karaoke', {
+      segments: [{ id: 'cap-0', text: 'hi', start: 0, end: 2 }],
+    })
+    const input = screen.getByLabelText('Caption text color') as HTMLInputElement
+
+    fireEvent.change(input, { target: { value: '#76b900' } })
+    expect(onProjectChange).toHaveBeenCalledTimes(1)
+    expect(onProjectChange.mock.calls[0][0].captions.color).toBe('#76b900')
+
+    fireEvent.blur(input, { target: { value: '#76b900' } })
+    expect(onCaptionEdit).toHaveBeenCalledTimes(1)
+    expect(onCaptionEdit.mock.calls[0][0].captions.color).toBe('#76b900')
+  })
+
+  it('a selected segment: swatch previews live via onProjectChange (only that segment patched) and commits via onCaptionSegmentChange — never onCaptionEdit', () => {
+    const { onCaptionEdit, onProjectChange, onCaptionSegmentChange } = renderPanel('karaoke', {
+      color: '#ffffff',
+      segments: [
+        { id: 'cap-0', text: 'hi', start: 0, end: 2 },
+        { id: 'cap-1', text: 'there', start: 2, end: 4 },
+      ],
+    }, { selectedCaptionId: 'cap-1' })
+
+    const input = screen.getByLabelText('Selected segment text color') as HTMLInputElement
+
+    // Live preview — onChange fires on every pick.
+    fireEvent.change(input, { target: { value: '#123456' } })
+    expect(onProjectChange).toHaveBeenCalledTimes(1)
+    const previewed = onProjectChange.mock.calls[0][0]
+    expect(previewed.captions.segments[1].color).toBe('#123456')
+    expect(previewed.captions.segments[0].color).toBeUndefined() // only the selected segment changes
+    expect(previewed.captions.color).toBe('#ffffff')             // track-level color untouched
+    expect(onCaptionSegmentChange).not.toHaveBeenCalled()
+    expect(onCaptionEdit).not.toHaveBeenCalled()
+
+    // Commit — onBlur fires once, through the segment-patch channel, not
+    // the whole-track onCaptionEdit channel. One commit per gesture.
+    fireEvent.blur(input, { target: { value: '#123456' } })
+    expect(onCaptionSegmentChange).toHaveBeenCalledTimes(1)
+    expect(onCaptionSegmentChange).toHaveBeenCalledWith('cap-1', { color: '#123456' })
+    expect(onCaptionEdit).not.toHaveBeenCalled()
+  })
+
+  it("the swatch reflects the selected segment's own color when it has one", () => {
+    renderPanel('karaoke', {
+      color: '#abcdef',
+      segments: [{ id: 'cap-0', text: 'hi', start: 0, end: 2, color: '#00ff00' }],
+    }, { selectedCaptionId: 'cap-0' })
+    expect((screen.getByLabelText('Selected segment text color') as HTMLInputElement).value).toBe('#00ff00')
+  })
+
+  it('the swatch falls back to the track color when the selected segment has none of its own', () => {
+    renderPanel('karaoke', {
+      color: '#abcdef',
+      segments: [{ id: 'cap-0', text: 'hi', start: 0, end: 2 }],
+    }, { selectedCaptionId: 'cap-0' })
+    expect((screen.getByLabelText('Selected segment text color') as HTMLInputElement).value).toBe('#abcdef')
+  })
+
+  it('a selectedCaptionId that matches no segment falls back to track-level behavior', () => {
+    renderPanel('karaoke', {
+      segments: [{ id: 'cap-0', text: 'hi', start: 0, end: 2 }],
+    }, { selectedCaptionId: 'cap-does-not-exist' })
+    expect(screen.getByLabelText('Caption text color')).toBeTruthy()
+    expect(screen.queryByLabelText('Selected segment text color')).toBeNull()
+  })
+})
+
 describe('TranscriptPanel caption text edits', () => {
   // Regression: makeCaptionEdit fires every callback it's given with the same
   // updated project. TranscriptPanel used to pass BOTH onProjectChange and