@kenkaiiii/gg-editor 0.7.0 → 0.7.1

package/dist/core/logger.js

@@ -0,0 +1,188 @@
+/**
+ * gg-editor debug logger — optimized for LLM consumption.
+ *
+ * Writes to `~/.gg/ggeditor.log`. Append mode across sessions, rotated at
+ * MAX_BYTES, one generation kept (`ggeditor.log.1`).
+ *
+ * Format choices (every byte fed to an LLM matters):
+ *   - Per-session HEADER carries the rarely-changing fields (date, sid,
+ *     version, provider, model, pid, platform). Lines below reference them
+ *     implicitly so we don't repeat ~80 bytes on every line.
+ *   - Each line: `HH:MM:SS.mmm L cat msg k=v k=v`
+ *       L  — single-letter level (I/W/E). Saves 3-4 bytes/line vs. INFO/WARN/ERROR.
+ *       cat — short stable category (tool, bridge, bridge.call, host, …).
+ *       msg — short imperative phrase, no decorative arrows.
+ *   - Field values JSON-encoded only when they need quoting; bare otherwise.
+ *   - Args/results truncated at MAX_FIELD_CHARS with `…(+N)` overflow marker
+ *     so the LLM sees the prefix + how much was elided.
+ *
+ * Categories:
+ *   startup       CLI launch line + capability probe result
+ *   bridge        Resolve Python bridge spawn/handshake/exit
+ *   bridge.call   Per-method round trips (one line per call: name + dur + ok/err)
+ *   tool          Agent tool calls (one line per call: name + dur + args + result)
+ *   host          Lazy host detection transitions
+ *   shutdown      Clean exit
+ *   fatal         Unhandled errors
+ *
+ * Filter a single run: `grep " sid=<id>" ~/.gg/ggeditor.log` once you've
+ * read the header. Multi-run greps key off the category column.
+ */
+import fs from "node:fs";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+const MAX_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_FIELD_CHARS = 200; // Per k=v value cap. Args/results truncated above this.
+let fd = null;
+let sessionId = "";
+/** Default path: `~/.gg/ggeditor.log`. */
+export function defaultLogPath() {
+    return join(homedir(), ".gg", "ggeditor.log");
+}
+function rotateIfNeeded(filePath) {
+    try {
+        const st = fs.statSync(filePath);
+        if (st.size < MAX_BYTES)
+            return;
+        const rotated = `${filePath}.1`;
+        try {
+            fs.unlinkSync(rotated);
+        }
+        catch {
+            // No prior rotation
+        }
+        fs.renameSync(filePath, rotated);
+    }
+    catch {
+        // Log file doesn't exist yet
+    }
+}
+/** Pad to 2/3 chars with leading zeros for stable column widths. */
+function pad(n, w) {
+    return String(n).padStart(w, "0");
+}
+function timestamp() {
+    const d = new Date();
+    return `${pad(d.getHours(), 2)}:${pad(d.getMinutes(), 2)}:${pad(d.getSeconds(), 2)}.${pad(d.getMilliseconds(), 3)}`;
+}
+/**
+ * Initialize logger. Idempotent. Writes a session HEADER line with the
+ * fields that don't change across the run, so per-line overhead stays low.
+ */
+export function initLogger(filePath = defaultLogPath(), meta) {
+    if (fd !== null)
+        return;
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+    }
+    catch {
+        // openSync below will surface real failures
+    }
+    rotateIfNeeded(filePath);
+    try {
+        fd = fs.openSync(filePath, "a");
+    }
+    catch {
+        return;
+    }
+    sessionId = randomBytes(4).toString("hex");
+    // Session header — all per-run constants in one line. Bash/awk friendly,
+    // human-readable, LLM-parseable. Subsequent lines don't repeat any of this.
+    const headerParts = [
+        `=== ${new Date().toISOString()}`,
+        `sid=${sessionId}`,
+        `ggeditor=${meta?.version ?? "?"}`,
+    ];
+    if (meta?.provider)
+        headerParts.push(`provider=${meta.provider}`);
+    if (meta?.model)
+        headerParts.push(`model=${meta.model}`);
+    if (meta?.host)
+        headerParts.push(`host=${meta.host}`);
+    headerParts.push(`pid=${process.pid}`, `platform=${process.platform}`, "===");
+    try {
+        fs.writeSync(fd, "\n" + headerParts.join(" ") + "\n");
+    }
+    catch {
+        // Header write failed — proceed; subsequent lines may still land
+    }
+}
+/** Session ID — useful for filtering one run out of an interleaved log. */
+export function getSessionId() {
+    return sessionId;
+}
+/** Hot-path skip flag for callers that want to avoid building log payloads. */
+export function isLoggerActive() {
+    return fd !== null;
+}
+/**
+ * Write a log line. Format: `HH:MM:SS.mmm L cat msg k=v k=v`.
+ *
+ * Values that contain spaces or `=` are JSON-quoted; bare otherwise. Long
+ * fields are truncated at MAX_FIELD_CHARS with `…(+N)` so the LLM sees the
+ * prefix plus a count of elided chars (rather than a silent cliff).
+ */
+export function log(level, category, message, data) {
+    if (fd === null)
+        return;
+    let line = `${timestamp()} ${level} ${category} ${message}`;
+    if (data) {
+        for (const [k, v] of Object.entries(data)) {
+            if (v === undefined || v === null)
+                continue;
+            line += ` ${k}=${formatValue(v)}`;
+        }
+    }
+    line += "\n";
+    try {
+        fs.writeSync(fd, line);
+    }
+    catch {
+        // Don't crash the CLI on a write failure
+    }
+}
+function formatValue(v) {
+    let s;
+    if (typeof v === "string") {
+        s = v;
+    }
+    else if (typeof v === "number" || typeof v === "boolean") {
+        return String(v); // numerics/booleans never need quoting and never overflow
+    }
+    else {
+        try {
+            s = JSON.stringify(v);
+        }
+        catch {
+            s = String(v);
+        }
+    }
+    if (s.length > MAX_FIELD_CHARS) {
+        s = s.slice(0, MAX_FIELD_CHARS) + `…(+${s.length - MAX_FIELD_CHARS})`;
+    }
+    // Quote when the value has whitespace, `=`, or quotes — so grep/awk on
+    // ` k=` boundaries works reliably. Bare otherwise (saves 2 bytes).
+    if (/[\s="]/.test(s)) {
+        return JSON.stringify(s);
+    }
+    return s;
+}
+export const logInfo = (cat, msg, data) => log("I", cat, msg, data);
+export const logWarn = (cat, msg, data) => log("W", cat, msg, data);
+export const logError = (cat, msg, data) => log("E", cat, msg, data);
+/** Close the log fd. Safe to call multiple times. */
+export function closeLogger() {
+    if (fd === null)
+        return;
+    log("I", "shutdown", "exit");
+    try {
+        fs.closeSync(fd);
+    }
+    catch {
+        // Ignore
+    }
+    fd = null;
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

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

package/dist/core/loop-match.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Loop-match filter builder for Shorts.
+ *
+ * YouTube Shorts auto-replays from the start when the clip ends. A
+ * crossfade between the last N ms and the first N ms makes the
+ * re-loop feel seamless. Loop rate is a confirmed Shorts ranking
+ * signal — see the `youtube-algorithm-primer` skill.
+ *
+ * This module produces the `-filter_complex` string and the matching
+ * `-map` directives. The wrapper tool then runs ffmpeg with libx264 +
+ * aac at standard delivery settings.
+ *
+ * Two modes:
+ *   - "crossfade" (default): xfade fade between the tail and a copy of
+ *     the head. Audio: acrossfade.
+ *   - "jumpcut": no crossfade — simply hard-cut the last cf seconds off
+ *     so the loop boundary lands right before the head's first frame.
+ *     Cheaper; safe for very short clips where any crossfade would eat
+ *     too much of the visible content.
+ */
+export type LoopMatchMethod = "crossfade" | "jumpcut";
+export interface LoopMatchPlan {
+    /** Effective crossfade duration after clamping. */
+    crossfadeSec: number;
+    /** Final output duration after the filter applies. */
+    outDurationSec: number;
+    method: LoopMatchMethod;
+    /** ffmpeg -filter_complex value. */
+    filter: string;
+    /** -map directives in order. */
+    maps: string[];
+}
+/**
+ * Build the filter graph for a loop-match pass.
+ *
+ * crossfade mode plan:
+ *   [0:v] split=2 [main][tail_src];
+ *   [main]   trim=0:T-cf, setpts=PTS-STARTPTS [vmain];
+ *   [tail_src] trim=T-cf:T,  setpts=PTS-STARTPTS [tail];
+ *   [0:v] trim=0:cf, setpts=PTS-STARTPTS [head];
+ *   [tail][head] xfade=transition=fade:duration=cf:offset=0 [xfade];
+ *   [vmain][xfade] concat=n=2:v=1:a=0 [vout]
+ *   ── audio ──
+ *   [0:a] asplit=2 [amain][atail_src];
+ *   [amain]    atrim=0:T-cf, asetpts=PTS-STARTPTS [aout1];
+ *   [atail_src] atrim=T-cf:T, asetpts=PTS-STARTPTS [atail];
+ *   [0:a]      atrim=0:cf,    asetpts=PTS-STARTPTS [ahead];
+ *   [atail][ahead] acrossfade=d=cf [axfade];
+ *   [aout1][axfade] concat=n=2:v=0:a=1 [aout]
+ *
+ * Final length = (T - cf) + cf = T. Duration unchanged; only the last
+ * cf seconds become a crossfade into the head.
+ *
+ * Pure — easy to unit-test the filter string. Throws on invalid input.
+ */
+export declare function buildLoopMatchFilter(durationSec: number, crossfadeSec: number, method?: LoopMatchMethod): LoopMatchPlan;
+//# sourceMappingURL=loop-match.d.ts.map

package/dist/core/loop-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-match.d.ts","sourceRoot":"","sources":["../../src/core/loop-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,eAAe,CAAC;IACxB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,eAA6B,GACpC,aAAa,CAqDf"}

package/dist/core/loop-match.js

@@ -0,0 +1,91 @@
+/**
+ * Loop-match filter builder for Shorts.
+ *
+ * YouTube Shorts auto-replays from the start when the clip ends. A
+ * crossfade between the last N ms and the first N ms makes the
+ * re-loop feel seamless. Loop rate is a confirmed Shorts ranking
+ * signal — see the `youtube-algorithm-primer` skill.
+ *
+ * This module produces the `-filter_complex` string and the matching
+ * `-map` directives. The wrapper tool then runs ffmpeg with libx264 +
+ * aac at standard delivery settings.
+ *
+ * Two modes:
+ *   - "crossfade" (default): xfade fade between the tail and a copy of
+ *     the head. Audio: acrossfade.
+ *   - "jumpcut": no crossfade — simply hard-cut the last cf seconds off
+ *     so the loop boundary lands right before the head's first frame.
+ *     Cheaper; safe for very short clips where any crossfade would eat
+ *     too much of the visible content.
+ */
+/**
+ * Build the filter graph for a loop-match pass.
+ *
+ * crossfade mode plan:
+ *   [0:v] split=2 [main][tail_src];
+ *   [main]   trim=0:T-cf, setpts=PTS-STARTPTS [vmain];
+ *   [tail_src] trim=T-cf:T,  setpts=PTS-STARTPTS [tail];
+ *   [0:v] trim=0:cf, setpts=PTS-STARTPTS [head];
+ *   [tail][head] xfade=transition=fade:duration=cf:offset=0 [xfade];
+ *   [vmain][xfade] concat=n=2:v=1:a=0 [vout]
+ *   ── audio ──
+ *   [0:a] asplit=2 [amain][atail_src];
+ *   [amain]    atrim=0:T-cf, asetpts=PTS-STARTPTS [aout1];
+ *   [atail_src] atrim=T-cf:T, asetpts=PTS-STARTPTS [atail];
+ *   [0:a]      atrim=0:cf,    asetpts=PTS-STARTPTS [ahead];
+ *   [atail][ahead] acrossfade=d=cf [axfade];
+ *   [aout1][axfade] concat=n=2:v=0:a=1 [aout]
+ *
+ * Final length = (T - cf) + cf = T. Duration unchanged; only the last
+ * cf seconds become a crossfade into the head.
+ *
+ * Pure — easy to unit-test the filter string. Throws on invalid input.
+ */
+export function buildLoopMatchFilter(durationSec, crossfadeSec, method = "crossfade") {
+    if (!Number.isFinite(durationSec) || durationSec <= 0) {
+        throw new Error("durationSec must be > 0");
+    }
+    if (!Number.isFinite(crossfadeSec) || crossfadeSec <= 0) {
+        throw new Error("crossfadeSec must be > 0");
+    }
+    // Crossfade can't be ≥ half the clip — there'd be no "main" body left.
+    const maxCf = durationSec / 2;
+    const cf = Math.min(crossfadeSec, +(maxCf - 0.05).toFixed(3));
+    if (cf <= 0) {
+        throw new Error(`clip too short (${durationSec.toFixed(2)}s) for any crossfade; pass crossfadeSec ≤ ${maxCf.toFixed(2)}`);
+    }
+    const T = +durationSec.toFixed(3);
+    const tailStart = +(T - cf).toFixed(3);
+    if (method === "jumpcut") {
+        // Just trim the last cf seconds. No xfade. Output is shorter.
+        const filter = `[0:v]trim=0:${tailStart},setpts=PTS-STARTPTS[vout];` +
+            `[0:a]atrim=0:${tailStart},asetpts=PTS-STARTPTS[aout]`;
+        return {
+            crossfadeSec: cf,
+            outDurationSec: tailStart,
+            method,
+            filter,
+            maps: ["[vout]", "[aout]"],
+        };
+    }
+    const filter = `[0:v]split=2[main][tail_src];` +
+        `[main]trim=0:${tailStart},setpts=PTS-STARTPTS[vmain];` +
+        `[tail_src]trim=${tailStart}:${T},setpts=PTS-STARTPTS[tail];` +
+        `[0:v]trim=0:${cf},setpts=PTS-STARTPTS[head];` +
+        `[tail][head]xfade=transition=fade:duration=${cf}:offset=0[xf];` +
+        `[vmain][xf]concat=n=2:v=1:a=0[vout];` +
+        `[0:a]asplit=2[amain][atail_src];` +
+        `[amain]atrim=0:${tailStart},asetpts=PTS-STARTPTS[aout1];` +
+        `[atail_src]atrim=${tailStart}:${T},asetpts=PTS-STARTPTS[atail];` +
+        `[0:a]atrim=0:${cf},asetpts=PTS-STARTPTS[ahead];` +
+        `[atail][ahead]acrossfade=d=${cf}[axf];` +
+        `[aout1][axf]concat=n=2:v=0:a=1[aout]`;
+    return {
+        crossfadeSec: cf,
+        outDurationSec: T,
+        method,
+        filter,
+        maps: ["[vout]", "[aout]"],
+    };
+}
+//# sourceMappingURL=loop-match.js.map

package/dist/core/loop-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-match.js","sourceRoot":"","sources":["../../src/core/loop-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgBH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,oBAAoB,CAClC,WAAmB,EACnB,YAAoB,EACpB,SAA0B,WAAW;IAErC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IACD,uEAAuE;IACvE,MAAM,KAAK,GAAG,WAAW,GAAG,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,mBAAmB,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,6CAA6C,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CACzG,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAEvC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,8DAA8D;QAC9D,MAAM,MAAM,GACV,eAAe,SAAS,6BAA6B;YACrD,gBAAgB,SAAS,6BAA6B,CAAC;QACzD,OAAO;YACL,YAAY,EAAE,EAAE;YAChB,cAAc,EAAE,SAAS;YACzB,MAAM;YACN,MAAM;YACN,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC;SAC3B,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GACV,+BAA+B;QAC/B,gBAAgB,SAAS,8BAA8B;QACvD,kBAAkB,SAAS,IAAI,CAAC,6BAA6B;QAC7D,eAAe,EAAE,6BAA6B;QAC9C,8CAA8C,EAAE,gBAAgB;QAChE,sCAAsC;QACtC,kCAAkC;QAClC,kBAAkB,SAAS,+BAA+B;QAC1D,oBAAoB,SAAS,IAAI,CAAC,+BAA+B;QACjE,gBAAgB,EAAE,+BAA+B;QACjD,8BAA8B,EAAE,QAAQ;QACxC,sCAAsC,CAAC;IAEzC,OAAO;QACL,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,CAAC;QACjB,MAAM;QACN,MAAM;QACN,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC;KAC3B,CAAC;AACJ,CAAC"}

package/dist/core/media/ffmpeg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ffmpeg.d.ts","sourceRoot":"","sources":["../../../src/core/media/ffmpeg.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,WAAW,IAAI,OAAO,CAGrC;AAED,wBAAgB,YAAY,IAAI,OAAO,CAGtC;AAED,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAClC,OAAO,CAAC,YAAY,CAAC,CAavB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA4C9D"}
+{"version":3,"file":"ffmpeg.d.ts","sourceRoot":"","sources":["../../../src/core/media/ffmpeg.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,WAAW,IAAI,OAAO,CAGrC;AAED,wBAAgB,YAAY,IAAI,OAAO,CAGtC;AAED,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAClC,OAAO,CAAC,YAAY,CAAC,CAuBvB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA4C9D"}

package/dist/core/media/ffmpeg.js

@@ -1,4 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
+import { wireChildAbort } from "../child-abort.js";
 export function checkFfmpeg() {
     const r = spawnSync("ffmpeg", ["-version"], { encoding: "utf8" });
     return r.status === 0;
@@ -16,9 +17,19 @@ export function runFfmpeg(args, opts = {}) {
         let stderr = "";
         child.stdout.on("data", (d) => (stdout += d.toString()));
         child.stderr.on("data", (d) => (stderr += d.toString()));
-        opts.signal?.addEventListener("abort", () => child.kill("SIGTERM"));
-        child.on("error", reject);
-        child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+        // Robust abort: SIGTERM → SIGKILL after 1.5s. ffmpeg respects SIGTERM
+        // quickly on its read loop; the SIGKILL backstop covers wedge cases.
+        // We resolve with a non-zero code on abort instead of rejecting because
+        // ffmpeg callers check `r.code !== 0` and surface a tailored error.
+        const cleanup = wireChildAbort(opts.signal, child);
+        child.on("error", (e) => {
+            cleanup();
+            reject(e);
+        });
+        child.on("close", (code) => {
+            cleanup();
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
     });
 }
 export function probeMedia(filePath) {

package/dist/core/media/ffmpeg.js.map

@@ -1 +1 @@
-{"version":3,"file":"ffmpeg.js","sourceRoot":"","sources":["../../../src/core/media/ffmpeg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AActD,MAAM,UAAU,WAAW;IACzB,MAAM,CAAC,GAAG,SAAS,CAAC,QAAQ,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAClE,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,CAAC,GAAG,SAAS,CAAC,SAAS,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACnE,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,IAAc,EACd,OAAiC,EAAE;IAEnC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,cAAc,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE;YAC7D,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;QACH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QACzD,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QACpE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACL,CAAC;AAaD,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,MAAM,CAAC,GAAG,SAAS,CACjB,SAAS,EACT,CAAC,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,QAAQ,CAAC,EACnF,EAAE,QAAQ,EAAE,MAAM,EAAE,CACrB,CAAC;IACF,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEhC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAW/B,CAAC;QAEF,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,OAAO,CAAC,CAAC;QAE9D,IAAI,SAA6B,CAAC;QAClC,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC;YACpB,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACzD,IAAI,GAAG,IAAI,GAAG;gBAAE,SAAS,GAAG,GAAG,GAAG,GAAG,CAAC;QACxC,CAAC;QAED,OAAO;YACL,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,IAAI,GAAG,CAAC;YACrD,KAAK,EAAE,CAAC,EAAE,KAAK;YACf,MAAM,EAAE,CAAC,EAAE,MAAM;YACjB,SAAS;YACT,UAAU,EAAE,CAAC,EAAE,UAAU;YACzB,UAAU,EAAE,CAAC,EAAE,UAAU;YACzB,aAAa,EAAE,CAAC,EAAE,QAAQ;YAC1B,eAAe,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;SAC1E,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"ffmpeg.js","sourceRoot":"","sources":["../../../src/core/media/ffmpeg.ts"],"names":[],"mappings":"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"}

package/dist/core/multi-format.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Multi-format render presets — the "render every platform at once" matrix.
+ *
+ * Pure dispatcher for `render_multi_format`: given a source resolution and a
+ * preset name, produces the ffmpeg `-vf` filter graph plus the target W×H.
+ * Spawning ffmpeg lives in the tool layer so this module stays trivially
+ * unit-testable.
+ *
+ * Two transform modes:
+ *
+ *   - "scale-pad"   — letterbox/pillarbox the source into the target frame
+ *                     without cropping. Used for 16:9-into-16:9 (different
+ *                     resolution) and any time we want to preserve every
+ *                     pixel of the source.
+ *
+ *   - "centre-crop" — crop the source to the target aspect, then scale to
+ *                     target resolution. The dumb / mechanical version of
+ *                     content-aware reframing — for face-tracked re-cropping
+ *                     the agent should pipe the source through `face_reframe`
+ *                     or Resolve `smart_reframe` BEFORE calling this tool.
+ */
+export type MultiFormat = "youtube-1080p" | "shorts-9x16" | "reels-9x16" | "tiktok-9x16" | "square-1x1" | "instagram-4x5" | "twitter-16x9";
+export declare const MULTI_FORMATS: readonly MultiFormat[];
+export type MultiFormatTransform = "scale-pad" | "centre-crop";
+interface PresetSpec {
+    width: number;
+    height: number;
+    transform: MultiFormatTransform;
+}
+export declare function multiFormatSpec(format: MultiFormat): PresetSpec;
+export interface BuildRenderFilterResult {
+    targetW: number;
+    targetH: number;
+    vf: string;
+    transform: MultiFormatTransform;
+}
+export interface BuildRenderFilterOptions {
+    /**
+     * If true, treat the source as already cropped to the target aspect (e.g.
+     * via face_reframe / smart_reframe upstream). Forces a non-cropping
+     * scale-pad regardless of the preset's default transform.
+     */
+    faceTracked?: boolean;
+}
+/**
+ * Build the ffmpeg `-vf` filter for a single (source, preset) pair.
+ *
+ * Pure function — no side effects, no I/O. Used by `render_multi_format`
+ * to compose ffmpeg args, and by the unit tests to lock the filter math.
+ *
+ * Math notes for centre-crop:
+ *
+ *   srcAR = srcW/srcH, tgtAR = Wt/Ht. The crop keeps the larger axis full.
+ *
+ *   - srcAR > tgtAR  ⇒  source is wider than target. Crop width.
+ *       cropW = ih * Wt/Ht ; cropH = ih ; x = (iw - cropW)/2 ; y = 0
+ *   - srcAR < tgtAR  ⇒  source is taller than target. Crop height.
+ *       cropW = iw ; cropH = iw * Ht/Wt ; x = 0 ; y = (ih - cropH)/2
+ *   - srcAR == tgtAR ⇒  no crop needed; emit `scale=Wt:Ht` only.
+ *
+ * Float crop dimensions are passed through to ffmpeg (which accepts them
+ * and rounds internally); the trailing `scale=Wt:Ht` enforces the final
+ * even-dimension target so x264 stays happy.
+ */
+export declare function buildRenderFilter(srcW: number, srcH: number, format: MultiFormat, opts?: BuildRenderFilterOptions): BuildRenderFilterResult;
+export {};
+//# sourceMappingURL=multi-format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"multi-format.d.ts","sourceRoot":"","sources":["../../src/core/multi-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,aAAa,GACb,YAAY,GACZ,aAAa,GACb,YAAY,GACZ,eAAe,GACf,cAAc,CAAC;AAEnB,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAQtC,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,aAAa,CAAC;AAE/D,UAAU,UAAU;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,oBAAoB,CAAC;CACjC;AAmBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,CAQ/D;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,oBAAoB,CAAC;CACjC;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,wBAA6B,GAClC,uBAAuB,CA0CzB"}

package/dist/core/multi-format.js

@@ -0,0 +1,127 @@
+/**
+ * Multi-format render presets — the "render every platform at once" matrix.
+ *
+ * Pure dispatcher for `render_multi_format`: given a source resolution and a
+ * preset name, produces the ffmpeg `-vf` filter graph plus the target W×H.
+ * Spawning ffmpeg lives in the tool layer so this module stays trivially
+ * unit-testable.
+ *
+ * Two transform modes:
+ *
+ *   - "scale-pad"   — letterbox/pillarbox the source into the target frame
+ *                     without cropping. Used for 16:9-into-16:9 (different
+ *                     resolution) and any time we want to preserve every
+ *                     pixel of the source.
+ *
+ *   - "centre-crop" — crop the source to the target aspect, then scale to
+ *                     target resolution. The dumb / mechanical version of
+ *                     content-aware reframing — for face-tracked re-cropping
+ *                     the agent should pipe the source through `face_reframe`
+ *                     or Resolve `smart_reframe` BEFORE calling this tool.
+ */
+export const MULTI_FORMATS = [
+    "youtube-1080p",
+    "shorts-9x16",
+    "reels-9x16",
+    "tiktok-9x16",
+    "square-1x1",
+    "instagram-4x5",
+    "twitter-16x9",
+];
+/**
+ * Per-preset target resolution + default transform.
+ *
+ * Resolutions are platform-canonical: 1080p horizontal, 1080×1920 vertical,
+ * 1080-square IG, 1080×1350 IG-portrait, 720p Twitter (their feed downsamples
+ * anything taller anyway).
+ */
+const PRESETS = {
+    "youtube-1080p": { width: 1920, height: 1080, transform: "scale-pad" },
+    "shorts-9x16": { width: 1080, height: 1920, transform: "centre-crop" },
+    "reels-9x16": { width: 1080, height: 1920, transform: "centre-crop" },
+    "tiktok-9x16": { width: 1080, height: 1920, transform: "centre-crop" },
+    "square-1x1": { width: 1080, height: 1080, transform: "centre-crop" },
+    "instagram-4x5": { width: 1080, height: 1350, transform: "centre-crop" },
+    "twitter-16x9": { width: 1280, height: 720, transform: "scale-pad" },
+};
+export function multiFormatSpec(format) {
+    const spec = PRESETS[format];
+    if (!spec) {
+        throw new Error(`unknown multi-format preset: ${format}; valid: ${Object.keys(PRESETS).join(", ")}`);
+    }
+    return spec;
+}
+/**
+ * Build the ffmpeg `-vf` filter for a single (source, preset) pair.
+ *
+ * Pure function — no side effects, no I/O. Used by `render_multi_format`
+ * to compose ffmpeg args, and by the unit tests to lock the filter math.
+ *
+ * Math notes for centre-crop:
+ *
+ *   srcAR = srcW/srcH, tgtAR = Wt/Ht. The crop keeps the larger axis full.
+ *
+ *   - srcAR > tgtAR  ⇒  source is wider than target. Crop width.
+ *       cropW = ih * Wt/Ht ; cropH = ih ; x = (iw - cropW)/2 ; y = 0
+ *   - srcAR < tgtAR  ⇒  source is taller than target. Crop height.
+ *       cropW = iw ; cropH = iw * Ht/Wt ; x = 0 ; y = (ih - cropH)/2
+ *   - srcAR == tgtAR ⇒  no crop needed; emit `scale=Wt:Ht` only.
+ *
+ * Float crop dimensions are passed through to ffmpeg (which accepts them
+ * and rounds internally); the trailing `scale=Wt:Ht` enforces the final
+ * even-dimension target so x264 stays happy.
+ */
+export function buildRenderFilter(srcW, srcH, format, opts = {}) {
+    if (!Number.isFinite(srcW) || srcW <= 0 || !Number.isFinite(srcH) || srcH <= 0) {
+        throw new Error(`invalid source dimensions: ${srcW}x${srcH}`);
+    }
+    const spec = multiFormatSpec(format);
+    const targetW = spec.width;
+    const targetH = spec.height;
+    const transform = opts.faceTracked ? "scale-pad" : spec.transform;
+    if (transform === "scale-pad") {
+        const vf = `scale=${targetW}:${targetH}:force_original_aspect_ratio=decrease,` +
+            `pad=${targetW}:${targetH}:(ow-iw)/2:(oh-ih)/2:color=black`;
+        return { targetW, targetH, vf, transform };
+    }
+    // centre-crop
+    const srcAR = srcW / srcH;
+    const tgtAR = targetW / targetH;
+    // Use a tiny tolerance so 1920x1080 vs perfectly-equal 16:9 sources round
+    // to the no-crop branch; prevents emitting `crop=iw:ih:0:0`.
+    const eps = 1e-6;
+    if (Math.abs(srcAR - tgtAR) < eps) {
+        return {
+            targetW,
+            targetH,
+            vf: `scale=${targetW}:${targetH}`,
+            transform,
+        };
+    }
+    if (srcAR > tgtAR) {
+        // crop width
+        const cropW = formatNum((srcH * targetW) / targetH);
+        const x = formatNum((srcW - (srcH * targetW) / targetH) / 2);
+        const vf = `crop=${cropW}:${srcH}:${x}:0,scale=${targetW}:${targetH}`;
+        return { targetW, targetH, vf, transform };
+    }
+    // srcAR < tgtAR — crop height
+    const cropH = formatNum((srcW * targetH) / targetW);
+    const y = formatNum((srcH - (srcW * targetH) / targetW) / 2);
+    const vf = `crop=${srcW}:${cropH}:0:${y},scale=${targetW}:${targetH}`;
+    return { targetW, targetH, vf, transform };
+}
+/**
+ * Format a number for inclusion in an ffmpeg filter expression. Trims any
+ * `.0` tail (e.g. 1080.0 → "1080") so integer paths remain integer-looking
+ * in the filter graph; otherwise emits up to 2 decimals.
+ */
+function formatNum(n) {
+    if (Number.isInteger(n))
+        return String(n);
+    // Two decimals is enough for any practical (W, H) from canonical sources;
+    // the trailing `scale` rounds to the final integer target.
+    const rounded = Math.round(n * 100) / 100;
+    return Number.isInteger(rounded) ? String(rounded) : String(rounded);
+}
+//# sourceMappingURL=multi-format.js.map

package/dist/core/multi-format.js.map

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

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

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

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

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