@prestyj/editor 0.7.1

package/dist/core/format.js

@@ -0,0 +1,57 @@
+/**
+ * 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 function compact(value) {
+    return JSON.stringify(value, (_k, v) => (v === null || v === undefined ? undefined : v));
+}
+/** Standard one-line error format. */
+export function err(cause, fix) {
+    return fix ? `error: ${cause}; fix: ${fix}` : `error: ${cause}`;
+}
+/**
+ * Frames → SMPTE timecode (HH:MM:SS:FF). Used for EDL emission.
+ * Non-drop frame; agent is responsible for fps choice.
+ */
+export function framesToTimecode(frames, fps) {
+    if (frames < 0)
+        frames = 0;
+    const ifps = Math.round(fps); // EDL uses integer fps; 23.976 → 24, 29.97 → 30
+    const totalSec = Math.floor(frames / ifps);
+    const ff = frames % ifps;
+    const hh = Math.floor(totalSec / 3600);
+    const mm = Math.floor((totalSec % 3600) / 60);
+    const ss = totalSec % 60;
+    return [hh, mm, ss, ff].map((n) => String(n).padStart(2, "0")).join(":");
+}
+/**
+ * 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 function summarizeList(items, keep = 20) {
+    if (items.length <= keep)
+        return { head: items, tail: [], total: items.length, omitted: 0 };
+    const half = Math.floor(keep / 2);
+    return {
+        head: items.slice(0, half),
+        tail: items.slice(-half),
+        total: items.length,
+        omitted: items.length - half * 2,
+    };
+}
+/** Cap a string at `max` chars with a single-char ellipsis suffix. */
+export function clip(s, max) {
+    return s.length <= max ? s : s.slice(0, max - 1) + "…";
+}
+//# sourceMappingURL=format.js.map

package/dist/core/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/core/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iFAAiF;AACjF,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,GAAG,CAAC,KAAa,EAAE,GAAY;IAC7C,OAAO,GAAG,CAAC,CAAC,CAAC,UAAU,KAAK,UAAU,GAAG,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,EAAE,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,GAAW;IAC1D,IAAI,MAAM,GAAG,CAAC;QAAE,MAAM,GAAG,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,gDAAgD;IAC9E,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3C,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACvC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9C,MAAM,EAAE,GAAG,QAAQ,GAAG,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAU,EACV,IAAI,GAAG,EAAE;IAOT,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC5F,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAClC,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;QAC1B,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;QACxB,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,OAAO,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,CAAC;KACjC,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,IAAI,CAAC,CAAS,EAAE,GAAW;IACzC,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;AACzD,CAAC"}

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

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

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

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

