@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/composition-ops/materializeGrid.js

@@ -1,99 +0,0 @@
-/**
- * materializeGrid — the pure media-time → timeline-time grid projection.
- *
- * A temporal GRID (beat map / word onsets / shot boundaries) lives in a media
- * item's own SOURCE time. To land cuts and transition midpoints on it, the grid
- * points must be mapped THROUGH a clip's placement (startTime, trim, playbackRate,
- * excludedRanges) into the composition's timeline, and written as markers.
- *
- * This module owns the pure projection + the marker minting; the DB-bound work
- * (reading the clip's source media evidence, idempotent marker replace) is the
- * route's — `services/convex/api/routes/materializeGrid.ts` — because the op is
- * route-materialized (the pure engine has no media reader), exactly like
- * `applyMotionPreset`.
- *
- * Source-time↔timeline mapping is NOT reinvented: the visible-window geometry
- * reuses `playableSpans` (@cueframe/core/render — the SAME trim-minus-excluded
- * span split the renderer projects), and the per-point timeline formula is the
- * one `mergeTimelineTranscripts` uses (`startTime + playedSource / playbackRate`),
- * extended to accumulate played source ACROSS excluded gaps.
- */
-import { playableSpans } from '@cueframe/core/render';
-/**
- * Fail-loud carrier for the materializeGrid guards. `code` is a registered
- * ErrorCode the op route re-throws as an `ApiError` (422) or folds into a
- * `dry_run` verdict. `opIndex` is stamped by the route (it knows the batch
- * position); the pure mapper leaves it undefined.
- */
-export class GridError extends Error {
-    code;
-    opIndex;
-    constructor(code, message, opIndex) {
-        super(message);
-        this.code = code;
-        this.opIndex = opIndex;
-        this.name = 'GridError';
-    }
-}
-/** Default marker cap (soft — a caller may raise it up to the hard ceiling). */
-export const GRID_DEFAULT_MAX_MARKERS = 500;
-/** Hard ceiling on markers materialized from one grid (never exceeded). */
-export const GRID_HARD_MAX_MARKERS = 2000;
-/**
- * Project media-time grid points (ms, in the source's own time) onto the
- * timeline through `placement`, minting one marker per VISIBLE point. Points
- * outside the clip's visible window (before/after the trim, or inside an
- * excluded range) are SKIPPED. Markers are named deterministically
- * (`<grid>-<n>`, id `grid-<grid>-<clipId>-<n>`, `n` = the running visible index)
- * so a re-run reproduces the exact set; `metadata.sourceClipId` records the
- * origin clip so the route can replace a prior materialization idempotently.
- *
- * Fails loud (`grid_cap_exceeded`) when the visible count exceeds `maxMarkers`
- * (default 500) — no silent truncation.
- */
-export function materializeGridMarkers(placement, gridPointsMs, opts) {
-    const { grid, clipId } = opts;
-    const cap = opts.maxMarkers ?? GRID_DEFAULT_MAX_MARKERS;
-    const rate = placement.playbackRate ?? 1;
-    const trimStart = placement.trim?.start ?? 0;
-    // Rate-correct source window when trim is absent: the clip plays
-    // `duration * rate` source-seconds from `trimStart`.
-    const trimEnd = placement.trim?.end ?? trimStart + placement.duration * rate;
-    const spans = playableSpans(trimStart, trimEnd, placement.excludedRanges);
-    const markers = [];
-    let n = 0;
-    for (const ms of gridPointsMs) {
-        const sourceSec = ms / 1000;
-        // Accumulate played source-seconds before this point, walking visible spans
-        // in order. A point that falls in a gap (excluded range) or past the last
-        // span is not visible → skipped (no marker, index not advanced).
-        let playedBefore = 0;
-        let visible = false;
-        for (const span of spans) {
-            if (sourceSec < span.start)
-                break; // in a gap before this span → invisible
-            if (sourceSec < span.end) {
-                playedBefore += sourceSec - span.start;
-                visible = true;
-                break;
-            }
-            playedBefore += span.end - span.start; // whole span is before the point
-        }
-        if (!visible)
-            continue;
-        markers.push({
-            id: `grid-${grid}-${clipId}-${n}`,
-            startTime: placement.startTime + playedBefore / rate,
-            kind: grid,
-            name: `${grid}-${n}`,
-            metadata: { sourceClipId: clipId },
-        });
-        n++;
-    }
-    if (markers.length > cap) {
-        throw new GridError('grid_cap_exceeded', `materializeGrid: ${markers.length} '${grid}' markers fall inside clip '${clipId}' — ` +
-            `over the cap of ${cap}. Raise maxMarkers (≤ ${GRID_HARD_MAX_MARKERS}) or narrow the ` +
-            `clip's visible window (trim / excludedRanges) so fewer grid points land.`);
-    }
-    return markers;
-}

