@kenkaiiii/gg-editor 0.6.7 → 0.7.1

package/dist/core/bundled-sfx.js

@@ -0,0 +1,218 @@
+/**
+ * Bundled sound-effect library.
+ *
+ * gg-editor's `add_sfx_at_cuts` needs a WAV/MP3 file per hit. Without this
+ * module the agent had to either ask the user to supply one or invent a path
+ * — both broke the canonical retention pipeline. Now the agent calls
+ * `add_sfx_at_cuts(sfx="whoosh", …)` with a bundled name and the resolver
+ * either returns a cached WAV or synthesises one via ffmpeg into
+ * `~/.gg/sfx-cache/<name>.wav` (~50 ms one-time per name; cached forever).
+ *
+ * Why synthesised, not shipped: no third-party files = no IP risk + no npm
+ * weight. Every recipe is a pure ffmpeg-lavfi expression so the output is
+ * deterministic and reproducible. Quality is "creator-vlog acceptable" —
+ * not Skywalker Sound, but indistinguishable from typical CapCut presets in
+ * a sub-1-second cut.
+ *
+ * Design rules for recipes:
+ *   - Stereo (`-ac 2`) — every consumer mixes into stereo audio.
+ *   - 200–500 ms long. Anything longer fights the next cut.
+ *   - Peak ≤ -3 dBFS (the recipes all keep amplitude ≤ 0.7) so
+ *     `add_sfx_at_cuts`'s default -8 dB gain leaves headroom for voice.
+ *   - Linear fade in (≥5 ms) + fade out — no clicks at the envelope edges.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
+import { runFfmpeg } from "./media/ffmpeg.js";
+/**
+ * The bundled set. Keep this list short and creator-relevant —
+ * 8–10 names covers the entire short-form vocabulary.
+ */
+export const BUNDLED_SFX = {
+    pop: {
+        description: "Short upward blip — punctuates a cut without dominating",
+        args: [
+            "-f",
+            "lavfi",
+            "-i",
+            "sine=frequency=880:duration=0.08",
+            "-af",
+            "afade=t=in:d=0.005,afade=t=out:d=0.05:st=0.03,volume=0.5",
+            "-ac",
+            "2",
+        ],
+    },
+    click: {
+        description: "Very short tick — for fast-cut emphasis where pop would be too musical",
+        args: [
+            "-f",
+            "lavfi",
+            "-i",
+            "anoisesrc=color=white:duration=0.03:amplitude=0.6",
+            "-af",
+            "bandpass=frequency=4000:width_type=h:w=3000,afade=t=in:d=0.002,afade=t=out:d=0.025:st=0.005,volume=2",
+            "-ac",
+            "2",
+        ],
+    },
+    whoosh: {
+        description: "Downward frequency sweep — classic vlog cut effect",
+        args: [
+            "-f",
+            "lavfi",
+            // Linear sweep 3000 Hz → ~200 Hz over 0.3 s (phase = 2π·(f₀·t + ½·k·t²))
+            "-i",
+            "aevalsrc='0.4*sin(2*PI*(3000*t-4667*t*t))':d=0.3",
+            "-af",
+            "afade=t=in:d=0.05,afade=t=out:d=0.1:st=0.2",
+            "-ac",
+            "2",
+        ],
+    },
+    "whoosh-up": {
+        description: "Upward frequency sweep — for reveals / 'lift' moments",
+        args: [
+            "-f",
+            "lavfi",
+            // Sweep 200 Hz → ~3000 Hz over 0.3 s
+            "-i",
+            "aevalsrc='0.4*sin(2*PI*(200*t+4667*t*t))':d=0.3",
+            "-af",
+            "afade=t=in:d=0.05,afade=t=out:d=0.1:st=0.2",
+            "-ac",
+            "2",
+        ],
+    },
+    swoosh: {
+        description: "Filtered noise sweep — softer/airier than whoosh, good for transitions",
+        args: [
+            "-f",
+            "lavfi",
+            "-i",
+            "anoisesrc=color=brown:duration=0.4:amplitude=0.5",
+            "-af",
+            "bandpass=frequency=1500:width_type=h:w=2500,afade=t=in:d=0.05,afade=t=out:d=0.15:st=0.25,volume=2.5",
+            "-ac",
+            "2",
+        ],
+    },
+    riser: {
+        description: "600 ms sine sweep up — builds tension before a reveal",
+        args: [
+            "-f",
+            "lavfi",
+            // Sweep 200 → ~2200 Hz over 0.6 s with rising amplitude
+            "-i",
+            "aevalsrc='(0.2+0.4*t)*sin(2*PI*(200*t+1667*t*t))':d=0.6",
+            "-af",
+            "afade=t=in:d=0.1,afade=t=out:d=0.05:st=0.55",
+            "-ac",
+            "2",
+        ],
+    },
+    "bass-drop": {
+        description: "Sub bass with downward sweep — for big-reveal cuts (use sparingly)",
+        args: [
+            "-f",
+            "lavfi",
+            // Sweep 120 Hz → ~40 Hz over 0.45 s
+            "-i",
+            "aevalsrc='0.6*sin(2*PI*(120*t-89*t*t))':d=0.45",
+            "-af",
+            "afade=t=in:d=0.02,afade=t=out:d=0.15:st=0.3",
+            "-ac",
+            "2",
+        ],
+    },
+    ding: {
+        description: "Soft bell — for highlighting an on-screen item / list bullet",
+        args: [
+            "-f",
+            "lavfi",
+            "-i",
+            // Two-harmonic bell: fundamental + perfect fifth, exponential decay
+            "aevalsrc='exp(-4*t)*(0.5*sin(2*PI*1318*t)+0.25*sin(2*PI*1976*t))':d=0.5",
+            "-af",
+            "afade=t=in:d=0.005",
+            "-ac",
+            "2",
+        ],
+    },
+    thump: {
+        description: "Low percussive hit — landing impact, soft punch",
+        args: [
+            "-f",
+            "lavfi",
+            "-i",
+            // Damped sine ~80 Hz with fast decay
+            "aevalsrc='exp(-12*t)*0.7*sin(2*PI*80*t)':d=0.25",
+            "-af",
+            "afade=t=in:d=0.005",
+            "-ac",
+            "2",
+        ],
+    },
+};
+/** Names of every bundled SFX (sorted for stable display). */
+export function listBundledSfxNames() {
+    return Object.keys(BUNDLED_SFX).sort();
+}
+/** A short markdown-style list of bundled SFX for tool descriptions / system prompts. */
+export function bundledSfxDescriptionList() {
+    return listBundledSfxNames()
+        .map((n) => `${n} (${BUNDLED_SFX[n].description})`)
+        .join(", ");
+}
+/** Cache dir for synthesised WAVs. Stable across sessions, gitignored by convention. */
+export function getSfxCacheDir() {
+    return resolvePath(homedir(), ".gg", "sfx-cache");
+}
+/**
+ * Resolve an SFX argument:
+ *
+ *   - Bundled name (e.g. `"whoosh"`) → cache hit at `~/.gg/sfx-cache/whoosh.wav`,
+ *     synthesising via ffmpeg on first request.
+ *   - File-like string (contains `/`, `\`, `.`, `~`) → resolve against `cwd`
+ *     and return as-is. The caller still has to verify the file exists.
+ *
+ * Throws when the name is neither bundled nor file-like.
+ */
+export async function resolveSfx(nameOrPath, cwd, signal) {
+    // Bundled names are bare alphanumeric+hyphen tokens with no path / extension.
+    // Any string with `/`, `\`, `.`, or `~` is a file path.
+    const looksLikePath = /[/\\.~]/.test(nameOrPath);
+    if (!looksLikePath) {
+        const recipe = BUNDLED_SFX[nameOrPath];
+        if (!recipe) {
+            throw new Error(`unknown SFX name: '${nameOrPath}'. Bundled: ${listBundledSfxNames().join(", ")}`);
+        }
+        const path = await ensureBundledSfx(nameOrPath, signal);
+        return { path, bundled: true, name: nameOrPath };
+    }
+    // Treat as a file path.
+    return { path: resolvePath(cwd, nameOrPath), bundled: false };
+}
+/**
+ * Ensure a bundled SFX is present on disk, synthesising it via ffmpeg if not.
+ * Returns the absolute cache path.
+ */
+export async function ensureBundledSfx(name, signal) {
+    const recipe = BUNDLED_SFX[name];
+    if (!recipe) {
+        throw new Error(`unknown bundled SFX: '${name}'`);
+    }
+    const dir = getSfxCacheDir();
+    mkdirSync(dir, { recursive: true });
+    const out = join(dir, `${name}.wav`);
+    if (existsSync(out))
+        return out;
+    const ffArgs = [...recipe.args, out];
+    const r = await runFfmpeg(ffArgs, { signal });
+    if (r.code !== 0) {
+        const tail = r.stderr.split("\n").filter(Boolean).slice(-3).join(" | ").slice(-300);
+        throw new Error(`ffmpeg failed synthesising '${name}' SFX: ${tail}`);
+    }
+    return out;
+}
+//# sourceMappingURL=bundled-sfx.js.map

