@kenkaiiii/gg-editor 0.1.0

package/dist/core/keyframes.js

@@ -0,0 +1,90 @@
+/**
+ * Keyframe sampling + easing curve helpers.
+ *
+ * Used by file-only ffmpeg helpers (Ken-Burns zoompan, speed-ramp curves)
+ * and by tests that want to verify FCPXML emission lines up with the
+ * mathematical sampled trajectory.
+ *
+ * Convention: t is normalized 0..1. Curves are pure functions of t so they
+ * compose cleanly. easeIn / easeOut use simple quadratic curves; smooth is
+ * smoothstep (3t² − 2t³). Linear is the identity.
+ */
+/** Linear interpolation. f(t) = t. */
+export function linear(t) {
+    return clamp01(t);
+}
+/** Quadratic ease-in. f(t) = t². Slow start, fast finish. */
+export function easeIn(t) {
+    const c = clamp01(t);
+    return c * c;
+}
+/** Quadratic ease-out. f(t) = 1 − (1−t)². Fast start, slow finish. */
+export function easeOut(t) {
+    const c = clamp01(t);
+    return 1 - (1 - c) * (1 - c);
+}
+/** Smoothstep. f(t) = 3t² − 2t³. Symmetric ease-in-out. */
+export function smooth(t) {
+    const c = clamp01(t);
+    return c * c * (3 - 2 * c);
+}
+/** Resolve an "interp" string to its curve function. */
+export function curveFor(interp) {
+    switch (interp) {
+        case "easeIn":
+            return easeIn;
+        case "easeOut":
+            return easeOut;
+        case "smooth":
+            return smooth;
+        case "linear":
+        case undefined:
+            return linear;
+    }
+}
+/**
+ * Sample a scalar keyframe sequence at a given clip-relative frame.
+ *
+ * Behaviour:
+ *   - Empty list → throws (caller bug).
+ *   - Single keyframe → returns its value (constant).
+ *   - Frame before first kf → first value (clamp).
+ *   - Frame after last kf → last value (clamp).
+ *   - Otherwise → interpolate between the two surrounding kfs using the
+ *     LEFT keyframe's `interp` setting.
+ */
+export function sampleCurve(kfs, frame, _fps) {
+    if (kfs.length === 0)
+        throw new Error("sampleCurve: empty keyframe list");
+    if (kfs.length === 1)
+        return kfs[0].value;
+    // Sorted-by-frame assumed; we don't sort here so the caller controls order.
+    if (frame <= kfs[0].frame)
+        return kfs[0].value;
+    if (frame >= kfs[kfs.length - 1].frame)
+        return kfs[kfs.length - 1].value;
+    for (let i = 0; i < kfs.length - 1; i++) {
+        const a = kfs[i];
+        const b = kfs[i + 1];
+        if (frame >= a.frame && frame <= b.frame) {
+            const span = b.frame - a.frame;
+            if (span <= 0)
+                return b.value;
+            const t = (frame - a.frame) / span;
+            const eased = curveFor(a.interp)(t);
+            return a.value + (b.value - a.value) * eased;
+        }
+    }
+    // Unreachable given the early-exit clamps above.
+    return kfs[kfs.length - 1].value;
+}
+function clamp01(t) {
+    if (!Number.isFinite(t))
+        return 0;
+    if (t < 0)
+        return 0;
+    if (t > 1)
+        return 1;
+    return t;
+}
+//# sourceMappingURL=keyframes.js.map

package/dist/core/keyframes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyframes.js","sourceRoot":"","sources":["../../src/core/keyframes.ts"],"names":[],"mappings":"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"}

package/dist/core/keyframes.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=keyframes.test.d.ts.map

package/dist/core/keyframes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyframes.test.d.ts","sourceRoot":"","sources":["../../src/core/keyframes.test.ts"],"names":[],"mappings":""}

package/dist/core/keyframes.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { curveFor, easeIn, easeOut, linear, sampleCurve, smooth } from "./keyframes.js";
+describe("curve helpers", () => {
+    it("linear is the identity, clamped to 0..1", () => {
+        expect(linear(0)).toBe(0);
+        expect(linear(0.5)).toBe(0.5);
+        expect(linear(1)).toBe(1);
+        expect(linear(-0.2)).toBe(0);
+        expect(linear(1.5)).toBe(1);
+    });
+    it("easeIn / easeOut are mirrored at t=0.5", () => {
+        expect(easeIn(0.5)).toBeCloseTo(0.25);
+        expect(easeOut(0.5)).toBeCloseTo(0.75);
+        expect(easeIn(0)).toBe(0);
+        expect(easeOut(1)).toBe(1);
+    });
+    it("smooth / smoothstep is symmetric: f(t) + f(1-t) = 1", () => {
+        for (const t of [0.1, 0.25, 0.4, 0.5, 0.75]) {
+            expect(smooth(t) + smooth(1 - t)).toBeCloseTo(1, 5);
+        }
+    });
+});
+describe("curveFor", () => {
+    it("maps interp strings to their curve functions", () => {
+        expect(curveFor("linear")).toBe(linear);
+        expect(curveFor("easeIn")).toBe(easeIn);
+        expect(curveFor("easeOut")).toBe(easeOut);
+        expect(curveFor("smooth")).toBe(smooth);
+        expect(curveFor(undefined)).toBe(linear);
+    });
+});
+describe("sampleCurve", () => {
+    it("returns single-keyframe value as constant", () => {
+        expect(sampleCurve([{ frame: 0, value: 42 }], 100, 30)).toBe(42);
+    });
+    it("clamps to first/last value outside the range", () => {
+        const kfs = [
+            { frame: 10, value: 1 },
+            { frame: 20, value: 2 },
+        ];
+        expect(sampleCurve(kfs, 0, 30)).toBe(1);
+        expect(sampleCurve(kfs, 9, 30)).toBe(1);
+        expect(sampleCurve(kfs, 100, 30)).toBe(2);
+    });
+    it("linearly interpolates between two keyframes", () => {
+        const kfs = [
+            { frame: 0, value: 0 },
+            { frame: 30, value: 10 },
+        ];
+        expect(sampleCurve(kfs, 15, 30)).toBeCloseTo(5);
+    });
+    it("uses the LEFT keyframe's interp for the segment", () => {
+        const kfs = [
+            { frame: 0, value: 0, interp: "easeIn" },
+            { frame: 30, value: 10 },
+        ];
+        // At t=0.5 with easeIn: t² = 0.25 → value = 0 + 10 * 0.25 = 2.5.
+        expect(sampleCurve(kfs, 15, 30)).toBeCloseTo(2.5);
+    });
+    it("works with multiple segments and uses the right one", () => {
+        const kfs = [
+            { frame: 0, value: 0 },
+            { frame: 30, value: 100 },
+            { frame: 60, value: 0 },
+        ];
+        expect(sampleCurve(kfs, 15, 30)).toBeCloseTo(50);
+        expect(sampleCurve(kfs, 45, 30)).toBeCloseTo(50);
+    });
+    it("throws on empty keyframe list", () => {
+        expect(() => sampleCurve([], 0, 30)).toThrow();
+    });
+});
+//# sourceMappingURL=keyframes.test.js.map

package/dist/core/keyframes.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyframes.test.js","sourceRoot":"","sources":["../../src/core/keyframes.test.ts"],"names":[],"mappings":"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"}

