restyle-sprites 0.1.0

package/.env.example

@@ -0,0 +1,3 @@
+GEMINI_API_KEY=
+OPENAI_API_KEY=
+GEMINI_IMAGE_MODEL=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# restyle-sprites
+
+AI-powered sprite restyling pipeline for generating cohesive game asset packs from legacy source sprites.
+
+It focuses on one hard problem: keep source geometry and gameplay readability while applying a new style.
+
+## Features
+
+- Restyle pipeline: source asset + style reference + prompt
+- Interactive style reference exploration (`explore`)
+- Batch generation for image and spritesheet assets
+- Pixel-art post-processing (palette quantization, alpha cleanup, nearest-neighbor resize)
+- Legacy colorkey stripping support for opaque source files (for example old BMP assets)
+- JSON and YAML config support
+- Provider setup: Gemini primary, OpenAI fallback
+- Engine-agnostic metadata support (`metadata` field per asset)
+
+## Install
+
+```bash
+npm install @yesterday-ai/restyle-sprites
+```
+
+or with pnpm:
+
+```bash
+pnpm add @yesterday-ai/restyle-sprites
+```
+
+## Quick Start
+
+1. Create a config file (`restyle.config.json` or `.yaml`).
+2. Add API keys to `.env` in the same directory as the config.
+3. Generate a style reference.
+4. Generate the full pack.
+
+### Environment variables
+
+```bash
+GEMINI_API_KEY=...
+OPENAI_API_KEY=...
+GEMINI_IMAGE_MODEL=gemini-3.1-flash-image-preview
+```
+
+`OPENAI_API_KEY` is optional, used as fallback.
+
+## CLI
+
+```bash
+restyle-sprites explore --name my-pack --config ./restyle.config.json
+restyle-sprites explore-once --name my-pack --config ./restyle.config.json --prompt "pixel-art fantasy"
+restyle-sprites generate --name my-pack --config ./restyle.config.json
+restyle-sprites init-default --config ./restyle.config.json
+```
+
+### Commands
+
+- `explore`: interactive style preview loop and approval flow
+- `explore-once`: one-shot style reference generation
+- `generate`: generate all configured assets into one pack
+- `init-default`: convert source assets to a baseline `default` pack
+
+## Config format
+
+All paths are resolved relative to the config file directory.
+
+```json
+{
+  "outputDir": "./public/assets/packs",
+  "defaultActivePack": "default",
+  "sampleSprites": [
+    "./public/assets/sprites/hero.png",
+    "./public/assets/sprites/tree.png"
+  ],
+  "assets": [
+    {
+      "id": "hero_walk",
+      "sourceFile": "./public/assets/sprites/hero_walk.png",
+      "outputFile": "sprites/hero_walk.png",
+      "kind": "spritesheet",
+      "category": "character",
+      "width": 96,
+      "height": 32,
+      "frameWidth": 32,
+      "frameHeight": 32,
+      "frameCount": 3,
+      "frameDirection": "horizontal",
+      "promptHint": "Hero walk cycle, three frames, preserve silhouette.",
+      "metadata": {
+        "engineKey": "hero_walk"
+      }
+    }
+  ]
+}
+```
+
+## Programmatic usage
+
+```ts
+import { loadConfig, BatchGenerator, ImageProcessor, OpenAIImageClient, PixelArtPostProcessor } from '@yesterday-ai/restyle-sprites';
+```
+
+For a full working setup, check:
+
+- `examples/restyle.config.json`
+- `examples/restyle.config.yaml`
+
+## CI And Security
+
+The package includes a GitHub Actions workflow at `.github/workflows/ci.yml` with:
+
+- build + typecheck (`pnpm typecheck`, `pnpm build`)
+- secret detection using Gitleaks on every push and pull request
+
+Release automation is configured with:
+
+- `.github/workflows/release.yml` using Changesets
+- automatic release PRs with version bumps and changelog updates
+- npm publish to the public registry using `NPM_TOKEN`
+
+Detailed release runbook: `RELEASING.md`
+
+## PR Blocking Policy
+
+Use GitHub branch protection (or rulesets) on `main` and require these status checks:
+
+- `Build And Typecheck`
+- `Secret Detection (Gitleaks)`
+
+This ensures no PR can be merged unless CI is green.
+
+## Changelog generation
+
+This package uses Changesets for versioning and changelog generation.
+
+Basic flow:
+
+1. Add a changeset in your PR:
+   ```bash
+   pnpm changeset
+   ```
+2. Merge PR to `main`.
+3. Release workflow opens/updates a release PR with:
+   - bumped version in `package.json`
+   - generated `CHANGELOG.md`
+4. Merge release PR to publish to npm.
+
+Required repository secret:
+
+- `NPM_TOKEN` (npm automation token with publish permissions for `@yesterday-ai`)
+
+## Notes
+
+- For very small sprites, the pipeline upscales before generation and downsamples with nearest-neighbor.
+- `metadata` is copied through to generated manifest entries unchanged.
+- Output pack manifests are written as `<outputDir>/<packName>/manifest.json`, and `<outputDir>/index.json` is refreshed after each command.