package/dist/_members/composition-ops/opRecorder.js

@@ -1,196 +0,0 @@
-const genTrackId = (kind) => `track-${kind}-${crypto.randomUUID().slice(0, 8)}`;
-export function wrapWithOpRecorder(base, opts) {
-    const { record, getComposition } = opts;
-    const wrapped = {
-        // ── clips ──
-        // clip.add is family-self-routing; a bare `media` source is ambiguous, so
-        // the editor's video-lane addClip stamps kind:'video' (replay byte-faithful:
-        // the SAME object goes to the base store and the op). Every mapping derives
-        // from ARGS + BEFORE-state only, so ops record BEFORE the base mutation —
-        // `before` is exact and a throwing base never leaves a phantom op behind
-        // (record throws first on invalid input; base throws are surfaced to the
-        // caller with the op already journaled, which the flush's server apply
-        // would then reject loudly — never silently).
-        addClip: (clip, options) => {
-            const before = getComposition();
-            const c = clip.kind ? clip : { ...clip, kind: 'video' };
-            if (options?.newTrack) {
-                const newTrackId = options.newTrackId ?? genTrackId('video');
-                record({ type: 'clip.add', clip: c, newTrack: true, newTrackId }, before);
-                base.addClip(c, { newTrack: true, newTrackId });
-            }
-            else {
-                record({ type: 'clip.add', clip: c }, before);
-                base.addClip(c);
-            }
-        },
-        removeClip: (id) => {
-            record({ type: 'clip.remove', clipId: id }, getComposition());
-            base.removeClip(id);
-        },
-        updateClip: (id, updates) => {
-            record({ type: 'clip.update', clipId: id, patch: updates }, getComposition());
-            base.updateClip(id, updates);
-        },
-        removeClipsByMediaId: (mediaId) => {
-            record({ type: 'removeClipsByMediaId', mediaId }, getComposition());
-            base.removeClipsByMediaId(mediaId);
-        },
-        setClipProperties: (id, props) => {
-            // playbackRate is a cross-field ripple (source.playbackRate), NOT a free
-            // clip.update merge. Editor lane: apply locally (the store's ripple is
-            // correct) + signal unjournalable (→ snapshot barrier). Bench lane
-            // (no handler): throw — its op-log must replay byte-faithfully.
-            const { playbackRate, ...patch } = props;
-            if (playbackRate !== undefined) {
-                if (opts.onUnjournalable) {
-                    const result = base.setClipProperties(id, props);
-                    opts.onUnjournalable('setClipProperties.playbackRate');
-                    return result;
-                }
-                throw new Error('opRecorder.setClipProperties: playbackRate is not serializable as a clip.update op ' +
-                    '(source.playbackRate triggers a cross-field ripple). Use the server-authoritative ripple path.');
-            }
-            record({ type: 'clip.update', clipId: id, patch: patch }, getComposition());
-            return base.setClipProperties(id, props);
-        },
-        // ── overlays (pre-emit the overlay track on first add: pinned id, targeted clip.add) ──
-        addOverlay: (clip) => {
-            const before = getComposition();
-            const track = before.tracks.find((t) => t.kind === 'overlay');
-            let trackId = track?.id;
-            if (!trackId) {
-                trackId = genTrackId('overlay');
-                record({ type: 'addTrack', kind: 'overlay', id: trackId }, before);
-                base.addTrack('overlay', undefined, trackId);
-            }
-            record({ type: 'clip.add', clip, trackId }, getComposition());
-            base.addOverlay(clip);
-        },
-        removeOverlay: (id) => {
-            record({ type: 'clip.remove', clipId: id }, getComposition());
-            base.removeOverlay(id);
-        },
-        updateOverlay: (id, updates) => {
-            record({ type: 'clip.update', clipId: id, patch: updates }, getComposition());
-            base.updateOverlay(id, updates);
-        },
-        loadOverlays: (clips) => {
-            record({ type: 'loadOverlays', clips }, getComposition());
-            base.loadOverlays(clips);
-        },
-        // ── audio (same pre-emit rule) ──
-        addAudioClip: (clip) => {
-            const before = getComposition();
-            const track = before.tracks.find((t) => t.kind === 'audio');
-            let trackId = track?.id;
-            if (!trackId) {
-                trackId = genTrackId('audio');
-                record({ type: 'addTrack', kind: 'audio', id: trackId }, before);
-                base.addTrack('audio', undefined, trackId);
-            }
-            record({ type: 'clip.add', clip, trackId }, getComposition());
-            base.addAudioClip(clip);
-        },
-        removeAudioClip: (id) => {
-            record({ type: 'clip.remove', clipId: id }, getComposition());
-            base.removeAudioClip(id);
-        },
-        updateAudioClip: (id, updates) => {
-            record({ type: 'clip.update', clipId: id, patch: updates }, getComposition());
-            base.updateAudioClip(id, updates);
-        },
-        // ── markers ──
-        addMarker: (marker) => {
-            record({ type: 'addMarker', marker }, getComposition());
-            base.addMarker(marker);
-        },
-        removeMarker: (id) => {
-            record({ type: 'removeMarker', markerId: id }, getComposition());
-            base.removeMarker(id);
-        },
-        updateMarker: (id, updates) => {
-            record({ type: 'updateMarker', markerId: id, updates }, getComposition());
-            base.updateMarker(id, updates);
-        },
-        // ── crop / effects / captions / format ──
-        setCropIntents: (clipId, segments) => {
-            record({ type: 'setCropIntents', clipId, segments }, getComposition());
-            base.setCropIntents(clipId, segments);
-        },
-        // Wholesale array — `[]` records the clear, same as any other set.
-        setEffects: (clipId, effects) => {
-            record({ type: 'setEffects', clipId, effects }, getComposition());
-            base.setEffects(clipId, effects);
-        },
-        setCaptionStyle: (style) => {
-            record({ type: 'setCaptionStyle', style }, getComposition());
-            base.setCaptionStyle(style);
-        },
-        setCaptions: (segments, style) => {
-            record({ type: 'setCaptions', segments, ...(style !== undefined ? { style } : {}) }, getComposition());
-            base.setCaptions(segments, style);
-        },
-        setFormat: (format) => {
-            record({ type: 'setFormat', format }, getComposition());
-            base.setFormat(format);
-        },
-        // ── tracks (always pin the id) ──
-        addTrack: (kind, name, id) => {
-            const useId = id ?? genTrackId(kind);
-            record({ type: 'addTrack', kind, ...(name !== undefined ? { name } : {}), id: useId }, getComposition());
-            base.addTrack(kind, name, useId);
-        },
-        removeTrack: (trackId) => {
-            record({ type: 'removeTrack', trackId }, getComposition());
-            base.removeTrack(trackId);
-        },
-        updateTrack: (trackId, updates) => {
-            record({ type: 'updateTrack', trackId, updates }, getComposition());
-            base.updateTrack(trackId, updates);
-        },
-        reorderTracks: (fromIndex, toIndex) => {
-            record({ type: 'reorderTracks', fromIndex, toIndex }, getComposition());
-            base.reorderTracks(fromIndex, toIndex);
-        },
-        moveClipToTrack: (clipId, targetTrackId, newStartTime) => {
-            record({
-                type: 'moveClipToTrack',
-                clipId,
-                targetTrackId,
-                ...(newStartTime !== undefined ? { newStartTime } : {}),
-            }, getComposition());
-            base.moveClipToTrack(clipId, targetTrackId, newStartTime);
-        },
-        duplicateClip: (id) => {
-            record({ type: 'duplicateClip', clipId: id }, getComposition());
-            return base.duplicateClip(id);
-        },
-        // ── server-authoritative (cross-field timeline recompute) ──
-        cutAndRipple: (start, end) => {
-            record({ type: 'cutAndRipple', start, end }, getComposition());
-            base.cutAndRipple(start, end);
-        },
-        ripple: (time, amount) => {
-            record({ type: 'ripple', time, amount }, getComposition());
-            base.ripple(time, amount);
-        },
-        addExcludedRange: (clipId, sourceStart, sourceEnd, reason) => {
-            record({
-                type: 'addExcludedRange',
-                clipId,
-                sourceStart,
-                sourceEnd,
-                ...(reason !== undefined ? { reason } : {}),
-            }, getComposition());
-            base.addExcludedRange(clipId, sourceStart, sourceEnd, reason);
-        },
-        removeExcludedRange: (clipId, rangeIdx) => {
-            record({ type: 'removeExcludedRange', clipId, rangeIdx }, getComposition());
-            base.removeExcludedRange(clipId, rangeIdx);
-        },
-    };
-    // Non-mutation members (getState, selection passthroughs, …) fall through to
-    // base untouched; the wrapped mutations shadow them.
-    return { ...base, ...wrapped };
-}

package/dist/_members/composition-ops/recordingStore.js

@@ -1,14 +0,0 @@
-import { createHeadlessStore, } from '@cueframe/composition/ops';
-import { wrapWithOpRecorder } from './opRecorder';
-export function createRecordingStore(initial) {
-    const base = createHeadlessStore(initial);
-    const ops = [];
-    const wrapped = wrapWithOpRecorder(base, {
-        record: (op, _before) => ops.push(op),
-        getComposition: () => base.getState().composition,
-    });
-    return {
-        ...wrapped,
-        getOps: () => [...ops],
-    };
-}

package/dist/_members/composition-ops/replaceRegion.js

@@ -1,102 +0,0 @@
-/**
- * `replaceRegion` — the NON-RIPPLING cut/overlay lowering (selector-abstraction
- * spec §6.2). The genuinely-new timeline primitive the switch instance needs:
- * neither existing authoring mode fits a same-track temporal cut —
- *   - `add_clip mode:"layer"` makes a FRESH track (b-roll over A-roll), and
- *   - `add_clip mode:"ripple-insert"` SHIFTS downstream content.
- * A multicam switch is an OVERWRITE: A→B→C occupy the SAME region of the SAME
- * track, back to back, with nothing rippling.
- *
- * PLACEMENT: this lives in `@cueframe/composition-ops` (NOT framework-bound; it
- * already depends on `@cueframe/composition` + `@cueframe/core`). It does NOT
- * import the Selector core — it consumes a plain `CutSchedule` (the resolver's
- * lowered advisory), so the source-only concepts (`programAudioSourceId`, cut vs
- * overlay, source-window placement) live HERE, never in the core.
- *
- * Two kinds (spec §6.2):
- *  - `kind:"cut"` (synced angles): video follows the chosen source; AUDIO FOLLOWS
- *    the video UNLESS `programAudioSourceId` is set, in which case audio is pinned
- *    to one continuous bed on a separate audio track while video cuts (topology-i).
- *  - `kind:"overlay"` (b-roll cutaway): video-over on a NEW overlay/video track,
- *    primary audio continues (this defers to the existing layer semantics; the
- *    presence-gate authored its windows). The switch instance authors `cut`.
- *
- * Validates fail-loud: the authored segments tile the region without overlap/gap
- * (the `Gap.strict()` lesson) and every source window is in-media; the result
- * round-trips `Composition.parse` + `validateComposition`. Pure + deterministic.
- */
-import { Composition as CompositionSchema, } from '@cueframe/composition/validators';
-const EPS = 1e-3;
-/** Author a non-rippling cut schedule (+ optional pinned audio bed) onto a fresh
- *  video track of the composition. Returns the new composition (pure). */
-export function replaceRegion(input) {
-    const { cutSchedule, programAudioSourceId, durationByMediaId } = input;
-    if (cutSchedule.length === 0) {
-        throw new Error('replaceRegion: empty cut schedule');
-    }
-    // 1. Validate the schedule TILES its region (no gap, no overlap) — the
-    //    Gap.strict() lesson: an overlap/gap is a silent render artifact.
-    const sorted = [...cutSchedule].sort((a, b) => a.startSec - b.startSec);
-    for (let i = 0; i < sorted.length; i++) {
-        const s = sorted[i];
-        if (s.endSec <= s.startSec)
-            throw new Error(`replaceRegion: cut span '${s.candidateId}' has non-positive duration [${s.startSec},${s.endSec}]`);
-        const dur = durationByMediaId[s.mediaId];
-        if (dur !== undefined && (s.sourceInSec < -EPS || s.sourceOutSec > dur + EPS)) {
-            throw new Error(`replaceRegion: cut span '${s.candidateId}' source [${s.sourceInSec},${s.sourceOutSec}] out of media [0,${dur}]`);
-        }
-        if (i > 0) {
-            const prev = sorted[i - 1];
-            if (Math.abs(s.startSec - prev.endSec) > EPS) {
-                throw new Error(`replaceRegion: cut schedule is not contiguous — gap/overlap between ${prev.endSec} and ${s.startSec}`);
-            }
-        }
-    }
-    const regionStart = sorted[0].startSec;
-    const regionEnd = sorted[sorted.length - 1].endSec;
-    // 2. Build the video cut track — each span is one OVERWRITE clip, placed back-
-    //    to-back (no ripple). When audio is pinned, the video clips are muted (the
-    //    pinned bed carries the program audio); else audio follows (default volume).
-    const audioPinned = programAudioSourceId !== undefined;
-    // `mediaId` is a branded `Id<"mediaItems">` on the validator, but the resolver
-    // supplies a plain string. Cast the source at the boundary (the same pattern as
-    // authoring/timeline.ts `add_clip`), then the schema re-validates the whole shape.
-    const mediaClip = (id, startTime, duration, mediaId, trimStart, trimEnd, extra = {}) => ({
-        id,
-        startTime,
-        duration,
-        source: { kind: 'media', mediaId, trim: { start: trimStart, end: trimEnd }, ...extra },
-    });
-    const videoTrack = {
-        id: `switch-cut-${stableSuffix(sorted)}`,
-        kind: 'video',
-        name: input.trackName ?? 'Switch Cut',
-        contents: sorted.map((s, i) => mediaClip(`cut-${i}-${s.candidateId}`, s.startSec, s.endSec - s.startSec, s.mediaId, s.sourceInSec, s.sourceOutSec, audioPinned ? { muted: true } : {})),
-    };
-    const tracks = [...input.composition.tracks, videoTrack];
-    // 3. Pinned program audio bed (topology-i): ONE continuous clip on a separate
-    //    audio track spanning the whole region from the program source.
-    if (audioPinned) {
-        const dur = durationByMediaId[programAudioSourceId];
-        const audioOut = regionEnd - regionStart; // program audio starts at region start
-        if (dur !== undefined && audioOut > dur + EPS) {
-            throw new Error(`replaceRegion: program audio source '${programAudioSourceId}' (${dur}s) shorter than the region (${audioOut}s)`);
-        }
-        tracks.push({
-            id: `switch-audio-${programAudioSourceId}`,
-            kind: 'audio',
-            name: 'Program Audio',
-            contents: [
-                mediaClip(`program-audio-${programAudioSourceId}`, regionStart, regionEnd - regionStart, programAudioSourceId, 0, regionEnd - regionStart, { sync: 'independent' }),
-            ],
-        });
-    }
-    const next = { ...input.composition, tracks };
-    // 4. Round-trip through the canonical zod validator (Composition.parse) — the
-    //    Gap.strict() union + every per-field invariant fire here, fail-loud.
-    return CompositionSchema.parse(next);
-}
-/** A stable id suffix from the schedule (deterministic — no Date/random). */
-function stableSuffix(spans) {
-    return spans.map((s) => `${s.candidateId}@${s.startSec.toFixed(2)}`).join('_').slice(0, 48).replace(/[^a-zA-Z0-9_@.-]/g, '');
-}