package/dist/core/keyword-captions.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Keyword-highlighted captions — the CapCut "active word" style that
+ * defines viral short-form aesthetics in 2025-2026.
+ *
+ * Plain word-by-word burned captions show every word in the same
+ * style. Keyword highlighting picks the 1-2 most content-bearing words
+ * per phrase and renders them in a stronger color / scale, so the eye
+ * locks onto the meaning even when the viewer is half-scrolling.
+ *
+ * No POS tagger needed — a small heuristic gets us 90% of the way:
+ *   - Numbers and ALL-CAPS tokens are always keywords.
+ *   - Words ≥ minKeywordLen and NOT in the stoplist are keywords.
+ *   - Words in the stoplist (articles / prepositions / fillers) are
+ *     never keywords.
+ *   - We cap to N keywords per phrase to keep emphasis meaningful.
+ *
+ * Output: AssCue list with two styles ("Default" + "Keyword"). The
+ * caller passes them straight into buildAss(); ffmpeg's `subtitles`
+ * filter renders the result.
+ */
+import type { AssCue, AssStyle } from "./ass.js";
+import type { TranscriptWord } from "./whisper.js";
+export interface KeywordCaptionOptions {
+    /** Words per cue. Default 3 — readable at fast speech rates. */
+    groupSize?: number;
+    /** Min gap (sec) at which we force a new cue. Default 0.4. */
+    gapSec?: number;
+    /** Min letters to consider a word a keyword by length. Default 5. */
+    minKeywordLen?: number;
+    /** Max keywords per cue. Default 1. Clamped to ≥0. */
+    maxKeywordsPerCue?: number;
+    /** Stoplist override (case-insensitive). Defaults to DEFAULT_STOPLIST. */
+    stoplist?: readonly string[];
+    /**
+     * Per-cue display duration cushion (sec) — extends each cue's end
+     * past the last word's end so the caption doesn't pop off mid-syllable.
+     * Default 0.08s.
+     */
+    endPaddingSec?: number;
+}
+/**
+ * The function-words / discourse markers we strip from keyword
+ * candidates. Lowercase, no punctuation.
+ */
+export declare const DEFAULT_STOPLIST: readonly ["a", "an", "the", "i", "me", "my", "mine", "you", "your", "yours", "he", "him", "his", "she", "her", "hers", "it", "its", "we", "us", "our", "ours", "they", "them", "their", "theirs", "this", "that", "these", "those", "is", "are", "was", "were", "be", "been", "being", "am", "do", "does", "did", "doing", "have", "has", "had", "having", "will", "would", "shall", "should", "may", "might", "must", "can", "could", "of", "in", "on", "at", "by", "to", "for", "with", "from", "as", "into", "onto", "out", "off", "up", "down", "over", "under", "and", "or", "but", "so", "if", "then", "than", "because", "while", "when", "where", "who", "which", "what", "why", "how", "not", "no", "yes", "okay", "ok", "well", "just", "really", "very", "much", "more", "most", "some", "any", "all", "each", "every", "um", "uh", "uhm", "like", "you know", "i mean"];
+/**
+ * Build the cues + styles for a keyword-highlighted caption track.
+ *
+ * Returns:
+ *   - styles: pass directly into AssOptions.styles (always 2 styles).
+ *   - cues:   one cue per N words OR per gap boundary. Cues with a
+ *             keyword embed the keyword via an inline `{\rKeyword}` ...
+ *             `{\rDefault}` reset so a single cue can mix both styles.
+ *
+ * The caller controls font/size/colors by overriding fields on the
+ * returned styles before passing them to buildAss.
+ */
+export declare function buildKeywordCaptions(words: TranscriptWord[], opts?: KeywordCaptionOptions): {
+    cues: AssCue[];
+    styles: AssStyle[];
+};
+/**
+ * Decide whether a single token (already normalized) is a keyword.
+ * Exported for unit testing.
+ */
+export declare function isKeywordToken(raw: string, stoplist: Set<string>, minLen: number): boolean;
+/**
+ * Sensible defaults that look right for vertical / 9:16 shorts:
+ *   - Default style: large white sans-serif with thick outline.
+ *   - Keyword style: punchy yellow, slightly larger, same font.
+ *
+ * Override via the returned array before passing into buildAss().
+ */
+export declare function defaultKeywordStyles(): AssStyle[];
+//# sourceMappingURL=keyword-captions.d.ts.map

package/dist/core/keyword-captions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-captions.d.ts","sourceRoot":"","sources":["../../src/core/keyword-captions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,q1BAuHnB,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EAAE,EACvB,IAAI,GAAE,qBAA0B,GAC/B;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,QAAQ,EAAE,CAAA;CAAE,CAoCxC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAgB1F;AAgDD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,QAAQ,EAAE,CAyBjD"}

package/dist/core/keyword-captions.js

