@bycrux/editor 0.11.2 → 1.0.1

package/src/video/captionActiveWord.ts

@@ -0,0 +1,74 @@
+/**
+ * captionActiveWord — derives the ONE caption word currently under the
+ * playhead, for the caption-styling panel's live font specimen (it shows the
+ * actual word from the user's video, rendered in the candidate typeface, so
+ * a font choice is judged against real content rather than a placeholder).
+ *
+ * DERIVED, NOT SELECTED — deliberately. The editor has no word-level
+ * selection: `selectedIds` (CaptionListPanel.tsx:76) is segment-level and
+ * shared across captions, clips, and audio. Inventing a word-selection model
+ * just for a font preview would mean touching that shared selection system
+ * for no benefit elsewhere. The playhead already tells us which word the
+ * user is looking at, so this module reads it from there instead.
+ *
+ * The active-segment test mirrors two existing call sites exactly rather than
+ * inventing a third notion of "active": the half-open `currentTime >= start
+ * && currentTime < end` predicate is `CaptionListPanel`'s row-highlight test
+ * and the caption render templates' `activeSegments` test. Segments can be
+ * simultaneously active across different lanes (`seg.lane`, see
+ * `captionLanes.ts`); when more than one is active this picks the operator's
+ * selection if it's among them, else the highest lane — the caption painted
+ * last and therefore on top — mirroring the target-segment pick in
+ * `preview/CaptionPreview.tsx`.
+ */
+import type { CaptionSegment, Captions } from '../schema'
+import { laneOf } from './captionLanes'
+
+export interface ActiveCaptionWord {
+  word: string
+  segmentId?: string
+}
+
+const isSegmentActive = (seg: CaptionSegment, t: number): boolean => t >= seg.start && t < seg.end
+
+/** Non-empty after trimming, else `undefined` — the shared guard behind the
+ *  "never return an empty-string word" rule: a hand-authored segment can have
+ *  blank `text` and no `words`, and that must read as "no word", not `''`. */
+function nonEmpty(s: string | undefined): string | undefined {
+  const trimmed = s?.trim()
+  return trimmed ? s : undefined
+}
+
+/** A segment's own first word, for when the playhead doesn't land inside any
+ *  `words[]` span: the segment's first transcribed word if it has one,
+ *  else the first whitespace-separated token of its `text` (segments authored
+ *  without word-level timing, e.g. non-animated styles). */
+function firstWordOfSegment(seg: CaptionSegment): string | undefined {
+  return nonEmpty(seg.words?.[0]?.word) ?? nonEmpty(seg.text?.trim().split(/\s+/)[0])
+}
+
+export function activeCaptionWord(
+  captions: Captions | undefined,
+  currentTime: number,
+  selectedSegmentId?: string,
+): ActiveCaptionWord | null {
+  const segments = captions?.segments ?? []
+  const activeSegs = segments.filter((seg) => isSegmentActive(seg, currentTime))
+
+  let target: CaptionSegment | undefined
+  if (activeSegs.length > 0) {
+    target =
+      (selectedSegmentId ? activeSegs.find((seg) => seg.id === selectedSegmentId) : undefined) ??
+      activeSegs.reduce((top, seg) => (laneOf(seg) > laneOf(top) ? seg : top))
+  } else if (selectedSegmentId) {
+    target = segments.find((seg) => seg.id === selectedSegmentId)
+  }
+
+  if (!target) return null
+
+  const spanningWord = target.words?.find((word) => currentTime >= word.start && currentTime < word.end)
+  const word = nonEmpty(spanningWord?.word) ?? firstWordOfSegment(target)
+  if (!word) return null
+
+  return { word, segmentId: target.id }
+}

package/src/video/captionLanes.ts

