@bycrux/editor 0.8.7 → 0.8.9

package/package.json

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

package/src/ControlsInfoModal.tsx

@@ -0,0 +1,157 @@
+import { useEffect } from 'react'
+import { X } from 'lucide-react'
+
+/** A single control/shortcut row. `keys` renders as <kbd> chips; omit for a pure gesture. */
+export interface ControlEntry {
+  keys?: string[]
+  label: string
+}
+
+export interface ControlSection {
+  heading: string
+  entries: ControlEntry[]
+}
+
+export interface ControlsInfoModalProps {
+  title: string
+  sections: ControlSection[]
+  onClose: () => void
+}
+
+/**
+ * Read-only "how to drive this editor" modal. Content is passed in per editor
+ * (video vs carousel) so this component stays a dumb, themed renderer. Matches
+ * the backdrop/Esc/close conventions of the other editor modals (TranscriptModal
+ * et al.) and uses the shared `--editor-*` theme tokens.
+ */
+export default function ControlsInfoModal({ title, sections, onClose }: ControlsInfoModalProps) {
+  useEffect(() => {
+    const onKey = (e: globalThis.KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [onClose])
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={title}
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm"
+      onClick={onClose}
+    >
+      <div
+        className="relative mx-4 flex max-h-[80vh] w-full max-w-md flex-col overflow-hidden rounded-lg border shadow-2xl"
+        style={{
+          background: 'var(--editor-surface)',
+          borderColor: 'var(--editor-border)',
+          color: 'var(--editor-text)',
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div
+          className="flex shrink-0 items-center justify-between border-b px-4 py-3"
+          style={{ borderColor: 'var(--editor-border)' }}
+        >
+          <h2 className="text-sm font-semibold">{title}</h2>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close"
+            className="cursor-pointer opacity-60 transition-opacity hover:opacity-100"
+          >
+            <X size={16} />
+          </button>
+        </div>
+
+        <div className="space-y-4 overflow-y-auto px-4 py-3">
+          {sections.map((section) => (
+            <div key={section.heading}>
+              <p className="mb-1.5 text-[11px] font-semibold uppercase tracking-wide opacity-50">
+                {section.heading}
+              </p>
+              <ul className="space-y-1.5">
+                {section.entries.map((entry, i) => (
+                  <li key={i} className="flex items-start justify-between gap-3 text-xs">
+                    <span className="opacity-80">{entry.label}</span>
+                    {entry.keys && entry.keys.length > 0 && (
+                      <span className="flex shrink-0 items-center gap-1">
+                        {entry.keys.map((k, j) => (
+                          <kbd
+                            key={j}
+                            className="rounded border px-1.5 py-0.5 font-mono text-[10px] leading-none"
+                            style={{ borderColor: 'var(--editor-border)', background: 'var(--editor-bg)' }}
+                          >
+                            {k}
+                          </kbd>
+                        ))}
+                      </span>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/** Controls reference for the video/timeline editor. Sourced from VideoEditor's
+ *  key handler (S / ⌘Z), the track-controls toolbar, and PreviewPlayer's
+ *  on-canvas transform (drag / corner-drag / scroll / rotate). */
+export const VIDEO_CONTROLS: ControlSection[] = [
+  {
+    heading: 'Preview',
+    entries: [
+      { label: 'Drag to move the selected clip or overlay' },
+      { label: 'Corner-drag or scroll to scale it' },
+      { label: 'Drag the rotate handle to turn an overlay' },
+    ],
+  },
+  {
+    heading: 'Timeline',
+    entries: [
+      { label: 'Drag a clip to reposition it' },
+      { label: "Drag a clip's edge to trim it" },
+      { label: 'Select a clip, then click ⓘ to inspect it' },
+    ],
+  },
+  {
+    heading: 'Toolbar',
+    entries: [
+      { label: 'Ripple: edits close the gap instead of leaving it' },
+      { label: 'Crop source: non-destructively crop the selected clip' },
+    ],
+  },
+  {
+    heading: 'Keyboard',
+    entries: [
+      { keys: ['S'], label: 'Split at the playhead' },
+      { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+    ],
+  },
+]
+
+/** Controls reference for the carousel editor. Sourced from CarouselEditor's key
+ *  handlers (undo/redo, Delete) and the canvas gesture hints. */
+export const CAROUSEL_CONTROLS: ControlSection[] = [
+  {
+    heading: 'Canvas',
+    entries: [
+      { label: 'Drag an element to reposition it' },
+      { label: 'Resize or rotate it via the handles' },
+      { label: 'Double-click text to edit it' },
+    ],
+  },
+  {
+    heading: 'Keyboard',
+    entries: [
+      { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+      { keys: ['⌘/Ctrl', '⇧', 'Z'], label: 'Redo' },
+      { keys: ['Delete'], label: 'Remove the selected element' },
+    ],
+  },
+]

package/src/__tests__/ControlsInfoModal.test.tsx

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { render, screen, fireEvent, cleanup } from '@testing-library/react'
+import ControlsInfoModal, {
+  VIDEO_CONTROLS,
+  CAROUSEL_CONTROLS,
+  type ControlSection,
+} from '../ControlsInfoModal'
+
+afterEach(() => cleanup())
+
+const SECTIONS: ControlSection[] = [
+  {
+    heading: 'Canvas',
+    entries: [
+      { label: 'Drag an element to reposition it' },
+      { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+    ],
+  },
+]
+
+describe('ControlsInfoModal', () => {
+  it('renders the title, section headings, entry labels, and kbd chips', () => {
+    render(<ControlsInfoModal title="Editor controls" sections={SECTIONS} onClose={vi.fn()} />)
+
+    expect(screen.getByRole('dialog', { name: 'Editor controls' })).toBeTruthy()
+    expect(screen.getByText('Canvas')).toBeTruthy()
+    expect(screen.getByText('Drag an element to reposition it')).toBeTruthy()
+    // Keys render as individual <kbd> chips.
+    expect(screen.getByText('⌘/Ctrl').tagName).toBe('KBD')
+    expect(screen.getByText('Z').tagName).toBe('KBD')
+  })
+
+  it('closes on Escape', () => {
+    const onClose = vi.fn()
+    render(<ControlsInfoModal title="Editor controls" sections={SECTIONS} onClose={onClose} />)
+    fireEvent.keyDown(window, { key: 'Escape' })
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('closes on backdrop click but not on panel click', () => {
+    const onClose = vi.fn()
+    render(<ControlsInfoModal title="Editor controls" sections={SECTIONS} onClose={onClose} />)
+
+    // Click inside the panel — should NOT close.
+    fireEvent.click(screen.getByText('Canvas'))
+    expect(onClose).not.toHaveBeenCalled()
+
+    // Click the backdrop (the dialog root) — should close.
+    fireEvent.click(screen.getByRole('dialog'))
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('ships real control content for both editors', () => {
+    // Guards against an empty/placeholder content regression.
+    const videoLabels = VIDEO_CONTROLS.flatMap((s) => s.entries.map((e) => e.label))
+    const carouselLabels = CAROUSEL_CONTROLS.flatMap((s) => s.entries.map((e) => e.label))
+    expect(videoLabels).toEqual(expect.arrayContaining(['Split at the playhead']))
+    expect(carouselLabels).toEqual(expect.arrayContaining(['Double-click text to edit it']))
+    expect(VIDEO_CONTROLS.length).toBeGreaterThan(0)
+    expect(CAROUSEL_CONTROLS.length).toBeGreaterThan(0)
+  })
+})

package/src/carousel/CarouselEditor.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
-import { RefreshCw, AlertCircle, Download } from 'lucide-react'
+import { RefreshCw, AlertCircle, Download, Info } 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'
@@ -7,6 +7,7 @@ import SlideCanvas from './SlideCanvas'
 import SlidePropertyPanel from './SlidePropertyPanel'
 import AddElementMenu from './AddElementMenu'
 import CarouselRenderModal from './CarouselRenderModal'
+import ControlsInfoModal, { CAROUSEL_CONTROLS } from '../ControlsInfoModal'
 import { Button } from '../ui'
 
 // Generic over the host's concrete project type `P` (default = the package's
@@ -167,6 +168,7 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
 
   const [skillPath, setSkillPath] = useState<string | null>(null)
   const [copied, setCopied] = useState(false)
+  const [showControls, setShowControls] = useState(false)
   const [refreshing, setRefreshing] = useState(false)
   const [refreshState, setRefreshState] = useState<'idle' | 'err'>('idle')
   const [rendering, setRendering] = useState(false)
@@ -505,9 +507,20 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
                 hiddenElementIds={hiddenElementIds}
               />
             </div>
-            <p className="flex-shrink-0 text-xs text-[var(--editor-text)]/60 text-center max-w-md">
-              Drag to reposition, resize/rotate via handles, double-click text to edit. Cmd/Ctrl+Z to undo.
-            </p>
+            <div className="flex-shrink-0 flex items-center justify-center gap-1.5 text-xs text-[var(--editor-text)]/60 max-w-md">
+              <span className="text-center">
+                Drag to reposition, resize/rotate via handles, double-click text to edit. Cmd/Ctrl+Z to undo.
+              </span>
+              <button
+                type="button"
+                onClick={() => setShowControls(true)}
+                title="Editor controls & shortcuts"
+                aria-label="Editor controls & shortcuts"
+                className="shrink-0 cursor-pointer opacity-60 transition-opacity hover:opacity-100"
+              >
+                <Info size={13} />
+              </button>
+            </div>
           </>
         ) : (
           <div className="text-[var(--editor-text)]/40 text-sm">No slides yet. Add one in the left panel.</div>
@@ -566,6 +579,14 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
         </div>
       )}
 
+      {showControls && (
+        <ControlsInfoModal
+          title="Editor controls"
+          sections={CAROUSEL_CONTROLS}
+          onClose={() => setShowControls(false)}
+        />
+      )}
+
       {renderOpen && (
         <CarouselRenderModal
           projectId={project.id}

package/src/schema.ts

@@ -43,13 +43,15 @@ export interface CaptionSegment {
 }
 
 export interface Captions {
-  style: 'word-by-word' | 'pop' | 'karaoke' | 'subtitle'
+  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
   position?: 'center' | 'top-left' | 'bottom-left'
   color?: string
   fontsize?: number
   bgColor?: string
+  accentColor?: string    // active-word/box accent color — highlight-box, outline
+  googleFonts?: string[]  // Google Fonts family specs for the caption template (e.g. ["Figtree:wght@700"])
 }
 
 export interface VisualItem {

package/src/video/VideoEditor.tsx

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { Crop, Magnet } from 'lucide-react'
+import { Crop, Info, Magnet } from 'lucide-react'
 import type { Project, VideoEditorProps } from '../types'
 import { VideoSourceCropModal } from '../crop/VideoSourceCropModal'
+import ControlsInfoModal, { VIDEO_CONTROLS } from '../ControlsInfoModal'
 import { getOverlayDesignCanvas } from './design-canvas'
 import { applyTheme, defaultMontajTheme } from '../theme'
 import { applyCutToItem, applyCutToTracks, collapseGaps, splitAtTime } from './cuts'
@@ -287,6 +288,7 @@ function ReviewSurface<P extends Project>({
   const [selectedIds, setSelectedIds] = useState<string[]>([])
   const primarySelectedId = selectedIds[0] ?? null
   const [rippleMode, setRippleMode]   = useState(false)
+  const [showControls, setShowControls] = useState(false)
   // Source-crop mode: when on, the VideoSourceCropModal opens for the selected
   // tracks[0] video item. Cleared when selection changes.
   const [cropMode, setCropMode]       = useState(false)
@@ -463,8 +465,16 @@ function ReviewSurface<P extends Project>({
           )}
         </div>
 
-        {/* Track controls bar — split + ripple + render */}
+        {/* Track controls bar — info + split + ripple + render */}
         <div className="shrink-0 flex items-center justify-end gap-1.5 px-3 py-1 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
+          <button
+            onClick={() => setShowControls(true)}
+            title="Editor controls & shortcuts"
+            aria-label="Editor controls & shortcuts"
+            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)] mr-auto"
+          >
+            <Info size={12} />
+          </button>
           <button
             onClick={() => handleSplit()}
             title="Split at playhead (S) — selected item or all clips"
@@ -613,6 +623,15 @@ function ReviewSurface<P extends Project>({
         />
       )}
 
+      {/* Controls & shortcuts reference */}
+      {showControls && (
+        <ControlsInfoModal
+          title="Editor controls"
+          sections={VIDEO_CONTROLS}
+          onClose={() => setShowControls(false)}
+        />
+      )}
+
       {/* Render modal — adapter.render stream + host export controls */}
       {renderOpen && (
         <RenderModal

package/src/video/preview/CaptionPreview.tsx

@@ -58,8 +58,17 @@ export default function CaptionPreview({ track, currentTime, fps, compileOverlay
 
   const frame    = Math.round(currentTime * fps)
   const lastSeg  = track.segments[track.segments.length - 1]
+
+  // Theme props for the template: everything on the track except style/segments
+  // (handled separately) and googleFonts (a render-time font-loading hint, not
+  // a template prop). Normalize the legacy lowercase `fontsize` key to the
+  // camelCase `fontSize` templates actually read.
+  const { style: _style, segments: _segments, googleFonts: _googleFonts, fontsize, ...theme } = track
+  const themeProps: Record<string, unknown> = { ...theme }
+  if (fontsize != null) themeProps.fontSize = fontsize
+
   const element  = (factory && scale !== null)
-    ? factory(frame, fps, Math.round((lastSeg?.end ?? 0) * fps), { segments: track.segments })
+    ? factory(frame, fps, Math.round((lastSeg?.end ?? 0) * fps), { segments: track.segments, ...themeProps })
     : null
 
   return (

package/src/video/timeline/Timeline.tsx

@@ -138,7 +138,12 @@ export default function Timeline({ project, currentTime, onTimeUpdate, onProject
     const fps = project.settings?.fps ?? 30
     const frame = 1 / fps
     const onKey = (e: globalThis.KeyboardEvent) => {
+      // While the transcript modal is open, or the caret is in editable text
+      // (caption segments are contentEditable), arrows move the text cursor —
+      // never the playhead.
+      if (transcriptModalOpen) return
       if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return
+      if ((e.target as HTMLElement).isContentEditable) return
       if (e.key === 'Escape') { setMarkers([null, null]); return }
       if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return
       e.preventDefault()
@@ -152,7 +157,7 @@ export default function Timeline({ project, currentTime, onTimeUpdate, onProject
     }
     document.addEventListener('keydown', onKey)
     return () => document.removeEventListener('keydown', onKey)
-  }, [totalDuration, currentTime, onTimeUpdate, project.settings?.fps])
+  }, [totalDuration, currentTime, onTimeUpdate, project.settings?.fps, transcriptModalOpen])
 
   // Derive selection from two placed markers
   const selection = markers[0] !== null && markers[1] !== null

package/src/video/timeline/TranscriptPanel.tsx

@@ -1,3 +1,4 @@
+import { useEffect, useRef, useState } from 'react'
 import type { Project } from '../../types'
 import { formatTime } from './utils'
 import { EditableSegment } from './EditableSegment'
@@ -17,6 +18,21 @@ interface TranscriptPanelProps {
 
 export default function TranscriptPanel({ project, captionTrack, currentTime, onCaptionEdit, onProjectChange, onExpand, onRegenerateCaptions }: TranscriptPanelProps) {
   const segs = captionTrack?.segments ?? []
+  const [confirmRemove, setConfirmRemove] = useState(false)
+  const removeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  // Live slider value during a drag — only committed (persisted) on
+  // pointer-up/key-up so mid-drag ticks don't each trigger a server PUT.
+  const [fontsize, setFontsize] = useState(captionTrack?.fontsize ?? 46)
+
+  useEffect(() => {
+    setFontsize(captionTrack?.fontsize ?? 46)
+  }, [captionTrack?.fontsize])
+
+  useEffect(() => {
+    return () => {
+      if (removeTimeoutRef.current) clearTimeout(removeTimeoutRef.current)
+    }
+  }, [])
   // Find active segment index
   const activeIdx = segs.findIndex(s => currentTime >= s.start && currentTime < s.end)
   const nearIdx   = activeIdx !== -1 ? activeIdx
@@ -31,8 +47,8 @@ export default function TranscriptPanel({ project, captionTrack, currentTime, on
     <div className="rounded border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 px-3 py-2.5">
       <div className="flex items-center justify-between mb-2">
         <span className="text-[10px] text-gray-500 uppercase tracking-wider">Captions</span>
-        <div className="flex items-center gap-2">
-          {captionTrack && (['word-by-word', 'pop', 'karaoke', 'subtitle'] as const).map(style => {
+        <div className="flex items-center gap-2 flex-wrap justify-end">
+          {captionTrack && (['word-by-word', 'pop', 'karaoke', 'subtitle', 'highlight-box', 'outline', 'clean'] as const).map(style => {
             const active = captionTrack.style === style
             return (
               <button
@@ -52,6 +68,38 @@ export default function TranscriptPanel({ project, captionTrack, currentTime, on
               </button>
             )
           })}
+          {captionTrack && (
+            <div className="flex items-center gap-1">
+              <input
+                type="range"
+                min={28}
+                max={120}
+                step={2}
+                value={fontsize}
+                className="w-20 sm:w-24 accent-purple-500"
+                onChange={e => {
+                  if (!project.captions) return
+                  const v = Number(e.target.value)
+                  setFontsize(v)
+                  // Live preview only — cheap local-state update, no save.
+                  onProjectChange?.({ ...project, captions: { ...project.captions, fontsize: v } })
+                }}
+                onPointerUp={e => {
+                  if (!project.captions) return
+                  const v = Number((e.target as HTMLInputElement).value)
+                  onCaptionEdit?.({ ...project, captions: { ...project.captions, fontsize: v } })
+                }}
+                onKeyUp={e => {
+                  if (!project.captions) return
+                  const v = Number((e.target as HTMLInputElement).value)
+                  onCaptionEdit?.({ ...project, captions: { ...project.captions, fontsize: v } })
+                }}
+              />
+              <span className="text-[10px] text-gray-500 dark:text-gray-400 font-mono w-9 text-right">
+                {fontsize}px
+              </span>
+            </div>
+          )}
           {onRegenerateCaptions && (
             <button
               className="text-[10px] text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-white border border-gray-300 dark:border-gray-700 hover:border-gray-400 dark:hover:border-gray-500 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded px-2 py-0.5 transition-all"
@@ -60,6 +108,30 @@ export default function TranscriptPanel({ project, captionTrack, currentTime, on
               Regenerate
             </button>
           )}
+          {captionTrack && (
+            <button
+              className={`text-[10px] rounded px-2 py-0.5 transition-all border ${
+                confirmRemove
+                  ? 'bg-red-500/20 border-red-500/60 text-red-400'
+                  : 'bg-gray-100 dark:bg-gray-800 border-gray-300 dark:border-gray-700 text-gray-500 hover:text-gray-700 dark:hover:text-gray-300 hover:border-gray-400 dark:hover:border-gray-500'
+              }`}
+              onClick={() => {
+                if (!confirmRemove) {
+                  setConfirmRemove(true)
+                  if (removeTimeoutRef.current) clearTimeout(removeTimeoutRef.current)
+                  removeTimeoutRef.current = setTimeout(() => setConfirmRemove(false), 3000)
+                  return
+                }
+                if (removeTimeoutRef.current) clearTimeout(removeTimeoutRef.current)
+                setConfirmRemove(false)
+                // Persistence needs an explicit `null` to clear the field server-side
+                // (a live PUT test confirmed `undefined` is dropped from the JSON body).
+                onCaptionEdit?.({ ...project, captions: null as unknown as undefined })
+              }}
+            >
+              {confirmRemove ? 'Really remove?' : 'Remove'}
+            </button>
+          )}
           {segs.length > 0 && (
             <button
               className="text-[10px] text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-white border border-gray-300 dark:border-gray-700 hover:border-gray-400 dark:hover:border-gray-500 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded px-2 py-0.5 transition-all"