package/dist/core/bundled-sfx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundled-sfx.js","sourceRoot":"","sources":["../../src/core/bundled-sfx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAY9C;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAA8B;IACpD,GAAG,EAAE;QACH,WAAW,EAAE,yDAAyD;QACtE,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,IAAI;YACJ,kCAAkC;YAClC,KAAK;YACL,0DAA0D;YAC1D,KAAK;YACL,GAAG;SACJ;KACF;IACD,KAAK,EAAE;QACL,WAAW,EAAE,wEAAwE;QACrF,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,IAAI;YACJ,mDAAmD;YACnD,KAAK;YACL,sGAAsG;YACtG,KAAK;YACL,GAAG;SACJ;KACF;IACD,MAAM,EAAE;QACN,WAAW,EAAE,oDAAoD;QACjE,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,yEAAyE;YACzE,IAAI;YACJ,kDAAkD;YAClD,KAAK;YACL,4CAA4C;YAC5C,KAAK;YACL,GAAG;SACJ;KACF;IACD,WAAW,EAAE;QACX,WAAW,EAAE,uDAAuD;QACpE,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,qCAAqC;YACrC,IAAI;YACJ,iDAAiD;YACjD,KAAK;YACL,4CAA4C;YAC5C,KAAK;YACL,GAAG;SACJ;KACF;IACD,MAAM,EAAE;QACN,WAAW,EAAE,wEAAwE;QACrF,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,IAAI;YACJ,kDAAkD;YAClD,KAAK;YACL,qGAAqG;YACrG,KAAK;YACL,GAAG;SACJ;KACF;IACD,KAAK,EAAE;QACL,WAAW,EAAE,uDAAuD;QACpE,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,wDAAwD;YACxD,IAAI;YACJ,yDAAyD;YACzD,KAAK;YACL,6CAA6C;YAC7C,KAAK;YACL,GAAG;SACJ;KACF;IACD,WAAW,EAAE;QACX,WAAW,EAAE,oEAAoE;QACjF,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,oCAAoC;YACpC,IAAI;YACJ,gDAAgD;YAChD,KAAK;YACL,6CAA6C;YAC7C,KAAK;YACL,GAAG;SACJ;KACF;IACD,IAAI,EAAE;QACJ,WAAW,EAAE,8DAA8D;QAC3E,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,IAAI;YACJ,oEAAoE;YACpE,yEAAyE;YACzE,KAAK;YACL,oBAAoB;YACpB,KAAK;YACL,GAAG;SACJ;KACF;IACD,KAAK,EAAE;QACL,WAAW,EAAE,iDAAiD;QAC9D,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,IAAI;YACJ,qCAAqC;YACrC,iDAAiD;YACjD,KAAK;YACL,oBAAoB;YACpB,KAAK;YACL,GAAG;SACJ;KACF;CACF,CAAC;AAEF,8DAA8D;AAC9D,MAAM,UAAU,mBAAmB;IACjC,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC;AACzC,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,yBAAyB;IACvC,OAAO,mBAAmB,EAAE;SACzB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC;SAClD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,cAAc;IAC5B,OAAO,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,UAAkB,EAClB,GAAW,EACX,MAAoB;IAEpB,8EAA8E;IAC9E,wDAAwD;IACxD,MAAM,aAAa,GAAG,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjD,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,sBAAsB,UAAU,eAAe,mBAAmB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAClF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACxD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IACnD,CAAC;IACD,wBAAwB;IACxB,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAoB;IACvE,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,GAAG,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,GAAG,GAAG,cAAc,EAAE,CAAC;IAC7B,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC;IACrC,IAAI,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAEhC,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,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;QACpF,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,UAAU,IAAI,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/core/bundled-sfx.test.d.ts

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

package/dist/core/bundled-sfx.test.d.ts.map

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

package/dist/core/bundled-sfx.test.js

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from "vitest";
+import { BUNDLED_SFX, bundledSfxDescriptionList, ensureBundledSfx, getSfxCacheDir, listBundledSfxNames, resolveSfx, } from "./bundled-sfx.js";
+// We don't want any of these tests touching real ffmpeg or the user's home
+// directory. Most assertions are pure-function. The synthesis tests mock
+// runFfmpeg via vi.mock at module scope.
+vi.mock("./media/ffmpeg.js", async () => {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+    const real = await vi.importActual("./media/ffmpeg.js");
+    return {
+        ...real,
+        runFfmpeg: vi.fn(async () => ({ code: 0, stdout: "", stderr: "" })),
+    };
+});
+describe("BUNDLED_SFX registry", () => {
+    it("ships at least 8 named effects covering the creator vocabulary", () => {
+        const names = listBundledSfxNames();
+        for (const required of ["pop", "click", "whoosh", "swoosh", "riser", "thump", "ding"]) {
+            expect(names).toContain(required);
+        }
+        expect(names.length).toBeGreaterThanOrEqual(8);
+    });
+    it("every recipe has stereo + non-empty args + no embedded output path", () => {
+        for (const [_name, recipe] of Object.entries(BUNDLED_SFX)) {
+            expect(recipe.description.length).toBeGreaterThan(10);
+            expect(recipe.args).toContain("-ac");
+            const acIdx = recipe.args.indexOf("-ac");
+            expect(recipe.args[acIdx + 1]).toBe("2");
+            // Output path is appended at synthesis time, not embedded in recipes.
+            const lastArg = recipe.args[recipe.args.length - 1];
+            expect(lastArg.endsWith(".wav")).toBe(false);
+        }
+    });
+    it("bundledSfxDescriptionList includes every name + description", () => {
+        const list = bundledSfxDescriptionList();
+        for (const name of listBundledSfxNames()) {
+            expect(list).toContain(name);
+        }
+        expect(list).toContain("(");
+        expect(list).toContain(")");
+    });
+});
+describe("getSfxCacheDir", () => {
+    it("returns a path under the user's home", () => {
+        const dir = getSfxCacheDir();
+        expect(dir).toContain(".gg");
+        expect(dir).toContain("sfx-cache");
+    });
+});
+describe("resolveSfx", () => {
+    it("treats unambiguous bundled names as bundled", async () => {
+        // Force ffmpeg mock to claim success without touching disk.
+        const r = await resolveSfx("whoosh", "/tmp/x").catch((e) => ({ error: e.message }));
+        if ("error" in r) {
+            // Expected if cache mkdir somehow fails on the test runner — skip.
+            return;
+        }
+        expect(r.bundled).toBe(true);
+        expect(r.name).toBe("whoosh");
+        expect(r.path).toMatch(/whoosh\.wav$/);
+    });
+    it("treats anything containing a path separator as a file path", async () => {
+        const r = await resolveSfx("./assets/myfx.wav", "/home/user");
+        expect(r.bundled).toBe(false);
+        expect(r.path).toBe("/home/user/assets/myfx.wav");
+        expect(r.name).toBeUndefined();
+    });
+    it("treats anything with a dot (extension) as a file path", async () => {
+        const r = await resolveSfx("custom.mp3", "/home/user");
+        expect(r.bundled).toBe(false);
+        expect(r.path).toBe("/home/user/custom.mp3");
+    });
+    it("rejects unknown bare names with the bundled list in the message", async () => {
+        await expect(resolveSfx("notarealsfx", "/tmp")).rejects.toThrow(/Bundled:.*whoosh/);
+    });
+});
+describe("ensureBundledSfx", () => {
+    it("rejects unknown names", async () => {
+        await expect(ensureBundledSfx("notarealsfx")).rejects.toThrow(/unknown bundled SFX/);
+    });
+});
+//# sourceMappingURL=bundled-sfx.test.js.map