@@ -0,0 +1,202 @@
+import type { CaptionSegment, Captions } from '../schema'
+
+/**
+ * Caption lanes — pure helpers over `CaptionSegment[]` / `Captions`. Every
+ * consumer that needs to know which lane a caption sits in, how lanes group
+ * up, or where a dragged caption should land reads it through this module, so
+ * lane semantics can't drift between the canvas painter, the caption
+ * sidebar, and the drag gesture that later phases build on top of this.
+ *
+ * See the `lane` field doc on `CaptionSegment` (schema.ts) for why caption
+ * lanes deliberately do NOT auto-increment the way `AudioTrack.lane` /
+ * `groupAudioLanes` do: absent means lane 0, full stop.
+ */
+
+// ── Reading a segment's lane ────────────────────────────────────────────────
+
+/**
+ * A segment's lane, defaulted and defensively coerced. Absent, negative,
+ * non-integer, or non-finite (`NaN`/`Infinity`) stored values all collapse to
+ * a safe in-range integer rather than propagating into array indexing or
+ * comparisons downstream — a hand-edited project.json is the realistic source
+ * of a bad value here, not this codebase.
+ */
+export function laneOf(seg: CaptionSegment): number {
+  const raw = seg.lane
+  if (raw == null || !Number.isFinite(raw)) return 0
+  const n = Math.trunc(raw)
+  return n < 0 ? 0 : n
+}
+
+/** Highest lane index present across `segments`, or 0 for an empty/lane-less
+ *  track — so callers can size a `0..maxCaptionLane` structure without
+ *  special-casing "no captions yet". */
+export function maxCaptionLane(segments: CaptionSegment[]): number {
+  return segments.reduce((max, seg) => Math.max(max, laneOf(seg)), 0)
+}
+
+// ── Grouping ─────────────────────────────────────────────────────────────
+
+export interface CaptionLaneGroup {
+  lane: number
+  segments: CaptionSegment[]
+}
+
+/**
+ * Group `segments` into one entry per lane, `0..maxCaptionLane(segments)`,
+ * INCLUDING holes as empty groups (`segments: []`). A hole must be
+ * representable, not just skipped, because a later phase renders one row per
+ * lane and needs a visible, drop-targetable empty band mid-drag even where no
+ * caption currently lives.
+ */
+export function groupCaptionLanes(segments: CaptionSegment[]): CaptionLaneGroup[] {
+  const groups: CaptionLaneGroup[] = Array.from(
+    { length: maxCaptionLane(segments) + 1 },
+    (_, lane) => ({ lane, segments: [] }),
+  )
+  for (const seg of segments) groups[laneOf(seg)].segments.push(seg)
+  return groups
+}
+
+/** Every segment whose (coerced) lane is `lane`. */
+export function segmentsInLane(segments: CaptionSegment[], lane: number): CaptionSegment[] {
+  return segments.filter(seg => laneOf(seg) === lane)
+}
+
+// ── Normalizing ──────────────────────────────────────────────────────────
+
+/**
+ * Collapse hole lanes and renumber dense from 0, preserving relative lane
+ * order (the segment(s) in the lowest occupied lane become lane 0, the next
+ * occupied lane becomes 1, and so on). Also rewrites any negative or
+ * non-integer stored `lane` to its canonical dense integer.
+ *
+ * Returns the SAME `Captions` reference when nothing changes — the contract
+ * every defensive normalizer in this codebase honours (see
+ * `backfillCaptionIds` in video/VideoEditor.tsx and `repairCaptionWords` in
+ * video/captionRepair.ts), so a caller that re-runs this after its own write
+ * converges to a true no-op instead of looping. Handles `captions` being
+ * `undefined` (passed straight back).
+ */
+export function normalizeCaptionLanes(captions: Captions | undefined): Captions | undefined {
+  if (!captions) return captions
+  const { segments } = captions
+  if (!segments.length) return captions
+
+  // Distinct lanes actually in use (after defensive coercion), ascending —
+  // the lane at sorted position i renumbers to i, closing any holes. Lane 0,
+  // if present at all, is always the smallest and so always renumbers to 0.
+  const present = [...new Set(segments.map(laneOf))].sort((a, b) => a - b)
+  const remap = new Map(present.map((lane, i) => [lane, i]))
+
+  let changed = false
+  const newSegments = segments.map(seg => {
+    const canonical = remap.get(laneOf(seg))!
+    const current = seg.lane ?? 0
+    if (current === canonical) return seg
+    changed = true
+    return { ...seg, lane: canonical }
+  })
+  if (!changed) return captions
+
+  return { ...captions, segments: newSegments }
+}
+
+// ── Drag support ─────────────────────────────────────────────────────────
+
+/**
+ * Does `[start, end)` avoid every OTHER segment already occupying `lane`?
+ * `id` names the segment being placed — if it happens to already sit in
+ * `lane`, it is excluded from the check, which is what makes it safe to call
+ * this on a segment's own prospective new position while dragging it.
+ * Touching edges (`end === seg.start` or `start === seg.end`) are not a
+ * collision.
+ */
+export function fitsInLane(
+  segments: CaptionSegment[],
+  id: string | undefined,
+  lane: number,
+  start: number,
+  end: number,
+): boolean {
+  return segmentsInLane(segments, lane).every(other => {
+    if (id !== undefined && other.id === id) return true // the segment itself — not a collision
+    return end <= other.start || start >= other.end
+  })
+}
+
+export interface CaptionLaneNeighbours {
+  prev: CaptionSegment | null
+  next: CaptionSegment | null
+}
+
+/**
+ * The nearest segments sharing `seg`'s lane on either side, by timeline
+ * position: `prev` is the closest segment ending at/before `seg.start`,
+ * `next` the closest starting at/after `seg.end`. `seg` itself is excluded
+ * (by id when it has one, otherwise by reference).
+ */
+export function sameLaneNeighbours(segments: CaptionSegment[], seg: CaptionSegment): CaptionLaneNeighbours {
+  const others = segmentsInLane(segments, laneOf(seg)).filter(other =>
+    seg.id !== undefined ? other.id !== seg.id : other !== seg,
+  )
+
+  let prev: CaptionSegment | null = null
+  let next: CaptionSegment | null = null
+  for (const other of others) {
+    if (other.end <= seg.start && (!prev || other.end > prev.end)) prev = other
+    if (other.start >= seg.end && (!next || other.start < next.start)) next = other
+  }
+  return { prev, next }
+}
+
+export interface ResolveDropLaneArgs {
+  /** Full segment list (including `seg` at its pre-drag position). */
+  segments: CaptionSegment[]
+  /** The segment being dragged. */
+  seg: CaptionSegment
+  /** The lane the drag started from. */
+  sourceLane: number
+  /** Lanes of vertical travel so far (see sign note below). */
+  laneDelta: number
+  /** The segment's prospective new [start, end) in the target lane. */
+  start: number
+  end: number
+}
+
+/**
+ * The target lane for a vertical caption drag.
+ *
+ * Caption lanes ascend UPWARD on the timeline (higher lane number = higher on
+ * screen) — the OPPOSITE of audio lanes — so a downward drag (`laneDelta`
+ * increasing) must LOWER the lane number, hence the minus sign below. A later
+ * phase's drag gesture relies on this sign.
+ *
+ * Fans out from `wanted = clamp(sourceLane - laneDelta, 0, maxLane + 1)` in
+ * the order `wanted, wanted-1, wanted+1, wanted-2, …`, bounded to
+ * `[0, maxLane + 1]`, returning the first lane where `fitsInLane` holds. This
+ * mirrors the nearest-first fan-out `moveItemAcrossTracks` uses for visual
+ * tracks: land as close to the lane the pointer actually points at as
+ * possible, not just at the first open lane found in one direction.
+ *
+ * `maxLane + 1` is always in range and is empty of every segment (dragged one
+ * included — its OWN lane is at most `maxLane`, strictly less than
+ * `maxLane + 1`), so `fitsInLane` at that lane always holds. Because the
+ * fan-out's largest possible offset (`max(wanted, maxLane + 1 - wanted)`) never
+ * exceeds `maxLane + 1`, the search reaches that guaranteed-empty lane before
+ * running out of offsets to try — so this function always terminates with an
+ * answer, never falling through un-returned.
+ */
+export function resolveDropLane({ segments, seg, sourceLane, laneDelta, start, end }: ResolveDropLaneArgs): number {
+  const upper = maxCaptionLane(segments) + 1
+  const wanted = Math.min(upper, Math.max(0, sourceLane - laneDelta))
+
+  for (let offset = 0; offset <= upper; offset++) {
+    const candidates = offset === 0 ? [wanted] : [wanted - offset, wanted + offset]
+    for (const candidate of candidates) {
+      if (candidate < 0 || candidate > upper) continue
+      if (fitsInLane(segments, seg.id, candidate, start, end)) return candidate
+    }
+  }
+  return upper // unreachable — see doc comment above — kept only so the function is total
+}