package/dist/AssetPackWriter.d.ts

@@ -0,0 +1,14 @@
+import { AssetPackManifest, AssetPackManifestEntry } from './types.js';
+export declare class AssetPackWriter {
+    writeManifest(params: {
+        packDir: string;
+        packName: string;
+        description: string;
+        styleReferenceImage?: string;
+        assets: AssetPackManifestEntry[];
+    }): Promise<AssetPackManifest>;
+    updatePackIndex(params: {
+        packsRootDir: string;
+        activePack: string;
+    }): Promise<void>;
+}

package/dist/AssetPackWriter.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export class AssetPackWriter {
+    async writeManifest(params) {
+        const manifest = {
+            name: params.packName,
+            description: params.description,
+            createdAt: new Date().toISOString(),
+            styleReferenceImage: params.styleReferenceImage,
+            assets: params.assets,
+        };
+        const manifestPath = path.join(params.packDir, 'manifest.json');
+        await fs.mkdir(params.packDir, { recursive: true });
+        await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+        return manifest;
+    }
+    async updatePackIndex(params) {
+        const indexPath = path.join(params.packsRootDir, 'index.json');
+        const dirEntries = await fs.readdir(params.packsRootDir, { withFileTypes: true });
+        const packs = (await Promise.all(dirEntries
+            .filter((entry) => entry.isDirectory())
+            .map(async (entry) => {
+            const manifestPath = path.join(params.packsRootDir, entry.name, 'manifest.json');
+            try {
+                await fs.access(manifestPath);
+                return {
+                    name: entry.name,
+                    manifest: `${entry.name}/manifest.json`,
+                };
+            }
+            catch {
+                return null;
+            }
+        }))).filter((item) => Boolean(item));
+        const content = {
+            activePack: packs.some((pack) => pack.name === params.activePack) ? params.activePack : 'default',
+            packs: packs.sort((a, b) => a.name.localeCompare(b.name)),
+        };
+        await fs.writeFile(indexPath, `${JSON.stringify(content, null, 2)}\n`, 'utf8');
+    }
+}

package/dist/BatchGenerator.d.ts

