@aibridge/cli 0.6.0 → 0.8.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as runCli, t as buildContext } from "./context-F8WLXzPv.mjs";
+import { r as runCli, t as buildContext } from "./context-DJtEcg6f.mjs";
 //#region src/cli.ts
 await runCli(buildContext(process), process.argv.slice(2));
 //#endregion

package/dist/{context-F8WLXzPv.mjs → context-DJtEcg6f.mjs}

@@ -2,7 +2,8 @@ import { createRequire } from "node:module";
 import { ExitCode, buildApplication, buildCommand, buildRouteMap, run } from "@stricli/core";
 import { appendFileSync, closeSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import sharp from "sharp";
 import * as agy from "@aibridge/driver-agy";
 import { fetchAgyQuota, findModelQuota } from "@aibridge/driver-agy";
 import * as claude from "@aibridge/driver-claude";
@@ -186,12 +187,20 @@ const IMAGE_GEN_FORMATS = /* @__PURE__ */ new Map([
 	["codex", "png"],
 	["grok", "jpg"]
 ]);
+const IMAGE_ALPHA = /* @__PURE__ */ new Map([
+	["agy", "chroma"],
+	["codex", "native"],
+	["grok", "chroma"]
+]);
 function supportsImageGen(resolved) {
 	return IMAGE_GEN_FORMATS.has(resolved.spec.backend);
 }
 function imageFormatFor(resolved) {
 	return IMAGE_GEN_FORMATS.get(resolved.spec.backend);
 }
+function imageAlphaFor(resolved) {
+	return IMAGE_ALPHA.get(resolved.spec.backend);
+}
 const EFFORTS_SET = /* @__PURE__ */ new Set([
 	"low",
 	"medium",
@@ -231,6 +240,10 @@ function listModelHelpLines(opts = {}) {
 		if (opts.imageOnly && !IMAGE_GEN_FORMATS.has(spec.backend)) continue;
 		lines.push(`  ${slug}`);
 		lines.push(`    ${spec.brief}`);
+		if (opts.imageOnly) {
+			const alpha = IMAGE_ALPHA.get(spec.backend);
+			if (alpha !== void 0) lines.push(`    --transparent: ${alpha === "native" ? "native alpha (soft edges)" : "chroma-keyed (binary edges)"}`);
+		}
 	}
 	return lines;
 }
@@ -299,6 +312,73 @@ function getDriver(backend) {
 	return driver;
 }
 //#endregion
+//#region src/transparency.ts
+const CHROMA_CLAUSE = "The entire background must be a perfectly flat solid #00ff00 chroma-key green. The background must be one uniform colour with no shadows, gradients, texture, reflections, or lighting variation. Keep the subject fully separated from the background with crisp edges. Do not use #00ff00 or any similar green anywhere on the subject. No cast shadow, no contact shadow, no reflection.";
+const NATIVE_ALPHA_CLAUSE = "Render the subject on a fully transparent background — PNG with a real alpha channel, no backdrop, no canvas colour, no cast shadow.";
+/**
+* Background-scoped only. `transparent` on its own describes subjects far more
+* often than backdrops ("transparent glass bottle", "goldfish in a transparent
+* bowl"), and refusing those would force `--transparent` onto a brief the chroma
+* clause actively fights.
+*/
+const TRANSPARENT_BACKGROUND = /\b(transparent (background|backdrop)|no background|without a background|alpha channel|chroma[- ]?key)/i;
+/** Does the prompt ask for a see-through *background* (as opposed to a see-through subject)? */
+function mentionsTransparentBackground(prompt) {
+	return TRANSPARENT_BACKGROUND.test(prompt);
+}
+const GREEN_MIN = 90;
+/**
+* How far green must lead both red and blue for a pixel to count as backdrop.
+* Position, not geometry, decides: a saturated green *subject* is keyed away too.
+* That is inherent to chroma keying — CHROMA_CLAUSE tells the model not to put
+* green on the subject, and a native-alpha seat is the answer when it must be.
+*/
+const DOMINANCE = 40;
+async function chromaKeyToPng(src, dest) {
+	const { data, info } = await sharp(src).toColourspace("srgb").ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+	const { width, height, channels } = info;
+	if (channels !== 4) throw new Error(`chroma key expected 4-channel RGBA, got ${channels} channels from ${src}`);
+	const totalPixels = width * height;
+	if (totalPixels === 0) {
+		await sharp(data, { raw: {
+			width,
+			height,
+			channels
+		} }).png({ compressionLevel: 9 }).toFile(dest);
+		return { transparentRatio: 0 };
+	}
+	const mask = new Uint8Array(totalPixels);
+	let keyedCount = 0;
+	for (let i = 0; i < totalPixels; i++) {
+		const offset = i * channels;
+		const r = data[offset] ?? 0;
+		const g = data[offset + 1] ?? 0;
+		const b = data[offset + 2] ?? 0;
+		if (g >= GREEN_MIN && g - r >= DOMINANCE && g - b >= DOMINANCE) {
+			data[offset + 3] = 0;
+			mask[i] = 1;
+			keyedCount++;
+		}
+	}
+	for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+		const idx = y * width + x;
+		if (mask[idx] === 1) continue;
+		const offset = idx * channels;
+		const r = data[offset] ?? 0;
+		const g = data[offset + 1] ?? 0;
+		const b = data[offset + 2] ?? 0;
+		if (g - r >= 20 && g - b >= 20) {
+			if (x > 0 && mask[idx - 1] === 1 || x < width - 1 && mask[idx + 1] === 1 || y > 0 && mask[idx - width] === 1 || y < height - 1 && mask[idx + width] === 1) data[offset + 1] = Math.max(r, b);
+		}
+	}
+	await sharp(data, { raw: {
+		width,
+		height,
+		channels
+	} }).png({ compressionLevel: 9 }).toFile(dest);
+	return { transparentRatio: keyedCount / totalPixels };
+}
+//#endregion
 //#region src/commands/image-gen/impl.ts
 const MIN_REAL_BYTES_CODEX = 1e5;
 const MIN_REAL_BYTES_TOOL = 1e4;
@@ -314,8 +394,15 @@ async function imageGen$1(flags, prompt) {
 	if (model.spec.backend === "codex" && model.effort) return fail(`effort "-${model.effort}" has no effect on image-gen (the image tool renders, not the seat model); pass the un-suffixed slug "${model.spec.slug}" instead.`);
 	const expected = imageFormatFor(model);
 	if (expected === void 0) return fail(formatImageGenModelError(inputSlug, model));
-	const label = expected === "png" ? "PNG" : "JPEG";
-	if (!(expected === "png" ? /\.png$/i.test(flags.out) : /\.jpe?g$/i.test(flags.out))) return fail(`--out "${flags.out}" must end in ${expected === "png" ? ".png" : ".jpg or .jpeg"} — the ${model.spec.slug} seat renders ${label} and aibridge does not convert.`);
+	const alpha = imageAlphaFor(model);
+	if (alpha === void 0) return fail(formatImageGenModelError(inputSlug, model));
+	const outFormat = flags.transparent ? "png" : expected;
+	const label = outFormat === "png" ? "PNG" : "JPEG";
+	if (!(outFormat === "png" ? /\.png$/i.test(flags.out) : /\.jpe?g$/i.test(flags.out))) {
+		const reason = flags.transparent && expected === "jpg" ? "--transparent always writes PNG" : `the ${model.spec.slug} seat renders ${label} and aibridge does not convert`;
+		return fail(`--out "${flags.out}" must end in ${outFormat === "png" ? ".png" : ".jpg or .jpeg"} — ${reason}.`);
+	}
+	if (!flags.transparent && alpha === "chroma" && mentionsTransparentBackground(prompt)) return fail(`the prompt asks for a transparent background but the ${model.spec.slug} seat cannot render alpha — pass --transparent (aibridge chroma-keys it locally, binary edges) or use a native-alpha seat (openai-codex/*). Re-run with --transparent to proceed.`);
 	let aspectRatio;
 	if (flags.aspectRatio !== void 0) {
 		const m = flags.aspectRatio.match(/^(\d+)\s*:\s*(\d+)$/);
@@ -334,9 +421,10 @@ async function imageGen$1(flags, prompt) {
 	if (!driver.generateImage) return fail(formatImageGenModelError(inputSlug, model));
 	const minBytes = model.spec.backend === "codex" ? MIN_REAL_BYTES_CODEX : MIN_REAL_BYTES_TOOL;
 	const work = mkdtempSync(join(tmpdir(), "aibridge-imagegen-"));
+	const effectivePrompt = flags.transparent ? `${prompt} ${alpha === "chroma" ? CHROMA_CLAUSE : NATIVE_ALPHA_CLAUSE}` : prompt;
 	try {
 		let outcome = await driver.generateImage({
-			prompt,
+			prompt: effectivePrompt,
 			workDir: work,
 			backendModel: backendModelId(model),
 			effort: model.effort,
@@ -347,7 +435,7 @@ async function imageGen$1(flags, prompt) {
 			minBytes
 		});
 		if (model.spec.backend === "codex" && outcome.kind === "suspect") outcome = await driver.generateImage({
-			prompt,
+			prompt: effectivePrompt,
 			workDir: work,
 			backendModel: backendModelId(model),
 			effort: model.effort,
@@ -362,10 +450,21 @@ async function imageGen$1(flags, prompt) {
 		if (outcome.kind === "suspect") return fail(model.spec.backend === "agy" ? "agy produced no usable image. Re-run with a simpler prompt, or check Antigravity image access." : model.spec.backend === "grok" ? "grok produced no usable image. Check SuperGrok image access and re-run with a simpler prompt." : "codex produced only a tiny/code-drawn image, not a real render. Try a clearer, simpler prompt.");
 		const local = join(work, "result.bin");
 		copyFileSync(outcome.path, local);
-		const dims = imageSize(local);
-		const actual = pngSize(local) ? "png" : jpegSize(local) ? "jpg" : null;
-		if (actual !== null && actual !== expected) this.process.stderr.write(`aibridge image-gen: expected a ${label} render from this seat but got ${actual === "png" ? "PNG" : "JPEG"}; wrote the raw bytes to ${outPath} anyway — the extension does not match the contents.\n`);
-		copyFileSync(local, outPath);
+		let artefact = local;
+		let transparency = null;
+		if (flags.transparent) if ((await sharp(local).metadata()).hasAlpha === true) transparency = "native";
+		else {
+			const keyed = join(work, "keyed.png");
+			const { transparentRatio } = await chromaKeyToPng(local, keyed);
+			transparency = "chroma";
+			if (transparentRatio < .02) this.process.stderr.write(`aibridge image-gen: --transparent keyed only ${(transparentRatio * 100).toFixed(1)}% of the image — the model likely ignored the chroma-key instruction; wrote it anyway. Re-run, or use a native-alpha seat.\n`);
+			artefact = keyed;
+		}
+		const dims = imageSize(artefact);
+		const actual = pngSize(artefact) ? "png" : jpegSize(artefact) ? "jpg" : null;
+		if (actual !== null && actual !== outFormat) this.process.stderr.write(`aibridge image-gen: expected a ${label} render from this seat but got ${actual === "png" ? "PNG" : "JPEG"}; wrote the raw bytes to ${outPath} anyway — the extension does not match the contents.\n`);
+		mkdirSync(dirname(outPath), { recursive: true });
+		copyFileSync(artefact, outPath);
 		const bytes = statSync(outPath).size;
 		if (flags.json) this.process.stdout.write(`${JSON.stringify({
 			out: outPath,
@@ -375,12 +474,14 @@ async function imageGen$1(flags, prompt) {
 			aspectRatio: flags.aspectRatio ?? null,
 			model: model.spec.slug,
 			backend: model.spec.backend,
+			transparency,
 			real: true
 		})}\n`);
 		else {
 			const kb = Math.round(bytes / 1024);
 			const dimStr = dims ? `${dims.width}x${dims.height}, ` : "";
-			this.process.stdout.write(`✓ Wrote ${outPath} (${dimStr}${kb} KB, ${model.spec.slug})\n`);
+			const transparencyStr = flags.transparent ? `, transparency: ${transparency === "native" ? "native alpha" : "chroma-keyed"}` : "";
+			this.process.stdout.write(`✓ Wrote ${outPath} (${dimStr}${kb} KB, ${model.spec.slug}${transparencyStr})\n`);
 		}
 	} finally {
 		rmSync(work, {
@@ -459,7 +560,12 @@ const imageGen = buildCommand({
 			out: {
 				kind: "parsed",
 				parse: String,
-				brief: "Path to write the image — extension must match the seat format (.png for codex, .jpg for agy/grok)"
+				brief: "Path to write the image — extension must match the seat format (.png for codex or any --transparent run, .jpg for agy/grok otherwise)"
+			},
+			transparent: {
+				kind: "boolean",
+				withNegated: false,
+				brief: "Transparent background: native alpha where the seat has it, chroma-keyed otherwise — always writes PNG"
 			},
 			aspectRatio: {
 				kind: "parsed",
@@ -876,6 +982,10 @@ function modelsImpl(flags) {
 				spec,
 				effort: void 0
 			}) ?? null,
+			imageAlpha: imageAlphaFor({
+				spec,
+				effort: void 0
+			}) ?? null,
 			brief: spec.brief
 		}));
 		this.process.stdout.write(`${JSON.stringify(jsonOutput)}\n`);
@@ -900,7 +1010,12 @@ function modelsImpl(flags) {
 				spec,
 				effort: void 0
 			});
-			segments.push(`image: ${img ?? "—"}`);
+			const alpha = imageAlphaFor({
+				spec,
+				effort: void 0
+			});
+			const imageStr = img ? `${img} (alpha: ${alpha ?? "—"})` : "—";
+			segments.push(`image: ${imageStr}`);
 			segments.push(`id: ${spec.backendModel}`);
 			this.process.stdout.write(`    ${segments.join(" · ")}\n`);
 			this.process.stdout.write(`    ${spec.brief}\n`);

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { S as supportsImageGen, _ as backendModelId, a as readRunLogs, b as listModelHelpLines, c as evaluateCodexPreflight, d as renderPreflightRefusal, f as delegate, g as MODELS, h as positiveIntSeconds, i as listRuns, l as preflightCodex, m as nonEmptyPrompt, n as app, o as startRun, p as getDriver, r as runCli, s as evaluateAgyPreflight, t as buildContext, u as preflightModel, v as formatImageGenModelError, x as resolveModel, y as formatUnknownModelError } from "./context-F8WLXzPv.mjs";
+import { S as supportsImageGen, _ as backendModelId, a as readRunLogs, b as listModelHelpLines, c as evaluateCodexPreflight, d as renderPreflightRefusal, f as delegate, g as MODELS, h as positiveIntSeconds, i as listRuns, l as preflightCodex, m as nonEmptyPrompt, n as app, o as startRun, p as getDriver, r as runCli, s as evaluateAgyPreflight, t as buildContext, u as preflightModel, v as formatImageGenModelError, x as resolveModel, y as formatUnknownModelError } from "./context-DJtEcg6f.mjs";
 export { MODELS, app, backendModelId, buildContext, delegate, evaluateAgyPreflight, evaluateCodexPreflight, formatImageGenModelError, formatUnknownModelError, getDriver, listModelHelpLines, listRuns, nonEmptyPrompt, positiveIntSeconds, preflightCodex, preflightModel, readRunLogs, renderPreflightRefusal, resolveModel, runCli, startRun, supportsImageGen };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibridge/cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "CLI that bridges tasks to AI CLIs on your machine (plan / implement / review / subagent / image-gen)",
   "type": "module",
   "license": "MIT",
@@ -35,11 +35,12 @@
   ],
   "dependencies": {
     "@stricli/core": "1.3.0",
-    "@aibridge/proc": "0.6.0",
-    "@aibridge/driver-codex": "0.6.0",
-    "@aibridge/driver-agy": "0.6.0",
-    "@aibridge/driver-grok": "0.6.0",
-    "@aibridge/driver-claude": "0.6.0"
+    "sharp": "^0.35.3",
+    "@aibridge/proc": "0.8.0",
+    "@aibridge/driver-agy": "0.8.0",
+    "@aibridge/driver-codex": "0.8.0",
+    "@aibridge/driver-claude": "0.8.0",
+    "@aibridge/driver-grok": "0.8.0"
   },
   "devDependencies": {
     "tsdown": "0.22.14"

package/src/commands/image-gen/command.ts

@@ -25,7 +25,13 @@ export const imageGen = buildCommand({
         kind: 'parsed',
         parse: String,
         brief:
-          'Path to write the image — extension must match the seat format (.png for codex, .jpg for agy/grok)',
+          'Path to write the image — extension must match the seat format (.png for codex or any --transparent run, .jpg for agy/grok otherwise)',
+      },
+      transparent: {
+        kind: 'boolean',
+        withNegated: false,
+        brief:
+          'Transparent background: native alpha where the seat has it, chroma-keyed otherwise — always writes PNG',
       },
       aspectRatio: {
         kind: 'parsed',

package/src/commands/image-gen/impl.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import type { LocalContext } from '../../context.ts';
+import imageGen, { type ImageGenFlags } from './impl.ts';
+
+/**
+ * Both refusals below must land before any backend spawns — that is the whole
+ * point of them, so these tests deliberately use a context with no driver stub:
+ * if validation ever moves after `getDriver`, they fail by trying to run a real CLI.
+ */
+const ctx = (): { ctx: LocalContext; stderr: () => string } => {
+  let stderr = '';
+  const fake = {
+    process: {
+      stderr: {
+        write: (s: string) => {
+          stderr += s;
+          return true;
+        },
+      },
+      stdout: { write: () => true },
+      cwd: () => '/tmp',
+      exitCode: 0,
+    },
+  };
+  return { ctx: fake as unknown as LocalContext, stderr: () => stderr };
+};
+
+const flags = (over: Partial<ImageGenFlags>): ImageGenFlags => ({
+  model: 'xai-grok/grok-4.6',
+  out: '/tmp/out.jpg',
+  json: false,
+  transparent: false,
+  ...over,
+});
+
+describe('image-gen validation', () => {
+  it('refuses --transparent with a .jpg --out', async () => {
+    const { ctx: c, stderr } = ctx();
+    await imageGen.call(c, flags({ transparent: true }), 'a fox');
+    expect(stderr()).toContain('must end in .png');
+    expect(stderr()).toContain('--transparent always writes PNG');
+    expect(c.process.exitCode).toBe(1);
+  });
+
+  it('refuses a transparent-background prompt on a chroma seat without the flag', async () => {
+    const { ctx: c, stderr } = ctx();
+    await imageGen.call(c, flags({}), 'a fox on a transparent background');
+    expect(stderr()).toContain('cannot render alpha');
+    expect(stderr()).toContain('--transparent');
+    expect(c.process.exitCode).toBe(1);
+  });
+
+  it('does not refuse a see-through subject', async () => {
+    const { ctx: c, stderr } = ctx();
+    // A transparent *subject* is a normal brief; only the background phrasing is
+    // a capability mismatch. This one must fall through to the .jpg/.png check.
+    await imageGen.call(c, flags({ out: '/tmp/out.png' }), 'a transparent glass bottle');
+    expect(stderr()).not.toContain('cannot render alpha');
+    expect(stderr()).toContain('must end in .jpg or .jpeg');
+  });
+});

package/src/commands/image-gen/impl.ts

@@ -2,6 +2,7 @@ import {
   closeSync,
   copyFileSync,
   existsSync,
+  mkdirSync,
   mkdtempSync,
   openSync,
   readSync,
@@ -9,7 +10,8 @@ import {
   statSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import sharp from 'sharp';
 import type { LocalContext } from '../../context.ts';
 import type { ImageResult } from '../../driver.ts';
 import { getDriver } from '../../drivers.ts';
@@ -17,10 +19,18 @@ import {
   backendModelId,
   formatImageGenModelError,
   formatUnknownModelError,
+  type ImageFormat,
+  imageAlphaFor,
   imageFormatFor,
   resolveModel,
   supportsImageGen,
 } from '../../models.ts';
+import {
+  CHROMA_CLAUSE,
+  chromaKeyToPng,
+  mentionsTransparentBackground,
+  NATIVE_ALPHA_CLAUSE,
+} from '../../transparency.ts';
 
 export interface ImageGenFlags {
   readonly model: string;
@@ -29,6 +39,7 @@ export interface ImageGenFlags {
   readonly image?: string;
   readonly timeout?: number;
   readonly json: boolean;
+  readonly transparent: boolean;
 }
 
 const MIN_REAL_BYTES_CODEX = 100_000;
@@ -58,11 +69,27 @@ export default async function imageGen(
   const expected = imageFormatFor(model);
   if (expected === undefined) return fail(formatImageGenModelError(inputSlug, model));
 
-  const label = expected === 'png' ? 'PNG' : 'JPEG';
-  const extValid = expected === 'png' ? /\.png$/i.test(flags.out) : /\.jpe?g$/i.test(flags.out);
+  const alpha = imageAlphaFor(model);
+  if (alpha === undefined) return fail(formatImageGenModelError(inputSlug, model));
+
+  const outFormat: ImageFormat = flags.transparent ? 'png' : expected;
+  const label = outFormat === 'png' ? 'PNG' : 'JPEG';
+  const extValid = outFormat === 'png' ? /\.png$/i.test(flags.out) : /\.jpe?g$/i.test(flags.out);
   if (!extValid) {
+    const reason =
+      flags.transparent && expected === 'jpg'
+        ? '--transparent always writes PNG'
+        : `the ${model.spec.slug} seat renders ${label} and aibridge does not convert`;
+    return fail(
+      `--out "${flags.out}" must end in ${outFormat === 'png' ? '.png' : '.jpg or .jpeg'} — ${reason}.`,
+    );
+  }
+
+  if (!flags.transparent && alpha === 'chroma' && mentionsTransparentBackground(prompt)) {
     return fail(
-      `--out "${flags.out}" must end in ${expected === 'png' ? '.png' : '.jpg or .jpeg'} — the ${model.spec.slug} seat renders ${label} and aibridge does not convert.`,
+      `the prompt asks for a transparent background but the ${model.spec.slug} seat cannot render alpha — ` +
+        `pass --transparent (aibridge chroma-keys it locally, binary edges) or use a native-alpha seat ` +
+        `(openai-codex/*). Re-run with --transparent to proceed.`,
     );
   }
 
@@ -98,9 +125,17 @@ export default async function imageGen(
   const minBytes = model.spec.backend === 'codex' ? MIN_REAL_BYTES_CODEX : MIN_REAL_BYTES_TOOL;
   const work = mkdtempSync(join(tmpdir(), 'aibridge-imagegen-'));
 
+  // Single space, never a newline: the codex driver wraps the prompt in a one-line
+  // `$imagegen …` invocation, and a blank line there makes it code-draw a substitute
+  // instead of calling the image tool (observed: --transparent failed while the same
+  // prompt without the clause rendered fine).
+  const effectivePrompt = flags.transparent
+    ? `${prompt} ${alpha === 'chroma' ? CHROMA_CLAUSE : NATIVE_ALPHA_CLAUSE}`
+    : prompt;
+
   try {
     let outcome: ImageResult = await driver.generateImage({
-      prompt,
+      prompt: effectivePrompt,
       workDir: work,
       backendModel: backendModelId(model),
       effort: model.effort,
@@ -113,7 +148,7 @@ export default async function imageGen(
 
     if (model.spec.backend === 'codex' && outcome.kind === 'suspect') {
       outcome = await driver.generateImage({
-        prompt,
+        prompt: effectivePrompt,
         workDir: work,
         backendModel: backendModelId(model),
         effort: model.effort,
@@ -144,17 +179,40 @@ export default async function imageGen(
     const local = join(work, 'result.bin');
     copyFileSync(outcome.path, local);
 
-    const dims = imageSize(local);
-    const actual = pngSize(local) ? 'png' : jpegSize(local) ? 'jpg' : null;
+    let artefact = local;
+    let transparency: 'native' | 'chroma' | null = null;
+    if (flags.transparent) {
+      const meta = await sharp(local).metadata();
+      const alreadyAlpha = meta.hasAlpha === true;
+      if (alreadyAlpha) {
+        transparency = 'native';
+      } else {
+        const keyed = join(work, 'keyed.png');
+        const { transparentRatio } = await chromaKeyToPng(local, keyed);
+        transparency = 'chroma';
+        if (transparentRatio < 0.02) {
+          this.process.stderr.write(
+            `aibridge image-gen: --transparent keyed only ${(transparentRatio * 100).toFixed(1)}% of the image — ` +
+              `the model likely ignored the chroma-key instruction; wrote it anyway. Re-run, or use a native-alpha seat.\n`,
+          );
+        }
+        artefact = keyed;
+      }
+    }
+
+    const dims = imageSize(artefact);
+    const actual = pngSize(artefact) ? 'png' : jpegSize(artefact) ? 'jpg' : null;
 
     // ponytail: guard for a backend changing formats in the future without throwing away a paid render
-    if (actual !== null && actual !== expected) {
+    if (actual !== null && actual !== outFormat) {
       this.process.stderr.write(
         `aibridge image-gen: expected a ${label} render from this seat but got ${actual === 'png' ? 'PNG' : 'JPEG'}; wrote the raw bytes to ${outPath} anyway — the extension does not match the contents.\n`,
       );
     }
 
-    copyFileSync(local, outPath);
+    // The render is already paid for — don't lose it to a missing --out directory.
+    mkdirSync(dirname(outPath), { recursive: true });
+    copyFileSync(artefact, outPath);
     const bytes = statSync(outPath).size;
 
     if (flags.json) {
@@ -167,13 +225,19 @@ export default async function imageGen(
           aspectRatio: flags.aspectRatio ?? null,
           model: model.spec.slug,
           backend: model.spec.backend,
+          transparency,
           real: true,
         })}\n`,
       );
     } else {
       const kb = Math.round(bytes / 1024);
       const dimStr = dims ? `${dims.width}x${dims.height}, ` : '';
-      this.process.stdout.write(`✓ Wrote ${outPath} (${dimStr}${kb} KB, ${model.spec.slug})\n`);
+      const transparencyStr = flags.transparent
+        ? `, transparency: ${transparency === 'native' ? 'native alpha' : 'chroma-keyed'}`
+        : '';
+      this.process.stdout.write(
+        `✓ Wrote ${outPath} (${dimStr}${kb} KB, ${model.spec.slug}${transparencyStr})\n`,
+      );
     }
   } finally {
     rmSync(work, { recursive: true, force: true });

package/src/commands/models/impl.test.ts

@@ -27,7 +27,7 @@ function createTestContext() {
 }
 
 describe('modelsImpl', () => {
-  it('--json emits parseable JSON with one entry per key of MODELS, with seven documented fields', () => {
+  it('--json emits parseable JSON with one entry per key of MODELS, with eight documented fields', () => {
     const { ctx, getStdout } = createTestContext();
     modelsImpl.call(ctx, { json: true });
 
@@ -44,8 +44,9 @@ describe('modelsImpl', () => {
       expect(item).toHaveProperty('efforts');
       expect(item).toHaveProperty('defaultEffort');
       expect(item).toHaveProperty('image');
+      expect(item).toHaveProperty('imageAlpha');
       expect(item).toHaveProperty('brief');
-      expect(Object.keys(item)).toHaveLength(7);
+      expect(Object.keys(item)).toHaveLength(8);
     }
   });
 
@@ -62,7 +63,7 @@ describe('modelsImpl', () => {
     expect(geminiPro.defaultEffort).toBe('high');
   });
 
-  it('reports backendModel and image correctly for opus-5 and gpt-5.6-sol in JSON', () => {
+  it('reports backendModel, image, and imageAlpha correctly for opus-5 and gpt-5.6-sol in JSON', () => {
     const { ctx, getStdout } = createTestContext();
     modelsImpl.call(ctx, { json: true });
 
@@ -71,10 +72,12 @@ describe('modelsImpl', () => {
     expect(opus).toBeDefined();
     expect(opus.backendModel).toBe('claude-opus-5[1m]');
     expect(opus.image).toBeNull();
+    expect(opus.imageAlpha).toBeNull();
 
     const sol = data.find((item: { slug: string }) => item.slug === 'openai-codex/gpt-5.6-sol');
     expect(sol).toBeDefined();
     expect(sol.image).toBe('png');
+    expect(sol.imageAlpha).toBe('native');
   });
 
   it('human output (no --json) contains every slug in MODELS', () => {

package/src/commands/models/impl.ts

@@ -1,5 +1,5 @@
 import type { LocalContext } from '../../context.ts';
-import { type Backend, imageFormatFor, MODELS } from '../../models.ts';
+import { type Backend, imageAlphaFor, imageFormatFor, MODELS } from '../../models.ts';
 
 export interface ModelsFlags {
   readonly json: boolean;
@@ -23,6 +23,7 @@ export default function modelsImpl(this: LocalContext, flags: ModelsFlags): void
       efforts: spec.efforts ? [...spec.efforts] : [],
       defaultEffort: spec.defaultEffort ?? null,
       image: imageFormatFor({ spec, effort: undefined }) ?? null,
+      imageAlpha: imageAlphaFor({ spec, effort: undefined }) ?? null,
       brief: spec.brief,
     }));
     this.process.stdout.write(`${JSON.stringify(jsonOutput)}\n`);
@@ -56,7 +57,9 @@ export default function modelsImpl(this: LocalContext, flags: ModelsFlags): void
         segments.push(`efforts: ${formattedEfforts}`);
       }
       const img = imageFormatFor({ spec, effort: undefined });
-      segments.push(`image: ${img ?? '—'}`);
+      const alpha = imageAlphaFor({ spec, effort: undefined });
+      const imageStr = img ? `${img} (alpha: ${alpha ?? '—'})` : '—';
+      segments.push(`image: ${imageStr}`);
       segments.push(`id: ${spec.backendModel}`);
 
       this.process.stdout.write(`    ${segments.join(' · ')}\n`);

package/src/models.test.ts

@@ -3,6 +3,7 @@ import {
   backendModelId,
   formatImageGenModelError,
   formatUnknownModelError,
+  imageAlphaFor,
   listModelHelpLines,
   resolveModel,
   supportsImageGen,
@@ -98,12 +99,26 @@ describe('models registry', () => {
     expect(supportsImageGen(claudeSonnet)).toBe(false);
   });
 
-  it('lists only image-capable seats when imageOnly', () => {
+  it('lists only image-capable seats when imageOnly and shows --transparent capability', () => {
     const lines = listModelHelpLines({ imageOnly: true }).join('\n');
     expect(lines).toContain('xai-grok/grok-4.6');
     expect(lines).toContain('openai-codex/gpt-5.6-sol');
     expect(lines).toContain('google-antigravity/gemini-3.7-flash');
     expect(lines).not.toContain('anthropic-claude/sonnet-5');
+    expect(lines).toContain('--transparent: native alpha (soft edges)');
+    expect(lines).toContain('--transparent: chroma-keyed (binary edges)');
+  });
+
+  it('reports correct imageAlpha for seats', () => {
+    const codex = resolveModel('openai-codex/gpt-5.6-sol');
+    const grok = resolveModel('xai-grok/grok-4.6');
+    const gemini = resolveModel('google-antigravity/gemini-3.7-flash');
+    const claudeSonnet = resolveModel('anthropic-claude/sonnet-5');
+    if (!codex || !grok || !gemini || !claudeSonnet) throw new Error('resolution failed');
+    expect(imageAlphaFor(codex)).toBe('native');
+    expect(imageAlphaFor(grok)).toBe('chroma');
+    expect(imageAlphaFor(gemini)).toBe('chroma');
+    expect(imageAlphaFor(claudeSonnet)).toBeUndefined();
   });
 
   it('formats image-gen model errors with capable seats only', () => {

package/src/models.ts

@@ -150,12 +150,21 @@ export const MODELS: Record<string, ModelSpec> = {
 
 export type ImageFormat = 'jpg' | 'png';
 
+/** Whether a seat's image tool can emit a real alpha channel, or needs local chroma keying. */
+export type ImageAlpha = 'native' | 'chroma';
+
 const IMAGE_GEN_FORMATS: ReadonlyMap<Backend, ImageFormat> = new Map([
   ['agy', 'jpg'],
   ['codex', 'png'],
   ['grok', 'jpg'],
 ]);
 
+const IMAGE_ALPHA: ReadonlyMap<Backend, ImageAlpha> = new Map([
+  ['agy', 'chroma'],
+  ['codex', 'native'],
+  ['grok', 'chroma'],
+]);
+
 export function supportsImageGen(resolved: ResolvedModel): boolean {
   return IMAGE_GEN_FORMATS.has(resolved.spec.backend);
 }
@@ -164,6 +173,10 @@ export function imageFormatFor(resolved: ResolvedModel): ImageFormat | undefined
   return IMAGE_GEN_FORMATS.get(resolved.spec.backend);
 }
 
+export function imageAlphaFor(resolved: ResolvedModel): ImageAlpha | undefined {
+  return IMAGE_ALPHA.get(resolved.spec.backend);
+}
+
 const EFFORTS_SET: ReadonlySet<string> = new Set<Effort>(['low', 'medium', 'high', 'xhigh', 'max']);
 
 export function resolveModel(input: string): ResolvedModel | undefined {
@@ -208,6 +221,14 @@ export function listModelHelpLines(opts: { readonly imageOnly?: boolean } = {}):
     if (opts.imageOnly && !IMAGE_GEN_FORMATS.has(spec.backend)) continue;
     lines.push(`  ${slug}`);
     lines.push(`    ${spec.brief}`);
+    if (opts.imageOnly) {
+      const alpha = IMAGE_ALPHA.get(spec.backend);
+      if (alpha !== undefined) {
+        lines.push(
+          `    --transparent: ${alpha === 'native' ? 'native alpha (soft edges)' : 'chroma-keyed (binary edges)'}`,
+        );
+      }
+    }
   }
   return lines;
 }

package/src/transparency.test.ts

@@ -0,0 +1,320 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import sharp from 'sharp';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { chromaKeyToPng, mentionsTransparentBackground } from './transparency.ts';
+
+describe('chromaKeyToPng', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'aibridge-transparency-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('keys the background, keeps the subject', async () => {
+    const width = 512;
+    const height = 512;
+    const buf = Buffer.alloc(width * height * 3);
+
+    // Fill with green background (17, 249, 19)
+    for (let i = 0; i < width * height; i++) {
+      const offset = i * 3;
+      buf[offset] = 17;
+      buf[offset + 1] = 249;
+      buf[offset + 2] = 19;
+    }
+
+    // Solid red (230, 80, 30) square in the center (from 200 to 312)
+    for (let y = 200; y < 312; y++) {
+      for (let x = 200; x < 312; x++) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 230;
+        buf[offset + 1] = 80;
+        buf[offset + 2] = 30;
+      }
+    }
+
+    const src = join(tempDir, 'input.png');
+    const dest = join(tempDir, 'output.png');
+
+    await sharp(buf, { raw: { width, height, channels: 3 } }).toFile(src);
+
+    const { transparentRatio } = await chromaKeyToPng(src, dest);
+
+    expect(transparentRatio).toBeGreaterThanOrEqual(0.7);
+    expect(transparentRatio).toBeLessThanOrEqual(0.99);
+
+    const { data } = await sharp(dest).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+
+    // Corner pixel (0, 0) should have alpha 0
+    const cornerOffset = (0 * width + 0) * 4;
+    expect(data[cornerOffset + 3]).toBe(0);
+
+    // Centre pixel (256, 256) should have alpha 255 and RGB (230, 80, 30)
+    const centreOffset = (256 * width + 256) * 4;
+    expect(data[centreOffset]).toBe(230);
+    expect(data[centreOffset + 1]).toBe(80);
+    expect(data[centreOffset + 2]).toBe(30);
+    expect(data[centreOffset + 3]).toBe(255);
+  });
+
+  it('interior light pixels survive', async () => {
+    const width = 512;
+    const height = 512;
+    const buf = Buffer.alloc(width * height * 3);
+
+    // Fill background with green (17, 249, 19)
+    for (let i = 0; i < width * height; i++) {
+      const offset = i * 3;
+      buf[offset] = 17;
+      buf[offset + 1] = 249;
+      buf[offset + 2] = 19;
+    }
+
+    // Red square (200..312)
+    for (let y = 200; y < 312; y++) {
+      for (let x = 200; x < 312; x++) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 230;
+        buf[offset + 1] = 80;
+        buf[offset + 2] = 30;
+      }
+    }
+
+    // White (255, 255, 255) block inside red square (240..270)
+    for (let y = 240; y < 270; y++) {
+      for (let x = 240; x < 270; x++) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 255;
+        buf[offset + 1] = 255;
+        buf[offset + 2] = 255;
+      }
+    }
+
+    const src = join(tempDir, 'input.png');
+    const dest = join(tempDir, 'output.png');
+
+    await sharp(buf, { raw: { width, height, channels: 3 } }).toFile(src);
+    await chromaKeyToPng(src, dest);
+
+    const { data } = await sharp(dest).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+
+    const whiteOffset = (255 * width + 255) * 4;
+    expect(data[whiteOffset]).toBe(255);
+    expect(data[whiteOffset + 1]).toBe(255);
+    expect(data[whiteOffset + 2]).toBe(255);
+    expect(data[whiteOffset + 3]).toBe(255);
+  });
+
+  it('keys a saturated green subject too — the standing cost of chroma keying', async () => {
+    const width = 64;
+    const height = 64;
+    const buf = Buffer.alloc(width * height * 3);
+
+    // Green background (17, 249, 19) with a red square, and a saturated green
+    // (40, 200, 60) block deep inside the subject. Dominance is 160/140, far past
+    // DOMINANCE — so it keys, wherever it sits. A chroma key cannot tell a green
+    // subject from a green backdrop; CHROMA_CLAUSE tells the model not to make one,
+    // and codex is the seat for subjects that must be green.
+    for (let i = 0; i < width * height; i++) {
+      const offset = i * 3;
+      buf[offset] = 17;
+      buf[offset + 1] = 249;
+      buf[offset + 2] = 19;
+    }
+    for (let y = 16; y < 48; y++) {
+      for (let x = 16; x < 48; x++) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 230;
+        buf[offset + 1] = 80;
+        buf[offset + 2] = 30;
+      }
+    }
+    for (let y = 28; y < 36; y++) {
+      for (let x = 28; x < 36; x++) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 40;
+        buf[offset + 1] = 200;
+        buf[offset + 2] = 60;
+      }
+    }
+
+    const src = join(tempDir, 'input.png');
+    const dest = join(tempDir, 'output.png');
+    await sharp(buf, { raw: { width, height, channels: 3 } }).toFile(src);
+    await chromaKeyToPng(src, dest);
+
+    const { data } = await sharp(dest).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    expect(data[(32 * width + 32) * 4 + 3]).toBe(0); // green block: keyed
+    expect(data[(20 * width + 20) * 4 + 3]).toBe(255); // red subject: kept
+  });
+
+  it('keeps a mildly green subject (below the dominance threshold) and does not despill it', async () => {
+    const width = 512;
+    const height = 512;
+    const buf = Buffer.alloc(width * height * 3);
+
+    // Fill background with green (17, 249, 19)
+    for (let i = 0; i < width * height; i++) {
+      const offset = i * 3;
+      buf[offset] = 17;
+      buf[offset + 1] = 249;
+      buf[offset + 2] = 19;
+    }
+
+    // Red square (200..312)
+    for (let y = 200; y < 312; y++) {
+      for (let x = 200; x < 312; x++) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 230;
+        buf[offset + 1] = 80;
+        buf[offset + 2] = 30;
+      }
+    }
+
+    // Green subject (130, 160, 130) fully inside red square (230..250, >2px from background edge at 200)
+    // g - r = 30 (< DOMINANCE 40 so not keyed in pass 1, >= 20 so would be despilled if ungated)
+    for (let y = 230; y < 250; y++) {
+      for (let x = 230; x < 250; x++) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 130;
+        buf[offset + 1] = 160;
+        buf[offset + 2] = 130;
+      }
+    }
+
+    const src = join(tempDir, 'input.png');
+    const dest = join(tempDir, 'output.png');
+
+    await sharp(buf, { raw: { width, height, channels: 3 } }).toFile(src);
+    await chromaKeyToPng(src, dest);
+
+    const { data } = await sharp(dest).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+
+    const greenOffset = (240 * width + 240) * 4;
+    expect(data[greenOffset]).toBe(130);
+    expect(data[greenOffset + 1]).toBe(160);
+    expect(data[greenOffset + 2]).toBe(130);
+    expect(data[greenOffset + 3]).toBe(255);
+  });
+
+  it('fringe is despilled', async () => {
+    const width = 512;
+    const height = 512;
+    const buf = Buffer.alloc(width * height * 3);
+
+    // Fill background with green (17, 249, 19)
+    for (let i = 0; i < width * height; i++) {
+      const offset = i * 3;
+      buf[offset] = 17;
+      buf[offset + 1] = 249;
+      buf[offset + 2] = 19;
+    }
+
+    // Red square interior (201..311)
+    for (let y = 201; y < 311; y++) {
+      for (let x = 201; x < 311; x++) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 230;
+        buf[offset + 1] = 80;
+        buf[offset + 2] = 30;
+      }
+    }
+
+    // 1-pixel fringe ring at y=200, y=311, x=200, x=311 with green-tinted (160, 190, 160)
+    // where g - r = 30 (>= 20 for despill, < 40 so not keyed)
+    for (let x = 200; x <= 311; x++) {
+      for (const y of [200, 311]) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 160;
+        buf[offset + 1] = 190;
+        buf[offset + 2] = 160;
+      }
+    }
+    for (let y = 200; y <= 311; y++) {
+      for (const x of [200, 311]) {
+        const offset = (y * width + x) * 3;
+        buf[offset] = 160;
+        buf[offset + 1] = 190;
+        buf[offset + 2] = 160;
+      }
+    }
+
+    const src = join(tempDir, 'input.png');
+    const dest = join(tempDir, 'output.png');
+
+    await sharp(buf, { raw: { width, height, channels: 3 } }).toFile(src);
+    await chromaKeyToPng(src, dest);
+
+    const { data } = await sharp(dest).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+
+    // Fringe pixel at (200, 200) was adjacent to keyed background
+    const fringeOffset = (200 * width + 200) * 4;
+    expect(data[fringeOffset + 3]).toBe(255); // stays opaque
+    expect(data[fringeOffset + 1]).toBeLessThanOrEqual(
+      Math.max(data[fringeOffset] ?? 0, data[fringeOffset + 2] ?? 0),
+    );
+    expect(data[fringeOffset + 1]).toBe(160);
+  });
+
+  it('handles an image with no green at all', async () => {
+    const width = 512;
+    const height = 512;
+    const buf = Buffer.alloc(width * height * 3);
+
+    // All red (255, 0, 0)
+    for (let i = 0; i < width * height; i++) {
+      const offset = i * 3;
+      buf[offset] = 255;
+      buf[offset + 1] = 0;
+      buf[offset + 2] = 0;
+    }
+
+    const src = join(tempDir, 'input.png');
+    const dest = join(tempDir, 'output.png');
+
+    await sharp(buf, { raw: { width, height, channels: 3 } }).toFile(src);
+    const { transparentRatio } = await chromaKeyToPng(src, dest);
+
+    expect(transparentRatio).toBe(0);
+
+    const { data } = await sharp(dest).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+
+    for (let i = 0; i < width * height; i++) {
+      expect(data[i * 4 + 3]).toBe(255);
+    }
+  });
+});
+
+describe('mentionsTransparentBackground', () => {
+  it('matches background phrasing', () => {
+    for (const p of [
+      'a fox on a transparent background',
+      'a fox, transparent backdrop',
+      'a fox with no background',
+      'a fox without a background',
+      'PNG with an alpha channel',
+      'shot on a chroma-key stage',
+      'chroma key green screen',
+    ]) {
+      expect(mentionsTransparentBackground(p)).toBe(true);
+    }
+  });
+
+  it('ignores see-through subjects and unrelated wording', () => {
+    for (const p of [
+      'a transparent glass bottle',
+      'a goldfish in a transparent bowl',
+      'frosted transparent plastic packaging',
+      'a paper cutout of a fox',
+      'transparency and trust, abstract illustration',
+    ]) {
+      expect(mentionsTransparentBackground(p)).toBe(false);
+    }
+  });
+});

package/src/transparency.ts

@@ -0,0 +1,107 @@
+import sharp from 'sharp';
+
+export const CHROMA_CLAUSE =
+  'The entire background must be a perfectly flat solid #00ff00 chroma-key green. The background must be one uniform colour with no shadows, gradients, texture, reflections, or lighting variation. Keep the subject fully separated from the background with crisp edges. Do not use #00ff00 or any similar green anywhere on the subject. No cast shadow, no contact shadow, no reflection.';
+
+export const NATIVE_ALPHA_CLAUSE =
+  'Render the subject on a fully transparent background — PNG with a real alpha channel, no backdrop, no canvas colour, no cast shadow.';
+
+export interface KeyResult {
+  readonly transparentRatio: number;
+}
+
+/**
+ * Background-scoped only. `transparent` on its own describes subjects far more
+ * often than backdrops ("transparent glass bottle", "goldfish in a transparent
+ * bowl"), and refusing those would force `--transparent` onto a brief the chroma
+ * clause actively fights.
+ */
+const TRANSPARENT_BACKGROUND =
+  /\b(transparent (background|backdrop)|no background|without a background|alpha channel|chroma[- ]?key)/i;
+
+/** Does the prompt ask for a see-through *background* (as opposed to a see-through subject)? */
+export function mentionsTransparentBackground(prompt: string): boolean {
+  return TRANSPARENT_BACKGROUND.test(prompt);
+}
+
+const GREEN_MIN = 90;
+/**
+ * How far green must lead both red and blue for a pixel to count as backdrop.
+ * Position, not geometry, decides: a saturated green *subject* is keyed away too.
+ * That is inherent to chroma keying — CHROMA_CLAUSE tells the model not to put
+ * green on the subject, and a native-alpha seat is the answer when it must be.
+ */
+const DOMINANCE = 40;
+
+export async function chromaKeyToPng(src: string, dest: string): Promise<KeyResult> {
+  // toColourspace before ensureAlpha: a greyscale source would otherwise come back
+  // 2-channel (Y+A) and every RGBA offset below would read the wrong byte.
+  const { data, info } = await sharp(src)
+    .toColourspace('srgb')
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  const { width, height, channels } = info;
+  if (channels !== 4) {
+    throw new Error(`chroma key expected 4-channel RGBA, got ${channels} channels from ${src}`);
+  }
+  const totalPixels = width * height;
+
+  if (totalPixels === 0) {
+    await sharp(data, { raw: { width, height, channels } })
+      .png({ compressionLevel: 9 })
+      .toFile(dest);
+    return { transparentRatio: 0 };
+  }
+
+  // Pass 1 — key: detect background green pixels and set alpha to 0.
+  const mask = new Uint8Array(totalPixels);
+  let keyedCount = 0;
+
+  for (let i = 0; i < totalPixels; i++) {
+    const offset = i * channels;
+    const r = data[offset] ?? 0;
+    const g = data[offset + 1] ?? 0;
+    const b = data[offset + 2] ?? 0;
+
+    if (g >= GREEN_MIN && g - r >= DOMINANCE && g - b >= DOMINANCE) {
+      data[offset + 3] = 0;
+      mask[i] = 1;
+      keyedCount++;
+    }
+  }
+
+  // ponytail: neighbour-gated despill — an ungated despill would grey out any green subject.
+  // Ceiling: binary alpha, 1px fringe ring; upgrade path is a real matte (feathered alpha) if soft edges are ever needed.
+  // Pass 2 — despill: clamp green for opaque fringe pixels adjacent to keyed pixels.
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const idx = y * width + x;
+      if (mask[idx] === 1) continue;
+
+      const offset = idx * channels;
+      const r = data[offset] ?? 0;
+      const g = data[offset + 1] ?? 0;
+      const b = data[offset + 2] ?? 0;
+
+      if (g - r >= 20 && g - b >= 20) {
+        const hasKeyedNeighbor =
+          (x > 0 && mask[idx - 1] === 1) ||
+          (x < width - 1 && mask[idx + 1] === 1) ||
+          (y > 0 && mask[idx - width] === 1) ||
+          (y < height - 1 && mask[idx + width] === 1);
+
+        if (hasKeyedNeighbor) {
+          data[offset + 1] = Math.max(r, b);
+        }
+      }
+    }
+  }
+
+  await sharp(data, { raw: { width, height, channels } }).png({ compressionLevel: 9 }).toFile(dest);
+
+  return {
+    transparentRatio: keyedCount / totalPixels,
+  };
+}