package/dist/core/format.test.js

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { clip, compact, err, framesToTimecode, summarizeList } from "./format.js";
+describe("compact", () => {
+    it("emits no whitespace", () => {
+        expect(compact({ a: 1, b: "x" })).toBe('{"a":1,"b":"x"}');
+    });
+    it("strips null/undefined fields", () => {
+        expect(compact({ a: 1, b: null, c: undefined, d: 2 })).toBe('{"a":1,"d":2}');
+    });
+});
+describe("err", () => {
+    it("formats cause only", () => {
+        expect(err("bad input")).toBe("error: bad input");
+    });
+    it("formats cause + fix", () => {
+        expect(err("no python", "install python3")).toBe("error: no python; fix: install python3");
+    });
+});
+describe("framesToTimecode", () => {
+    it("formats zero", () => {
+        expect(framesToTimecode(0, 30)).toBe("00:00:00:00");
+    });
+    it("formats one second", () => {
+        expect(framesToTimecode(30, 30)).toBe("00:00:01:00");
+    });
+    it("formats sub-second remainder", () => {
+        expect(framesToTimecode(45, 30)).toBe("00:00:01:15");
+    });
+    it("formats hours/minutes", () => {
+        expect(framesToTimecode(30 * 3725, 30)).toBe("01:02:05:00");
+    });
+    it("rounds fractional fps", () => {
+        expect(framesToTimecode(24, 23.976)).toBe("00:00:01:00");
+    });
+    it("clamps negative frames to zero", () => {
+        // The CMX 3600 spec doesn't allow negative timecode; we clamp instead of
+        // emitting a malformed string.
+        expect(framesToTimecode(-30, 30)).toBe("00:00:00:00");
+    });
+    it("handles 24 hours of footage at 30fps without overflow into 3-digit hours", () => {
+        // 24 hours = 24 * 3600 * 30 = 2,592,000 frames — should land at 24:00:00:00.
+        expect(framesToTimecode(2592000, 30)).toBe("24:00:00:00");
+    });
+    it("emits 3-digit hour fields when needed (no truncation)", () => {
+        // 100 hours — padStart(2) doesn't TRUNCATE, so we get "100:00:00:00".
+        // Out-of-spec for strict CMX 3600 but the most defensive choice.
+        const r = framesToTimecode(100 * 3600 * 30, 30);
+        expect(r).toBe("100:00:00:00");
+    });
+    it("frame field never overflows the integer fps (no '60' frames at 30fps)", () => {
+        // 30 frames at 30fps must roll into 1 second, NOT show ff=30.
+        expect(framesToTimecode(30, 30)).toBe("00:00:01:00");
+        // 59 frames at 30fps = 1 sec + 29 frames
+        expect(framesToTimecode(59, 30)).toBe("00:00:01:29");
+    });
+});
+describe("summarizeList", () => {
+    it("returns head only when under keep", () => {
+        const r = summarizeList([1, 2, 3], 10);
+        expect(r.total).toBe(3);
+        expect(r.omitted).toBe(0);
+        expect(r.head).toEqual([1, 2, 3]);
+        expect(r.tail).toEqual([]);
+    });
+    it("splits head/tail when over keep", () => {
+        const r = summarizeList(Array.from({ length: 100 }, (_, i) => i + 1), 10);
+        expect(r.total).toBe(100);
+        expect(r.omitted).toBe(90);
+        expect(r.head).toEqual([1, 2, 3, 4, 5]);
+        expect(r.tail).toEqual([96, 97, 98, 99, 100]);
+    });
+});
+describe("clip", () => {
+    it("returns input when short", () => {
+        expect(clip("hi", 10)).toBe("hi");
+    });
+    it("ellipsizes when long", () => {
+        expect(clip("0123456789", 5)).toBe("0123…");
+    });
+});
+//# sourceMappingURL=format.test.js.map

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

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