package/dist/_members/composition-ops/testFixtures.js

@@ -1,19 +0,0 @@
-/** A media-source clip with an EXPLICIT family `kind` (video|audio|image). */
-export const mediaClip = (id, kind) => ({
-    id,
-    startTime: 0,
-    duration: 5,
-    ...(kind ? { kind } : {}),
-    source: { kind: 'media', mediaId: 'media-1', trim: { start: 0, end: 5 } },
-});
-/** An overlay-source clip — family derives from `source.kind` (no clip.kind). */
-export const overlayClip = (id) => ({
-    id,
-    startTime: 0,
-    duration: 3,
-    source: { kind: 'overlay', primitiveId: 'cinematic-title', params: { text: 'hi' } },
-});
-/** An audio clip: a media source carried on the `audio` family. */
-export const audioClip = (id) => mediaClip(id, 'audio');
-/** A minimal valid Marker (point marker on the timeline). */
-export const marker = (id, startTime = 1) => ({ id, startTime, kind: 'note', name: `marker ${id}` });

package/dist/_members/core/index.js

@@ -1,5 +0,0 @@
-export * from './types';
-// Re-export render module, excluding OverlayTemplate and OverlayParams which
-// are already exported from ./types with a different (generic) shape.
-// Consumers that need the Remotion-specific versions import from '@cueframe/core/render'.
-export { buildEmphasisSet, isEmphasized, extractCaptionWordsFromDoc, DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, computeExportDimensions, ensureEven, } from './render';

