import { Buffer } from 'buffer';
import { type WorldPatch } from '@bitmagic/asset-core';
import type { GenerationOutcome } from '../generate/stream.js';
import { type GenerateRunDeps } from './generate.js';
/** The design document `bitmagic init` scaffolds and the coding agent maintains. */
export declare const GAME_DESIGN_FILE = "GAME-DESIGN.md";
export declare function coverImagePath(root: string): string;
export interface CoverRecord {
    /** The public image URL, as written into world.json. */
    url: string;
    /** Hash of the design text this cover was drawn from — see `readCoverRecord`. */
    designHash: string;
    generatedAt: string;
}
/**
 * Identifies the design text a cover was generated from, so a repeat `bitmagic cover` on an
 * unchanged design can decline to spend sparks on the same picture twice. This is the local
 * equivalent of `PLAN_COVER_CACHE` in game-play-agent's PromptToGameController, which does the
 * same for Planning Mode, keyed the same way — on the design text rather than the game.
 */
export declare function hashDesign(designText: string): string;
export declare function readCoverRecord(root: string): CoverRecord | null;
/**
 * The prose the cover is drawn from: `--prompt` when given, otherwise GAME-DESIGN.md.
 *
 * `--prompt` is a one-call override and is never written to the file — the design document belongs
 * to the creator, and a flag silently rewriting it would be a surprise the next `bitmagic cover`
 * inherits.
 *
 * The error path matters as much as the happy one: projects scaffolded before GAME-DESIGN.md
 * existed have no such file, and an agent that only sees "not found" cannot tell whether it should
 * create one or has run the command in the wrong place. So the message says both what to write and
 * what to run instead.
 */
export declare function resolveDesignText(options: {
    promptFlag?: string | undefined;
    root: string;
    readFile?: (file: string) => string;
}): string;
/**
 * The generated image's URL, read back out of the patch the image generator returned.
 *
 * The generator's terminal frame carries only `{ success, message, patches }` — the URL is not a
 * separate field on the wire — so the patch it upserts into `assets[]` is where it lives. Matched
 * on the patch's own shape rather than on the message text, which is prose and not a contract.
 */
export declare function coverUrlFromPatches(patches: WorldPatch[]): string | null;
/**
 * The patch that puts the cover behind the game's start screen.
 *
 * `set`, NOT `setRoot`: `set` addresses a path inside `worldProfileData`, which is where the
 * engine's GameRuntimeController reads `hud.startScreen.imageUrl` from. A root-level write would
 * land somewhere nothing ever looks and report success — the exact trap apply-patches.ts documents.
 */
export declare function startScreenPatch(url: string): WorldPatch;
export interface CoverArgs {
    prompt?: string;
    force?: boolean;
    'reference-image-url'?: string;
    /** A local image file to use as this cover's reference — uploaded first. */
    'reference-image'?: string;
    /** citty's negative boolean: `--no-reference` arrives here as `false`. */
    reference?: boolean;
    /** citty's negative form of the boolean flag: `--no-start-screen` arrives here as `false`. */
    'start-screen'?: boolean;
    json?: boolean;
}
export interface CoverRunDeps extends GenerateRunDeps {
    /**
     * Seam over `runAssetGeneration`, so a test can drive this without a network or a token.
     *
     * Deliberately narrower than `runAssetGeneration`'s own signature: it omits that function's
     * `json` parameter, because this command always passes `false` there. Under `--json` stdout must
     * carry exactly one document, and this command emits its own.
     */
    generate: (type: string, label: string, body: Record<string, unknown>, json: boolean, deps: GenerateRunDeps) => Promise<GenerationOutcome>;
    /** Returns whether the terminal actually drew the image. */
    renderImage: (bytes: Buffer) => boolean;
    /** The machine-readable result, emitted only under `--json`. */
    result: (value: unknown) => void;
}
export declare function runCover(args: CoverArgs, deps?: CoverRunDeps): Promise<void>;
export declare const coverCommand: import("citty").CommandDef<{
    readonly prompt: {
        readonly type: "string";
        readonly description: "Describe the game for this call only, instead of reading GAME-DESIGN.md. Never written to the file.";
    };
    readonly force: {
        readonly type: "boolean";
        readonly description: "Generate a new cover even when the design has not changed since the last one.";
    };
    readonly 'start-screen': {
        readonly type: "boolean";
        readonly negativeDescription: "Leave hud.startScreen.imageUrl alone — still saves the cover and uses it as the publish thumbnail.";
    };
    readonly 'reference-image-url': {
        readonly type: "string";
        readonly description: "Style/composition reference image URL forwarded to the image model. Overrides the accepted project reference for this call.";
    };
    readonly 'reference-image': {
        readonly type: "string";
        readonly description: "A local image file (PNG/JPEG/WebP) to use as the reference for this call — uploaded to the game's storage first. Overrides the accepted project reference.";
    };
    readonly reference: {
        readonly type: "boolean";
        readonly negativeDescription: "Do not apply the accepted project reference image (`bitmagic reference`) to this call.";
    };
    readonly 'original-prompt': {
        readonly type: "string";
        readonly description: string;
    };
    readonly json: {
        readonly type: "boolean";
        readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
    };
}>;