package/dist/core/frames.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Frame extraction helpers. Used by score_shot and (later) any other tool
+ * that needs sampled frames.
+ *
+ * Two modes:
+ *  - extractAtTimes: per-timestamp sampling (one ffmpeg call per frame). Slower
+ *    but precise; agent picks exactly what to inspect.
+ *  - extractAtInterval: regular sampling via the fps filter (one ffmpeg call
+ *    total). Fast; ideal for "score this whole video".
+ */
+export interface ExtractedFrame {
+    path: string;
+    atSec: number;
+}
+export interface ExtractOptions {
+    /** Output dir; defaults to a fresh temp dir. */
+    outDir?: string;
+    /** JPEG quality 1-31 (lower = better, ffmpeg convention). Default 4. */
+    quality?: number;
+    /** Optional max width to scale frames down to (saves vision tokens). */
+    maxWidth?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Extract one frame per requested timestamp. Returns paths in the same order.
+ */
+export declare function extractAtTimes(inputPath: string, times: number[], opts?: ExtractOptions): Promise<ExtractedFrame[]>;
+/**
+ * Extract one frame every `intervalSec`. Returns frames in temporal order.
+ *
+ * Single ffmpeg invocation regardless of how many frames are produced; way
+ * faster than per-timestamp for whole-video sampling.
+ */
+export declare function extractAtInterval(inputPath: string, intervalSec: number, totalSec: number, opts?: ExtractOptions): Promise<ExtractedFrame[]>;
+//# sourceMappingURL=frames.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/core/frames.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,cAAc,EAAE,CAAC,CAmB3B;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,cAAc,EAAE,CAAC,CA6B3B"}

package/dist/core/frames.js

@@ -0,0 +1,64 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runFfmpeg } from "./media/ffmpeg.js";
+/**
+ * Extract one frame per requested timestamp. Returns paths in the same order.
+ */
+export async function extractAtTimes(inputPath, times, opts = {}) {
+    const dir = opts.outDir ?? mkdtempSync(join(tmpdir(), "ezeditor-frames-"));
+    const q = String(opts.quality ?? 4);
+    const out = [];
+    for (let i = 0; i < times.length; i++) {
+        const t = times[i];
+        const path = join(dir, `frame-t${t.toFixed(3)}-${i.toString().padStart(4, "0")}.jpg`);
+        const args = ["-ss", String(t), "-i", inputPath, "-frames:v", "1", "-q:v", q];
+        if (opts.maxWidth)
+            args.push("-vf", `scale=${opts.maxWidth}:-1`);
+        args.push(path);
+        const r = await runFfmpeg(args, { signal: opts.signal });
+        if (r.code !== 0) {
+            throw new Error(`ffmpeg failed extracting frame @${t}s: ${tail(r.stderr)}`);
+        }
+        out.push({ path, atSec: t });
+    }
+    return out;
+}
+/**
+ * Extract one frame every `intervalSec`. Returns frames in temporal order.
+ *
+ * Single ffmpeg invocation regardless of how many frames are produced; way
+ * faster than per-timestamp for whole-video sampling.
+ */
+export async function extractAtInterval(inputPath, intervalSec, totalSec, opts = {}) {
+    if (intervalSec <= 0)
+        throw new Error("intervalSec must be > 0");
+    const dir = opts.outDir ?? mkdtempSync(join(tmpdir(), "ezeditor-frames-"));
+    const q = String(opts.quality ?? 4);
+    const pattern = join(dir, "frame-%04d.jpg");
+    const filter = opts.maxWidth
+        ? `fps=1/${intervalSec},scale=${opts.maxWidth}:-1`
+        : `fps=1/${intervalSec}`;
+    const r = await runFfmpeg(["-i", inputPath, "-vf", filter, "-q:v", q, pattern], {
+        signal: opts.signal,
+    });
+    if (r.code !== 0) {
+        throw new Error(`ffmpeg failed sampling frames: ${tail(r.stderr)}`);
+    }
+    // The fps filter starts the first frame at intervalSec/2 by ffmpeg
+    // convention; agent code shouldn't rely on exact alignment. We compute
+    // expected times as N * intervalSec offset by intervalSec/2.
+    // We can also list the directory, but predicting timestamps avoids fs walk.
+    const count = Math.floor(totalSec / intervalSec);
+    const out = [];
+    for (let i = 1; i <= count; i++) {
+        const path = join(dir, `frame-${i.toString().padStart(4, "0")}.jpg`);
+        const atSec = (i - 0.5) * intervalSec;
+        out.push({ path, atSec });
+    }
+    return out;
+}
+function tail(s) {
+    return s.split("\n").filter(Boolean).slice(-3).join(" | ").slice(-300);
+}
+//# sourceMappingURL=frames.js.map

package/dist/core/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../src/core/frames.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AA4B9C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,SAAiB,EACjB,KAAe,EACf,OAAuB,EAAE;IAEzB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC3E,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;IACpC,MAAM,GAAG,GAAqB,EAAE,CAAC;IAEjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACtF,MAAM,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QAC9E,IAAI,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC;QACjE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEhB,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC9E,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAiB,EACjB,WAAmB,EACnB,QAAgB,EAChB,OAAuB,EAAE;IAEzB,IAAI,WAAW,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACjE,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC3E,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;IAE5C,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ;QAC1B,CAAC,CAAC,SAAS,WAAW,UAAU,IAAI,CAAC,QAAQ,KAAK;QAClD,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC;IAE3B,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAC9E,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IACH,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,mEAAmE;IACnE,uEAAuE;IACvE,6DAA6D;IAC7D,4EAA4E;IAC5E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,WAAW,CAAC,CAAC;IACjD,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACrE,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,WAAW,CAAC;QACtC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,IAAI,CAAC,CAAS;IACrB,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AACzE,CAAC"}