package/dist/_members/core/render/bookends.js

@@ -1,53 +0,0 @@
-/** Card bumper default length when the kit didn't set one (mirrors the resolver). */
-export const CARD_BOOKEND_DEFAULT_MS = 1500;
-/**
- * Video bumper fallback length when the kit set no `durationMs`. The resolver
- * forces no default for `kind:'video'` ("clip length governs"), but the pure
- * timeline math can't probe the clip's intrinsic length, so the renderer
- * reserves this deterministic window. A kit that sets `durationMs` overrides it.
- */
-export const VIDEO_BOOKEND_DEFAULT_MS = 3000;
-/**
- * Frames a single intro/outro bumper reserves on the timeline, or 0 when it is
- * absent/odd (soft). `card` always reserves (defaults to 1.5s); `video` reserves
- * only with a usable `src` (else there is nothing to play).
- */
-export function bookendFrames(bumper, fps) {
-    if (!bumper)
-        return 0;
-    if (bumper.kind !== "card" && bumper.kind !== "video")
-        return 0;
-    if (!Number.isFinite(fps) || fps <= 0)
-        return 0;
-    // A video bumper with no source can't render — soft no-op.
-    if (bumper.kind === "video" &&
-        (typeof bumper.src !== "string" || bumper.src.length === 0)) {
-        return 0;
-    }
-    const fallbackMs = bumper.kind === "card" ? CARD_BOOKEND_DEFAULT_MS : VIDEO_BOOKEND_DEFAULT_MS;
-    const ms = typeof bumper.durationMs === "number" &&
-        Number.isFinite(bumper.durationMs) &&
-        bumper.durationMs > 0
-        ? bumper.durationMs
-        : fallbackMs;
-    const frames = Math.round((ms / 1000) * fps);
-    return frames > 0 ? frames : 0;
-}
-/**
- * Forward timeline math: given the resolved kit's bumpers and the body's frame
- * length, place the bookends and compute the extended total. fps-driven; a
- * non-positive body folds to 0 (the total is then just the bookends).
- */
-export function resolveBookendTimeline(brandKit, bodyFrames, fps) {
-    const introFrames = bookendFrames(brandKit?.intro, fps);
-    const outroFrames = bookendFrames(brandKit?.outro, fps);
-    const safeBody = Number.isFinite(bodyFrames) && bodyFrames > 0 ? bodyFrames : 0;
-    return {
-        introFrames,
-        outroFrames,
-        bodyStartFrames: introFrames,
-        bodyFrames: safeBody,
-        outroStartFrames: introFrames + safeBody,
-        totalFrames: introFrames + safeBody + outroFrames,
-    };
-}