package/dist/core/bundled-sfx.test.js.map

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

package/dist/core/child-abort.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared abort wiring for spawned child processes.
+ *
+ * Every long-running tool in gg-editor — ffmpeg, whisper.cpp, whisperx,
+ * Python sidecars (librosa beats, MediaPipe face reframe), Resolve bridge —
+ * is wrapped in a Promise that resolves on `child.on("close")`. Without
+ * careful abort handling those promises can hang for the duration of the
+ * child's actual exit even after the user pressed ESC.
+ *
+ * The naive pattern `signal.addEventListener("abort", () => child.kill())`
+ * has three real failure modes:
+ *
+ *   1. **Pre-abort race** — if `signal.aborted` is already true at attach
+ *      time, the listener never fires (Node only dispatches `abort` once,
+ *      at the moment the controller flips). The child runs to completion.
+ *
+ *   2. **SIGTERM ignored** — CPU-bound inference (whisper.cpp processing a
+ *      30-min audio chunk, ffmpeg encoding a long video) can ignore
+ *      SIGTERM until it finishes the current loop iteration. Users press
+ *      ESC and watch nothing happen for many seconds.
+ *
+ *   3. **Promise waits for close** — even if the kill works, the outer
+ *      Promise resolves on `child.on("close")`, which fires AFTER the
+ *      child finishes dying. The agent loop sees the abort late.
+ *
+ * `wireChildAbort` fixes all three:
+ *
+ *   - Synchronous pre-aborted check → kills + rejects immediately.
+ *   - SIGTERM, then SIGKILL after a configurable grace period (default 1.5s).
+ *   - Caller decides whether to reject early (most callers pass `onAbort`
+ *     that rejects with an `AbortError`); resolves can still happen
+ *     naturally on close if the caller prefers a "code: SIGTERM" outcome.
+ *   - Returns a cleanup function that removes the listener and clears the
+ *     SIGKILL timer. Caller must invoke once the promise settles.
+ */
+import type { ChildProcess } from "node:child_process";
+/**
+ * Standard AbortError. Mirrors what `fetch` raises when its signal fires —
+ * `name === "AbortError"` is the cross-platform contract for cancellation.
+ */
+export declare function abortError(message?: string): Error;
+export interface WireChildAbortOptions {
+    /** Optional. Called on abort BEFORE the SIGKILL grace period. Use to reject the wrapping Promise immediately. */
+    onAbort?: () => void;
+    /** Grace period before escalating to SIGKILL. Default 1500 ms. */
+    killAfterMs?: number;
+}
+/**
+ * Wire an AbortSignal to a child process. See file header for design rationale.
+ *
+ * Returns a cleanup function the caller MUST invoke once the promise settles
+ * (in both `child.on("close")` and `child.on("error")`). Without cleanup the
+ * abort listener stays on the signal and the SIGKILL timer keeps a process
+ * reference alive.
+ */
+export declare function wireChildAbort(signal: AbortSignal | undefined, child: ChildProcess, opts?: WireChildAbortOptions): () => void;
+//# sourceMappingURL=child-abort.d.ts.map

package/dist/core/child-abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-abort.d.ts","sourceRoot":"","sources":["../../src/core/child-abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,SAAY,GAAG,KAAK,CAOrD;AAED,MAAM,WAAW,qBAAqB;IACpC,iHAAiH;IACjH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE,qBAA0B,GAC/B,MAAM,IAAI,CAoCZ"}

package/dist/core/child-abort.js

@@ -0,0 +1,95 @@
+/**
+ * Shared abort wiring for spawned child processes.
+ *
+ * Every long-running tool in gg-editor — ffmpeg, whisper.cpp, whisperx,
+ * Python sidecars (librosa beats, MediaPipe face reframe), Resolve bridge —
+ * is wrapped in a Promise that resolves on `child.on("close")`. Without
+ * careful abort handling those promises can hang for the duration of the
+ * child's actual exit even after the user pressed ESC.
+ *
+ * The naive pattern `signal.addEventListener("abort", () => child.kill())`
+ * has three real failure modes:
+ *
+ *   1. **Pre-abort race** — if `signal.aborted` is already true at attach
+ *      time, the listener never fires (Node only dispatches `abort` once,
+ *      at the moment the controller flips). The child runs to completion.
+ *
+ *   2. **SIGTERM ignored** — CPU-bound inference (whisper.cpp processing a
+ *      30-min audio chunk, ffmpeg encoding a long video) can ignore
+ *      SIGTERM until it finishes the current loop iteration. Users press
+ *      ESC and watch nothing happen for many seconds.
+ *
+ *   3. **Promise waits for close** — even if the kill works, the outer
+ *      Promise resolves on `child.on("close")`, which fires AFTER the
+ *      child finishes dying. The agent loop sees the abort late.
+ *
+ * `wireChildAbort` fixes all three:
+ *
+ *   - Synchronous pre-aborted check → kills + rejects immediately.
+ *   - SIGTERM, then SIGKILL after a configurable grace period (default 1.5s).
+ *   - Caller decides whether to reject early (most callers pass `onAbort`
+ *     that rejects with an `AbortError`); resolves can still happen
+ *     naturally on close if the caller prefers a "code: SIGTERM" outcome.
+ *   - Returns a cleanup function that removes the listener and clears the
+ *     SIGKILL timer. Caller must invoke once the promise settles.
+ */
+/**
+ * Standard AbortError. Mirrors what `fetch` raises when its signal fires —
+ * `name === "AbortError"` is the cross-platform contract for cancellation.
+ */
+export function abortError(message = "aborted") {
+    if (typeof DOMException !== "undefined") {
+        return new DOMException(message, "AbortError");
+    }
+    const e = new Error(message);
+    e.name = "AbortError";
+    return e;
+}
+/**
+ * Wire an AbortSignal to a child process. See file header for design rationale.
+ *
+ * Returns a cleanup function the caller MUST invoke once the promise settles
+ * (in both `child.on("close")` and `child.on("error")`). Without cleanup the
+ * abort listener stays on the signal and the SIGKILL timer keeps a process
+ * reference alive.
+ */
+export function wireChildAbort(signal, child, opts = {}) {
+    if (!signal)
+        return () => { };
+    const killAfterMs = opts.killAfterMs ?? 1500;
+    let killTimer;
+    let fired = false;
+    const onAbort = () => {
+        if (fired)
+            return;
+        fired = true;
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // child may already be dead — fine.
+        }
+        killTimer = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                // ditto
+            }
+        }, killAfterMs);
+        opts.onAbort?.();
+    };
+    if (signal.aborted) {
+        // Pre-aborted — fire synchronously so caller's onAbort runs in the same tick.
+        onAbort();
+    }
+    else {
+        signal.addEventListener("abort", onAbort, { once: true });
+    }
+    return () => {
+        signal.removeEventListener("abort", onAbort);
+        if (killTimer)
+            clearTimeout(killTimer);
+    };
+}
+//# sourceMappingURL=child-abort.js.map