package/dist/core/hook-analysis.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Hook analysis — does the first 3 seconds of a video earn the
+ * scroll-stop?
+ *
+ * Platform algorithms (TikTok / Reels / Shorts / YouTube) treat the
+ * first 2-3 seconds as the algorithmic checkpoint. Videos with strong
+ * 3-second retention get pushed to larger audiences; videos that lose
+ * viewers immediately get buried. This module bundles the four checks
+ * every retention guide preaches:
+ *
+ *   1. Speech in the first 0.5s   — silent openings = scroll death.
+ *   2. On-screen text             — sound-off mobile is the default.
+ *   3. Visual motion              — static openers fail (sample two frames).
+ *   4. Clear subject (face/etc.)  — abstract intro cards underperform.
+ *
+ * #1 is a silencedetect probe (deterministic, free).
+ * #2-#4 are folded into ONE vision call against an early-frame sample.
+ *
+ * Returns a structured score plus a short list of issues the agent can
+ * surface verbatim. The agent's job is to drop a red marker if the
+ * score is below a threshold and propose a stronger opener.
+ */
+export interface HookAnalysisFinding {
+    /** Stable id for this issue. */
+    id: "silent_open" | "no_on_screen_text" | "static_first_frame" | "no_clear_subject" | "weak_emotional_hook";
+    severity: "info" | "warn" | "block";
+    /** One-line human description. */
+    message: string;
+}
+export interface HookAnalysisResult {
+    /** 0-100. ≥70 = solid hook, 40-69 = weak, <40 = will tank retention. */
+    score: number;
+    /** True if score >= passThreshold (default 70). */
+    passes: boolean;
+    /** Sub-scores (0-1). */
+    speechAt0_5s: number;
+    onScreenText: number;
+    motion: number;
+    subjectClarity: number;
+    emotionalIntensity: number;
+    findings: HookAnalysisFinding[];
+    /** ≤120 char overall verdict from the vision pass. */
+    why: string;
+}
+/**
+ * Compute the speech-at-0.5s score from a list of silence ranges
+ * within the first `windowSec` seconds.
+ *
+ * 1.0  = speech is active throughout the first 500ms.
+ * 0.0  = totally silent for the entire first 500ms.
+ * Linear in between. Used both by the live tool and the unit tests.
+ */
+export declare function speechAt0_5sScore(silences: Array<{
+    startSec: number;
+    endSec: number;
+}>, windowSec?: number): number;
+export interface HookVisionResponse {
+    onScreenText: number;
+    motion: number;
+    subjectClarity: number;
+    emotionalIntensity: number;
+    why: string;
+}
+export declare function parseHookVisionResponse(content: string): HookVisionResponse;
+export interface HookVisionOptions {
+    apiKey?: string;
+    model?: string;
+    detail?: "low" | "high";
+    signal?: AbortSignal;
+}
+export declare function runHookVision(earlyFramePath: string, laterFramePath: string, opts?: HookVisionOptions): Promise<HookVisionResponse>;
+export interface ScoreOptions {
+    /** Pass threshold (default 70). */
+    passThreshold?: number;
+    /** Component weights (sum doesn't have to equal 1). */
+    weights?: {
+        speech?: number;
+        onScreenText?: number;
+        motion?: number;
+        subjectClarity?: number;
+        emotionalIntensity?: number;
+    };
+}
+/**
+ * Combine the deterministic speech score and the vision response into
+ * an overall HookAnalysisResult. Pure function — easy to unit-test the
+ * scoring rubric without booting ffmpeg or OpenAI.
+ */
+export declare function buildHookResult(speech: number, vision: HookVisionResponse, opts?: ScoreOptions): HookAnalysisResult;
+//# sourceMappingURL=hook-analysis.d.ts.map

package/dist/core/hook-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-analysis.d.ts","sourceRoot":"","sources":["../../src/core/hook-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,EAAE,EACE,aAAa,GACb,mBAAmB,GACnB,oBAAoB,GACpB,kBAAkB,GAClB,qBAAqB,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACpC,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAC;IAChB,wBAAwB;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;CACb;AAID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EACrD,SAAS,SAAM,GACd,MAAM,CAUR;AAqCD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAc3E;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAsB,aAAa,CACjC,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAkD7B;AAID,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAUD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,kBAAkB,EAC1B,IAAI,GAAE,YAAiB,GACtB,kBAAkB,CAiEpB"}

package/dist/core/hook-analysis.js

