@prestyj/editor 0.7.1

package/dist/core/skills-loader.js

@@ -0,0 +1,161 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve as resolvePath } from "node:path";
+export function discoverSkills(opts) {
+    const home = opts.homeDir ?? homedir();
+    const projectDirs = [
+        resolvePath(opts.cwd, ".ezcoder/editor-skills"),
+        resolvePath(opts.cwd, ".ezcoder/skills"),
+    ];
+    const userDirs = [
+        resolvePath(home, ".ezcoder/editor-skills"),
+        resolvePath(home, ".ezcoder/skills"),
+    ];
+    const bundled = opts.bundled.map((s) => ({
+        name: s.name,
+        description: s.description,
+        content: s.content,
+        origin: "bundled",
+    }));
+    const project = projectDirs.flatMap((d) => readSkillDir(d, "project"));
+    const user = userDirs.flatMap((d) => readSkillDir(d, "user"));
+    // last-wins by name across [bundled, project, user]
+    const byName = new Map();
+    for (const s of [...bundled, ...project, ...user]) {
+        byName.set(s.name, s);
+    }
+    return [...byName.values()];
+}
+function readSkillDir(dir, origin) {
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        const path = join(dir, e);
+        let st;
+        try {
+            st = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        // Flat layout: <name>.md
+        if (st.isFile() && e.endsWith(".md")) {
+            try {
+                const content = readFileSync(path, "utf8");
+                out.push(parseSkill(content, origin, path, basename(e, ".md")));
+            }
+            catch {
+                /* skip unreadable */
+            }
+            continue;
+        }
+        // Bundle layout: <name>/SKILL.md (Anthropic skill spec / skills.sh).
+        if (st.isDirectory()) {
+            const skillFile = join(path, "SKILL.md");
+            try {
+                const fst = statSync(skillFile);
+                if (!fst.isFile())
+                    continue;
+                const content = readFileSync(skillFile, "utf8");
+                out.push(parseSkill(content, origin, skillFile, e));
+            }
+            catch {
+                /* no SKILL.md — skip */
+            }
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Parse a skill markdown into a SkillSource. Supports optional
+ * 3-dash-delimited YAML frontmatter (only `name:` and `description:` are
+ * inspected — additional keys are tolerated and ignored).
+ *
+ * The parsed `content` retains the frontmatter when present, so consumers
+ * (read_skill / agent prompts) see the full file as authored. This matches
+ * how ezcoder and the skills.sh ecosystem treat skill files.
+ */
+export function parseSkill(raw, origin, path, fallbackName) {
+    const fm = parseFrontmatter(raw);
+    return {
+        name: fm.name ?? fallbackName,
+        description: fm.description ?? extractDescription(stripFrontmatter(raw)),
+        content: raw,
+        origin,
+        path,
+    };
+}
+/**
+ * Read a YAML-ish frontmatter block at the start of a file. Only supports the
+ * tiny subset we care about — `key: value` lines, no nesting, no lists. That
+ * matches the Anthropic skill spec exactly. Multi-line `description: |` is
+ * NOT supported by design (skill descriptions should fit on one line so the
+ * system-prompt index reads cleanly).
+ */
+export function parseFrontmatter(raw) {
+    if (!raw.startsWith("---"))
+        return {};
+    const end = raw.indexOf("\n---", 3);
+    if (end < 0)
+        return {};
+    const block = raw.slice(3, end).trim();
+    const out = {};
+    for (const line of block.split(/\r?\n/)) {
+        const colon = line.indexOf(":");
+        if (colon < 0)
+            continue;
+        const key = line.slice(0, colon).trim().toLowerCase();
+        let value = line.slice(colon + 1).trim();
+        // Strip surrounding quotes (YAML allows either) — single OR double — so
+        // descriptions that contain colons can be quoted defensively.
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key === "name")
+            out.name = value;
+        else if (key === "description")
+            out.description = value;
+    }
+    return out;
+}
+/** Drop the frontmatter block (if any), return body only. */
+export function stripFrontmatter(raw) {
+    if (!raw.startsWith("---"))
+        return raw;
+    const end = raw.indexOf("\n---", 3);
+    if (end < 0)
+        return raw;
+    return raw.slice(end + 4).replace(/^\r?\n/, "");
+}
+/**
+ * Extract a one-line description from a skill markdown.
+ *
+ * Strategy: the first non-empty, non-heading line of plain text. Truncated at
+ * 200 chars. Falls back to "(no description)" if absent.
+ */
+export function extractDescription(content) {
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        if (line.startsWith("#"))
+            continue;
+        if (line.startsWith("---"))
+            continue;
+        if (line.startsWith("```"))
+            continue;
+        const out = line.length > 200 ? line.slice(0, 199) + "…" : line;
+        return out;
+    }
+    return "(no description)";
+}
+//# sourceMappingURL=skills-loader.js.map

package/dist/core/skills-loader.js.map

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

package/dist/core/skills-loader.test.d.ts

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

package/dist/core/skills-loader.test.d.ts.map

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

package/dist/core/skills-loader.test.js

@@ -0,0 +1,130 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { discoverSkills, extractDescription, parseFrontmatter, stripFrontmatter, } from "./skills-loader.js";
+const BUNDLED = [
+    { name: "alpha", description: "bundled alpha", content: "# alpha\nbundled body" },
+    { name: "beta", description: "bundled beta", content: "# beta\nbundled body" },
+];
+function tmp(prefix) {
+    return mkdtempSync(join(tmpdir(), prefix));
+}
+describe("extractDescription", () => {
+    it("returns the first non-heading paragraph", () => {
+        const md = "# title\n\nFirst real line.\nSecond.";
+        expect(extractDescription(md)).toBe("First real line.");
+    });
+    it("falls back when only headings", () => {
+        expect(extractDescription("# only\n## headings")).toBe("(no description)");
+    });
+    it("truncates at 200 chars", () => {
+        const long = "x".repeat(300);
+        const r = extractDescription(`# t\n\n${long}`);
+        expect(r.length).toBe(200);
+        expect(r.endsWith("…")).toBe(true);
+    });
+});
+describe("discoverSkills", () => {
+    it("returns bundled-only when no dirs exist", () => {
+        const cwd = tmp("gg-skills-cwd-");
+        const home = tmp("gg-skills-home-");
+        const r = discoverSkills({ cwd, homeDir: home, bundled: BUNDLED });
+        expect(r.map((s) => s.name).sort()).toEqual(["alpha", "beta"]);
+        expect(r.every((s) => s.origin === "bundled")).toBe(true);
+    });
+    it("loads project skills with extracted description", () => {
+        const cwd = tmp("gg-skills-cwd-");
+        const home = tmp("gg-skills-home-");
+        mkdirSync(join(cwd, ".ezcoder/editor-skills"), { recursive: true });
+        writeFileSync(join(cwd, ".ezcoder/editor-skills/gamma.md"), "# gamma\n\nProject-only skill body.\n");
+        const r = discoverSkills({ cwd, homeDir: home, bundled: BUNDLED });
+        const gamma = r.find((s) => s.name === "gamma");
+        expect(gamma?.origin).toBe("project");
+        expect(gamma?.description).toBe("Project-only skill body.");
+    });
+    it("user skill overrides bundled (last-wins)", () => {
+        const cwd = tmp("gg-skills-cwd-");
+        const home = tmp("gg-skills-home-");
+        mkdirSync(join(home, ".ezcoder/editor-skills"), { recursive: true });
+        writeFileSync(join(home, ".ezcoder/editor-skills/alpha.md"), "# alpha\n\nUser-overridden alpha.\n");
+        const r = discoverSkills({ cwd, homeDir: home, bundled: BUNDLED });
+        const alpha = r.find((s) => s.name === "alpha");
+        expect(alpha?.origin).toBe("user");
+        expect(alpha?.description).toBe("User-overridden alpha.");
+    });
+    it("user wins over project when both define the same name", () => {
+        const cwd = tmp("gg-skills-cwd-");
+        const home = tmp("gg-skills-home-");
+        mkdirSync(join(cwd, ".ezcoder/editor-skills"), { recursive: true });
+        mkdirSync(join(home, ".ezcoder/editor-skills"), { recursive: true });
+        writeFileSync(join(cwd, ".ezcoder/editor-skills/alpha.md"), "# a\n\nfrom project\n");
+        writeFileSync(join(home, ".ezcoder/editor-skills/alpha.md"), "# a\n\nfrom user\n");
+        const r = discoverSkills({ cwd, homeDir: home, bundled: BUNDLED });
+        const alpha = r.find((s) => s.name === "alpha");
+        expect(alpha?.origin).toBe("user");
+    });
+    it("reads YAML frontmatter for name + description", () => {
+        const cwd = tmp("gg-skills-cwd-");
+        const home = tmp("gg-skills-home-");
+        mkdirSync(join(cwd, ".ezcoder/editor-skills"), { recursive: true });
+        const md = '---\nname: my-skill\ndescription: "Use when X happens."\n---\n\n# My Skill\n\nBody.\n';
+        writeFileSync(join(cwd, ".ezcoder/editor-skills/anything.md"), md);
+        const r = discoverSkills({ cwd, homeDir: home, bundled: BUNDLED });
+        const s = r.find((s) => s.name === "my-skill");
+        expect(s).toBeTruthy();
+        expect(s?.description).toBe("Use when X happens.");
+        // Content retains the frontmatter as authored — read_skill returns the
+        // full file so the agent can see metadata if it cares to.
+        expect(s?.content.startsWith("---\nname:")).toBe(true);
+    });
+    it("frontmatter falls back to filename + body extraction when keys missing", () => {
+        const cwd = tmp("gg-skills-cwd-");
+        const home = tmp("gg-skills-home-");
+        mkdirSync(join(cwd, ".ezcoder/editor-skills"), { recursive: true });
+        writeFileSync(join(cwd, ".ezcoder/editor-skills/foo.md"), "---\nother: stuff\n---\n\nA body line.\n");
+        const r = discoverSkills({ cwd, homeDir: home, bundled: BUNDLED });
+        const s = r.find((s) => s.name === "foo");
+        expect(s?.description).toBe("A body line.");
+    });
+    it("loads bundle-layout skill (<name>/SKILL.md)", () => {
+        const cwd = tmp("gg-skills-cwd-");
+        const home = tmp("gg-skills-home-");
+        mkdirSync(join(cwd, ".ezcoder/editor-skills/bundled-name"), { recursive: true });
+        writeFileSync(join(cwd, ".ezcoder/editor-skills/bundled-name/SKILL.md"), "---\nname: real-name\ndescription: From SKILL.md\n---\n\nBody.\n");
+        const r = discoverSkills({ cwd, homeDir: home, bundled: BUNDLED });
+        const s = r.find((s) => s.name === "real-name");
+        expect(s?.origin).toBe("project");
+        expect(s?.description).toBe("From SKILL.md");
+        expect(s?.path?.endsWith("SKILL.md")).toBe(true);
+    });
+    it("discovers from .ezcoder/skills/ as well as legacy .ezcoder/editor-skills/", () => {
+        const cwd = tmp("gg-skills-cwd-");
+        const home = tmp("gg-skills-home-");
+        mkdirSync(join(cwd, ".ezcoder/skills"), { recursive: true });
+        writeFileSync(join(cwd, ".ezcoder/skills/ecosystem.md"), "---\nname: ecosystem\ndescription: skills.sh format\n---\nBody\n");
+        const r = discoverSkills({ cwd, homeDir: home, bundled: BUNDLED });
+        expect(r.find((s) => s.name === "ecosystem")?.origin).toBe("project");
+    });
+});
+describe("parseFrontmatter / stripFrontmatter", () => {
+    it("empty frontmatter when no leading ---", () => {
+        expect(parseFrontmatter("# heading\n\nbody")).toEqual({});
+    });
+    it("unterminated frontmatter is ignored", () => {
+        expect(parseFrontmatter("---\nname: x\n")).toEqual({});
+    });
+    it("strips quotes around values", () => {
+        const fm = parseFrontmatter("---\nname: \"with: colon\"\ndescription: 'single'\n---\n");
+        expect(fm.name).toBe("with: colon");
+        expect(fm.description).toBe("single");
+    });
+    it("stripFrontmatter removes the block + leading newline", () => {
+        const md = "---\nname: x\n---\n# heading\n";
+        expect(stripFrontmatter(md)).toBe("# heading\n");
+    });
+    it("stripFrontmatter is a no-op when no frontmatter", () => {
+        expect(stripFrontmatter("# h\n")).toBe("# h\n");
+    });
+});
+//# sourceMappingURL=skills-loader.test.js.map

package/dist/core/skills-loader.test.js.map

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

package/dist/core/skin-grade.d.ts

@@ -0,0 +1,62 @@
+export interface SkinGradeColorBalance {
+    shadows: [number, number, number];
+    midtones: [number, number, number];
+    highlights: [number, number, number];
+}
+export interface SkinGradeSelectiveColor {
+    reds: [number, number, number, number];
+    yellows: [number, number, number, number];
+}
+export interface SkinGradeEq {
+    saturation: number;
+    contrast: number;
+    brightness: number;
+}
+export interface SkinGradeCdl {
+    slope: [number, number, number];
+    offset: [number, number, number];
+    power: [number, number, number];
+    saturation: number;
+}
+export interface SkinGrade {
+    colorbalance: SkinGradeColorBalance;
+    selectivecolor: SkinGradeSelectiveColor;
+    eq: SkinGradeEq;
+    cdl: SkinGradeCdl;
+    /** Confidence 0-1; below 0.4 means "I'm guessing" — don't apply blindly. */
+    confidence: number;
+    /** ≤120 char rationale. */
+    why: string;
+}
+export interface SkinGradeOptions {
+    apiKey?: string;
+    model?: string;
+    detail?: "low" | "high";
+    signal?: AbortSignal;
+}
+export declare function deriveSkinGrade(referenceFramePath: string, targetFramePath: string, opts?: SkinGradeOptions): Promise<SkinGrade>;
+/**
+ * Parse a model JSON response into a SkinGrade with all values clamped to
+ * safe ranges. Tolerates missing fields (falls back to neutral) and prose
+ * wrapping around the JSON.
+ */
+export declare function parseSkinGradeResponse(content: string): SkinGrade;
+/**
+ * Build the ffmpeg `-vf` filter string for a SkinGrade. Returns an empty
+ * string when the grade is effectively neutral (no-op pass-through).
+ */
+export declare function buildSkinGradeFilter(grade: SkinGrade): string;
+export interface ApplySkinGradeOptions {
+    videoCodec?: string;
+    crf?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Spawn ffmpeg to render `inputPath` through a SkinGrade filter chain into
+ * `outputPath`. Audio is copied. Returns the absolute output path.
+ *
+ * If the grade is effectively neutral, ffmpeg still re-encodes (since the
+ * caller asked for an output file) but with no `-vf` filter.
+ */
+export declare function applySkinGrade(inputPath: string, outputPath: string, grade: SkinGrade, opts?: ApplySkinGradeOptions): Promise<string>;
+//# sourceMappingURL=skin-grade.d.ts.map

package/dist/core/skin-grade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skin-grade.d.ts","sourceRoot":"","sources":["../../src/core/skin-grade.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,qBAAqB,CAAC;IACpC,cAAc,EAAE,uBAAuB,CAAC;IACxC,EAAE,EAAE,WAAW,CAAC;IAChB,GAAG,EAAE,YAAY,CAAC;IAClB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb;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,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAiDD,wBAAsB,eAAe,CACnC,kBAAkB,EAAE,MAAM,EAC1B,eAAe,EAAE,MAAM,EACvB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,SAAS,CAAC,CAoDpB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CA+CjE;AAmBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAa7D;AAwBD,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,SAAS,EAChB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,MAAM,CAAC,CAYjB"}

package/dist/core/skin-grade.js

@@ -0,0 +1,271 @@
+/**
+ * Skin-tone matching grade derivation.
+ *
+ * Resolve's scripting API can only do CDL/LUT/copy-grade. The biggest gap for
+ * creators is *skin-tone matching across clips* — making a face look the same
+ * warmth, exposure, and saturation as a reference shot. Power windows,
+ * qualifiers, and curves aren't scriptable.
+ *
+ * This module asks GPT-4o to compare two frames and emit a structured grade
+ * tuned for skin tones (warmth in reds + yellows). The grade ships in two
+ * complementary representations:
+ *
+ *   1. ffmpeg filter chain — `colorbalance` + `selectivecolor` + `eq`. Used
+ *      by `grade_skin_tones` to bake a graded file (works on every host).
+ *   2. CDL approximation — slope/offset/power/saturation. Used by
+ *      `match_clip_color` to pipe through `set_primary_correction` (Resolve
+ *      only, non-baked).
+ *
+ * Only one vision call covers both paths.
+ */
+import { readFileSync } from "node:fs";
+import { resolveApiKey } from "./auth/api-keys.js";
+import { runFfmpeg } from "./media/ffmpeg.js";
+const SYSTEM = `You match the SKIN TONE LOOK of a target frame to a reference frame.
+
+Skin tones live primarily in the REDS and YELLOWS of the image. Your job is
+to bring the target's faces toward the reference's faces — warmth (R/Y
+balance), exposure (luma), and saturation. Don't grade the whole image
+into a different look; grade the skin.
+
+Output a JSON object with these EXACT keys (no extras, no prose):
+{
+  "colorbalance": {
+    "shadows":    [r, g, b],
+    "midtones":   [r, g, b],
+    "highlights": [r, g, b]
+  },
+  "selectivecolor": {
+    "reds":    [c, m, y, k],
+    "yellows": [c, m, y, k]
+  },
+  "eq": {
+    "saturation": <number>,
+    "contrast":   <number>,
+    "brightness": <number>
+  },
+  "cdl": {
+    "slope":      [r, g, b],
+    "offset":     [r, g, b],
+    "power":      [r, g, b],
+    "saturation": <number>
+  },
+  "confidence": <0..1>,
+  "why": "<≤120 char rationale>"
+}
+
+Neutral (no change) values:
+  colorbalance.shadows / midtones / highlights = [0, 0, 0]
+  selectivecolor.reds / yellows                = [0, 0, 0, 0]
+  eq.saturation = 1, eq.contrast = 1, eq.brightness = 0
+  cdl.slope = [1,1,1], cdl.offset = [0,0,0], cdl.power = [1,1,1], cdl.saturation = 1
+
+Conventions:
+  - colorbalance components: ±0.3 typical, ±0.5 max. Positive R warms, positive B cools.
+  - selectivecolor components: ±0.3 typical. Positive C/M/Y/K shifts the reds/yellows toward that primary.
+  - eq.saturation 0.5..1.5 typical. eq.contrast 0.8..1.2 typical. eq.brightness ±0.1 typical.
+  - cdl is the SAME correction expressed as slope/offset/power so a host that only takes CDL can apply it.
+
+Stay subtle. If the two frames look indistinguishable, return neutral values + low confidence. The CDL must approximate the same look — don't let the two paths drift.`;
+export async function deriveSkinGrade(referenceFramePath, targetFramePath, opts = {}) {
+    const apiKey = opts.apiKey ?? resolveApiKey("OPENAI_API_KEY", "openai");
+    if (!apiKey)
+        throw new Error("OPENAI_API_KEY required for skin-tone matching.");
+    const refB64 = readFileSync(referenceFramePath).toString("base64");
+    const tgtB64 = readFileSync(targetFramePath).toString("base64");
+    const detail = opts.detail ?? "low";
+    const model = opts.model ?? "gpt-4o-mini";
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: SYSTEM },
+            {
+                role: "user",
+                content: [
+                    { type: "text", text: "REFERENCE (skin look you want):" },
+                    {
+                        type: "image_url",
+                        image_url: { url: `data:image/jpeg;base64,${refB64}`, detail },
+                    },
+                    { type: "text", text: "TARGET (needs to match the reference):" },
+                    {
+                        type: "image_url",
+                        image_url: { url: `data:image/jpeg;base64,${tgtB64}`, 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("skin-grade: empty model response");
+    return parseSkinGradeResponse(content);
+}
+/**
+ * Parse a model JSON response into a SkinGrade with all values clamped to
+ * safe ranges. Tolerates missing fields (falls back to neutral) and prose
+ * wrapping around the JSON.
+ */
+export function parseSkinGradeResponse(content) {
+    const start = content.indexOf("{");
+    const end = content.lastIndexOf("}");
+    if (start < 0 || end < start) {
+        throw new Error("skin-grade: no JSON object in response");
+    }
+    const parsed = JSON.parse(content.slice(start, end + 1));
+    const cb = (parsed.colorbalance ?? {});
+    const sc = (parsed.selectivecolor ?? {});
+    const eq = (parsed.eq ?? {});
+    const cdl = (parsed.cdl ?? {});
+    const triple3 = (v, fb, lo, hi) => clampTriple(toTriple(v, fb), lo, hi);
+    const quad4 = (v, fb, lo, hi) => clampQuad(toQuad(v, fb), lo, hi);
+    return {
+        colorbalance: {
+            shadows: triple3(cb.shadows, [0, 0, 0], -0.5, 0.5),
+            midtones: triple3(cb.midtones, [0, 0, 0], -0.5, 0.5),
+            highlights: triple3(cb.highlights, [0, 0, 0], -0.5, 0.5),
+        },
+        selectivecolor: {
+            reds: quad4(sc.reds, [0, 0, 0, 0], -1, 1),
+            yellows: quad4(sc.yellows, [0, 0, 0, 0], -1, 1),
+        },
+        eq: {
+            saturation: clamp(num(eq.saturation, 1), 0, 3),
+            contrast: clamp(num(eq.contrast, 1), 0, 3),
+            brightness: clamp(num(eq.brightness, 0), -0.3, 0.3),
+        },
+        cdl: {
+            slope: triple3(cdl.slope, [1, 1, 1], 0.5, 2),
+            offset: triple3(cdl.offset, [0, 0, 0], -0.3, 0.3),
+            power: triple3(cdl.power, [1, 1, 1], 0.5, 2),
+            saturation: clamp(num(cdl.saturation, 1), 0, 3),
+        },
+        confidence: clamp(num(parsed.confidence, 0), 0, 1),
+        why: String(parsed.why ?? "").slice(0, 200),
+    };
+}
+const NEUTRAL_CB = {
+    shadows: [0, 0, 0],
+    midtones: [0, 0, 0],
+    highlights: [0, 0, 0],
+};
+const NEUTRAL_SC = {
+    reds: [0, 0, 0, 0],
+    yellows: [0, 0, 0, 0],
+};
+const NEUTRAL_EQ = {
+    saturation: 1,
+    contrast: 1,
+    brightness: 0,
+};
+/**
+ * Build the ffmpeg `-vf` filter string for a SkinGrade. Returns an empty
+ * string when the grade is effectively neutral (no-op pass-through).
+ */
+export function buildSkinGradeFilter(grade) {
+    const parts = [];
+    if (!eqDeep(grade.colorbalance, NEUTRAL_CB)) {
+        parts.push(buildColorBalance(grade.colorbalance));
+    }
+    if (!eqDeep(grade.selectivecolor, NEUTRAL_SC)) {
+        parts.push(buildSelectiveColor(grade.selectivecolor));
+    }
+    if (!eqDeep(grade.eq, NEUTRAL_EQ)) {
+        parts.push(buildEq(grade.eq));
+    }
+    return parts.join(",");
+}
+function buildColorBalance(cb) {
+    const [rs, gs, bs] = cb.shadows;
+    const [rm, gm, bm] = cb.midtones;
+    const [rh, gh, bh] = cb.highlights;
+    return ("colorbalance=" +
+        `rs=${fmt(rs)}:gs=${fmt(gs)}:bs=${fmt(bs)}:` +
+        `rm=${fmt(rm)}:gm=${fmt(gm)}:bm=${fmt(bm)}:` +
+        `rh=${fmt(rh)}:gh=${fmt(gh)}:bh=${fmt(bh)}`);
+}
+function buildSelectiveColor(sc) {
+    const r = sc.reds.map(fmt).join(" ");
+    const y = sc.yellows.map(fmt).join(" ");
+    return `selectivecolor=reds=${r}:yellows=${y}`;
+}
+function buildEq(eq) {
+    return `eq=saturation=${fmt(eq.saturation)}:contrast=${fmt(eq.contrast)}:brightness=${fmt(eq.brightness)}`;
+}
+/**
+ * Spawn ffmpeg to render `inputPath` through a SkinGrade filter chain into
+ * `outputPath`. Audio is copied. Returns the absolute output path.
+ *
+ * If the grade is effectively neutral, ffmpeg still re-encodes (since the
+ * caller asked for an output file) but with no `-vf` filter.
+ */
+export async function applySkinGrade(inputPath, outputPath, grade, opts = {}) {
+    const filter = buildSkinGradeFilter(grade);
+    const codec = opts.videoCodec ?? "libx264";
+    const crf = String(opts.crf ?? 18);
+    const args = ["-i", inputPath];
+    if (filter)
+        args.push("-vf", filter);
+    args.push("-c:v", codec, "-crf", crf, "-c:a", "copy", outputPath);
+    const r = await runFfmpeg(args, { signal: opts.signal });
+    if (r.code !== 0) {
+        throw new Error(`ffmpeg skin-grade failed: ${tail(r.stderr)}`);
+    }
+    return outputPath;
+}
+function fmt(n) {
+    // Trim trailing zeros, but keep at least one digit after the decimal so
+    // ffmpeg parses it as a float consistently.
+    if (!Number.isFinite(n))
+        return "0";
+    const rounded = Math.round(n * 10000) / 10000;
+    return String(rounded);
+}
+function toTriple(v, fb) {
+    if (Array.isArray(v) && v.length === 3) {
+        return [num(v[0], fb[0]), num(v[1], fb[1]), num(v[2], fb[2])];
+    }
+    return fb;
+}
+function toQuad(v, fb) {
+    if (Array.isArray(v) && v.length === 4) {
+        return [num(v[0], fb[0]), num(v[1], fb[1]), num(v[2], fb[2]), num(v[3], fb[3])];
+    }
+    return fb;
+}
+function clampTriple(v, lo, hi) {
+    return [clamp(v[0], lo, hi), clamp(v[1], lo, hi), clamp(v[2], lo, hi)];
+}
+function clampQuad(v, lo, hi) {
+    return [clamp(v[0], lo, hi), clamp(v[1], lo, hi), clamp(v[2], lo, hi), clamp(v[3], lo, hi)];
+}
+function num(v, fb) {
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) ? n : fb;
+}
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}
+function eqDeep(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function tail(s) {
+    return s.split("\n").filter(Boolean).slice(-3).join(" | ").slice(-300);
+}
+//# sourceMappingURL=skin-grade.js.map