@@ -0,0 +1,28 @@
+import { OpenAIImageClient } from './OpenAIImageClient.js';
+import { ImageProcessor } from './ImageProcessor.js';
+import { PixelArtPostProcessor } from './PixelArtPostProcessor.js';
+import { AssetDefinition, AssetPackManifestEntry } from './types.js';
+export declare class BatchGenerator {
+    private readonly openAI;
+    private readonly imageProcessor;
+    private readonly postProcessor;
+    private static readonly MAX_RENDER_ATTEMPTS;
+    private static readonly MAX_STYLE_PROMPT_CHARS;
+    private static readonly MAX_ASSET_HINT_CHARS;
+    constructor(openAI: OpenAIImageClient, imageProcessor: ImageProcessor, postProcessor: PixelArtPostProcessor);
+    generatePackAssets(params: {
+        workspaceRoot: string;
+        assets: AssetDefinition[];
+        styleReferencePath: string;
+        outputPackDir: string;
+        stylePrompt: string;
+    }): Promise<AssetPackManifestEntry[]>;
+    private fileExists;
+    private isModerationBlocked;
+    private buildFallbackPrompt;
+    private renderWithRetry;
+    private buildPrompt;
+    private buildPaletteConstraint;
+    private getCategoryPromptContext;
+    private compactText;
+}

package/dist/BatchGenerator.js