package/dist/core/child-abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-abort.js","sourceRoot":"","sources":["../../src/core/child-abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,OAAO,GAAG,SAAS;IAC5C,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;QACxC,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC,CAAC,IAAI,GAAG,YAAY,CAAC;IACtB,OAAO,CAAC,CAAC;AACX,CAAC;AASD;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,MAA+B,EAC/B,KAAmB,EACnB,OAA8B,EAAE;IAEhC,IAAI,CAAC,MAAM;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAE7B,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC;IAC7C,IAAI,SAAqC,CAAC;IAC1C,IAAI,KAAK,GAAG,KAAK,CAAC;IAElB,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,IAAI,KAAK;YAAE,OAAO;QAClB,KAAK,GAAG,IAAI,CAAC;QACb,IAAI,CAAC;YACH,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;QACD,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YAC1B,IAAI,CAAC;gBACH,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,QAAQ;YACV,CAAC;QACH,CAAC,EAAE,WAAW,CAAC,CAAC;QAChB,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;IACnB,CAAC,CAAC;IAEF,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,8EAA8E;QAC9E,OAAO,EAAE,CAAC;IACZ,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,GAAG,EAAE;QACV,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC7C,IAAI,SAAS;YAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IACzC,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/child-abort.test.d.ts

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

