@prestyj/editor 0.7.1

package/dist/core/filler-words.js

@@ -0,0 +1,273 @@
+/**
+ * Filler-word detection on word-timestamped transcripts.
+ *
+ * The single biggest creator-time-saver in long-form editing: scan the
+ * transcript word-by-word, mark every "um" / "uh" / "like" / "you know"
+ * range, then EMIT KEEP RANGES (the inverse). That keep list goes
+ * straight into write_edl → import_edl → done.
+ *
+ * What counts as a "filler" is configurable. The defaults reflect the
+ * canonical short list every YouTube auto-cutter (FireCut, Wisecut,
+ * Descript) ships with. We also support multi-word phrases ("you know",
+ * "i mean", "kind of") because the most distracting fillers are
+ * two-word verbal tics.
+ *
+ * Pure logic only — no I/O. The tool wrapper handles transcript loading
+ * and EDL emission.
+ */
+/**
+ * Default filler vocabulary. Single words and common multi-word verbal
+ * tics. The matcher normalizes punctuation and case, so we list bare
+ * surface forms.
+ */
+export const DEFAULT_FILLERS = [
+    "um",
+    "uh",
+    "uhm",
+    "umm",
+    "uhh",
+    "er",
+    "ah",
+    "hmm",
+    "you know",
+    "i mean",
+    "kind of",
+    "sort of",
+    "like",
+    "actually",
+    "basically",
+    "literally",
+    "honestly",
+    "right",
+    "so",
+];
+const NON_AGGRESSIVE_SAFE_LIST = new Set([
+    "um",
+    "uh",
+    "uhm",
+    "umm",
+    "uhh",
+    "er",
+    "ah",
+    "hmm",
+    "you know",
+    "i mean",
+    "kind of",
+    "sort of",
+]);
+/**
+ * Find filler-word ranges across the whole transcript. Requires
+ * word-level timestamps (transcribe with wordTimestamps=true).
+ *
+ * Returns ranges in temporal order with no overlaps; adjacent ranges
+ * within `mergeGapMs` are merged into a single cut.
+ */
+export function detectFillerRanges(transcript, opts = {}) {
+    // Default 0 ms — trust whisper's word timings. Previously defaulted to
+    // 20 ms with the wrong sign, producing 5+ s of unintended speech loss
+    // across a 73-cut podcast. See DetectFillersOptions docs.
+    const padStart = (opts.paddingStartMs ?? 0) / 1000;
+    const padEnd = (opts.paddingEndMs ?? 0) / 1000;
+    const mergeGap = (opts.mergeGapMs ?? 150) / 1000;
+    const aggressive = opts.aggressiveSingleWords ?? false;
+    const vocab = (opts.fillers ?? DEFAULT_FILLERS)
+        .map((f) => f.trim().toLowerCase())
+        .filter((f) => f.length > 0)
+        .filter((f) => aggressive || NON_AGGRESSIVE_SAFE_LIST.has(f));
+    // Sort so multi-word phrases match before single-word ones at the same
+    // position. Otherwise "you" + "know" gets matched as two single words.
+    const sortedVocab = [...vocab].sort((a, b) => b.split(/\s+/).length - a.split(/\s+/).length);
+    const out = [];
+    for (const segment of transcript.segments) {
+        const words = segment.words;
+        if (!words || words.length === 0)
+            continue;
+        const normalized = words.map((w) => normalizeWord(w.text));
+        let i = 0;
+        while (i < words.length) {
+            const match = findVocabMatch(sortedVocab, normalized, i);
+            if (!match) {
+                i++;
+                continue;
+            }
+            const startWord = words[i];
+            const endWord = words[i + match.length - 1];
+            // Padding now SHRINKS the filler range — positive padStart means
+            // the cut starts LATER (preserves more of the previous word's tail);
+            // positive padEnd means the cut ends EARLIER (preserves more of the
+            // next word's head). Old code used `- padStart` / `+ padEnd` which
+            // EXPANDED the cut outward, eating ~40 ms per filler.
+            const rawStart = startWord.start + padStart;
+            const rawEnd = endWord.end - padEnd;
+            // Clamp: padding can't make the filler range negative-duration; if
+            // it would, keep the original word boundaries unpadded.
+            const startSec = rawEnd > rawStart ? Math.max(0, rawStart) : Math.max(0, startWord.start);
+            const endSec = rawEnd > rawStart ? rawEnd : endWord.end;
+            out.push({
+                startSec,
+                endSec,
+                text: match.phrase,
+                startWordIndex: i,
+                endWordIndex: i + match.length,
+            });
+            i += match.length;
+        }
+    }
+    return mergeOverlappingFillers(out, mergeGap);
+}
+/**
+ * Compute KEEP ranges between fillers. The returned list is what you
+ * pass into write_edl as a sequence of source-in / source-out pairs.
+ *
+ * Adjacent keep ranges with a tiny gap (< minKeepDurSec) get dropped —
+ * a 40ms keep clip between two filler cuts is just noise.
+ */
+export function keepRangesFromFillers(fillers, totalSec, minKeepDurSec = 0.05) {
+    if (totalSec <= 0)
+        return [];
+    const sorted = [...fillers].sort((a, b) => a.startSec - b.startSec);
+    const keeps = [];
+    let cursor = 0;
+    for (const f of sorted) {
+        if (f.startSec > cursor) {
+            const start = cursor;
+            const end = Math.min(totalSec, f.startSec);
+            if (end - start >= minKeepDurSec) {
+                keeps.push({ startSec: start, endSec: end });
+            }
+        }
+        cursor = Math.max(cursor, Math.min(totalSec, f.endSec));
+    }
+    if (cursor < totalSec) {
+        const dur = totalSec - cursor;
+        if (dur >= minKeepDurSec) {
+            keeps.push({ startSec: cursor, endSec: totalSec });
+        }
+    }
+    return keeps;
+}
+/**
+ * From a sorted keep-range list, compute the TIMELINE-space cut points.
+ *
+ * After `import_edl` lands the keep ranges concatenated onto the timeline,
+ * each junction between adjacent keeps becomes a visible cut at the
+ * timeline-relative timestamp = sum of all earlier keep durations.
+ *
+ * Example: keeps = [[0,10], [12,25], [28,40]]
+ *   timeline = [0..10] + [10..23] + [23..35]
+ *   cuts at  =        10s,         23s   (two junctions)
+ *
+ * Why this matters: tools like `add_sfx_to_timeline` and `add_sfx_at_cuts`
+ * place SFX at TIMELINE timestamps. If callers pass SOURCE timestamps from
+ * the transcript, the drift compounds with every cut and the SFX lands
+ * progressively further out of sync (fine for the first ~30s, off by 20+s
+ * by the end of a typical podcast). This helper exists to remove that
+ * footgun.
+ */
+export function keepRangesToTimelineCuts(keeps) {
+    if (keeps.length <= 1)
+        return [];
+    const cuts = [];
+    let acc = 0;
+    for (let i = 0; i < keeps.length - 1; i++) {
+        acc += keeps[i].endSec - keeps[i].startSec;
+        cuts.push(+acc.toFixed(3));
+    }
+    return cuts;
+}
+/**
+ * Frame-align keep ranges. Rounds OUTWARD (start floors, end ceils) so
+ * we never DROP speech that lives in a partial frame at the keep's edge.
+ *
+ * Was: rounds inward (start ceils, end floors). Inward rounding never
+ * extends INTO an adjacent filler, but it ALSO loses up to one frame at
+ * each end of every keep — ~33 ms at 30 fps, ~17 ms at 60 fps. Across
+ * a 73-cut podcast that's 5+ seconds of speech disappearing into
+ * sub-frame rounding error.
+ *
+ * Trade-off: outward rounding can include up to one frame of an adjacent
+ * filler at each junction. That's ~33 ms at 30 fps — well within whisper
+ * timing noise (typically ±50 ms) and inaudible compared to losing 5 s
+ * of actual speech. Worth it.
+ */
+export function keepRangesToFrameRanges(keeps, fps) {
+    const out = [];
+    for (const k of keeps) {
+        const sf = Math.floor(k.startSec * fps);
+        const ef = Math.ceil(k.endSec * fps);
+        if (ef > sf)
+            out.push({ startFrame: sf, endFrame: ef });
+    }
+    return out;
+}
+// ── Internal ─────────────────────────────────────────────────
+function normalizeWord(text) {
+    // Lowercase and strip non-letter trailing/leading punctuation.
+    // We keep apostrophes inside words ("don't", "i'm").
+    return text
+        .toLowerCase()
+        .trim()
+        .replace(/^[^a-z']+/u, "")
+        .replace(/[^a-z']+$/u, "");
+}
+function findVocabMatch(sortedVocab, normalized, startIndex) {
+    for (const phrase of sortedVocab) {
+        const parts = phrase.split(/\s+/);
+        if (startIndex + parts.length > normalized.length)
+            continue;
+        let ok = true;
+        for (let j = 0; j < parts.length; j++) {
+            if (normalized[startIndex + j] !== parts[j]) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok)
+            return { phrase, length: parts.length };
+    }
+    return undefined;
+}
+function mergeOverlappingFillers(ranges, mergeGap) {
+    if (ranges.length <= 1)
+        return ranges;
+    const sorted = [...ranges].sort((a, b) => a.startSec - b.startSec);
+    const out = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+        const prev = out[out.length - 1];
+        const cur = sorted[i];
+        if (cur.startSec - prev.endSec <= mergeGap) {
+            out[out.length - 1] = {
+                startSec: prev.startSec,
+                endSec: Math.max(prev.endSec, cur.endSec),
+                text: `${prev.text} + ${cur.text}`,
+                startWordIndex: prev.startWordIndex,
+                endWordIndex: cur.endWordIndex,
+            };
+        }
+        else {
+            out.push(cur);
+        }
+    }
+    return out;
+}
+export function summarizeFillers(fillers) {
+    const counts = new Map();
+    let totalRemovedSec = 0;
+    for (const f of fillers) {
+        totalRemovedSec += f.endSec - f.startSec;
+        // For merged ranges the .text is "a + b" — we count each token.
+        for (const piece of f.text.split(/\s*\+\s*/)) {
+            counts.set(piece, (counts.get(piece) ?? 0) + 1);
+        }
+    }
+    const topFillers = [...counts.entries()]
+        .map(([text, count]) => ({ text, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 5);
+    return {
+        count: fillers.length,
+        totalRemovedSec: +totalRemovedSec.toFixed(3),
+        topFillers,
+    };
+}
+//# sourceMappingURL=filler-words.js.map

package/dist/core/filler-words.js.map

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

package/dist/core/filler-words.test.d.ts

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

package/dist/core/filler-words.test.d.ts.map

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

package/dist/core/filler-words.test.js

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "vitest";
+import { detectFillerRanges, keepRangesFromFillers, keepRangesToFrameRanges, keepRangesToTimelineCuts, summarizeFillers, } from "./filler-words.js";
+/**
+ * Build a synthetic transcript whose words have known timing. Each word
+ * is 0.3s long with a 0.05s gap between, starting at `startAt`.
+ */
+function makeTranscript(text, startAt = 0) {
+    const tokens = text.split(/\s+/).filter(Boolean);
+    let t = startAt;
+    const words = tokens.map((tok) => {
+        const start = t;
+        const end = t + 0.3;
+        t = end + 0.05;
+        return { start, end, text: tok };
+    });
+    return {
+        language: "en",
+        durationSec: t,
+        segments: [
+            {
+                start: words[0]?.start ?? 0,
+                end: words[words.length - 1]?.end ?? 0,
+                text: tokens.join(" "),
+                words,
+            },
+        ],
+    };
+}
+describe("detectFillerRanges", () => {
+    it("finds single-word fillers (um, uh)", () => {
+        const t = makeTranscript("hello um world uh goodbye");
+        const fillers = detectFillerRanges(t);
+        expect(fillers).toHaveLength(2);
+        expect(fillers[0].text).toBe("um");
+        expect(fillers[1].text).toBe("uh");
+    });
+    it("matches multi-word phrases (you know)", () => {
+        const t = makeTranscript("the answer you know is forty two");
+        const fillers = detectFillerRanges(t);
+        expect(fillers).toHaveLength(1);
+        expect(fillers[0].text).toBe("you know");
+        // The cut should span both words.
+        const word2 = t.segments[0].words[2]; // "you"
+        const word3 = t.segments[0].words[3]; // "know"
+        expect(fillers[0].startSec).toBeLessThanOrEqual(word2.start);
+        expect(fillers[0].endSec).toBeGreaterThanOrEqual(word3.end);
+    });
+    it("multi-word phrases match before single-word substrings", () => {
+        // 'you know' is multi-word filler. 'know' alone is not.
+        const t = makeTranscript("you know about it");
+        const fillers = detectFillerRanges(t);
+        expect(fillers).toHaveLength(1);
+        expect(fillers[0].text).toBe("you know");
+        expect(fillers[0].endWordIndex - fillers[0].startWordIndex).toBe(2);
+    });
+    it("strips punctuation when matching ('Um,' → 'um')", () => {
+        const t = makeTranscript("Hello Um, world.");
+        const fillers = detectFillerRanges(t);
+        expect(fillers).toHaveLength(1);
+        expect(fillers[0].text).toBe("um");
+    });
+    it("merges adjacent fillers within mergeGapMs", () => {
+        // "um uh" with a 0.05s gap between words — well within default 150ms.
+        const t = makeTranscript("um uh hello");
+        const fillers = detectFillerRanges(t);
+        expect(fillers).toHaveLength(1);
+        expect(fillers[0].text).toContain("um");
+        expect(fillers[0].text).toContain("uh");
+    });
+    it("respects custom vocabulary", () => {
+        const t = makeTranscript("hello banana world");
+        // aggressiveSingleWords=true so custom non-safe-list words are not filtered out.
+        const fillers = detectFillerRanges(t, { fillers: ["banana"], aggressiveSingleWords: true });
+        expect(fillers).toHaveLength(1);
+        expect(fillers[0].text).toBe("banana");
+    });
+    it("aggressiveSingleWords=false (default) skips 'like' / 'so' / 'actually'", () => {
+        const t = makeTranscript("i like the so called actually working idea");
+        // Default (false): only the safe-list filler vocabulary applies.
+        expect(detectFillerRanges(t)).toHaveLength(0);
+        // Explicit false: same result.
+        expect(detectFillerRanges(t, { aggressiveSingleWords: false })).toHaveLength(0);
+    });
+    it("aggressiveSingleWords=true includes 'like' / 'so' / 'actually'", () => {
+        const t = makeTranscript("i like the so called actually working idea");
+        // Explicit true: aggressive words match.
+        const aggressive = detectFillerRanges(t, { aggressiveSingleWords: true });
+        expect(aggressive.length).toBeGreaterThan(0);
+    });
+    it("returns empty when transcript has no word timings", () => {
+        const t = {
+            language: "en",
+            durationSec: 5,
+            segments: [{ start: 0, end: 5, text: "um hello uh world" }],
+        };
+        expect(detectFillerRanges(t)).toEqual([]);
+    });
+    it("padding SHRINKS the cut range (preserves speech around the filler)", () => {
+        const t = makeTranscript("hello um world");
+        const um = t.segments[0].words[1];
+        const fillers = detectFillerRanges(t, { paddingStartMs: 50, paddingEndMs: 50 });
+        // padStart=50ms means cut starts 50ms LATER than the word boundary —
+        // i.e. we keep MORE of the previous word's tail.
+        expect(fillers[0].startSec).toBeCloseTo(um.start + 0.05, 3);
+        expect(fillers[0].endSec).toBeCloseTo(um.end - 0.05, 3);
+    });
+    it("default padding is 0 — trust whisper's word boundaries", () => {
+        const t = makeTranscript("hello um world");
+        const um = t.segments[0].words[1];
+        const fillers = detectFillerRanges(t);
+        // No padding by default: cut spans exactly the word's reported timing.
+        expect(fillers[0].startSec).toBeCloseTo(um.start, 3);
+        expect(fillers[0].endSec).toBeCloseTo(um.end, 3);
+    });
+    it("falls back to unpadded boundaries when padding would invert the range", () => {
+        // 200ms of padding on a 100ms word would produce a negative duration.
+        // We clamp by reverting to the unpadded word boundaries rather than
+        // emitting a degenerate range.
+        const t = makeTranscript("um hello world");
+        const um = t.segments[0].words[0];
+        const fillers = detectFillerRanges(t, { paddingStartMs: 200, paddingEndMs: 200 });
+        expect(fillers[0].startSec).toBeCloseTo(um.start, 3);
+        expect(fillers[0].endSec).toBeCloseTo(um.end, 3);
+    });
+});
+describe("keepRangesFromFillers", () => {
+    it("emits the inverse of filler ranges", () => {
+        const fillers = [
+            { startSec: 1, endSec: 2, text: "um", startWordIndex: 0, endWordIndex: 1 },
+            { startSec: 4, endSec: 5, text: "uh", startWordIndex: 0, endWordIndex: 1 },
+        ];
+        const keeps = keepRangesFromFillers(fillers, 7);
+        expect(keeps).toEqual([
+            { startSec: 0, endSec: 1 },
+            { startSec: 2, endSec: 4 },
+            { startSec: 5, endSec: 7 },
+        ]);
+    });
+    it("returns the whole timeline when there are no fillers", () => {
+        expect(keepRangesFromFillers([], 10)).toEqual([{ startSec: 0, endSec: 10 }]);
+    });
+    it("handles fillers at the very start and end", () => {
+        const fillers = [
+            { startSec: 0, endSec: 0.5, text: "um", startWordIndex: 0, endWordIndex: 1 },
+            { startSec: 4.5, endSec: 5, text: "uh", startWordIndex: 0, endWordIndex: 1 },
+        ];
+        const keeps = keepRangesFromFillers(fillers, 5);
+        expect(keeps).toEqual([{ startSec: 0.5, endSec: 4.5 }]);
+    });
+    it("drops sub-minimum keep ranges", () => {
+        const fillers = [
+            { startSec: 1, endSec: 2, text: "um", startWordIndex: 0, endWordIndex: 1 },
+            { startSec: 2.02, endSec: 3, text: "uh", startWordIndex: 0, endWordIndex: 1 },
+        ];
+        const keeps = keepRangesFromFillers(fillers, 5, 0.05);
+        // The 0.02s gap between the two fillers should be dropped.
+        expect(keeps).toEqual([
+            { startSec: 0, endSec: 1 },
+            { startSec: 3, endSec: 5 },
+        ]);
+    });
+});
+describe("keepRangesToFrameRanges", () => {
+    it("rounds OUTWARD (floor start, ceil end) to preserve speech in partial frames", () => {
+        const keeps = [{ startSec: 0.4, endSec: 1.6 }];
+        const frames = keepRangesToFrameRanges(keeps, 30);
+        // floor(0.4 * 30) = 12 ; ceil(1.6 * 30) = 48
+        expect(frames).toEqual([{ startFrame: 12, endFrame: 48 }]);
+    });
+    it("keeps tiny ranges intact (used to drop them with inward rounding)", () => {
+        // floor(0.97 * 30) = 29 ; ceil(1.0 * 30) = 30 — 1-frame keep, valid.
+        // (Was zero-frame and dropped under inward rounding — the bug that ate 5+ s
+        //  of speech across 73 cuts.)
+        const keeps = [{ startSec: 0.97, endSec: 1.0 }];
+        const frames = keepRangesToFrameRanges(keeps, 30);
+        expect(frames).toEqual([{ startFrame: 29, endFrame: 30 }]);
+    });
+    it("drops zero-frame ranges (start equals end after rounding)", () => {
+        // floor(1.0 * 30) = 30 ; ceil(1.0 * 30) = 30 — same frame, dropped.
+        const keeps = [{ startSec: 1.0, endSec: 1.0 }];
+        const frames = keepRangesToFrameRanges(keeps, 30);
+        expect(frames).toEqual([]);
+    });
+});
+describe("summarizeFillers", () => {
+    it("counts occurrences and total removed time", () => {
+        const fillers = [
+            { startSec: 0, endSec: 0.3, text: "um", startWordIndex: 0, endWordIndex: 1 },
+            { startSec: 1, endSec: 1.5, text: "um", startWordIndex: 0, endWordIndex: 1 },
+            { startSec: 2, endSec: 2.5, text: "uh", startWordIndex: 0, endWordIndex: 1 },
+        ];
+        const stats = summarizeFillers(fillers);
+        expect(stats.count).toBe(3);
+        expect(stats.totalRemovedSec).toBeCloseTo(1.3, 3);
+        expect(stats.topFillers[0]).toEqual({ text: "um", count: 2 });
+        expect(stats.topFillers[1]).toEqual({ text: "uh", count: 1 });
+    });
+    it("splits merged fillers when counting", () => {
+        const fillers = [
+            { startSec: 0, endSec: 0.5, text: "um + uh", startWordIndex: 0, endWordIndex: 2 },
+        ];
+        const stats = summarizeFillers(fillers);
+        const counts = Object.fromEntries(stats.topFillers.map((f) => [f.text, f.count]));
+        expect(counts).toEqual({ um: 1, uh: 1 });
+    });
+});
+describe("keepRangesToTimelineCuts", () => {
+    it("emits one cut per junction in TIMELINE space (cumulative keep durations)", () => {
+        // Source: keep [0,10] + filler [10,12] + keep [12,25] + filler [25,28] + keep [28,40]
+        // After import_edl, the timeline = 10s + 13s + 12s = 35s with cuts at 10s and 23s
+        const keeps = [
+            { startSec: 0, endSec: 10 },
+            { startSec: 12, endSec: 25 },
+            { startSec: 28, endSec: 40 },
+        ];
+        expect(keepRangesToTimelineCuts(keeps)).toEqual([10, 23]);
+    });
+    it("returns empty when there are zero or one keep ranges", () => {
+        expect(keepRangesToTimelineCuts([])).toEqual([]);
+        expect(keepRangesToTimelineCuts([{ startSec: 0, endSec: 10 }])).toEqual([]);
+    });
+    it("compounds the cumulative offset correctly across many small keeps", () => {
+        // Each keep is 5s with 1s of filler between them.
+        // Timeline cuts land at 5, 10, 15, 20.
+        const keeps = [
+            { startSec: 0, endSec: 5 },
+            { startSec: 6, endSec: 11 },
+            { startSec: 12, endSec: 17 },
+            { startSec: 18, endSec: 23 },
+            { startSec: 24, endSec: 29 },
+        ];
+        expect(keepRangesToTimelineCuts(keeps)).toEqual([5, 10, 15, 20]);
+    });
+    it("the SOURCE-vs-TIMELINE drift bug — cuts diverge linearly with cumulative removed time", () => {
+        // The bug we're protecting against: agent passes source timestamps to a
+        // timeline tool. After 24s of total filler removed, a source-space cut at
+        // 60s is at timeline 60s - 24s = 36s. By 100s+ the drift is the full 24s.
+        // This test documents the math we're encoding for the agent.
+        const keeps = [
+            { startSec: 0, endSec: 30 }, // 30s kept
+            { startSec: 32, endSec: 60 }, // 28s kept (source 30-32 = 2s filler removed)
+            { startSec: 65, endSec: 100 }, // 35s kept (5s filler removed)
+        ];
+        const timelineCuts = keepRangesToTimelineCuts(keeps);
+        expect(timelineCuts).toEqual([30, 58]); // junction 1 at 30s timeline, junction 2 at 30+28=58s
+        // If the agent had passed SOURCE timestamps (32s and 65s), the second
+        // SFX would have landed at timeline=65s — 7s LATE relative to the actual
+        // junction at 58s. That's the bug.
+    });
+});
+//# sourceMappingURL=filler-words.test.js.map

package/dist/core/filler-words.test.js.map

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

package/dist/core/format.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Output formatters — all tool results pass through here.
+ *
+ * Design rule: tool output is consumed by an LLM, never a human directly.
+ * Optimize for token economy and machine parsability:
+ *   - No prose filler ("I successfully did X").
+ *   - No labels the LLM can already infer from the call it just made.
+ *   - JSON when fields > 1; bare value when result is a single fact.
+ *   - Errors: "error: <cause>; fix: <next-step>" — one line, actionable.
+ *   - Cap unbounded lists with a summary header.
+ */
+/** Render a value as compact JSON (no whitespace). Drops null/undefined keys. */
+export declare function compact(value: unknown): string;
+/** Standard one-line error format. */
+export declare function err(cause: string, fix?: string): string;
+/**
+ * Frames → SMPTE timecode (HH:MM:SS:FF). Used for EDL emission.
+ * Non-drop frame; agent is responsible for fps choice.
+ */
+export declare function framesToTimecode(frames: number, fps: number): string;
+/**
+ * Truncate a list with a summary header when it exceeds `keep`. Always shows
+ * the first and last `keep/2` items so the LLM sees both endpoints.
+ *
+ *   summarizeList([1,2,…,200], 10) →
+ *     { head: [1..5], tail: [196..200], total: 200, omitted: 190 }
+ */
+export declare function summarizeList<T>(items: T[], keep?: number): {
+    head: T[];
+    tail: T[];
+    total: number;
+    omitted: number;
+};
+/** Cap a string at `max` chars with a single-char ellipsis suffix. */
+export declare function clip(s: string, max: number): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/core/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/core/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE9C;AAED,sCAAsC;AACtC,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CASpE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,IAAI,SAAK,GACR;IACD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CASA;AAED,sEAAsE;AACtE,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD"}