package/dist/_members/core/render/captions.js

@@ -1,127 +0,0 @@
-import { buildEmphasisSet, isEmphasized } from './emphasis';
-/**
- * Slice a transcript's word stream to a clip window.
- *
- * Source: `utterances[].words[]` with second-precision `start` / `end`.
- * Output: `CaptionWord[]` with millisecond timings rebased so the
- * first word's `startMs` is 0 (relative to the clip, not the source).
- * Words wholly outside `[fromSec, toSec)` are dropped; words that
- * straddle either edge are clamped to the boundary.
- *
- * Pure function — no I/O, no DB. Caller fetches the transcript blob
- * (typically from R2) and feeds the parsed `utterances` here.
- */
-export function sliceTranscriptWords(utterances, fromSec, toSec) {
-    const out = [];
-    for (const utt of utterances) {
-        if (!utt.words || utt.words.length === 0)
-            continue;
-        for (const w of utt.words) {
-            if (w.end <= fromSec)
-                continue;
-            if (w.start >= toSec)
-                continue;
-            const start = Math.max(w.start, fromSec);
-            const end = Math.min(w.end, toSec);
-            const text = (w.text ?? '').trim();
-            if (!text)
-                continue;
-            out.push({
-                text,
-                startMs: Math.round((start - fromSec) * 1000),
-                endMs: Math.round((end - fromSec) * 1000),
-            });
-        }
-    }
-    return out;
-}
-/**
- * Walk a TipTap doc JSONContent and extract non-deleted timedWord nodes
- * as CaptionWord[].
- *
- * In v2 the wire-shape composition encodes cuts physically (clip
- * startTime/duration), so caption timings are taken straight off the
- * timedWord attrs without any deletion-range shift.
- *
- * This makes the ProseMirror doc the single source of truth for caption text,
- * instead of re-reading raw Whisper transcripts.
- */
-export function extractCaptionWordsFromDoc(doc, emphasisWords) {
-    const captions = [];
-    const emphasisSet = buildEmphasisSet(emphasisWords);
-    function walk(node) {
-        if (node.type === 'timedWord' && node.attrs && !node.attrs.deleted) {
-            const start = node.attrs.start;
-            const end = node.attrs.end;
-            const text = node.content?.[0]?.text ?? '';
-            if (!text.trim())
-                return;
-            captions.push({
-                text,
-                startMs: start * 1000,
-                endMs: end * 1000,
-                emphasis: isEmphasized(emphasisSet, node.attrs.mediaId, node.attrs.sourceStart) || undefined,
-            });
-        }
-        if (node.content) {
-            for (const child of node.content)
-                walk(child);
-        }
-    }
-    walk(doc);
-    return captions;
-}
-// Common abbreviations whose trailing period is NOT a sentence end. Lower-cased,
-// period stripped. Not exhaustive — sentence-boundary disambiguation is
-// inherently lossy; this covers the frequent cases (titles, latin, units) so
-// captions don't false-break mid-sentence. Erring toward UNDER-splitting is
-// correct here: a missed split merges two short sentences (mildly long page),
-// whereas a false split is the exact mid-sentence cut this fix removes.
-const SENTENCE_ABBREVIATIONS = new Set([
-    'mr', 'mrs', 'ms', 'dr', 'prof', 'sr', 'jr', 'st', 'rev', 'gen', 'sen', 'gov',
-    'rep', 'capt', 'sgt', 'lt', 'col', 'vs', 'etc', 'inc', 'ltd', 'co', 'corp',
-    'mt', 'no', 'vol', 'dept', 'fig', 'al', 'approx',
-]);
-/** Whether a word's text terminates a sentence. `!`/`?` always do; a trailing
- *  `.` does NOT when the token is an initialism (`U.S.`, `e.g.`, `a.m.`) or a
- *  known abbreviation (`Dr.`, `etc.`). A number like "3.14" ends in a digit. */
-function isSentenceEnd(text) {
-    const t = text.trim();
-    if (/[!?]$/.test(t))
-        return true;
-    if (!t.endsWith('.'))
-        return false;
-    // Initialism / dotted abbreviation: every letter followed by a period
-    // (U.S., e.g., i.e., a.m., p.m.) — internal periods mark it as not-a-stop.
-    if (/^(\p{L}\.)+$/u.test(t))
-        return false;
-    if (SENTENCE_ABBREVIATIONS.has(t.slice(0, -1).toLowerCase()))
-        return false;
-    return true;
-}
-/**
- * Group a flat word stream into sentence-bounded segments — start a new segment
- * after any word that ends a sentence (`isSentenceEnd`). Caption words carry
- * punctuation from Deepgram's `punctuated_word`, so the trailing-character test
- * is reliable; abbreviations and initialisms are guarded so they don't
- * false-split mid-sentence.
- *
- * This is how a raw transcript slice becomes `composition.captions.segments`:
- * the renderer treats each segment as a hard caption-page boundary, so
- * sentence-bounded segments make captions cut at sentence ends. A stream with
- * no terminal punctuation yields a single segment; an empty stream yields none.
- */
-export function splitIntoSentences(words) {
-    const segments = [];
-    let current = [];
-    for (const word of words) {
-        current.push(word);
-        if (isSentenceEnd(word.text)) {
-            segments.push(current);
-            current = [];
-        }
-    }
-    if (current.length > 0)
-        segments.push(current);
-    return segments;
-}