package/src/video/captionRepair.ts

@@ -11,6 +11,7 @@
  * downstream save/notify).
  */
 import type { Captions, CaptionSegment } from '../schema'
+import { floorWordDurations } from './captionWordFloor'
 
 // Collapses any run of whitespace to a single space, in addition to trim +
 // case-fold, before the two sides are compared. `newWords` below is always
@@ -31,13 +32,16 @@ function repairSegment(seg: CaptionSegment): CaptionSegment {
   const newWords = seg.text.split(/\s+/).filter(Boolean)
   const segDur = seg.end - seg.start
   const wordDur = segDur / (newWords.length || 1)
+  const spreadWords = newWords.map((w, i) => ({
+    word: w,
+    start: seg.start + i * wordDur,
+    end: seg.start + (i + 1) * wordDur,
+  }))
   return {
     ...seg,
-    words: newWords.map((w, i) => ({
-      word: w,
-      start: seg.start + i * wordDur,
-      end: seg.start + (i + 1) * wordDur,
-    })),
+    // Uniform spread has no minimum of its own — floor it so a short word
+    // never falls below a frame at any fps. See captionWordFloor.ts.
+    words: floorWordDurations(spreadWords, seg.end),
   }
 }
 

package/src/video/captionStyleDefaults.ts

@@ -0,0 +1,100 @@
+/**
+ * Per-style default values for the caption text-styling fields — the ones
+ * each of the seven JSX caption templates applies via its own destructuring
+ * default (`fontWeight = 700`, etc.) whenever the corresponding `Captions`
+ * field is absent from the project.
+ *
+ * DELIBERATE DUPLICATION, the same shape as the `seg.lane ?? 0` duplication
+ * documented at the top of every template's `activeSegments` (see e.g.
+ * clean.jsx): the templates live in `montaj_assets/render/templates/
+ * captions/*.jsx`, compiled standalone for the browser/Puppeteer render
+ * path, and can import nothing but `montaj/render` — not this editor
+ * package, and not each other. The editor still needs these same numbers to
+ * show what an ABSENT field will actually render as — CaptionSpecimen's
+ * weight/family preview, and CaptionListPanel's steppers/case chips
+ * reporting the effective value instead of a blank one — and there is no
+ * module either side can import, so the values are copied here by hand.
+ *
+ * Whoever changes a template's own default MUST change the matching entry
+ * here too, in the same commit. Verified against the actual `function Xxx({
+ * ... })` destructuring defaults in:
+ *   clean.jsx, karaoke.jsx, subtitle.jsx, pop.jsx, word-by-word.jsx,
+ *   highlight-box.jsx, outline.jsx
+ * (all under montaj_assets/render/templates/captions/).
+ */
+import type { Captions } from '../schema'
+
+type Style = Captions['style']
+
+/** `Captions.fontWeight`'s default per style (CSS `font-weight`). */
+export const CAPTION_STYLE_FONT_WEIGHT: Record<Style, number> = {
+  clean: 700,
+  karaoke: 700,
+  subtitle: 600,
+  pop: 800,
+  'word-by-word': 800,
+  'highlight-box': 900,
+  outline: 900,
+}
+
+/** `Captions.fontFamily`'s default per style. Six of the seven templates
+ *  share the plain system-sans stack as their parameter default; only
+ *  `clean` names a specific face (Figtree) as its designed look. */
+export const CAPTION_STYLE_FONT_FAMILY: Record<Style, string> = {
+  clean: '"Figtree", system-ui, sans-serif',
+  karaoke: 'system-ui, -apple-system, sans-serif',
+  subtitle: 'system-ui, -apple-system, sans-serif',
+  pop: 'system-ui, -apple-system, sans-serif',
+  'word-by-word': 'system-ui, -apple-system, sans-serif',
+  'highlight-box': 'system-ui, -apple-system, sans-serif',
+  outline: 'system-ui, -apple-system, sans-serif',
+}
+
+/** `Captions.letterSpacing`'s default per style. A style absent from this
+ *  table has no default at all — `karaoke`, `subtitle`, `highlight-box`, and
+ *  `outline` all destructure `letterSpacing` with no `= ...`, so an unset
+ *  field renders with the browser's normal spacing on those four. */
+export const CAPTION_STYLE_LETTER_SPACING: Partial<Record<Style, string>> = {
+  clean: '0.01em',
+  pop: '-0.02em',
+  'word-by-word': '-0.02em',
+}
+
+/** `Captions.lineHeight`'s default per style.
+ *
+ *  `highlight-box` and `outline` are a special case: their template has NO
+ *  parameter-level default (a bare `lineHeight` destructure) — the value
+ *  below only takes effect through an inline `lineHeight ?? 1.25` /
+ *  `lineHeight ?? 1.15` at the WORDS-branch call site in `renderSegment`. A
+ *  segment with no `words` array (the no-timestamps fallback branch) renders
+ *  with no line-height at all, whether or not this field is set. `clean` and
+ *  `subtitle` are plain parameter defaults and apply unconditionally.
+ *  `karaoke`, `pop`, and `word-by-word` have no default in any branch. */
+export const CAPTION_STYLE_LINE_HEIGHT: Partial<Record<Style, number>> = {
+  clean: 1.3,
+  subtitle: 1.4,
+  'highlight-box': 1.25,
+  outline: 1.15,
+}
+
+/** `Captions.textAlign`'s default per style — every template centers text by
+ *  default, with no exceptions. */
+export const CAPTION_STYLE_TEXT_ALIGN: Record<Style, string> = {
+  clean: 'center',
+  karaoke: 'center',
+  subtitle: 'center',
+  pop: 'center',
+  'word-by-word': 'center',
+  'highlight-box': 'center',
+  outline: 'center',
+}
+
+/** `Captions.textTransform`'s default per style. Only `outline` has one — its
+ *  all-caps stencil look — and, like its `lineHeight` default above, it only
+ *  takes effect on the WORDS branch (`textTransform ?? 'uppercase'` at the
+ *  `renderSegment` call site); the no-timestamps fallback branch renders the
+ *  segment text as-is, never uppercased. Every other style has no default in
+ *  any branch. */
+export const CAPTION_STYLE_TEXT_TRANSFORM: Partial<Record<Style, string>> = {
+  outline: 'uppercase',
+}

package/src/video/captionWordFloor.ts

@@ -0,0 +1,83 @@
+/**
+ * captionWordFloor — TS mirror of steps/lyrics/caption.py's
+ * `floor_word_durations`. Same waterfall, same constant (50ms — enough for
+ * >=1 frame at every fps montaj ships), same binary donation gate: a shared
+ * boundary between two words moves fully to `start_i + floor` or not at
+ * all, never partially, because the per-word caption templates select with
+ * `.find()` (first match wins) — a partial donation would leave a sliver of
+ * dead time where nothing matches, reproducing the invisibility bug the
+ * floor exists to fix. See caption.py's docstring for the full rationale;
+ * this file only documents the one deliberate divergence from it.
+ *
+ * WHY A MIRROR EXISTS AT ALL: caption.py is the single funnel for the SSE
+ * route and the CLI step, but two editor-side generators independently
+ * invent word timings with no minimum — `captionRepair.ts` and
+ * `makeCaptionEdit.ts`, both via a uniform `segDur / n` spread. This helper
+ * is applied to that spread's output, but on a uniform spread the donation
+ * gate is unsatisfiable by construction: it needs `2*dur - floor >= floor`,
+ * i.e. `dur >= floor`, which contradicts `dur < floor` — the precondition
+ * for a word being short enough to enter this function's donation logic at
+ * all. So the call is inert at both sites today; this file exists so a
+ * future non-uniform editor spread is covered without anyone having to
+ * remember it. (Hand-authored `PUT` captions stay uncovered by design —
+ * Montaj stores whatever it receives.)
+ *
+ * AND THAT INERTNESS IS DELIBERATE — do not "fix" it by widening the
+ * segment. The only way to give n words a floor inside a fixed segment is
+ * to make the segment longer (a uniform spread has no surplus to
+ * redistribute: `dur < floor` implies `segDur < n * floor`), and montaj
+ * follows CapCut here — editing a caption's text never moves its end.
+ * Duration is the user's to set; a caption holding more words than it has
+ * room for shows them fast, and the remedy is to lengthen or split the
+ * caption, both of which the timeline supports via caption trim handles.
+ * Auto-growing a caption because its text changed would surprise anyone
+ * coming from CapCut. See MASTER.md open thread 1.
+ *
+ * THE ONE DIVERGENCE: caption.py runs at the flatten, before any segment
+ * exists, so its transcript-final word has no `seg_end` to clamp against and
+ * is extended unconditionally into trailing silence. This mirror runs
+ * per-segment instead — both call sites regenerate `words` for ONE segment
+ * at a time from a freshly uniform-spread duration — so a segment end IS
+ * available here, and the segment-final word is extended only up to
+ * `segEnd`, never past it: overrunning the segment boundary would bleed
+ * this caption's last word into whatever comes next on the timeline.
+ */
+import type { Word } from '../schema'
+
+export const MIN_WORD_DURATION_S = 0.05
+
+export function floorWordDurations(words: Word[], segEnd: number, floorS = MIN_WORD_DURATION_S): Word[] {
+  if (words.length === 0) return words
+
+  const out = words.map((w) => ({ ...w }))
+  const n = out.length
+  for (let i = 0; i < n; i++) {
+    const dur = out[i].end - out[i].start
+    if (dur >= floorS) continue
+
+    if (i + 1 >= n) {
+      // Segment-final word: extend up to the floor, clamped at segEnd — the
+      // one divergence from caption.py, see file header.
+      out[i].end = Math.min(out[i].end + (floorS - dur), segEnd)
+      continue
+    }
+
+    const gap = out[i + 1].start - out[i].end
+    if (gap > 0) {
+      // Non-contiguous: spend existing slack, never touch the successor.
+      out[i].end = Math.min(out[i].end + (floorS - dur), out[i + 1].start)
+      continue
+    }
+
+    // Contiguous: binary donation gate on the shared boundary.
+    const candidateBoundary = out[i].start + floorS
+    const successorNewDur = out[i + 1].end - candidateBoundary
+    if (successorNewDur >= floorS) {
+      out[i].end = candidateBoundary
+      out[i + 1].start = candidateBoundary
+    }
+    // else: donation refused. Word i is left completely unchanged.
+  }
+
+  return out
+}