@bycrux/editor 0.11.2 → 1.0.1

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

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest'
+import { activeCaptionWord } from '../captionActiveWord'
+import type { CaptionSegment, Captions, Word } from '../../schema'
+
+function w(word: string, start: number, end: number): Word {
+  return { word, start, end }
+}
+
+function seg(over: Partial<CaptionSegment> = {}): CaptionSegment {
+  return { text: 'x', start: 0, end: 1, ...over }
+}
+
+function captions(segments: CaptionSegment[]): Captions {
+  return { style: 'word-by-word', segments }
+}
+
+describe('activeCaptionWord', () => {
+  it('returns the word the playhead is inside', () => {
+    const track = captions([
+      seg({ id: 'a', start: 0, end: 2, text: 'hello world', words: [w('hello', 0, 1), w('world', 1, 2)] }),
+    ])
+    expect(activeCaptionWord(track, 0.5)).toEqual({ word: 'hello', segmentId: 'a' })
+    expect(activeCaptionWord(track, 1.5)).toEqual({ word: 'world', segmentId: 'a' })
+  })
+
+  it('falls back to the segment\'s first word when the playhead is in a gap between words', () => {
+    const track = captions([
+      seg({ id: 'a', start: 0, end: 2, text: 'hello world', words: [w('hello', 0, 0.4), w('world', 0.6, 1)] }),
+    ])
+    // 0.5 is between the two words' spans (0.4-0.6 gap), but still inside the segment.
+    expect(activeCaptionWord(track, 0.5)).toEqual({ word: 'hello', segmentId: 'a' })
+  })
+
+  it('is inclusive at a word\'s start (half-open interval)', () => {
+    const track = captions([
+      seg({ id: 'a', start: 0, end: 2, text: 'hello world', words: [w('hello', 0, 1), w('world', 1, 2)] }),
+    ])
+    expect(activeCaptionWord(track, 1)).toEqual({ word: 'world', segmentId: 'a' })
+  })
+
+  it('is exclusive at a word\'s end: falls to the next word if one starts there, else the gap fallback', () => {
+    const track = captions([
+      seg({ id: 'a', start: 0, end: 2, text: 'hello world', words: [w('hello', 0, 1), w('world', 1, 2)] }),
+    ])
+    // t=1 lands on "hello".end / "world".start: "hello" is excluded, "world" matches.
+    expect(activeCaptionWord(track, 1)).toEqual({ word: 'world', segmentId: 'a' })
+
+    const trackWithGap = captions([
+      seg({ id: 'a', start: 0, end: 2, text: 'hello world', words: [w('hello', 0, 0.5), w('world', 0.6, 2)] }),
+    ])
+    // t=0.5 lands on "hello".end but "world" doesn't start until 0.6: gap fallback.
+    expect(activeCaptionWord(trackWithGap, 0.5)).toEqual({ word: 'hello', segmentId: 'a' })
+  })
+
+  it('is exclusive at seg.end: the next segment is active there instead', () => {
+    const track = captions([
+      seg({ id: 'a', start: 0, end: 1, text: 'hello', words: [w('hello', 0, 1)] }),
+      seg({ id: 'b', start: 1, end: 2, text: 'world', words: [w('world', 1, 2)] }),
+    ])
+    expect(activeCaptionWord(track, 1)).toEqual({ word: 'world', segmentId: 'b' })
+  })
+
+  it('uses the first whitespace-separated token of seg.text when there is no words array', () => {
+    const track = captions([seg({ id: 'a', start: 0, end: 1, text: 'hello world' })])
+    expect(activeCaptionWord(track, 0.5)).toEqual({ word: 'hello', segmentId: 'a' })
+  })
+
+  it('falls through without an empty word when text is empty/whitespace and there are no words', () => {
+    expect(activeCaptionWord(captions([seg({ id: 'a', start: 0, end: 1, text: '' })]), 0.5)).toBeNull()
+    expect(activeCaptionWord(captions([seg({ id: 'a', start: 0, end: 1, text: '   ' })]), 0.5)).toBeNull()
+  })
+
+  it('falls back to the selected segment\'s first word when the playhead is between segments', () => {
+    const track = captions([
+      seg({ id: 'a', start: 0, end: 1, text: 'hello world' }),
+      seg({ id: 'b', start: 2, end: 3, text: 'goodbye moon' }),
+    ])
+    expect(activeCaptionWord(track, 1.5, 'b')).toEqual({ word: 'goodbye', segmentId: 'b' })
+  })
+
+  it('returns null when the playhead is between segments with no selection', () => {
+    const track = captions([
+      seg({ id: 'a', start: 0, end: 1, text: 'hello world' }),
+      seg({ id: 'b', start: 2, end: 3, text: 'goodbye moon' }),
+    ])
+    expect(activeCaptionWord(track, 1.5)).toBeNull()
+  })
+
+  it('returns null for an empty caption track and for undefined captions, without throwing', () => {
+    expect(activeCaptionWord(captions([]), 0.5)).toBeNull()
+    expect(activeCaptionWord(undefined, 0.5)).toBeNull()
+  })
+
+  it('prefers the highest lane when two segments are active at once, unless selection names the lower lane', () => {
+    const track = captions([
+      seg({ id: 'lo', start: 0, end: 2, text: 'bottom row', lane: 0 }),
+      seg({ id: 'hi', start: 0, end: 2, text: 'top row', lane: 1 }),
+    ])
+    expect(activeCaptionWord(track, 1)).toEqual({ word: 'top', segmentId: 'hi' })
+    expect(activeCaptionWord(track, 1, 'lo')).toEqual({ word: 'bottom', segmentId: 'lo' })
+  })
+
+  it('splits on irregular internal whitespace when falling back to seg.text', () => {
+    const track = captions([seg({ id: 'a', start: 0, end: 1, text: '  hello   world ' })])
+    expect(activeCaptionWord(track, 0.5)).toEqual({ word: 'hello', segmentId: 'a' })
+  })
+})

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