@@ -0,0 +1,223 @@
+/**
+ * Hook analysis — does the first 3 seconds of a video earn the
+ * scroll-stop?
+ *
+ * Platform algorithms (TikTok / Reels / Shorts / YouTube) treat the
+ * first 2-3 seconds as the algorithmic checkpoint. Videos with strong
+ * 3-second retention get pushed to larger audiences; videos that lose
+ * viewers immediately get buried. This module bundles the four checks
+ * every retention guide preaches:
+ *
+ *   1. Speech in the first 0.5s   — silent openings = scroll death.
+ *   2. On-screen text             — sound-off mobile is the default.
+ *   3. Visual motion              — static openers fail (sample two frames).
+ *   4. Clear subject (face/etc.)  — abstract intro cards underperform.
+ *
+ * #1 is a silencedetect probe (deterministic, free).
+ * #2-#4 are folded into ONE vision call against an early-frame sample.
+ *
+ * Returns a structured score plus a short list of issues the agent can
+ * surface verbatim. The agent's job is to drop a red marker if the
+ * score is below a threshold and propose a stronger opener.
+ */
+import { readFileSync } from "node:fs";
+import { resolveApiKey } from "./auth/api-keys.js";
+// ── Silence-side helpers ────────────────────────────────────
+/**
+ * Compute the speech-at-0.5s score from a list of silence ranges
+ * within the first `windowSec` seconds.
+ *
+ * 1.0  = speech is active throughout the first 500ms.
+ * 0.0  = totally silent for the entire first 500ms.
+ * Linear in between. Used both by the live tool and the unit tests.
+ */
+export function speechAt0_5sScore(silences, windowSec = 0.5) {
+    if (windowSec <= 0)
+        return 1;
+    let silentSec = 0;
+    for (const s of silences) {
+        const lo = Math.max(0, s.startSec);
+        const hi = Math.min(windowSec, s.endSec);
+        if (hi > lo)
+            silentSec += hi - lo;
+    }
+    const speechSec = Math.max(0, windowSec - silentSec);
+    return +(speechSec / windowSec).toFixed(3);
+}
+// ── Vision-side: prompt + parser ────────────────────────────
+const VISION_SYSTEM = `You are a short-form video retention analyst. You see ONE frame from the FIRST SECOND of a video and ONE frame from the THIRD SECOND. Your job is to score the OPENING for scroll-stop power on TikTok / Reels / YouTube Shorts.
+
+Output a JSON object with these EXACT keys (no extras, no prose):
+{
+  "onScreenText":       <0..1>,
+  "motion":             <0..1>,
+  "subjectClarity":     <0..1>,
+  "emotionalIntensity": <0..1>,
+  "why": "<≤120 char rationale>"
+}
+
+Scoring rubric:
+
+onScreenText  — Is there bold, readable on-screen text in either frame?
+  1.0 = large hook text (e.g. "DON'T DO THIS"); 0.5 = small caption only;
+  0.0 = no text at all.
+
+motion        — Did the framing change between frame 1 and frame 2?
+  1.0 = camera move / cut to a new angle / clear visual change;
+  0.5 = subject moved within the frame; 0.0 = static lockoff.
+
+subjectClarity — Is there an obvious focal point (face, product, action)?
+  1.0 = clear single subject filling significant frame area;
+  0.5 = subject present but small or off-centre; 0.0 = abstract / cluttered.
+
+emotionalIntensity — Does anyone in frame display a strong emotion or
+  is something visually surprising happening?
+  1.0 = laughing / shouting / pointing / fail moment / dramatic action;
+  0.5 = neutral but engaged; 0.0 = blank / corporate / boring.
+
+Be honest — this rubric exists so the creator knows when to recut their
+opener. A bland but technically competent intro should score 0.3, not 0.7.`;
+export function parseHookVisionResponse(content) {
+    const start = content.indexOf("{");
+    const end = content.lastIndexOf("}");
+    if (start < 0 || end < start) {
+        throw new Error("hook-analysis: no JSON object in response");
+    }
+    const parsed = JSON.parse(content.slice(start, end + 1));
+    return {
+        onScreenText: clamp01(num(parsed.onScreenText, 0)),
+        motion: clamp01(num(parsed.motion, 0)),
+        subjectClarity: clamp01(num(parsed.subjectClarity, 0)),
+        emotionalIntensity: clamp01(num(parsed.emotionalIntensity, 0)),
+        why: String(parsed.why ?? "").slice(0, 200),
+    };
+}
+export async function runHookVision(earlyFramePath, laterFramePath, opts = {}) {
+    const apiKey = opts.apiKey ?? resolveApiKey("OPENAI_API_KEY", "openai");
+    if (!apiKey)
+        throw new Error("OPENAI_API_KEY required for analyze_hook.");
+    const earlyB64 = readFileSync(earlyFramePath).toString("base64");
+    const laterB64 = readFileSync(laterFramePath).toString("base64");
+    const detail = opts.detail ?? "low";
+    const model = opts.model ?? "gpt-4o-mini";
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: VISION_SYSTEM },
+            {
+                role: "user",
+                content: [
+                    { type: "text", text: "FRAME 1 (~0.5s into video):" },
+                    {
+                        type: "image_url",
+                        image_url: { url: `data:image/jpeg;base64,${earlyB64}`, detail },
+                    },
+                    { type: "text", text: "FRAME 2 (~2.5s into video):" },
+                    {
+                        type: "image_url",
+                        image_url: { url: `data:image/jpeg;base64,${laterB64}`, detail },
+                    },
+                ],
+            },
+        ],
+        response_format: { type: "json_object" },
+        temperature: 0,
+    };
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`OpenAI HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    const data = (await res.json());
+    const content = data.choices[0]?.message?.content;
+    if (!content)
+        throw new Error("analyze_hook: empty model response");
+    return parseHookVisionResponse(content);
+}
+const DEFAULT_WEIGHTS = {
+    speech: 25,
+    onScreenText: 25,
+    motion: 15,
+    subjectClarity: 20,
+    emotionalIntensity: 15,
+};
+/**
+ * Combine the deterministic speech score and the vision response into
+ * an overall HookAnalysisResult. Pure function — easy to unit-test the
+ * scoring rubric without booting ffmpeg or OpenAI.
+ */
+export function buildHookResult(speech, vision, opts = {}) {
+    const w = { ...DEFAULT_WEIGHTS, ...(opts.weights ?? {}) };
+    const wSum = w.speech + w.onScreenText + w.motion + w.subjectClarity + w.emotionalIntensity;
+    const raw = w.speech * speech +
+        w.onScreenText * vision.onScreenText +
+        w.motion * vision.motion +
+        w.subjectClarity * vision.subjectClarity +
+        w.emotionalIntensity * vision.emotionalIntensity;
+    const score = Math.round((raw / wSum) * 100);
+    const findings = [];
+    if (speech < 0.5) {
+        findings.push({
+            id: "silent_open",
+            severity: speech < 0.2 ? "block" : "warn",
+            message: "Silent (or near-silent) opening detected. Move the punchline / strongest line to frame 1; cold-open instead of leading with breath/pause.",
+        });
+    }
+    if (vision.onScreenText < 0.4) {
+        findings.push({
+            id: "no_on_screen_text",
+            severity: "warn",
+            message: "No bold on-screen hook text. ~60% of mobile views are sound-off — burn the hook line large in the first 2 seconds.",
+        });
+    }
+    if (vision.motion < 0.3) {
+        findings.push({
+            id: "static_first_frame",
+            severity: "warn",
+            message: "First frames look static. Add a quick zoom, cut to a different angle, or open mid-action to give the eye something to lock onto.",
+        });
+    }
+    if (vision.subjectClarity < 0.4) {
+        findings.push({
+            id: "no_clear_subject",
+            severity: "warn",
+            message: "No clear focal subject. Re-frame so the face / product / action fills the frame in the first second.",
+        });
+    }
+    if (vision.emotionalIntensity < 0.3) {
+        findings.push({
+            id: "weak_emotional_hook",
+            severity: "info",
+            message: "Low emotional intensity in the opener. Consider starting with a reaction / surprise / dramatic line — neutral intros lose retention.",
+        });
+    }
+    const passThreshold = opts.passThreshold ?? 70;
+    return {
+        score,
+        passes: score >= passThreshold,
+        speechAt0_5s: speech,
+        onScreenText: vision.onScreenText,
+        motion: vision.motion,
+        subjectClarity: vision.subjectClarity,
+        emotionalIntensity: vision.emotionalIntensity,
+        findings,
+        why: vision.why,
+    };
+}
+// ── Helpers ─────────────────────────────────────────────────
+function num(v, fb) {
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) ? n : fb;
+}
+function clamp01(n) {
+    return Math.max(0, Math.min(1, n));
+}
+//# sourceMappingURL=hook-analysis.js.map

package/dist/core/hook-analysis.js.map

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

package/dist/core/hook-analysis.test.d.ts

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

package/dist/core/hook-analysis.test.d.ts.map

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