@@ -0,0 +1,285 @@
+/**
+ * Keyword-highlighted captions — the CapCut "active word" style that
+ * defines viral short-form aesthetics in 2025-2026.
+ *
+ * Plain word-by-word burned captions show every word in the same
+ * style. Keyword highlighting picks the 1-2 most content-bearing words
+ * per phrase and renders them in a stronger color / scale, so the eye
+ * locks onto the meaning even when the viewer is half-scrolling.
+ *
+ * No POS tagger needed — a small heuristic gets us 90% of the way:
+ *   - Numbers and ALL-CAPS tokens are always keywords.
+ *   - Words ≥ minKeywordLen and NOT in the stoplist are keywords.
+ *   - Words in the stoplist (articles / prepositions / fillers) are
+ *     never keywords.
+ *   - We cap to N keywords per phrase to keep emphasis meaningful.
+ *
+ * Output: AssCue list with two styles ("Default" + "Keyword"). The
+ * caller passes them straight into buildAss(); ffmpeg's `subtitles`
+ * filter renders the result.
+ */
+/**
+ * The function-words / discourse markers we strip from keyword
+ * candidates. Lowercase, no punctuation.
+ */
+export const DEFAULT_STOPLIST = [
+    // articles
+    "a",
+    "an",
+    "the",
+    // pronouns
+    "i",
+    "me",
+    "my",
+    "mine",
+    "you",
+    "your",
+    "yours",
+    "he",
+    "him",
+    "his",
+    "she",
+    "her",
+    "hers",
+    "it",
+    "its",
+    "we",
+    "us",
+    "our",
+    "ours",
+    "they",
+    "them",
+    "their",
+    "theirs",
+    "this",
+    "that",
+    "these",
+    "those",
+    // common verbs / aux
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "am",
+    "do",
+    "does",
+    "did",
+    "doing",
+    "have",
+    "has",
+    "had",
+    "having",
+    "will",
+    "would",
+    "shall",
+    "should",
+    "may",
+    "might",
+    "must",
+    "can",
+    "could",
+    // prepositions / conjunctions
+    "of",
+    "in",
+    "on",
+    "at",
+    "by",
+    "to",
+    "for",
+    "with",
+    "from",
+    "as",
+    "into",
+    "onto",
+    "out",
+    "off",
+    "up",
+    "down",
+    "over",
+    "under",
+    "and",
+    "or",
+    "but",
+    "so",
+    "if",
+    "then",
+    "than",
+    "because",
+    "while",
+    "when",
+    "where",
+    "who",
+    "which",
+    "what",
+    "why",
+    "how",
+    "not",
+    "no",
+    "yes",
+    "okay",
+    "ok",
+    "well",
+    "just",
+    "really",
+    "very",
+    "much",
+    "more",
+    "most",
+    "some",
+    "any",
+    "all",
+    "each",
+    "every",
+    // common fillers (also covered by cut_filler_words but we don't
+    // assume those are gone)
+    "um",
+    "uh",
+    "uhm",
+    "like",
+    "you know",
+    "i mean",
+];
+/**
+ * Build the cues + styles for a keyword-highlighted caption track.
+ *
+ * Returns:
+ *   - styles: pass directly into AssOptions.styles (always 2 styles).
+ *   - cues:   one cue per N words OR per gap boundary. Cues with a
+ *             keyword embed the keyword via an inline `{\rKeyword}` ...
+ *             `{\rDefault}` reset so a single cue can mix both styles.
+ *
+ * The caller controls font/size/colors by overriding fields on the
+ * returned styles before passing them to buildAss.
+ */
+export function buildKeywordCaptions(words, opts = {}) {
+    const groupSize = Math.max(1, opts.groupSize ?? 3);
+    const gapSec = Math.max(0, opts.gapSec ?? 0.4);
+    const minLen = Math.max(1, opts.minKeywordLen ?? 5);
+    const maxKw = Math.max(0, opts.maxKeywordsPerCue ?? 1);
+    const endPad = Math.max(0, opts.endPaddingSec ?? 0.08);
+    const stoplist = new Set((opts.stoplist ?? DEFAULT_STOPLIST).map((s) => s.toLowerCase().trim()));
+    const styles = defaultKeywordStyles();
+    const cues = [];
+    if (words.length === 0)
+        return { cues, styles };
+    let cueWords = [];
+    const flush = () => {
+        if (cueWords.length === 0)
+            return;
+        cues.push(buildCue(cueWords, stoplist, minLen, maxKw, endPad));
+        cueWords = [];
+    };
+    for (let i = 0; i < words.length; i++) {
+        const w = words[i];
+        if (cueWords.length === 0) {
+            cueWords.push(w);
+            continue;
+        }
+        const prev = cueWords[cueWords.length - 1];
+        const gap = w.start - prev.end;
+        if (gap >= gapSec || cueWords.length >= groupSize) {
+            flush();
+        }
+        cueWords.push(w);
+    }
+    flush();
+    return { cues, styles };
+}
+/**
+ * Decide whether a single token (already normalized) is a keyword.
+ * Exported for unit testing.
+ */
+export function isKeywordToken(raw, stoplist, minLen) {
+    const stripped = raw.replace(/[^a-zA-Z0-9']/g, "");
+    if (stripped.length === 0)
+        return false;
+    // Numbers always count.
+    if (/^\d+([.,]\d+)?$/.test(stripped))
+        return true;
+    // Pure ALL-CAPS at length >=2 (avoids "I").
+    if (stripped.length >= 2 && stripped === stripped.toUpperCase() && /[A-Z]/.test(stripped)) {
+        return true;
+    }
+    const lower = stripped.toLowerCase();
+    if (stoplist.has(lower))
+        return false;
+    // Multi-word stoplist phrases like "you know" — token might be either
+    // half. We only check single-token entries here (multi-word stops are
+    // applied at the cut_filler_words layer).
+    if (stripped.length < minLen)
+        return false;
+    return true;
+}
+// ── Internals ───────────────────────────────────────────────
+function buildCue(cueWords, stoplist, minLen, maxKw, endPad) {
+    // Score each word: 0 = function word, 1 = candidate keyword.
+    // Sort by length (longer = more salient), break ties by source order.
+    const candidates = cueWords
+        .map((w, idx) => ({ idx, isKw: isKeywordToken(w.text, stoplist, minLen) }))
+        .filter((c) => c.isKw);
+    // Take up to maxKw, preferring longer words.
+    const chosen = new Set([...candidates]
+        .sort((a, b) => {
+        const la = cueWords[a.idx].text.length;
+        const lb = cueWords[b.idx].text.length;
+        if (la !== lb)
+            return lb - la;
+        return a.idx - b.idx;
+    })
+        .slice(0, maxKw)
+        .map((c) => c.idx));
+    // Build the ASS dialogue text. ASS supports inline style overrides via
+    // {\rStyleName} which switches to that style; {\r} resets to default.
+    const parts = [];
+    cueWords.forEach((w, idx) => {
+        const text = w.text.trim();
+        if (chosen.has(idx)) {
+            parts.push(`{\\rKeyword}${text}{\\r}`);
+        }
+        else {
+            parts.push(text);
+        }
+    });
+    return {
+        start: cueWords[0].start,
+        end: cueWords[cueWords.length - 1].end + endPad,
+        text: parts.join(" "),
+    };
+}
+/**
+ * Sensible defaults that look right for vertical / 9:16 shorts:
+ *   - Default style: large white sans-serif with thick outline.
+ *   - Keyword style: punchy yellow, slightly larger, same font.
+ *
+ * Override via the returned array before passing into buildAss().
+ */
+export function defaultKeywordStyles() {
+    return [
+        {
+            name: "Default",
+            fontName: "Arial",
+            fontSize: 84,
+            primaryColor: "FFFFFF",
+            outlineColor: "000000",
+            outline: 4,
+            bold: true,
+            alignment: 2,
+            marginV: 220,
+        },
+        {
+            name: "Keyword",
+            fontName: "Arial",
+            fontSize: 96,
+            primaryColor: "FFEA00",
+            outlineColor: "000000",
+            outline: 5,
+            bold: true,
+            alignment: 2,
+            marginV: 220,
+        },
+    ];
+}
+//# sourceMappingURL=keyword-captions.js.map

package/dist/core/keyword-captions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-captions.js","sourceRoot":"","sources":["../../src/core/keyword-captions.ts"],"names":[],"mappings":"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"}

package/dist/core/keyword-captions.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=keyword-captions.test.d.ts.map

package/dist/core/keyword-captions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-captions.test.d.ts","sourceRoot":"","sources":["../../src/core/keyword-captions.test.ts"],"names":[],"mappings":""}

package/dist/core/keyword-captions.test.js

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { buildAss } from "./ass.js";
+import { buildKeywordCaptions, DEFAULT_STOPLIST, isKeywordToken } from "./keyword-captions.js";
+const STOP = new Set(DEFAULT_STOPLIST.map((s) => s.toLowerCase()));
+function w(text, start, end) {
+    return { start, end, text };
+}
+describe("isKeywordToken", () => {
+    it("rejects stoplist function words", () => {
+        expect(isKeywordToken("the", STOP, 5)).toBe(false);
+        expect(isKeywordToken("This", STOP, 5)).toBe(false);
+        expect(isKeywordToken("um", STOP, 5)).toBe(false);
+    });
+    it("accepts long content words", () => {
+        expect(isKeywordToken("retention", STOP, 5)).toBe(true);
+        expect(isKeywordToken("creators", STOP, 5)).toBe(true);
+    });
+    it("rejects words shorter than minLen", () => {
+        expect(isKeywordToken("dog", STOP, 5)).toBe(false);
+    });
+    it("accepts numbers regardless of length / stoplist", () => {
+        expect(isKeywordToken("12", STOP, 5)).toBe(true);
+        expect(isKeywordToken("3.14", STOP, 5)).toBe(true);
+        expect(isKeywordToken("80%", STOP, 5)).toBe(true);
+    });
+    it("accepts ALL-CAPS tokens (>= 2 chars) regardless of length", () => {
+        expect(isKeywordToken("AI", STOP, 5)).toBe(true);
+        expect(isKeywordToken("CEO", STOP, 5)).toBe(true);
+        // single capital letter does NOT count (avoids highlighting "I").
+        expect(isKeywordToken("I", STOP, 5)).toBe(false);
+    });
+    it("strips trailing punctuation when matching", () => {
+        expect(isKeywordToken("retention,", STOP, 5)).toBe(true);
+        expect(isKeywordToken("the.", STOP, 5)).toBe(false);
+    });
+});
+describe("buildKeywordCaptions", () => {
+    it("returns empty cues for empty input", () => {
+        const r = buildKeywordCaptions([]);
+        expect(r.cues).toEqual([]);
+        expect(r.styles.length).toBeGreaterThanOrEqual(2);
+    });
+    it("groups words into cues of groupSize", () => {
+        const words = Array.from({ length: 6 }, (_, i) => w(`word${i}`, i * 0.3, i * 0.3 + 0.25));
+        const r = buildKeywordCaptions(words, { groupSize: 2, gapSec: 5 });
+        expect(r.cues).toHaveLength(3);
+    });
+    it("breaks cues on a gap >= gapSec even mid-group", () => {
+        const words = [w("hello", 0, 0.3), w("world", 0.5, 0.8), w("again", 2.0, 2.3)];
+        const r = buildKeywordCaptions(words, { groupSize: 5, gapSec: 0.5 });
+        // gap between word2 and word3 is 1.2s — forces a new cue.
+        expect(r.cues).toHaveLength(2);
+    });
+    it("emits two styles named Default and Keyword", () => {
+        const r = buildKeywordCaptions([w("retention", 0, 0.3)]);
+        const names = r.styles.map((s) => s.name);
+        expect(names).toContain("Default");
+        expect(names).toContain("Keyword");
+    });
+    it("wraps the longest content word with {\\rKeyword} ... {\\r}", () => {
+        const words = [w("the", 0, 0.2), w("retention", 0.25, 0.65), w("graph", 0.7, 0.95)];
+        const r = buildKeywordCaptions(words, { groupSize: 3, maxKeywordsPerCue: 1 });
+        expect(r.cues[0].text).toContain("{\\rKeyword}retention{\\r}");
+        expect(r.cues[0].text).not.toContain("{\\rKeyword}the");
+    });
+    it("respects maxKeywordsPerCue=2 — can highlight two words", () => {
+        const words = [w("retention", 0, 0.4), w("graph", 0.5, 0.8), w("creators", 0.85, 1.3)];
+        const r = buildKeywordCaptions(words, { groupSize: 3, maxKeywordsPerCue: 2 });
+        const text = r.cues[0].text;
+        expect((text.match(/\{\\rKeyword\}/g) ?? []).length).toBe(2);
+    });
+    it("respects maxKeywordsPerCue=0 — no highlighting", () => {
+        const words = [w("retention", 0, 0.4), w("graph", 0.5, 0.8)];
+        const r = buildKeywordCaptions(words, { groupSize: 3, maxKeywordsPerCue: 0 });
+        expect(r.cues[0].text).not.toContain("{\\rKeyword}");
+    });
+    it("pads cue end past the last word", () => {
+        const r = buildKeywordCaptions([w("hello", 0, 0.3)], { endPaddingSec: 0.2 });
+        expect(r.cues[0].end).toBeCloseTo(0.5, 3);
+    });
+    it("output cues are accepted by buildAss without errors", () => {
+        const words = [w("the", 0, 0.2), w("creator", 0.25, 0.7), w("retention", 0.75, 1.2)];
+        const r = buildKeywordCaptions(words);
+        const ass = buildAss({ styles: r.styles, cues: r.cues, playResX: 1080, playResY: 1920 });
+        expect(ass).toContain("[V4+ Styles]");
+        expect(ass).toContain("Style: Keyword");
+        expect(ass).toContain("retention");
+    });
+});
+//# sourceMappingURL=keyword-captions.test.js.map