@@ -0,0 +1,214 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export class BatchGenerator {
+    openAI;
+    imageProcessor;
+    postProcessor;
+    static MAX_RENDER_ATTEMPTS = 2;
+    static MAX_STYLE_PROMPT_CHARS = 400;
+    static MAX_ASSET_HINT_CHARS = 400;
+    constructor(openAI, imageProcessor, postProcessor) {
+        this.openAI = openAI;
+        this.imageProcessor = imageProcessor;
+        this.postProcessor = postProcessor;
+    }
+    async generatePackAssets(params) {
+        const generated = [];
+        for (const asset of params.assets) {
+            const absoluteSourcePath = path.join(params.workspaceRoot, asset.sourceFile);
+            const absoluteOutputPath = path.join(params.outputPackDir, asset.outputFile);
+            const renderSize = this.imageProcessor.chooseRenderSize(asset.width, asset.height);
+            if (await this.fileExists(absoluteOutputPath)) {
+                console.log(`Skipping ${asset.id} (already generated).`);
+                generated.push({
+                    id: asset.id,
+                    metadata: asset.metadata,
+                    file: asset.outputFile,
+                    kind: asset.kind,
+                    width: asset.width,
+                    height: asset.height,
+                    frameWidth: asset.kind === 'spritesheet' ? asset.frameWidth : undefined,
+                    frameHeight: asset.kind === 'spritesheet' ? asset.frameHeight : undefined,
+                    frameCount: asset.kind === 'spritesheet' ? asset.frameCount : undefined,
+                    frameDirection: asset.kind === 'spritesheet' ? asset.frameDirection : undefined,
+                });
+                continue;
+            }
+            console.log(`Generating ${asset.id} ...`);
+            try {
+                const sourceAssetRaw = await this.imageProcessor.readAsPngBuffer(absoluteSourcePath);
+                const sourceAsset = await this.postProcessor.stripLegacyBackground(sourceAssetRaw);
+                const sourcePalette = await this.postProcessor.extractPalette(sourceAsset);
+                if (asset.kind === 'image') {
+                    const upscaledSource = await this.imageProcessor.upscaleForGeneration(sourceAsset, renderSize);
+                    const rendered = await this.renderWithRetry(async (prompt) => this.openAI.restyleAssetBuffer({
+                        sourceAsset: upscaledSource,
+                        styleReferencePath: params.styleReferencePath,
+                        prompt,
+                        renderSize,
+                    }), asset.promptHint, params.stylePrompt, `${asset.width}x${asset.height}`, sourcePalette, asset.category);
+                    const processed = await this.postProcessor.process(rendered, asset.width, asset.height, {
+                        sourceReference: sourceAsset,
+                        category: asset.category,
+                    });
+                    await this.imageProcessor.writeBuffer(processed, absoluteOutputPath);
+                }
+                else {
+                    const sourceFramesRaw = await this.imageProcessor.extractSpriteFrames(absoluteSourcePath, asset);
+                    const sourceFrames = await Promise.all(sourceFramesRaw.map((frame) => this.postProcessor.stripLegacyBackground(frame)));
+                    const styledFrames = [];
+                    for (let frameIndex = 0; frameIndex < sourceFrames.length; frameIndex += 1) {
+                        const upscaledFrame = await this.imageProcessor.upscaleForGeneration(sourceFrames[frameIndex], renderSize);
+                        const frameHint = `${asset.promptHint} Frame ${frameIndex + 1} of ${sourceFrames.length}. Keep animation continuity.`;
+                        const frame = await this.renderWithRetry(async (prompt) => this.openAI.restyleAssetBuffer({
+                            sourceAsset: upscaledFrame,
+                            styleReferencePath: params.styleReferencePath,
+                            prompt,
+                            renderSize,
+                        }), frameHint, params.stylePrompt, `${asset.frameWidth}x${asset.frameHeight}`, sourcePalette, asset.category);
+                        const processedFrame = await this.postProcessor.process(frame, asset.frameWidth, asset.frameHeight, {
+                            sourceReference: sourceFrames[frameIndex],
+                            category: asset.category,
+                        });
+                        styledFrames.push(processedFrame);
+                    }
+                    await this.imageProcessor.stitchVerticalSpriteSheet(styledFrames, asset.frameWidth, asset.frameHeight, absoluteOutputPath);
+                }
+            }
+            catch (error) {
+                if (!this.isModerationBlocked(error)) {
+                    throw error;
+                }
+                console.warn(`Moderation blocked ${asset.id}; using source fallback for this asset.`);
+                await this.imageProcessor.convertToPng(absoluteSourcePath, absoluteOutputPath);
+            }
+            generated.push({
+                id: asset.id,
+                metadata: asset.metadata,
+                file: asset.outputFile,
+                kind: asset.kind,
+                width: asset.width,
+                height: asset.height,
+                frameWidth: asset.kind === 'spritesheet' ? asset.frameWidth : undefined,
+                frameHeight: asset.kind === 'spritesheet' ? asset.frameHeight : undefined,
+                frameCount: asset.kind === 'spritesheet' ? asset.frameCount : undefined,
+                frameDirection: asset.kind === 'spritesheet' ? asset.frameDirection : undefined,
+            });
+        }
+        return generated;
+    }
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    isModerationBlocked(error) {
+        if (!(error instanceof Error)) {
+            return false;
+        }
+        const message = error.message.toLowerCase();
+        return message.includes('moderation_blocked') || message.includes('rejected by the safety system');
+    }
+    buildFallbackPrompt(assetHint, targetSize, sourcePaletteHex, category) {
+        const shortHint = this.compactText(assetHint, BatchGenerator.MAX_ASSET_HINT_CHARS);
+        const categoryContext = this.getCategoryPromptContext(category);
+        const paletteConstraint = this.buildPaletteConstraint(sourcePaletteHex);
+        return [
+            'Image 1 is the source sprite, upscaled with nearest-neighbor so the original pixel grid is clear.',
+            'Image 2 is the approved style reference.',
+            'TASK: Redraw Image 1 in the style of Image 2.',
+            categoryContext,
+            `Asset details: ${shortHint}.`,
+            'PRESERVE from Image 1: exact silhouette, proportions, object identity, pose, orientation, framing, and aspect ratio.',
+            'CHANGE to match Image 2: palette, shading style, edge treatment, texture mood, and color harmony.',
+            paletteConstraint,
+            'PIXEL ART CONSTRAINTS: hard edges only, no anti-aliasing, no blur, no gradients, no soft shadows, no sub-pixel rendering, no dithering.',
+            'Each visible pixel must be a clean square with a uniform color value.',
+            'The subject must fill at least 80% of the canvas and remain centered.',
+            `The output will be downscaled to ${targetSize} with nearest-neighbor, so detail must survive tiny scale.`,
+            'OUTPUT: one centered sprite only, transparent PNG background, no text, no borders, no extra objects.',
+        ].join(' ');
+    }
+    async renderWithRetry(renderer, assetHint, stylePrompt, targetSize, sourcePaletteHex, category) {
+        const prompts = [
+            this.buildPrompt(assetHint, stylePrompt, targetSize, sourcePaletteHex, category),
+            this.buildFallbackPrompt(assetHint, targetSize, sourcePaletteHex, category),
+        ];
+        let lastError;
+        for (let attempt = 0; attempt < BatchGenerator.MAX_RENDER_ATTEMPTS; attempt += 1) {
+            try {
+                return await renderer(prompts[attempt] ?? prompts[prompts.length - 1]);
+            }
+            catch (error) {
+                lastError = error;
+                if (!this.isModerationBlocked(error) || attempt >= BatchGenerator.MAX_RENDER_ATTEMPTS - 1) {
+                    throw error;
+                }
+                console.warn(`Retrying with safer prompt after moderation block (attempt ${attempt + 2}).`);
+            }
+        }
+        throw lastError instanceof Error ? lastError : new Error('Asset rendering failed.');
+    }
+    buildPrompt(assetHint, stylePrompt, targetSize, sourcePaletteHex, category) {
+        const shortStyle = this.compactText(stylePrompt, BatchGenerator.MAX_STYLE_PROMPT_CHARS);
+        const shortHint = this.compactText(assetHint, BatchGenerator.MAX_ASSET_HINT_CHARS);
+        const categoryContext = this.getCategoryPromptContext(category);
+        const paletteConstraint = this.buildPaletteConstraint(sourcePaletteHex);
+        return [
+            'Image 1 is the SOURCE sprite, upscaled with nearest-neighbor so each original pixel appears as a clean square.',
+            'Image 2 is the approved STYLE REFERENCE for target art direction.',
+            'TASK: Redraw Image 1 in the style of Image 2.',
+            categoryContext,
+            `STYLE DIRECTION: ${shortStyle}.`,
+            `Asset details: ${shortHint}.`,
+            'PRESERVE from Image 1: exact silhouette and proportions (pixel-grid aligned), object identity, recognizable features, pose, orientation, framing, and aspect ratio.',
+            'CHANGE to match Image 2: color palette, shading approach, surface texture, edge language, and overall visual mood.',
+            paletteConstraint,
+            'PIXEL ART CONSTRAINTS:',
+            '- Hard pixel edges only. No anti-aliasing, no blur, no gradients, no soft shadows, no sub-pixel rendering, no dithering.',
+            '- Maximum 16-24 distinct colors.',
+            '- Keep pixel-grid consistency and block clarity with a 16-bit SNES sprite aesthetic.',
+            '- Each visible pixel must be a clean square with a uniform color value.',
+            '- The subject must fill at least 80% of the canvas and remain centered.',
+            `- Output must remain readable after nearest-neighbor downscale to ${targetSize}.`,
+            'OUTPUT: one centered sprite, transparent PNG background, no text, no border, no extra elements.',
+        ].join(' ');
+    }
+    buildPaletteConstraint(sourcePaletteHex) {
+        if (sourcePaletteHex.length === 0) {
+            return 'Use a compact retro palette with 16-24 colors max.';
+        }
+        return `Use ONLY these colors (or very close variations): ${sourcePaletteHex.join(', ')}.`;
+    }
+    getCategoryPromptContext(category) {
+        switch (category) {
+            case 'character':
+                return 'Category context: animation sprite frame. Maintain character identity, stable body proportions, and continuity across frames.';
+            case 'resource':
+                return 'Category context: top-down resource node. Keep a strong silhouette and immediate recognition at tiny scale.';
+            case 'effect':
+                return 'Category context: gameplay VFX icon. Keep lightweight form and high contrast over varied backgrounds.';
+            case 'prop':
+                return 'Category context: world prop. Preserve distinct shape language and clear readability across camera zoom levels.';
+            case 'icon':
+                return 'Category context: marker icon. Prioritize maximum readability at 16x16.';
+            case 'scene':
+                return 'Category context: full scene artwork. Preserve overall composition, layer depth, and camera perspective.';
+            case 'font':
+                return 'Category context: bitmap font strip. Preserve exact glyph grid, spacing, baseline, and character order.';
+            default:
+                return 'Category context: game sprite. Keep gameplay readability and clear shape separation.';
+        }
+    }
+    compactText(value, maxChars) {
+        const normalized = value.replace(/\s+/g, ' ').trim();
+        if (normalized.length <= maxChars) {
+            return normalized;
+        }
+        return `${normalized.slice(0, maxChars - 3)}...`;
+    }
+}