@@ -0,0 +1,262 @@
+import { describe, it, expect } from 'vitest'
+import type { CaptionSegment, Captions } from '../../schema'
+import {
+  laneOf,
+  maxCaptionLane,
+  groupCaptionLanes,
+  normalizeCaptionLanes,
+  segmentsInLane,
+  fitsInLane,
+  sameLaneNeighbours,
+  resolveDropLane,
+} from '../captionLanes'
+
+function seg(over: Partial<CaptionSegment> = {}): CaptionSegment {
+  return { text: 'x', start: 0, end: 1, ...over }
+}
+
+function captions(segments: CaptionSegment[]): Captions {
+  return { style: 'subtitle', segments }
+}
+
+describe('laneOf', () => {
+  it('defaults an absent lane to 0', () => {
+    expect(laneOf(seg())).toBe(0)
+  })
+
+  it('passes through a valid non-negative integer', () => {
+    expect(laneOf(seg({ lane: 3 }))).toBe(3)
+  })
+
+  it('floors a negative lane at 0', () => {
+    expect(laneOf(seg({ lane: -5 }))).toBe(0)
+  })
+
+  it('truncates a non-integer lane', () => {
+    expect(laneOf(seg({ lane: 2.9 }))).toBe(2)
+  })
+
+  it('treats NaN/Infinity as absent', () => {
+    expect(laneOf(seg({ lane: NaN }))).toBe(0)
+    expect(laneOf(seg({ lane: Infinity }))).toBe(0)
+    expect(laneOf(seg({ lane: -Infinity }))).toBe(0)
+  })
+})
+
+describe('maxCaptionLane', () => {
+  it('is 0 for an empty list', () => {
+    expect(maxCaptionLane([])).toBe(0)
+  })
+
+  it('is 0 for an all-lane-less (legacy) track', () => {
+    expect(maxCaptionLane([seg(), seg(), seg()])).toBe(0)
+  })
+
+  it('is the highest coerced lane present', () => {
+    expect(maxCaptionLane([seg({ lane: 0 }), seg({ lane: 4 }), seg({ lane: 2 })])).toBe(4)
+  })
+})
+
+describe('groupCaptionLanes', () => {
+  it('puts a legacy all-lane-less track entirely in exactly one lane', () => {
+    const groups = groupCaptionLanes([seg({ text: 'a' }), seg({ text: 'b' }), seg({ text: 'c' })])
+    expect(groups).toHaveLength(1)
+    expect(groups[0].lane).toBe(0)
+    expect(groups[0].segments.map(s => s.text)).toEqual(['a', 'b', 'c'])
+  })
+
+  it('represents a hole between occupied lanes as an empty group', () => {
+    const groups = groupCaptionLanes([seg({ lane: 0, text: 'bottom' }), seg({ lane: 3, text: 'top' })])
+    expect(groups).toHaveLength(4)
+    expect(groups.map(g => g.lane)).toEqual([0, 1, 2, 3])
+    expect(groups[0].segments.map(s => s.text)).toEqual(['bottom'])
+    expect(groups[1].segments).toEqual([])
+    expect(groups[2].segments).toEqual([])
+    expect(groups[3].segments.map(s => s.text)).toEqual(['top'])
+  })
+})
+
+describe('segmentsInLane', () => {
+  it('returns only the segments coerced to the given lane', () => {
+    const a = seg({ lane: 0, text: 'a' })
+    const b = seg({ lane: -9, text: 'b' }) // coerces to 0
+    const c = seg({ lane: 1, text: 'c' })
+    expect(segmentsInLane([a, b, c], 0).map(s => s.text)).toEqual(['a', 'b'])
+    expect(segmentsInLane([a, b, c], 1).map(s => s.text)).toEqual(['c'])
+    expect(segmentsInLane([a, b, c], 2)).toEqual([])
+  })
+})
+
+describe('normalizeCaptionLanes', () => {
+  it('passes undefined captions through unchanged', () => {
+    expect(normalizeCaptionLanes(undefined)).toBeUndefined()
+  })
+
+  it('returns the SAME reference for empty captions', () => {
+    const c = captions([])
+    expect(normalizeCaptionLanes(c)).toBe(c)
+  })
+
+  it('returns the SAME reference when lanes are already dense from 0', () => {
+    // Mix of absent (⇒ lane 0) and explicit values — both are already canonical.
+    const c = captions([seg({ text: 'a' }), seg({ lane: 1, text: 'b' }), seg({ lane: 2, text: 'c' })])
+    expect(normalizeCaptionLanes(c)).toBe(c)
+  })
+
+  it('collapses a hole (0, 3) down to dense (0, 1)', () => {
+    const c = captions([seg({ lane: 0, text: 'bottom' }), seg({ lane: 3, text: 'top' })])
+    const out = normalizeCaptionLanes(c)!
+    expect(out).not.toBe(c)
+    expect(out.segments.find(s => s.text === 'bottom')!.lane ?? 0).toBe(0)
+    expect(out.segments.find(s => s.text === 'top')!.lane).toBe(1)
+    expect(maxCaptionLane(out.segments)).toBe(1)
+    // Fully dense now — a second pass changes nothing further.
+    expect(normalizeCaptionLanes(out)).toBe(out)
+  })
+
+  it('normalizes sparse, negative, and non-integer lanes together to dense integers from 0', () => {
+    const bottom = seg({ text: 'absent' })          // absent ⇒ 0
+    const sparse = seg({ lane: 5, text: 'sparse' })   // sparse high lane
+    const negative = seg({ lane: -3, text: 'negative' }) // coerces to 0, alongside `bottom`
+    const fractional = seg({ lane: 2.7, text: 'fractional' }) // truncates to 2
+
+    const out = normalizeCaptionLanes(captions([bottom, sparse, negative, fractional]))!
+    const laneByText = Object.fromEntries(out.segments.map(s => [s.text, laneOf(s)]))
+
+    // Present coerced lanes were {0, 5, 0, 2} → three distinct lanes, renumbered
+    // in ascending order: 0→0, 2→1, 5→2.
+    expect(laneByText).toEqual({ absent: 0, negative: 0, fractional: 1, sparse: 2 })
+    expect(maxCaptionLane(out.segments)).toBe(2)
+
+    // Idempotent: normalizing the already-normalized result is a true no-op.
+    expect(normalizeCaptionLanes(out)).toBe(out)
+  })
+})
+
+describe('fitsInLane', () => {
+  const occupied = [seg({ id: 'a', lane: 0, start: 0, end: 5 }), seg({ id: 'b', lane: 0, start: 8, end: 10 })]
+
+  it('fits in a free gap', () => {
+    expect(fitsInLane(occupied, 'new', 0, 5, 8)).toBe(true)
+  })
+
+  it('does not fit when it overlaps an existing segment', () => {
+    expect(fitsInLane(occupied, 'new', 0, 4, 6)).toBe(false)
+  })
+
+  it('touching edges are not a collision', () => {
+    expect(fitsInLane(occupied, 'new', 0, 5, 8)).toBe(true) // butts both neighbors exactly
+  })
+
+  it('excludes the segment being placed from the collision check by id', () => {
+    // 'a' checked against its own current window — must not collide with itself.
+    expect(fitsInLane(occupied, 'a', 0, 0, 5)).toBe(true)
+  })
+
+  it('an empty lane always fits', () => {
+    expect(fitsInLane(occupied, 'new', 7, 0, 100)).toBe(true)
+  })
+})
+
+describe('sameLaneNeighbours', () => {
+  it('finds the nearest prev/next in the same lane, ignoring other lanes', () => {
+    const target = seg({ id: 'mid', lane: 0, start: 10, end: 12 })
+    const segments = [
+      seg({ id: 'far-prev', lane: 0, start: 0, end: 2 }),
+      seg({ id: 'near-prev', lane: 0, start: 5, end: 8 }),
+      seg({ id: 'other-lane', lane: 1, start: 8, end: 9 }),
+      target,
+      seg({ id: 'near-next', lane: 0, start: 14, end: 16 }),
+      seg({ id: 'far-next', lane: 0, start: 20, end: 22 }),
+    ]
+    const { prev, next } = sameLaneNeighbours(segments, target)
+    expect(prev?.id).toBe('near-prev')
+    expect(next?.id).toBe('near-next')
+  })
+
+  it('returns nulls when alone in its lane', () => {
+    const target = seg({ id: 'solo', lane: 2, start: 0, end: 1 })
+    const { prev, next } = sameLaneNeighbours([target], target)
+    expect(prev).toBeNull()
+    expect(next).toBeNull()
+  })
+})
+
+describe('resolveDropLane', () => {
+  it('lands directly on the wanted lane when it is free', () => {
+    const dragged = seg({ id: 'd', lane: 0, start: 0, end: 2 })
+    // A filler segment in lane 3 (elsewhere in time) just establishes maxLane
+    // so the clamp doesn't itself cap `wanted` below 2 in this fixture.
+    const filler = seg({ id: 'filler', lane: 3, start: 20, end: 22 })
+    const lane = resolveDropLane({
+      segments: [dragged, filler], seg: dragged, sourceLane: 0, laneDelta: -2, start: 0, end: 2,
+    })
+    expect(lane).toBe(2) // upward drag: sourceLane(0) - laneDelta(-2) = 2
+  })
+
+  it('a downward drag lowers the lane number (sign convention)', () => {
+    const seg1 = seg({ id: 'd', lane: 3, start: 0, end: 2 })
+    const lane = resolveDropLane({
+      segments: [seg1], seg: seg1, sourceLane: 3, laneDelta: 2, start: 0, end: 2,
+    })
+    expect(lane).toBe(1)
+  })
+
+  it('floors the wanted lane at 0 — never goes negative', () => {
+    const seg1 = seg({ id: 'd', lane: 1, start: 0, end: 2 })
+    const lane = resolveDropLane({
+      segments: [seg1], seg: seg1, sourceLane: 1, laneDelta: 10, start: 0, end: 2,
+    })
+    expect(lane).toBe(0)
+  })
+
+  it('fans out in order wanted, wanted-1, wanted+1: prefers wanted-1 when both are free', () => {
+    // wanted = 2 is occupied by a colliding segment; lanes 1 and 3 are both
+    // free at the drop window — order must pick 1 (wanted-1) over 3 (wanted+1).
+    const dragged = seg({ id: 'd', lane: 2, start: 0, end: 2 })
+    const blocker = seg({ id: 'blocker', lane: 2, start: 0, end: 2 })
+    const lane = resolveDropLane({
+      segments: [dragged, blocker], seg: dragged, sourceLane: 2, laneDelta: 0, start: 0, end: 2,
+    })
+    expect(lane).toBe(1)
+  })
+
+  it('falls through to wanted+1 when wanted-1 is also occupied', () => {
+    const dragged = seg({ id: 'd', lane: 2, start: 0, end: 2 })
+    const blockAt2 = seg({ id: 'b2', lane: 2, start: 0, end: 2 })
+    const blockAt1 = seg({ id: 'b1', lane: 1, start: 0, end: 2 })
+    const lane = resolveDropLane({
+      segments: [dragged, blockAt2, blockAt1], seg: dragged, sourceLane: 2, laneDelta: 0, start: 0, end: 2,
+    })
+    expect(lane).toBe(3)
+  })
+
+  it('mints the maxLane+1 lane when every existing lane collides', () => {
+    // Lanes 0, 1, 2 all carry a colliding segment at the drop window — the
+    // dragged segment (currently in an unrelated, non-colliding position)
+    // must land in the freshly minted lane 3.
+    const dragged = seg({ id: 'd', lane: 0, start: 50, end: 52 }) // elsewhere in time, doesn't block itself
+    const segments = [
+      dragged,
+      seg({ id: 'b0', lane: 0, start: 0, end: 2 }),
+      seg({ id: 'b1', lane: 1, start: 0, end: 2 }),
+      seg({ id: 'b2', lane: 2, start: 0, end: 2 }),
+    ]
+    const lane = resolveDropLane({
+      segments, seg: dragged, sourceLane: 0, laneDelta: 0, start: 0, end: 2,
+    })
+    expect(lane).toBe(3) // maxLane(2) + 1
+  })
+
+  it('always terminates with an in-range lane even with many fully-occupied lanes', () => {
+    const dragged = seg({ id: 'd', lane: 0, start: 100, end: 102 })
+    const blockers = Array.from({ length: 30 }, (_, i) => seg({ id: `b${i}`, lane: i, start: 0, end: 2 }))
+    const segments = [dragged, ...blockers]
+    const lane = resolveDropLane({
+      segments, seg: dragged, sourceLane: 15, laneDelta: 0, start: 0, end: 2,
+    })
+    expect(lane).toBe(30) // maxLane(29) + 1, guaranteed empty
+    expect(Number.isInteger(lane)).toBe(true)
+    expect(lane).toBeGreaterThanOrEqual(0)
+  })
+})

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