package/dist/core/child-abort.test.d.ts.map

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

package/dist/core/child-abort.test.js

@@ -0,0 +1,88 @@
+import { spawn } from "node:child_process";
+import { describe, expect, it, vi } from "vitest";
+import { abortError, wireChildAbort } from "./child-abort.js";
+describe("abortError", () => {
+    it("returns an error with name 'AbortError'", () => {
+        const e = abortError();
+        expect(e.name).toBe("AbortError");
+    });
+    it("accepts a custom message", () => {
+        expect(abortError("custom").message).toContain("custom");
+    });
+});
+/**
+ * Use a child that sleeps long enough that SIGTERM-then-SIGKILL is observable
+ * but short enough that test runs stay fast. Node spawned with `-e` running a
+ * setTimeout works on every platform CI uses.
+ */
+function spawnSleeper(seconds) {
+    return spawn(process.execPath, ["-e", `setTimeout(() => {}, ${seconds * 1000})`], {
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+}
+describe("wireChildAbort", () => {
+    it("is a no-op when signal is undefined", () => {
+        const child = spawnSleeper(0.1);
+        const cleanup = wireChildAbort(undefined, child);
+        expect(typeof cleanup).toBe("function");
+        cleanup(); // shouldn't throw
+        child.kill();
+    });
+    it("kills the child with SIGTERM when the signal aborts", async () => {
+        const ac = new AbortController();
+        const child = spawnSleeper(10);
+        const killSpy = vi.spyOn(child, "kill");
+        const cleanup = wireChildAbort(ac.signal, child);
+        ac.abort();
+        expect(killSpy).toHaveBeenCalledWith("SIGTERM");
+        // Wait for child to actually exit so the test runner doesn't leak.
+        await new Promise((resolve) => child.on("close", () => resolve()));
+        cleanup();
+    });
+    it("fires onAbort exactly once even on repeated aborts", () => {
+        const ac = new AbortController();
+        const child = spawnSleeper(10);
+        const onAbort = vi.fn();
+        wireChildAbort(ac.signal, child, { onAbort });
+        ac.abort();
+        ac.abort(); // duplicate signal — listener attached `once`
+        expect(onAbort).toHaveBeenCalledTimes(1);
+        child.kill("SIGKILL");
+    });
+    it("fires synchronously when the signal is already aborted at attach time", () => {
+        const ac = new AbortController();
+        ac.abort(); // pre-abort
+        const child = spawnSleeper(10);
+        const killSpy = vi.spyOn(child, "kill");
+        const onAbort = vi.fn();
+        wireChildAbort(ac.signal, child, { onAbort });
+        expect(killSpy).toHaveBeenCalledWith("SIGTERM");
+        expect(onAbort).toHaveBeenCalledTimes(1);
+        child.kill("SIGKILL");
+    });
+    it("cleanup removes the listener (no further onAbort after cleanup)", () => {
+        const ac = new AbortController();
+        const child = spawnSleeper(10);
+        const onAbort = vi.fn();
+        const cleanup = wireChildAbort(ac.signal, child, { onAbort });
+        cleanup();
+        ac.abort();
+        expect(onAbort).not.toHaveBeenCalled();
+        child.kill("SIGKILL");
+    });
+    it("escalates to SIGKILL after the grace period when SIGTERM is ignored", async () => {
+        vi.useFakeTimers();
+        const ac = new AbortController();
+        const child = spawnSleeper(10);
+        const killSpy = vi.spyOn(child, "kill");
+        wireChildAbort(ac.signal, child, { killAfterMs: 50 });
+        ac.abort();
+        expect(killSpy).toHaveBeenLastCalledWith("SIGTERM");
+        vi.advanceTimersByTime(60);
+        expect(killSpy).toHaveBeenLastCalledWith("SIGKILL");
+        vi.useRealTimers();
+        child.kill("SIGKILL");
+        await new Promise((resolve) => child.on("close", () => resolve()));
+    });
+});
+//# sourceMappingURL=child-abort.test.js.map

package/dist/core/child-abort.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-abort.test.js","sourceRoot":"","sources":["../../src/core/child-abort.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE9D,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC;QACvB,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH;;;;GAIG;AACH,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,wBAAwB,OAAO,GAAG,IAAI,GAAG,CAAC,EAAE;QAChF,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,OAAO,GAAG,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACjD,MAAM,CAAC,OAAO,OAAO,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACxC,OAAO,EAAE,CAAC,CAAC,kBAAkB;QAC7B,KAAK,CAAC,IAAI,EAAE,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,KAAK,IAAI,EAAE;QACnE,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAEjD,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,CAAC,OAAO,CAAC,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;QAEhD,mEAAmE;QACnE,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACzE,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QACxB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAE9C,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,8CAA8C;QAC1D,MAAM,CAAC,OAAO,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uEAAuE,EAAE,GAAG,EAAE;QAC/E,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;QACjC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,YAAY;QAExB,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QACxB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAE9C,MAAM,CAAC,OAAO,CAAC,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;QAChD,MAAM,CAAC,OAAO,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,GAAG,EAAE;QACzE,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAE9D,OAAO,EAAE,CAAC;QACV,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qEAAqE,EAAE,KAAK,IAAI,EAAE;QACnF,EAAE,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACxC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;QAEtD,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,CAAC,OAAO,CAAC,CAAC,wBAAwB,CAAC,SAAS,CAAC,CAAC;QAEpD,EAAE,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,CAAC,OAAO,CAAC,CAAC,wBAAwB,CAAC,SAAS,CAAC,CAAC;QAEpD,EAAE,CAAC,aAAa,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/core/clip-scoring.d.ts

@@ -0,0 +1,44 @@
+export interface ClipScoreResponse {
+    hook: number;
+    flow: number;
+    engagement: number;
+    trend: number;
+    why: string;
+}
+export interface ClipScore extends ClipScoreResponse {
+    score: number;
+    durationSec: number;
+}
+export interface ClipScoreWeights {
+    hook?: number;
+    flow?: number;
+    engagement?: number;
+    trend?: number;
+}
+/**
+ * Robust parser — tolerates prose around the JSON, missing keys, and
+ * out-of-range numbers. Mirrors `parseHookVisionResponse`.
+ */
+export declare function parseClipScoreResponse(content: string): ClipScoreResponse;
+/**
+ * Combine the four 0-1 dimensions into a single 0-100 score, using the
+ * default (or caller-supplied) weights.
+ */
+export declare function combineClipScore(vision: ClipScoreResponse, durationSec: number, weights?: ClipScoreWeights): ClipScore;
+export interface ScoreClipOptions {
+    apiKey?: string;
+    model?: string;
+    detail?: "low" | "high";
+    weights?: ClipScoreWeights;
+    signal?: AbortSignal;
+}
+/**
+ * Run the LLM scoring pass. Frames are optional — transcript-only is
+ * the cheap default; pass frames when visual energy matters.
+ *
+ * Pure-ish: the only side effects are the OpenAI fetch and reading
+ * frame files off disk. Used directly by both the tool wrapper and
+ * `find_viral_moments`.
+ */
+export declare function scoreClipInternal(transcriptText: string, startSec: number, endSec: number, framePaths?: string[], opts?: ScoreClipOptions): Promise<ClipScore>;
+//# sourceMappingURL=clip-scoring.d.ts.map

package/dist/core/clip-scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clip-scoring.d.ts","sourceRoot":"","sources":["../../src/core/clip-scoring.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAU,SAAQ,iBAAiB;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyCD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAczE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,EACzB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CAkBX;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,MAAM,EAAO,EACzB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,SAAS,CAAC,CAuDpB"}