package/dist/ImageProcessor.d.ts

@@ -0,0 +1,15 @@
+import { SpriteSheetAssetDefinition } from './types.js';
+export type ImageRenderSize = '256x256' | '512x512' | '1024x1024';
+export declare class ImageProcessor {
+    private parseRenderSize;
+    chooseRenderSize(width: number, height: number): ImageRenderSize;
+    private loadAsPngBufferWithFallback;
+    ensureDir(dirPath: string): Promise<void>;
+    readAsPngBuffer(sourcePath: string): Promise<Buffer>;
+    convertToPng(sourcePath: string, outputPath: string): Promise<void>;
+    writeBuffer(buffer: Buffer, outputPath: string): Promise<void>;
+    fitToExactSize(input: Buffer | string, width: number, height: number, outputPath?: string): Promise<Buffer>;
+    upscaleForGeneration(source: Buffer, renderSize: ImageRenderSize): Promise<Buffer>;
+    extractSpriteFrames(sourcePath: string, spriteSheet: SpriteSheetAssetDefinition): Promise<Buffer[]>;
+    stitchVerticalSpriteSheet(frames: Buffer[], frameWidth: number, frameHeight: number, outputPath: string): Promise<void>;
+}

package/dist/ImageProcessor.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import sharp from 'sharp';
+const execFileAsync = promisify(execFile);
+export class ImageProcessor {
+    parseRenderSize(renderSize) {
+        return Number.parseInt(renderSize.split('x')[0] ?? '1024', 10);
+    }
+    chooseRenderSize(width, height) {
+        const maxDimension = Math.max(width, height);
+        if (maxDimension <= 20) {
+            return '256x256';
+        }
+        if (maxDimension <= 96) {
+            return '512x512';
+        }
+        return '1024x1024';
+    }
+    async loadAsPngBufferWithFallback(sourcePath) {
+        try {
+            return await sharp(sourcePath).png().toBuffer();
+        }
+        catch {
+            const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'restyle-sprites-'));
+            const tempPngPath = path.join(tempDir, 'source.png');
+            try {
+                await execFileAsync('sips', ['-s', 'format', 'png', sourcePath, '--out', tempPngPath]);
+                return await fs.readFile(tempPngPath);
+            }
+            finally {
+                await fs.rm(tempDir, { recursive: true, force: true });
+            }
+        }
+    }
+    async ensureDir(dirPath) {
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+    async readAsPngBuffer(sourcePath) {
+        return this.loadAsPngBufferWithFallback(sourcePath);
+    }
+    async convertToPng(sourcePath, outputPath) {
+        await this.ensureDir(path.dirname(outputPath));
+        try {
+            await sharp(sourcePath).png().toFile(outputPath);
+        }
+        catch {
+            await execFileAsync('sips', ['-s', 'format', 'png', sourcePath, '--out', outputPath]);
+        }
+    }
+    async writeBuffer(buffer, outputPath) {
+        await this.ensureDir(path.dirname(outputPath));
+        await fs.writeFile(outputPath, buffer);
+    }
+    async fitToExactSize(input, width, height, outputPath) {
+        const normalizedInput = typeof input === 'string' ? await this.loadAsPngBufferWithFallback(input) : input;
+        const buffer = await sharp(normalizedInput)
+            .resize(width, height, {
+            fit: 'contain',
+            position: 'centre',
+            background: { r: 0, g: 0, b: 0, alpha: 0 },
+            kernel: sharp.kernel.nearest,
+        })
+            .png()
+            .toBuffer();
+        if (outputPath) {
+            await this.ensureDir(path.dirname(outputPath));
+            await fs.writeFile(outputPath, buffer);
+        }
+        return buffer;
+    }
+    async upscaleForGeneration(source, renderSize) {
+        const targetSize = this.parseRenderSize(renderSize);
+        return sharp(source)
+            .resize(targetSize, targetSize, {
+            fit: 'contain',
+            position: 'centre',
+            background: { r: 0, g: 0, b: 0, alpha: 0 },
+            kernel: sharp.kernel.nearest,
+        })
+            .png()
+            .toBuffer();
+    }
+    async extractSpriteFrames(sourcePath, spriteSheet) {
+        const normalizedSource = await this.loadAsPngBufferWithFallback(sourcePath);
+        const frames = [];
+        for (let frameIndex = 0; frameIndex < spriteSheet.frameCount; frameIndex += 1) {
+            const left = spriteSheet.frameDirection === 'horizontal' ? frameIndex * spriteSheet.frameWidth : 0;
+            const top = spriteSheet.frameDirection === 'vertical' ? frameIndex * spriteSheet.frameHeight : 0;
+            const frameBuffer = await sharp(normalizedSource)
+                .extract({
+                left,
+                top,
+                width: spriteSheet.frameWidth,
+                height: spriteSheet.frameHeight,
+            })
+                .png()
+                .toBuffer();
+            frames.push(frameBuffer);
+        }
+        return frames;
+    }
+    async stitchVerticalSpriteSheet(frames, frameWidth, frameHeight, outputPath) {
+        const canvasHeight = frameHeight * frames.length;
+        const composite = frames.map((input, index) => ({
+            input,
+            left: 0,
+            top: index * frameHeight,
+        }));
+        const output = await sharp({
+            create: {
+                width: frameWidth,
+                height: canvasHeight,
+                channels: 4,
+                background: { r: 0, g: 0, b: 0, alpha: 0 },
+            },
+        })
+            .composite(composite)
+            .png()
+            .toBuffer();
+        await this.ensureDir(path.dirname(outputPath));
+        await fs.writeFile(outputPath, output);
+    }
+}

package/dist/OpenAIImageClient.d.ts

@@ -0,0 +1,38 @@
+import type { ImageRenderSize } from './ImageProcessor.js';
+export interface OpenAIImageClientOptions {
+    model?: 'gpt-image-1.5' | 'gpt-image-1' | 'gpt-image-1-mini';
+}
+export interface StyleReferenceResult {
+    image: Buffer;
+    revisedPrompt?: string;
+    responseId?: string;
+}
+export declare class OpenAIImageClient {
+    private static readonly STYLE_REFERENCE_MAX_ATTEMPTS;
+    private readonly client;
+    private readonly model;
+    private readonly geminiModel;
+    constructor(options?: OpenAIImageClientOptions);
+    private getOpenAIModelCandidates;
+    generateStyleReference(prompt: string, inspirationImagePath?: string): Promise<StyleReferenceResult>;
+    restyleAsset(params: {
+        sourceAssetPath: string;
+        styleReferencePath: string;
+        prompt: string;
+        renderSize?: ImageRenderSize;
+    }): Promise<Buffer>;
+    restyleAssetBuffer(params: {
+        sourceAsset: Buffer;
+        styleReferencePath: string;
+        prompt: string;
+        renderSize?: ImageRenderSize;
+    }): Promise<Buffer>;
+    private generateWithOpenAI;
+    private generateWithOpenAIRestyle;
+    private shouldFallbackToOpenAI;
+    private isModelNotFound;
+    private generateWithGemini;
+    private sanitizeStyleReferenceBuffer;
+    private analyzeStyleReferenceQuality;
+    private isNeutralCheckerColor;
+}