@@ -18,9 +18,14 @@
 //     ResizeObserver calls back synchronously with a fixed size.
 //   - Range.prototype.getBoundingClientRect does not exist in jsdom at all
 //     (throws "is not a function"), and Element.prototype.getBoundingClientRect
-//     always returns zeros. CaptionPreview's measureCaptionContentRect walks
-//     real text nodes via Range on every commit, so without a stub any test
-//     that renders actual caption content crashes.
+//     always returns zeros. measureCaptionContentRect (captionDragState.ts,
+//     called from CaptionPreview's layout effect) walks real text nodes via
+//     Range on every commit, so without a stub any test that renders actual
+//     caption content crashes.
+//
+// The fake template below emits no `data-caption-id`, deliberately: that also
+// exercises measureCaptionContentRect's fallback to the whole root, which is
+// what keeps a host-supplied or pre-lane template's selection box working.
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { render, waitFor, fireEvent } from '@testing-library/react'
 import type { ReactElement } from 'react'

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

@@ -0,0 +1,228 @@
+import { describe, it, expect } from 'vitest'
+import { floorWordDurations, MIN_WORD_DURATION_S } from '../captionWordFloor'
+import type { Word } from '../../schema'
+
+// Mirrors tests/steps/test_caption.py's waterfall matrix for
+// steps/lyrics/caption.py::floor_word_durations. The only behavioral
+// difference under test is the segment-final word: here it's clamped at
+// `segEnd` instead of extended unconditionally (this mirror runs
+// per-segment, not at the transcript flatten — see captionWordFloor.ts).
+
+function w(start: number, end: number, word = 'w'): Word {
+  return { word, start, end }
+}
+
+describe('floorWordDurations', () => {
+  it('is 50ms', () => {
+    expect(MIN_WORD_DURATION_S).toBe(0.05)
+  })
+
+  it('is a no-op on an empty list', () => {
+    expect(floorWordDurations([], 1)).toEqual([])
+  })
+
+  it('extends a single-word list (n==1) to the floor when segEnd allows it', () => {
+    // Pins the n==1 path: with no words after it, `i + 1 >= n` is already
+    // true at i=0, routing straight into the segment-final branch.
+    const words = [w(0, 0.02)]
+    const out = floorWordDurations(words, 1, 0.05)
+    expect(out[0].start).toBeCloseTo(0)
+    expect(out[0].end).toBeCloseTo(0.05)
+  })
+
+  it('clamps a single-word list (n==1) at a tight segEnd', () => {
+    const words = [w(0, 0.02)]
+    const out = floorWordDurations(words, 0.03, 0.05)
+    expect(out[0].start).toBeCloseTo(0)
+    expect(out[0].end).toBeCloseTo(0.03)
+  })
+
+  it('accepts a donation when the successor retains >= floor', () => {
+    // successor retains 0.400 - 0.050 = 0.350 >= floor
+    const words = [w(0, 0.02), w(0.02, 0.4)]
+    const out = floorWordDurations(words, 0.4, 0.05)
+    expect(out[0].start).toBeCloseTo(0)
+    expect(out[0].end).toBeCloseTo(0.05)
+    expect(out[1].start).toBeCloseTo(0.05)
+    expect(out[1].end).toBeCloseTo(0.4)
+  })
+
+  it('accepts a donation when the successor retains EXACTLY the floor (inclusive boundary)', () => {
+    // Pins the >= in the donation gate: the spec is "retain >= floor_s", not
+    // "> floor_s" — no other case in this matrix distinguishes the two, so
+    // without this one a regression to `>` would leave the suite green.
+    // Exact, not float-luck: candidateBoundary = 0 + 0.05 = 0.05;
+    // successorNewDur = 0.10 - 0.05 = 0.05 === floor exactly at these
+    // values. Word 1's own original duration (0.08) is already >= floor, so
+    // it never enters the "short" branch itself, pre- or post-donation —
+    // this case is clean of the segment-final clamp too.
+    const words = [w(0, 0.02), w(0.02, 0.1)]
+    const out = floorWordDurations(words, 0.1, 0.05)
+    expect(out[0].start).toBeCloseTo(0)
+    expect(out[0].end).toBeCloseTo(0.05)
+    expect(out[1].start).toBeCloseTo(0.05)
+    expect(out[1].end).toBeCloseTo(0.1)
+  })
+
+  it('refuses a donation when the successor would drop below floor, leaving word i unchanged', () => {
+    // successor would retain only 0.060 - 0.050 = 0.010 < floor: refused.
+    // Word 1 here is the segment-final word (clamped at segEnd=0.06, so no
+    // room to extend) — it stays exactly as-is too, unlike the Python
+    // mirror's unconditional-extension case tested separately below.
+    const words = [w(0, 0.02), w(0.02, 0.06)]
+    const out = floorWordDurations(words, 0.06, 0.05)
+    expect(out[0]).toEqual(w(0, 0.02))
+    expect(out[1]).toEqual(w(0.02, 0.06))
+  })
+
+  it('does not touch a final word at exactly the floor duration, even with room past segEnd to spare', () => {
+    // Pins the TRIGGER condition, not just the segEnd clamp: with segEnd far
+    // past the word's current end there is plenty of room to extend, yet a
+    // word already AT the floor never qualifies as short in the first
+    // place (the `dur >= floorS` skip fires before any extension logic).
+    const words = [w(0, 0.5), w(0.5, 0.55)] // duration exactly 0.05 == floor
+    const out = floorWordDurations(words, 10, 0.05)
+    expect(out).toEqual(words)
+  })
+
+  it('does not touch a final word comfortably above the floor', () => {
+    const words = [w(0, 0.5), w(0.5, 0.62)] // duration 0.12
+    const out = floorWordDurations(words, 10, 0.05)
+    expect(out).toEqual(words)
+  })
+
+  it('leaves an entirely starved run unchanged when every donation is refused and the last word is not short', () => {
+    const words = [w(0, 0.02), w(0.02, 0.04), w(0.04, 0.06), w(0.06, 0.11)]
+    const out = floorWordDurations(words, 0.11, 0.05)
+    expect(out).toEqual(words)
+  })
+
+  it('rescues only the starved run\'s last boundary when it is followed by a long word (per-boundary, not per-run)', () => {
+    const words = [w(0, 0.02), w(0.02, 0.04), w(0.04, 0.06), w(0.06, 0.5)]
+    const out = floorWordDurations(words, 0.5, 0.05)
+    expect(out[0]).toEqual(w(0, 0.02))
+    expect(out[1]).toEqual(w(0.02, 0.04))
+    expect(out[2].start).toBeCloseTo(0.04)
+    expect(out[2].end).toBeCloseTo(0.09)
+    expect(out[3].start).toBeCloseTo(0.09)
+    expect(out[3].end).toBeCloseTo(0.5)
+  })
+
+  it('extends a non-contiguous word into an existing gap without touching the successor start', () => {
+    const words = [w(0, 0.02), w(0.1, 0.2)]
+    const out = floorWordDurations(words, 0.2, 0.05)
+    expect(out[0].start).toBeCloseTo(0)
+    expect(out[0].end).toBeCloseTo(0.05)
+    expect(out[1]).toEqual(w(0.1, 0.2))
+  })
+
+  it('caps the non-contiguous extension at the gap size, not the full floor deficit', () => {
+    const words = [w(0, 0.02), w(0.03, 0.2)]
+    const out = floorWordDurations(words, 0.2, 0.05)
+    expect(out[0].start).toBeCloseTo(0)
+    expect(out[0].end).toBeCloseTo(0.03)
+    expect(out[1]).toEqual(w(0.03, 0.2))
+  })
+
+  it('leaves already-long words untouched (identical values out)', () => {
+    const words = [w(0, 0.5), w(0.5, 1.0), w(1.0, 1.8)]
+    const out = floorWordDurations(words, 1.8, 0.05)
+    expect(out).toEqual(words)
+  })
+
+  it('never creates overlap', () => {
+    const matrices: Word[][] = [
+      [w(0, 0.02), w(0.02, 0.4)],
+      [w(0, 0.02), w(0.02, 0.06)],
+      [w(0, 0.02), w(0.02, 0.04), w(0.04, 0.06), w(0.06, 0.11)],
+      [w(0, 0.02), w(0.02, 0.04), w(0.04, 0.06), w(0.06, 0.5)],
+      [w(0, 0.02), w(0.1, 0.2)],
+      [w(0, 0.02), w(0.03, 0.2)],
+    ]
+    for (const words of matrices) {
+      const segEnd = words[words.length - 1].end
+      const out = floorWordDurations(words, segEnd, 0.05)
+      for (let i = 0; i < out.length - 1; i++) {
+        expect(out[i].end).toBeLessThanOrEqual(out[i + 1].start + 1e-9)
+      }
+    }
+  })
+
+  it('never introduces a gap where words were previously flush', () => {
+    // word-by-word.jsx falls back to rendering the segment's LAST word when
+    // no word matches the current time — a gap introduced mid-segment would
+    // make the caption visibly jump to its final word and back. The
+    // waterfall must never do this: it only moves a shared boundary forward
+    // together, and the non-contiguous branch only ever shrinks a gap.
+    const matrices: Word[][] = [
+      [w(0, 0.02), w(0.02, 0.4)],
+      [w(0, 0.02), w(0.02, 0.06)],
+      [w(0, 0.02), w(0.02, 0.04), w(0.04, 0.06), w(0.06, 0.11)],
+      [w(0, 0.02), w(0.02, 0.04), w(0.04, 0.06), w(0.06, 0.5)],
+    ]
+    for (const words of matrices) {
+      const segEnd = words[words.length - 1].end
+      const flushBefore = words.slice(0, -1).map((word, i) => word.end === words[i + 1].start)
+      const out = floorWordDurations(words, segEnd, 0.05)
+      flushBefore.forEach((wasFlush, i) => {
+        if (wasFlush) expect(out[i].end).toBe(out[i + 1].start)
+      })
+    }
+  })
+
+  it('does not mutate the input', () => {
+    const words = [w(0, 0.02), w(0.02, 0.4)]
+    const snapshot = words.map((word) => ({ ...word }))
+    floorWordDurations(words, 0.4, 0.05)
+    expect(words).toEqual(snapshot)
+  })
+
+  describe('segment-final clamp (divergence from the Python mirror)', () => {
+    it('extends a short segment-final word only up to segEnd, never past it', () => {
+      const words = [w(0, 0.4), w(0.4, 0.42)]
+      const out = floorWordDurations(words, 0.42, 0.05)
+      expect(out[0]).toEqual(w(0, 0.4))
+      // Deficit would be 0.03 (→ 0.45) but segEnd caps it at 0.42.
+      expect(out[1].start).toBeCloseTo(0.4)
+      expect(out[1].end).toBeCloseTo(0.42)
+    })
+
+    it('extends a short segment-final word up to the floor when segEnd leaves enough room', () => {
+      const words = [w(0, 0.4), w(0.4, 0.42)]
+      const out = floorWordDurations(words, 0.46, 0.05)
+      expect(out[1].start).toBeCloseTo(0.4)
+      expect(out[1].end).toBeCloseTo(0.45)
+    })
+  })
+
+  describe('uniform spread (the actual editor-side call site)', () => {
+    it('is a no-op on a uniform segDur / n spread: the donation gate can never fire', () => {
+      // 4 words uniformly spread across 0.12s → 0.03s each, all sub-floor.
+      // For a contiguous run of equal-duration words, successorNewDur works
+      // out to 2*dur - floor, so the gate (successorNewDur >= floor)
+      // reduces to dur >= floor -- which contradicts dur < floor, the
+      // precondition for a word entering the donation branch at all. So no
+      // boundary in a uniform spread is ever eligible: this is not "starves
+      // gracefully", it is a hard no-op. (The segment-final word is a
+      // separate no-op too: a uniform spread's last word already ends
+      // exactly at segEnd, so the clamp there is a no-op by construction.)
+      // This pins that the editor-side call sites (captionRepair.ts,
+      // makeCaptionEdit.ts) are currently inert, not that they work. That is
+      // the intended behaviour, not a latent bug: a uniform editor spread is
+      // deliberately left unfloored to match CapCut (edited caption text
+      // never changes the caption's duration; lengthen or split it instead).
+      // Don't "fix" this test by making it non-vacuous in the direction of
+      // asserting the floor should fire here — that would be reintroducing
+      // the behaviour this test exists to keep out.
+      const n = 4
+      const segStart = 0
+      const segEnd = 0.12
+      const wordDur = (segEnd - segStart) / n
+      const spread = Array.from({ length: n }, (_, i) =>
+        w(segStart + i * wordDur, segStart + (i + 1) * wordDur, `w${i}`),
+      )
+      const out = floorWordDurations(spread, segEnd, 0.05)
+      expect(out).toEqual(spread)
+    })
+  })
+})