Skip to content

gabelul/pixeltamer-gpt-image-skill

pixeltamer

Flagged

Generate, edit, and compose images with GPT Image 2.6, including transparent PNGs with a real alpha channel. Three backends — OpenAI API key (full feature set), codex CLI on your ChatGPT subscription (agent-driven, no key needed), or the direct ChatGPT image route on the same subscription token (--backend codex-images, PNG-only, opt-in). Four modes — one-shot generate, edit or inpaint an existing image, multi-reference composition (up to 16 inputs blended into one), and multi-image batch with verification. Use when the user asks to make an image, generate a poster, draw a mockup, design an icon or sticker, create an ad creative, build an infographic, blend reference images, edit or inpaint an existing image, or produce a cutout asset with a transparent background — "transparent PNG", "no background", "alpha channel", "works on any background". Not for: stripping the background off an existing image you want to keep (that's rembg or ImageMagick, not a generator); file operations that don't change the picture (compression, format conversion, resizing); reading, describing or OCRing an image; video.

scripts/lib/verify-entry.mjs

View on GitHub
import { resolve, extname } from 'node:path';
import { readFileSync, openSync, readSync, closeSync } from 'node:fs';
import { inspectGifFile as inspectGifFileDefault } from './gif-inspect.mjs';

const MIN_FILE_SIZE = 10 * 1024;
// SVG is text: a legitimate hand-sized icon sits far below the raster floor,
// so SVG entries get their own minimum (keep the shared max).
const MIN_SVG_FILE_SIZE = 64;
// Root tag sits near the head of the file; read only this much, not the whole
// path-sized payload.
const SVG_HEAD_BYTES = 4096;
const MAX_FILE_SIZE = 10 * 1024 * 1024;

const PNG_EXTS = new Set(['.png']);
const JPG_EXTS = new Set(['.jpg', '.jpeg']);
const GIF_EXTS = new Set(['.gif']);
const SVG_EXTS = new Set(['.svg']);

export function verifyEntry(entry, projectRoot, deps) {
  const { fs, getDimensions, getHasAlpha, getAlphaCoverage } = deps;
  const inspectGifFile = deps.inspectGifFile ?? inspectGifFileDefault;
  const readSvgHead = deps.readSvgHead ?? readSvgHeadDefault;
  const fullPath = resolve(projectRoot, entry.path);

  if (!fs.existsSync(fullPath)) {
    return { ok: false, reason: 'file not found' };
  }

  const { size } = fs.statSync(fullPath);
  const formatLower = entry.format.toLowerCase();
  const minSize = formatLower.includes('svg') ? MIN_SVG_FILE_SIZE : MIN_FILE_SIZE;
  if (size < minSize) {
    return { ok: false, reason: `file too small (${size} bytes, minimum ${minSize})` };
  }
  if (size > MAX_FILE_SIZE) {
    return { ok: false, reason: `file too large (${size} bytes, maximum ${MAX_FILE_SIZE})` };
  }

  const ext = extname(entry.path).toLowerCase();

  if (formatLower.includes('gif')) {
    return verifyGifEntry({ entry, fullPath, ext, size, formatLower, inspectGifFile });
  }

  if (formatLower.includes('svg')) {
    return verifySvgEntry({ entry, fullPath, ext, formatLower, readSvgHead });
  }

  let allowedExts;
  if (formatLower.includes('png')) {
    allowedExts = PNG_EXTS;
  } else if (formatLower.includes('jpg') || formatLower.includes('jpeg')) {
    allowedExts = JPG_EXTS;
  } else {
    return { ok: false, reason: `unrecognized format field: "${entry.format}"` };
  }
  if (!allowedExts.has(ext)) {
    return { ok: false, reason: `extension ${ext} does not match format "${entry.format}"` };
  }

  const expected = parseSize(entry.nativeSize);
  if (!expected) {
    return { ok: false, reason: `unparseable native size: "${entry.nativeSize}"` };
  }

  const actual = getDimensions(fullPath);
  if (!actual || typeof actual.width !== 'number' || typeof actual.height !== 'number') {
    return { ok: false, reason: 'unable to read image dimensions' };
  }

  if (actual.width !== expected.width || actual.height !== expected.height) {
    return {
      ok: false,
      reason: `dimensions ${actual.width}×${actual.height} expected ${expected.width}×${expected.height}`,
    };
  }

  // "PNG transparent" in the Format field is a promise the file has to keep.
  // The common failure is silent: the prompt described a backdrop, gpt-image-2
  // obliged, and you get flat RGB back with no error anywhere in the chain.
  //
  // Header-only check — see parseHasAlphaChannel. It catches "no alpha channel
  // at all", which is most of the misses. It CANNOT catch an alpha channel
  // that's fully opaque; that one is the visual self-review step's job.
  //
  // getHasAlpha stays optional so older callers passing only {fs, getDimensions}
  // keep working instead of throwing on an undefined call.
  if (formatLower.includes('transparent') && getHasAlpha) {
    const hasAlpha = getHasAlpha(fullPath);
    if (hasAlpha === null) {
      return { ok: false, reason: 'unable to read alpha channel' };
    }
    if (!hasAlpha) {
      return {
        ok: false,
        reason: 'format says transparent but the PNG has no alpha channel',
      };
    }

    // Having an alpha channel is not the same as using it. A PNG can be RGBA
    // with every pixel opaque — the model painted a backdrop — and that passes
    // every check above while being useless for the one job it had.
    if (getAlphaCoverage) {
      const coverage = getAlphaCoverage(fullPath);
      if (coverage && coverage.transparentPct < 1) {
        return {
          ok: false,
          reason: `alpha channel present but only ${coverage.transparentPct}% transparent — the prompt probably described a background`,
        };
      }
    }
  }

  return { ok: true };
}

/**
 * Verify a GIF batch entry: signature, bounded structure, per-frame timing,
 * and dimensions from the logical screen descriptor.
 *
 * GIF transparency is binary palette transparency — it can't be measured the
 * way PNG alpha is, and the client refuses to generate it — so a `transparent`
 * token on a GIF entry is a config error, not a checkable promise. Structural
 * parsing also can't prove the frames differ; for that, use the visual
 * self-review step or ImageMagick's frame RMSE.
 *
 * @param {object} params
 * @param {object} params.entry - parsed prompts.md entry
 * @param {string} params.fullPath - resolved file path
 * @param {string} params.ext - lower-cased path extension
 * @param {number} params.size - file size in bytes (bounds already checked)
 * @param {string} params.formatLower - lower-cased Format field
 * @param {Function} params.inspectGifFile - structural GIF reader
 * @returns {{ok: boolean, reason?: string, frames?: number}}
 */
function verifyGifEntry({ entry, fullPath, ext, size, formatLower, inspectGifFile }) {
  if (!GIF_EXTS.has(ext)) {
    return { ok: false, reason: `extension ${ext} does not match format "${entry.format}"` };
  }
  if (formatLower.includes('transparent')) {
    return {
      ok: false,
      reason: 'transparent is not offered with GIF output (binary palette transparency, unverifiable); use PNG transparent instead',
    };
  }

  const expected = parseSize(entry.nativeSize);
  if (!expected) {
    return { ok: false, reason: `unparseable native size: "${entry.nativeSize}"` };
  }

  const gif = inspectGifFile(fullPath);
  if (!gif) {
    return { ok: false, reason: 'unable to read GIF structure' };
  }
  if (!gif.ok) {
    return { ok: false, reason: `invalid GIF (${gif.reason})` };
  }

  if (gif.width !== expected.width || gif.height !== expected.height) {
    return {
      ok: false,
      reason: `dimensions ${gif.width}×${gif.height} expected ${expected.width}×${expected.height}`,
    };
  }

  // "GIF animated" is the promise that the file actually moves. A single-frame
  // GIF passes every structural check while failing the one job it had.
  if (formatLower.includes('animated') && gif.frames < 2) {
    return { ok: false, reason: `format says animated but the GIF has ${gif.frames} frame(s)` };
  }

  return { ok: true, frames: gif.frames };
}

/**
 * Verify an SVG batch entry: extension, that it IS svg, and declared
 * dimensions (width/height attributes, falling back to the viewBox) against
 * Native size.
 *
 * The checks are deliberately shallow — XML well-formedness, semantics, and
 * visual output belong to the visual self-review step. A `transparent` token
 * is rejected: SVG transparency is real but unmeasurable by tooling, so it
 * can't be treated as a verifiable promise; use PNG transparent when the
 * cutout has to be provable.
 *
 * @param {object} params
 * @param {object} params.entry - parsed prompts.md entry
 * @param {string} params.fullPath - resolved file path
 * @param {string} params.ext - lower-cased path extension
 * @param {string} params.formatLower - lower-cased Format field
 * @returns {{ok: boolean, reason?: string, width?: number, height?: number}}
 */
/**
 * Bounded head read for SVG files: opens the file and reads at most
 * SVG_HEAD_BYTES bytes, so a path-sized payload is never pulled into memory
 * just to find the root tag. Injectable so tests can stub it.
 *
 * @param {string} fullPath
 * @returns {string} UTF-8 decoded head
 */
function readSvgHeadDefault(fullPath) {
  const fd = openSync(fullPath, 'r');
  try {
    const buf = Buffer.alloc(SVG_HEAD_BYTES);
    const bytesRead = readSync(fd, buf, 0, SVG_HEAD_BYTES, 0);
    return buf.toString('utf8', 0, bytesRead);
  } finally {
    closeSync(fd);
  }
}

/**
 * Walk the prolog of an SVG document (whitespace, comments, processing
 * instructions, declarations) and return its first real element. Detecting
 * the root this way stops impostors — an HTML file containing an SVG string,
 * or a commented-out fake — from passing as SVG.
 *
 * @param {string} head - beginning of the file
 * @returns {{root: string|null, tag?: string}} lower-cased root element name
 *   and its full start tag when found
 */
function findSvgRoot(head) {
  let i = 0;
  while (i < head.length) {
    while (i < head.length && /\s/.test(head[i])) i += 1;
    if (i >= head.length) return { root: null }; // truncated in the prolog
    if (head[i] !== '<') return { root: null }; // garbage before any element
    if (head.startsWith('<!--', i)) {
      const end = head.indexOf('-->', i + 4);
      if (end === -1) return { root: null }; // unterminated comment
      i = end + 3;
      continue;
    }
    if (head.startsWith('<?', i)) {
      const end = head.indexOf('?>', i + 2);
      if (end === -1) return { root: null }; // unterminated processing instruction
      i = end + 2;
      continue;
    }
    if (head.startsWith('<!', i)) {
      const end = head.indexOf('>', i + 2);
      if (end === -1) return { root: null }; // unterminated declaration
      i = end + 1;
      continue;
    }
    const m = head.slice(i).match(/^<([A-Za-z][\w:.-]*)(\s[^>]*)?>/);
    if (!m) return { root: null };
    return { root: m[1].toLowerCase(), tag: m[0] };
  }
  return { root: null };
}

/**
 * Parse a dimension attribute value like "512" or "512px". Rejects anything
 * that is not a finite positive number — fractional values stay fractional so
 * the exact compare below can fail them.
 *
 * @param {string} raw
 * @returns {number|null}
 */
function parseSvgDim(raw) {
  const stripped = raw.replace(/px$/i, '');
  const n = Number(stripped);
  if (!Number.isFinite(n) || n <= 0) return null;
  return n;
}

/**
 * Verify an SVG batch entry: extension, that the file IS an SVG document
 * (root element after a well-formed prolog), and declared dimensions
 * (width/height attributes, falling back to the viewBox) against Native size.
 *
 * The checks are deliberately shallow — XML well-formedness beyond the
 * prolog, semantics, and visual output belong to the visual self-review step.
 * A `transparent` token is rejected: SVG transparency is real but
 * unmeasurable by tooling, so it can't be treated as a verifiable promise;
 * use PNG transparent when the cutout has to be provable.
 *
 * viewBox numbers are user units, not guaranteed viewport pixels — using
 * them as Native size is a project convention, applied only when explicit
 * width/height attributes are absent.
 *
 * @param {object} params
 * @param {object} params.entry - parsed prompts.md entry
 * @param {string} params.fullPath - resolved file path
 * @param {string} params.ext - lower-cased path extension
 * @param {string} params.formatLower - lower-cased Format field
 * @param {(path: string) => string} params.readSvgHead - bounded head reader
 * @returns {{ok: boolean, reason?: string, width?: number, height?: number}}
 */
function verifySvgEntry({ entry, fullPath, ext, formatLower, readSvgHead }) {
  if (!SVG_EXTS.has(ext)) {
    return { ok: false, reason: `extension ${ext} does not match format "${entry.format}"` };
  }
  if (formatLower.includes('transparent')) {
    return {
      ok: false,
      reason: 'transparent is not verifiable on SVG entries (no raster alpha to measure); use PNG transparent when the cutout must be provable',
    };
  }

  const expected = parseSize(entry.nativeSize);
  if (!expected) {
    return { ok: false, reason: `unparseable native size: "${entry.nativeSize}"` };
  }

  let head;
  try {
    head = readSvgHead(fullPath);
  } catch {
    return { ok: false, reason: 'unable to read SVG file' };
  }

  const { root, tag } = findSvgRoot(head);
  if (root === null) {
    return { ok: false, reason: 'no SVG root element found — not an SVG document (or truncated)' };
  }
  if (root !== 'svg') {
    return { ok: false, reason: `root element is <${root}>, not <svg>` };
  }

  const wAttr = tag.match(/(?:^|\s)width\s*=\s*["']([^"']+)["']/i);
  const hAttr = tag.match(/(?:^|\s)height\s*=\s*["']([^"']+)["']/i);
  const viewBox = tag.match(/(?:^|\s)viewBox\s*=\s*["']([^"']+)["']/i);

  let width;
  let height;
  if (wAttr && hAttr) {
    width = parseSvgDim(wAttr[1]);
    height = parseSvgDim(hAttr[1]);
  } else if (viewBox) {
    // min-x min-y width height, whitespace- or comma-separated, may be
    // negative/exponential. Only width/height are meaningful here.
    const nums = viewBox[1].trim().split(/[\s,]+/).map(Number);
    if (nums.length === 4 && nums.every((n) => Number.isFinite(n))) {
      width = nums[2] > 0 ? nums[2] : null;
      height = nums[3] > 0 ? nums[3] : null;
    }
  }

  if (width == null || height == null) {
    return {
      ok: false,
      reason: 'SVG declares no verifiable width/height or viewBox — dimension check impossible',
    };
  }

  // Exact compare on purpose: a 511.6×512 file is not a 512×512 asset.
  if (width !== expected.width || height !== expected.height) {
    return {
      ok: false,
      reason: `dimensions ${width}×${height} expected ${expected.width}×${expected.height}`,
    };
  }

  return { ok: true, width, height };
}

function parseSize(value) {
  const m = value.match(/^\s*(\d+)\s*[×x]\s*(\d+)\s*$/);
  if (!m) return null;
  return { width: Number(m[1]), height: Number(m[2]) };
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall