pixelkiln 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,2679 @@
+import { z } from 'zod';
+
+/**
+ * Which PixelLab endpoint produces the asset. The choice is mostly about cost,
+ * and the gap is enormous — all figures measured against a live account.
+ *
+ *   map   POST /map-objects — THE DEFAULT.
+ *         A flat 1 generation at any size. Purpose-built for standalone props
+ *         with transparent backgrounds, which is what an icon or a prop is.
+ *         Arbitrary width x height. Returns exactly one result, so there is no
+ *         selection step: if you dislike it, re-roll for 1 more.
+ *
+ *   1dir  POST /create-1-direction-object — 20-40 generations.
+ *         The single-facing sibling of create-8-direction-object, meant for
+ *         objects you may later want rotations or animations of. Square only.
+ *         Returns 4-64 candidates for its one fixed price, which is genuinely
+ *         useful when you want to compare options side by side — but at 40x the
+ *         cost of a map object, re-rolling a map object forty times is the same
+ *         money. Reach for this when you need rotations, or when the extra
+ *         rendering detail is worth 40x.
+ *
+ * Rule of thumb: if the asset is a standalone image and you are not going to
+ * animate or rotate it, `map` is the right call. Generating 65 icons costs 65
+ * generations that way and 2,600 the other.
+ *
+ * Not yet implemented, but measured and worth knowing (see README):
+ *   POST /create-image-pixflux also costs 1 generation, returns the image
+ *   INLINE with no polling, and accepts `color_image` — a forced palette that
+ *   constrains output to exact hex values. Verified: a four-colour Game Boy
+ *   swatch produced output containing precisely those four colours. The same
+ *   parameter on /map-objects returns a 500, so the palette lock is
+ *   pixflux-only. Its rendering is flatter than 1dir's.
+ */
+declare const GeneratorSchema: z.ZodEnum<["1dir", "map", "pixflux", "tiles"]>;
+type Generator = z.infer<typeof GeneratorSchema>;
+/** A decoded style reference ready for a provider-specific request body. */
+interface ResolvedStyleImage {
+    base64: string;
+    width: number;
+    height: number;
+    format: "png" | "jpeg";
+}
+/**
+ * `tiles` is the odd one out: the unit of work is a *set*, not a sprite.
+ *
+ * POST /create-tiles-pro draws tile shape outlines and fills them, returning
+ * many variations from one call. Independent variations land in the same
+ * review-then-pick flow as `1dir`; connectable features are structural sets
+ * and every returned storage URL is retained. There is no select-frames step
+ * to run for either form.
+ *
+ * Two properties make it worth a generator of its own rather than a flag on
+ * `1dir`:
+ *
+ *   - **Style mode overrides geometry.** Passing `styleImages` makes the API
+ *     copy tile shape and dimensions from the reference and ignore
+ *     `tileType`/`tileView` entirely. For an existing tileset that is the
+ *     point: it is the only way to land new art on the same ground plane as
+ *     the tiles already in the sheet.
+ *   - **`tileFeature` generates connectable sets.** `"tileset"` returns a
+ *     16-tile Wang corner set for a terrain transition, `"roads"` an
+ *     18-configuration path set. Those are structural outputs; a consumer
+ *     slices them by index, not by eye.
+ */
+/**
+ * Variations a `tiles` call returns. The API derives this from the tile size
+ * and how many numbered descriptions the prompt contains; observed at 4 per
+ * numbered description for 32px isometric tiles. Clamped so a prompt with no
+ * numbering still reports at least one.
+ */
+declare function tileVariationCount(descriptions: number): number;
+/** Known structural output counts for connectable tile features. */
+declare function tileFeatureOutputCount(feature: string | undefined): number | null;
+/**
+ * Numbered items in a `tiles` prompt. The endpoint documents `"1). grass
+ * 2). dirt"` as the way to control what comes back, and returns a group of
+ * variations per number.
+ */
+declare function countNumberedDescriptions(prompt: string): number;
+/** Candidate frames returned per call, derived from size. Extra candidates are free. */
+declare function candidateCount(size: number): number;
+/**
+ * Generation cost per call. Measured against a live account, not inferred.
+ *
+ * The two generators are priced completely differently, and the gap is wide
+ * enough to change which one you should reach for:
+ *
+ *   map   FLAT 1 generation, any size. Verified: a 32x36 and a 64x96 map object
+ *         each cost exactly 1 (balance 4751 → 4750 → 4749). Single result.
+ *
+ *   1dir  20-40 by canvas tier (1K=20, 2K=25, 4K=40), returning 4-64
+ *         candidates for that one price.
+ *
+ *   tiles 20-40 on the same canvas tiers as `1dir`, but the canvas is picked
+ *         from tile size x variation count rather than a single sprite, so a
+ *         small tile in a large set can still reach the top tier. Reported by
+ *         the API at submit time; estimated here from the widest canvas the
+ *         request can produce, which is the honest direction to be wrong in
+ *         for a `--budget` check.
+ *
+ * So `1dir` buys candidate variety at 20-40x the price, and `map` buys
+ * arbitrary (non-square) dimensions nearly free. For a single-result asset,
+ * forty re-rolls of a map object cost the same as one 1dir call.
+ */
+declare function generationCost(width: number, height: number, generator?: Generator): number;
+/**
+ * Cost of one `tiles` call. Same canvas tiers as `1dir`, but the canvas is the
+ * sheet the API lays the variations out on, not one tile — so tile size alone
+ * under-reads it badly (a 32px tile is 1024px on its own and would always
+ * price at the floor).
+ *
+ * Estimated from tileSize^2 x variations, which is the area actually drawn.
+ * `plan` prints this before anything is spent and `--budget` refuses on it, so
+ * over-reading is the safe direction: a call that comes in cheaper than
+ * budgeted is a pleasant surprise, one that comes in dearer is an overspend.
+ */
+declare function tilesCost(tileSize: number, variations: number): number;
+declare const StyleSchema: z.ZodEffects<z.ZodObject<{
+    generator: z.ZodDefault<z.ZodEnum<["1dir", "map", "pixflux", "tiles"]>>;
+    /** Square edge length for `1dir`. 32-256. */
+    size: z.ZodOptional<z.ZodNumber>;
+    view: z.ZodOptional<z.ZodString>;
+    /** Appended to every asset prompt in this style. Where the look is defined. */
+    promptSuffix: z.ZodDefault<z.ZodString>;
+    /** Prepended to every asset prompt in this style. */
+    promptPrefix: z.ZodDefault<z.ZodString>;
+    /** Style reference images. */
+    styleImages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** Path to a PNG/JPEG, relative to the manifest file. Max 256x256. */
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path: string;
+    }>, "many">>;
+    /** Output root for this style, relative to the manifest. */
+    outDir: z.ZodString;
+    /** `map` generator only. */
+    outline: z.ZodOptional<z.ZodString>;
+    shading: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+    /**
+     * `tiles` generator only. Edge length of one tile, 16-256.
+     *
+     * Ignored when `styleImages` is set — style mode takes the tile's shape
+     * and dimensions from the reference image, which is the whole reason to
+     * use it against an existing sheet.
+     */
+    tileSize: z.ZodOptional<z.ZodNumber>;
+    /** `tiles` generator only. Defaults to the API's `isometric`. */
+    tileType: z.ZodOptional<z.ZodEnum<["hex", "hex_pointy", "isometric", "oblique", "octagon", "square_topdown"]>>;
+    /** `tiles` generator only. Defaults to the API's `low top-down`. */
+    tileView: z.ZodOptional<z.ZodEnum<["top-down", "high top-down", "low top-down", "side"]>>;
+    /**
+     * `tiles` generator only. Asks for a connectable set instead of
+     * independent variations:
+     *
+     *   roads    18-configuration path set
+     *   tileset  16-tile Wang corner set for a terrain transition — describe
+     *            the asset as the transition itself ("fairway grass to rough
+     *            meadow"), not as one terrain
+     *   building floor/wall/doorway construction kit
+     *
+     * A consumer slices these by index, so the order the API returns them in
+     * is load-bearing; do not sort a connectable set by anything else.
+     */
+    tileFeature: z.ZodOptional<z.ZodEnum<["roads", "tileset", "building"]>>;
+    /**
+     * `tiles` generator only. How tile edges are drawn.
+     *
+     * The API default is `outline`, which draws a dark border around every
+     * tile. That is right for tiles meant to read as discrete objects and
+     * wrong for ground: laid on a grid, the per-tile borders turn a continuous
+     * surface into visible quilting, with a dark seam at every cell edge.
+     * `segmentation` omits them and the same set tiles seamlessly.
+     *
+     * Measured on a fairway-to-rough terrain set — the difference decided
+     * whether the art was usable at all, so it is worth setting deliberately
+     * rather than inheriting.
+     */
+    outlineMode: z.ZodOptional<z.ZodEnum<["outline", "segmentation"]>>;
+    /**
+     * `pixflux` only. Whether to strip the generated background.
+     *
+     * Defaults to true, which is right for the sprites this tool was built
+     * for — a prop or an icon wants to sit on whatever is behind it. It is
+     * wrong for anything that IS a scene: a cover banner, a splash, a
+     * backdrop. The API's own default is false; forcing it true unconditionally
+     * meant a full-bleed image came back as a small subject floating in a
+     * mostly-empty frame, and prose asking for an "opaque background" does not
+     * override it.
+     */
+    noBackground: z.ZodDefault<z.ZodBoolean>;
+    /** Fixed seed for reproducibility where the endpoint supports it. */
+    seed: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Forced palette, as `#rrggbb` values. `pixflux` only.
+     *
+     * Unlike prose, this is a hard constraint — the API is handed a swatch
+     * image and the output is limited to those colours. Verified: a four-colour
+     * Game Boy palette produced output containing exactly those four values.
+     * Prose asking for the same thing does not reliably hold, which is why the
+     * map-generated monochrome sets came back with a yellow star and a brown
+     * chocolate bar.
+     */
+    palette: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Composites this style's assets into declared cells of a sheet, rather
+     * than letting `pack` derive a layout. Use it when the atlas coordinates
+     * are already load-bearing somewhere else — a tile engine naming tiles by
+     * cell, or saved data storing cell indices — since `pack`'s id-sorted grid
+     * moves every position when an asset is added or renamed.
+     *
+     * Assets in a mounted style declare their own `cell`; ones that do not are
+     * left out of the sheet.
+     */
+    mount: z.ZodOptional<z.ZodObject<{
+        /**
+         * Existing sheet to composite into, relative to the manifest. Every
+         * pixel outside a declared cell survives byte-for-byte, so a
+         * hand-authored sheet can be part generated and part drawn. Omit to
+         * start from transparent.
+         */
+        base: z.ZodOptional<z.ZodString>;
+        cellWidth: z.ZodNumber;
+        cellHeight: z.ZodNumber;
+        /** Where the composited sheet is written, relative to the manifest. */
+        out: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        cellWidth: number;
+        cellHeight: number;
+        out: string;
+        base?: string | undefined;
+    }, {
+        cellWidth: number;
+        cellHeight: number;
+        out: string;
+        base?: string | undefined;
+    }>>;
+    /** Tags applied to every object generated in this style, for server-side filtering. */
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    generator: "1dir" | "map" | "pixflux" | "tiles";
+    promptSuffix: string;
+    promptPrefix: string;
+    styleImages: {
+        path: string;
+    }[];
+    outDir: string;
+    noBackground: boolean;
+    palette: string[];
+    tags: string[];
+    size?: number | undefined;
+    view?: string | undefined;
+    outline?: string | undefined;
+    shading?: string | undefined;
+    detail?: string | undefined;
+    tileSize?: number | undefined;
+    tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+    tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+    tileFeature?: "roads" | "tileset" | "building" | undefined;
+    outlineMode?: "outline" | "segmentation" | undefined;
+    seed?: number | undefined;
+    mount?: {
+        cellWidth: number;
+        cellHeight: number;
+        out: string;
+        base?: string | undefined;
+    } | undefined;
+}, {
+    outDir: string;
+    generator?: "1dir" | "map" | "pixflux" | "tiles" | undefined;
+    size?: number | undefined;
+    view?: string | undefined;
+    promptSuffix?: string | undefined;
+    promptPrefix?: string | undefined;
+    styleImages?: {
+        path: string;
+    }[] | undefined;
+    outline?: string | undefined;
+    shading?: string | undefined;
+    detail?: string | undefined;
+    tileSize?: number | undefined;
+    tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+    tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+    tileFeature?: "roads" | "tileset" | "building" | undefined;
+    outlineMode?: "outline" | "segmentation" | undefined;
+    noBackground?: boolean | undefined;
+    seed?: number | undefined;
+    palette?: string[] | undefined;
+    mount?: {
+        cellWidth: number;
+        cellHeight: number;
+        out: string;
+        base?: string | undefined;
+    } | undefined;
+    tags?: string[] | undefined;
+}>, {
+    generator: "1dir" | "map" | "pixflux" | "tiles";
+    promptSuffix: string;
+    promptPrefix: string;
+    styleImages: {
+        path: string;
+    }[];
+    outDir: string;
+    noBackground: boolean;
+    palette: string[];
+    tags: string[];
+    size?: number | undefined;
+    view?: string | undefined;
+    outline?: string | undefined;
+    shading?: string | undefined;
+    detail?: string | undefined;
+    tileSize?: number | undefined;
+    tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+    tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+    tileFeature?: "roads" | "tileset" | "building" | undefined;
+    outlineMode?: "outline" | "segmentation" | undefined;
+    seed?: number | undefined;
+    mount?: {
+        cellWidth: number;
+        cellHeight: number;
+        out: string;
+        base?: string | undefined;
+    } | undefined;
+}, {
+    outDir: string;
+    generator?: "1dir" | "map" | "pixflux" | "tiles" | undefined;
+    size?: number | undefined;
+    view?: string | undefined;
+    promptSuffix?: string | undefined;
+    promptPrefix?: string | undefined;
+    styleImages?: {
+        path: string;
+    }[] | undefined;
+    outline?: string | undefined;
+    shading?: string | undefined;
+    detail?: string | undefined;
+    tileSize?: number | undefined;
+    tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+    tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+    tileFeature?: "roads" | "tileset" | "building" | undefined;
+    outlineMode?: "outline" | "segmentation" | undefined;
+    noBackground?: boolean | undefined;
+    seed?: number | undefined;
+    palette?: string[] | undefined;
+    mount?: {
+        cellWidth: number;
+        cellHeight: number;
+        out: string;
+        base?: string | undefined;
+    } | undefined;
+    tags?: string[] | undefined;
+}>;
+declare const AssetSchema: z.ZodObject<{
+    /** The subject. Style wrapping comes from the style's prefix/suffix. */
+    prompt: z.ZodString;
+    /** Subdirectory under the style's outDir. Optional. */
+    category: z.ZodOptional<z.ZodString>;
+    /** Overrides the style default. `map` generator only. */
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    /** Overrides the style default. `1dir` generator only. */
+    size: z.ZodOptional<z.ZodNumber>;
+    /** Explicit output path relative to outDir. Defaults to `<category>/<id>.png`. */
+    file: z.ZodOptional<z.ZodString>;
+    /**
+     * Grid cell this asset owns in a mounted style, as [column, row].
+     *
+     * Declared rather than derived, which is the point of `mount`: the
+     * coordinate is a contract with whatever already reads the sheet, so it
+     * must not move when the asset set changes. Assets without one are left
+     * out of the mounted sheet.
+     */
+    cell: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    /**
+     * Path, relative to the manifest, of the art that goes on a mounted
+     * sheet — when that is not the raw generated output.
+     *
+     * `mount` otherwise takes its pixels from the lockfile, which records
+     * what the API returned. That is the wrong file whenever the art needs a
+     * step pixelkiln does not perform: a palette reduction onto a sheet's
+     * closed palette, a hand touch-up, an alignment shift. Without somewhere
+     * to say so, the choice is to mount the unprocessed art or to abandon
+     * `mount` and composite by hand — and the hand-composited sheet is
+     * exactly the unreproducible artifact `mount` exists to replace.
+     *
+     * An asset with a `source` needs no lockfile entry at all, so art
+     * generated outside pixelkiln can still be placed by cell alongside art
+     * that wasn't. `prompt` still records what was asked for.
+     */
+    source: z.ZodOptional<z.ZodString>;
+    /**
+     * Generated output role to place in `cell` when this asset expands to
+     * several files. Omit for ordinary single-output assets. A structural set
+     * is otherwise ambiguous and `mount` refuses to guess by taking index zero.
+     */
+    outputRole: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Restrict this asset to specific styles. Empty means all styles. */
+    styles: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Per-style replacement for `prompt`, keyed by style id.
+     *
+     * A style can need different wording rather than different styling. A
+     * monochrome style is the clear case: prompts that name colours
+     * ("green purple gold", "colorful rainbow") override the palette
+     * instruction and survive into the output, while the same prompt is
+     * exactly right for a colour style. Editing the shared prompt to suit one
+     * style would invalidate every other style's already-generated art.
+     */
+    promptByStyle: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    tags: string[];
+    prompt: string;
+    styles: string[];
+    promptByStyle: Record<string, string>;
+    size?: number | undefined;
+    category?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    file?: string | undefined;
+    cell?: [number, number] | undefined;
+    source?: string | undefined;
+    outputRole?: string | undefined;
+}, {
+    prompt: string;
+    size?: number | undefined;
+    tags?: string[] | undefined;
+    category?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    file?: string | undefined;
+    cell?: [number, number] | undefined;
+    source?: string | undefined;
+    outputRole?: string | undefined;
+    styles?: string[] | undefined;
+    promptByStyle?: Record<string, string> | undefined;
+}>;
+declare const ManifestSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    styles: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        generator: z.ZodDefault<z.ZodEnum<["1dir", "map", "pixflux", "tiles"]>>;
+        /** Square edge length for `1dir`. 32-256. */
+        size: z.ZodOptional<z.ZodNumber>;
+        view: z.ZodOptional<z.ZodString>;
+        /** Appended to every asset prompt in this style. Where the look is defined. */
+        promptSuffix: z.ZodDefault<z.ZodString>;
+        /** Prepended to every asset prompt in this style. */
+        promptPrefix: z.ZodDefault<z.ZodString>;
+        /** Style reference images. */
+        styleImages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Path to a PNG/JPEG, relative to the manifest file. Max 256x256. */
+            path: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+        }, {
+            path: string;
+        }>, "many">>;
+        /** Output root for this style, relative to the manifest. */
+        outDir: z.ZodString;
+        /** `map` generator only. */
+        outline: z.ZodOptional<z.ZodString>;
+        shading: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        /**
+         * `tiles` generator only. Edge length of one tile, 16-256.
+         *
+         * Ignored when `styleImages` is set — style mode takes the tile's shape
+         * and dimensions from the reference image, which is the whole reason to
+         * use it against an existing sheet.
+         */
+        tileSize: z.ZodOptional<z.ZodNumber>;
+        /** `tiles` generator only. Defaults to the API's `isometric`. */
+        tileType: z.ZodOptional<z.ZodEnum<["hex", "hex_pointy", "isometric", "oblique", "octagon", "square_topdown"]>>;
+        /** `tiles` generator only. Defaults to the API's `low top-down`. */
+        tileView: z.ZodOptional<z.ZodEnum<["top-down", "high top-down", "low top-down", "side"]>>;
+        /**
+         * `tiles` generator only. Asks for a connectable set instead of
+         * independent variations:
+         *
+         *   roads    18-configuration path set
+         *   tileset  16-tile Wang corner set for a terrain transition — describe
+         *            the asset as the transition itself ("fairway grass to rough
+         *            meadow"), not as one terrain
+         *   building floor/wall/doorway construction kit
+         *
+         * A consumer slices these by index, so the order the API returns them in
+         * is load-bearing; do not sort a connectable set by anything else.
+         */
+        tileFeature: z.ZodOptional<z.ZodEnum<["roads", "tileset", "building"]>>;
+        /**
+         * `tiles` generator only. How tile edges are drawn.
+         *
+         * The API default is `outline`, which draws a dark border around every
+         * tile. That is right for tiles meant to read as discrete objects and
+         * wrong for ground: laid on a grid, the per-tile borders turn a continuous
+         * surface into visible quilting, with a dark seam at every cell edge.
+         * `segmentation` omits them and the same set tiles seamlessly.
+         *
+         * Measured on a fairway-to-rough terrain set — the difference decided
+         * whether the art was usable at all, so it is worth setting deliberately
+         * rather than inheriting.
+         */
+        outlineMode: z.ZodOptional<z.ZodEnum<["outline", "segmentation"]>>;
+        /**
+         * `pixflux` only. Whether to strip the generated background.
+         *
+         * Defaults to true, which is right for the sprites this tool was built
+         * for — a prop or an icon wants to sit on whatever is behind it. It is
+         * wrong for anything that IS a scene: a cover banner, a splash, a
+         * backdrop. The API's own default is false; forcing it true unconditionally
+         * meant a full-bleed image came back as a small subject floating in a
+         * mostly-empty frame, and prose asking for an "opaque background" does not
+         * override it.
+         */
+        noBackground: z.ZodDefault<z.ZodBoolean>;
+        /** Fixed seed for reproducibility where the endpoint supports it. */
+        seed: z.ZodOptional<z.ZodNumber>;
+        /**
+         * Forced palette, as `#rrggbb` values. `pixflux` only.
+         *
+         * Unlike prose, this is a hard constraint — the API is handed a swatch
+         * image and the output is limited to those colours. Verified: a four-colour
+         * Game Boy palette produced output containing exactly those four values.
+         * Prose asking for the same thing does not reliably hold, which is why the
+         * map-generated monochrome sets came back with a yellow star and a brown
+         * chocolate bar.
+         */
+        palette: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Composites this style's assets into declared cells of a sheet, rather
+         * than letting `pack` derive a layout. Use it when the atlas coordinates
+         * are already load-bearing somewhere else — a tile engine naming tiles by
+         * cell, or saved data storing cell indices — since `pack`'s id-sorted grid
+         * moves every position when an asset is added or renamed.
+         *
+         * Assets in a mounted style declare their own `cell`; ones that do not are
+         * left out of the sheet.
+         */
+        mount: z.ZodOptional<z.ZodObject<{
+            /**
+             * Existing sheet to composite into, relative to the manifest. Every
+             * pixel outside a declared cell survives byte-for-byte, so a
+             * hand-authored sheet can be part generated and part drawn. Omit to
+             * start from transparent.
+             */
+            base: z.ZodOptional<z.ZodString>;
+            cellWidth: z.ZodNumber;
+            cellHeight: z.ZodNumber;
+            /** Where the composited sheet is written, relative to the manifest. */
+            out: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            cellWidth: number;
+            cellHeight: number;
+            out: string;
+            base?: string | undefined;
+        }, {
+            cellWidth: number;
+            cellHeight: number;
+            out: string;
+            base?: string | undefined;
+        }>>;
+        /** Tags applied to every object generated in this style, for server-side filtering. */
+        tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        generator: "1dir" | "map" | "pixflux" | "tiles";
+        promptSuffix: string;
+        promptPrefix: string;
+        styleImages: {
+            path: string;
+        }[];
+        outDir: string;
+        noBackground: boolean;
+        palette: string[];
+        tags: string[];
+        size?: number | undefined;
+        view?: string | undefined;
+        outline?: string | undefined;
+        shading?: string | undefined;
+        detail?: string | undefined;
+        tileSize?: number | undefined;
+        tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+        tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+        tileFeature?: "roads" | "tileset" | "building" | undefined;
+        outlineMode?: "outline" | "segmentation" | undefined;
+        seed?: number | undefined;
+        mount?: {
+            cellWidth: number;
+            cellHeight: number;
+            out: string;
+            base?: string | undefined;
+        } | undefined;
+    }, {
+        outDir: string;
+        generator?: "1dir" | "map" | "pixflux" | "tiles" | undefined;
+        size?: number | undefined;
+        view?: string | undefined;
+        promptSuffix?: string | undefined;
+        promptPrefix?: string | undefined;
+        styleImages?: {
+            path: string;
+        }[] | undefined;
+        outline?: string | undefined;
+        shading?: string | undefined;
+        detail?: string | undefined;
+        tileSize?: number | undefined;
+        tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+        tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+        tileFeature?: "roads" | "tileset" | "building" | undefined;
+        outlineMode?: "outline" | "segmentation" | undefined;
+        noBackground?: boolean | undefined;
+        seed?: number | undefined;
+        palette?: string[] | undefined;
+        mount?: {
+            cellWidth: number;
+            cellHeight: number;
+            out: string;
+            base?: string | undefined;
+        } | undefined;
+        tags?: string[] | undefined;
+    }>, {
+        generator: "1dir" | "map" | "pixflux" | "tiles";
+        promptSuffix: string;
+        promptPrefix: string;
+        styleImages: {
+            path: string;
+        }[];
+        outDir: string;
+        noBackground: boolean;
+        palette: string[];
+        tags: string[];
+        size?: number | undefined;
+        view?: string | undefined;
+        outline?: string | undefined;
+        shading?: string | undefined;
+        detail?: string | undefined;
+        tileSize?: number | undefined;
+        tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+        tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+        tileFeature?: "roads" | "tileset" | "building" | undefined;
+        outlineMode?: "outline" | "segmentation" | undefined;
+        seed?: number | undefined;
+        mount?: {
+            cellWidth: number;
+            cellHeight: number;
+            out: string;
+            base?: string | undefined;
+        } | undefined;
+    }, {
+        outDir: string;
+        generator?: "1dir" | "map" | "pixflux" | "tiles" | undefined;
+        size?: number | undefined;
+        view?: string | undefined;
+        promptSuffix?: string | undefined;
+        promptPrefix?: string | undefined;
+        styleImages?: {
+            path: string;
+        }[] | undefined;
+        outline?: string | undefined;
+        shading?: string | undefined;
+        detail?: string | undefined;
+        tileSize?: number | undefined;
+        tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+        tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+        tileFeature?: "roads" | "tileset" | "building" | undefined;
+        outlineMode?: "outline" | "segmentation" | undefined;
+        noBackground?: boolean | undefined;
+        seed?: number | undefined;
+        palette?: string[] | undefined;
+        mount?: {
+            cellWidth: number;
+            cellHeight: number;
+            out: string;
+            base?: string | undefined;
+        } | undefined;
+        tags?: string[] | undefined;
+    }>>;
+    assets: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** The subject. Style wrapping comes from the style's prefix/suffix. */
+        prompt: z.ZodString;
+        /** Subdirectory under the style's outDir. Optional. */
+        category: z.ZodOptional<z.ZodString>;
+        /** Overrides the style default. `map` generator only. */
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        /** Overrides the style default. `1dir` generator only. */
+        size: z.ZodOptional<z.ZodNumber>;
+        /** Explicit output path relative to outDir. Defaults to `<category>/<id>.png`. */
+        file: z.ZodOptional<z.ZodString>;
+        /**
+         * Grid cell this asset owns in a mounted style, as [column, row].
+         *
+         * Declared rather than derived, which is the point of `mount`: the
+         * coordinate is a contract with whatever already reads the sheet, so it
+         * must not move when the asset set changes. Assets without one are left
+         * out of the mounted sheet.
+         */
+        cell: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        /**
+         * Path, relative to the manifest, of the art that goes on a mounted
+         * sheet — when that is not the raw generated output.
+         *
+         * `mount` otherwise takes its pixels from the lockfile, which records
+         * what the API returned. That is the wrong file whenever the art needs a
+         * step pixelkiln does not perform: a palette reduction onto a sheet's
+         * closed palette, a hand touch-up, an alignment shift. Without somewhere
+         * to say so, the choice is to mount the unprocessed art or to abandon
+         * `mount` and composite by hand — and the hand-composited sheet is
+         * exactly the unreproducible artifact `mount` exists to replace.
+         *
+         * An asset with a `source` needs no lockfile entry at all, so art
+         * generated outside pixelkiln can still be placed by cell alongside art
+         * that wasn't. `prompt` still records what was asked for.
+         */
+        source: z.ZodOptional<z.ZodString>;
+        /**
+         * Generated output role to place in `cell` when this asset expands to
+         * several files. Omit for ordinary single-output assets. A structural set
+         * is otherwise ambiguous and `mount` refuses to guess by taking index zero.
+         */
+        outputRole: z.ZodOptional<z.ZodString>;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Restrict this asset to specific styles. Empty means all styles. */
+        styles: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Per-style replacement for `prompt`, keyed by style id.
+         *
+         * A style can need different wording rather than different styling. A
+         * monochrome style is the clear case: prompts that name colours
+         * ("green purple gold", "colorful rainbow") override the palette
+         * instruction and survive into the output, while the same prompt is
+         * exactly right for a colour style. Editing the shared prompt to suit one
+         * style would invalidate every other style's already-generated art.
+         */
+        promptByStyle: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strict", z.ZodTypeAny, {
+        tags: string[];
+        prompt: string;
+        styles: string[];
+        promptByStyle: Record<string, string>;
+        size?: number | undefined;
+        category?: string | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+        file?: string | undefined;
+        cell?: [number, number] | undefined;
+        source?: string | undefined;
+        outputRole?: string | undefined;
+    }, {
+        prompt: string;
+        size?: number | undefined;
+        tags?: string[] | undefined;
+        category?: string | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+        file?: string | undefined;
+        cell?: [number, number] | undefined;
+        source?: string | undefined;
+        outputRole?: string | undefined;
+        styles?: string[] | undefined;
+        promptByStyle?: Record<string, string> | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    styles: Record<string, {
+        generator: "1dir" | "map" | "pixflux" | "tiles";
+        promptSuffix: string;
+        promptPrefix: string;
+        styleImages: {
+            path: string;
+        }[];
+        outDir: string;
+        noBackground: boolean;
+        palette: string[];
+        tags: string[];
+        size?: number | undefined;
+        view?: string | undefined;
+        outline?: string | undefined;
+        shading?: string | undefined;
+        detail?: string | undefined;
+        tileSize?: number | undefined;
+        tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+        tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+        tileFeature?: "roads" | "tileset" | "building" | undefined;
+        outlineMode?: "outline" | "segmentation" | undefined;
+        seed?: number | undefined;
+        mount?: {
+            cellWidth: number;
+            cellHeight: number;
+            out: string;
+            base?: string | undefined;
+        } | undefined;
+    }>;
+    name: string;
+    assets: Record<string, {
+        tags: string[];
+        prompt: string;
+        styles: string[];
+        promptByStyle: Record<string, string>;
+        size?: number | undefined;
+        category?: string | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+        file?: string | undefined;
+        cell?: [number, number] | undefined;
+        source?: string | undefined;
+        outputRole?: string | undefined;
+    }>;
+    $schema?: string | undefined;
+}, {
+    styles: Record<string, {
+        outDir: string;
+        generator?: "1dir" | "map" | "pixflux" | "tiles" | undefined;
+        size?: number | undefined;
+        view?: string | undefined;
+        promptSuffix?: string | undefined;
+        promptPrefix?: string | undefined;
+        styleImages?: {
+            path: string;
+        }[] | undefined;
+        outline?: string | undefined;
+        shading?: string | undefined;
+        detail?: string | undefined;
+        tileSize?: number | undefined;
+        tileType?: "hex" | "hex_pointy" | "isometric" | "oblique" | "octagon" | "square_topdown" | undefined;
+        tileView?: "top-down" | "high top-down" | "low top-down" | "side" | undefined;
+        tileFeature?: "roads" | "tileset" | "building" | undefined;
+        outlineMode?: "outline" | "segmentation" | undefined;
+        noBackground?: boolean | undefined;
+        seed?: number | undefined;
+        palette?: string[] | undefined;
+        mount?: {
+            cellWidth: number;
+            cellHeight: number;
+            out: string;
+            base?: string | undefined;
+        } | undefined;
+        tags?: string[] | undefined;
+    }>;
+    name: string;
+    assets: Record<string, {
+        prompt: string;
+        size?: number | undefined;
+        tags?: string[] | undefined;
+        category?: string | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+        file?: string | undefined;
+        cell?: [number, number] | undefined;
+        source?: string | undefined;
+        outputRole?: string | undefined;
+        styles?: string[] | undefined;
+        promptByStyle?: Record<string, string> | undefined;
+    }>;
+    $schema?: string | undefined;
+}>;
+type Manifest = z.infer<typeof ManifestSchema>;
+type Style = z.infer<typeof StyleSchema>;
+type Asset = z.infer<typeof AssetSchema>;
+/**
+ * One line of the lockfile: the mapping from a spec to the PixelLab object that
+ * satisfies it and the file on disk that came from it. This is the record that
+ * did not exist before — without it, generated objects and downloaded files are
+ * two unrelated piles.
+ */
+declare const LockEntrySchema: z.ZodObject<{
+    styleId: z.ZodString;
+    assetId: z.ZodString;
+    /** sha256 of the resolved spec. Changing a prompt/size/style invalidates it. */
+    specHash: z.ZodString;
+    generator: z.ZodEnum<["1dir", "map", "pixflux", "tiles"]>;
+    /** Connectable tiles must remain multi-output even when polling is resumed later. */
+    tileFeature: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** The resolved prompt actually sent, kept for auditing and for adopt matching. */
+    prompt: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    /** Set at submit time, before the request is awaited, so a crash is recoverable. */
+    jobId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** For `1dir`: the multi-candidate parent object awaiting selection. */
+    reviewObjectId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** The chosen candidate's own object id, once selected. */
+    objectId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    candidateIndex: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    status: z.ZodDefault<z.ZodEnum<["pending", "processing", "review", "selected", "downloaded", "download-failed", "failed"]>>;
+    error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sourceUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Every source in a structural multi-output result, in provider order. */
+    sourceUrls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        role?: string | undefined;
+    }, {
+        url: string;
+        role?: string | undefined;
+    }>, "many">>;
+    /**
+     * Files this entry produced. A plain object generates one; asset kinds that
+     * expand into many — an animated character is ~35 spritesheets plus an engine
+     * resource — need the list, which is why v1's single `file` became this.
+     *
+     * `role` labels non-primary artifacts (e.g. "portrait", "spriteframes") so a
+     * consumer can find the one it wants without pattern-matching on paths.
+     */
+    outputs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        sha256: string;
+        role?: string | undefined;
+    }, {
+        path: string;
+        sha256: string;
+        role?: string | undefined;
+    }>, "many">>;
+    /**
+     * Provider-owned data retained for downstream consumers, namespaced by
+     * provider id. PixelLab connectable sets keep their exact `tileRules` here
+     * so exporters can map images to adjacency rules.
+     */
+    providerMetadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    submittedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    downloadedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Successful-submission estimate in `costUnit`; may be fractional USD. */
+    cost: z.ZodDefault<z.ZodNumber>;
+    /** Unit for `cost`. Defaults preserve pre-unit PixelLab lockfiles. */
+    costUnit: z.ZodDefault<z.ZodEnum<["generations", "usd", "free"]>>;
+    /** Which provider produced this. Absent on entries written before providers. */
+    provider: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "processing" | "review" | "selected" | "downloaded" | "download-failed" | "failed";
+    generator: "1dir" | "map" | "pixflux" | "tiles";
+    tileFeature: string | null;
+    prompt: string;
+    width: number;
+    height: number;
+    styleId: string;
+    assetId: string;
+    specHash: string;
+    jobId: string | null;
+    reviewObjectId: string | null;
+    objectId: string | null;
+    candidateIndex: number | null;
+    error: string | null;
+    sourceUrl: string | null;
+    sourceUrls: {
+        url: string;
+        role?: string | undefined;
+    }[];
+    outputs: {
+        path: string;
+        sha256: string;
+        role?: string | undefined;
+    }[];
+    providerMetadata: Record<string, Record<string, unknown>>;
+    submittedAt: string | null;
+    downloadedAt: string | null;
+    cost: number;
+    costUnit: "generations" | "usd" | "free";
+    provider: string;
+}, {
+    generator: "1dir" | "map" | "pixflux" | "tiles";
+    prompt: string;
+    width: number;
+    height: number;
+    styleId: string;
+    assetId: string;
+    specHash: string;
+    status?: "pending" | "processing" | "review" | "selected" | "downloaded" | "download-failed" | "failed" | undefined;
+    tileFeature?: string | null | undefined;
+    jobId?: string | null | undefined;
+    reviewObjectId?: string | null | undefined;
+    objectId?: string | null | undefined;
+    candidateIndex?: number | null | undefined;
+    error?: string | null | undefined;
+    sourceUrl?: string | null | undefined;
+    sourceUrls?: {
+        url: string;
+        role?: string | undefined;
+    }[] | undefined;
+    outputs?: {
+        path: string;
+        sha256: string;
+        role?: string | undefined;
+    }[] | undefined;
+    providerMetadata?: Record<string, Record<string, unknown>> | undefined;
+    submittedAt?: string | null | undefined;
+    downloadedAt?: string | null | undefined;
+    cost?: number | undefined;
+    costUnit?: "generations" | "usd" | "free" | undefined;
+    provider?: string | undefined;
+}>;
+declare const LockSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    entries: z.ZodRecord<z.ZodString, z.ZodObject<{
+        styleId: z.ZodString;
+        assetId: z.ZodString;
+        /** sha256 of the resolved spec. Changing a prompt/size/style invalidates it. */
+        specHash: z.ZodString;
+        generator: z.ZodEnum<["1dir", "map", "pixflux", "tiles"]>;
+        /** Connectable tiles must remain multi-output even when polling is resumed later. */
+        tileFeature: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        /** The resolved prompt actually sent, kept for auditing and for adopt matching. */
+        prompt: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        /** Set at submit time, before the request is awaited, so a crash is recoverable. */
+        jobId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        /** For `1dir`: the multi-candidate parent object awaiting selection. */
+        reviewObjectId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        /** The chosen candidate's own object id, once selected. */
+        objectId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        candidateIndex: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        status: z.ZodDefault<z.ZodEnum<["pending", "processing", "review", "selected", "downloaded", "download-failed", "failed"]>>;
+        error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        sourceUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        /** Every source in a structural multi-output result, in provider order. */
+        sourceUrls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            role: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            role?: string | undefined;
+        }, {
+            url: string;
+            role?: string | undefined;
+        }>, "many">>;
+        /**
+         * Files this entry produced. A plain object generates one; asset kinds that
+         * expand into many — an animated character is ~35 spritesheets plus an engine
+         * resource — need the list, which is why v1's single `file` became this.
+         *
+         * `role` labels non-primary artifacts (e.g. "portrait", "spriteframes") so a
+         * consumer can find the one it wants without pattern-matching on paths.
+         */
+        outputs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+            role: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            sha256: string;
+            role?: string | undefined;
+        }, {
+            path: string;
+            sha256: string;
+            role?: string | undefined;
+        }>, "many">>;
+        /**
+         * Provider-owned data retained for downstream consumers, namespaced by
+         * provider id. PixelLab connectable sets keep their exact `tileRules` here
+         * so exporters can map images to adjacency rules.
+         */
+        providerMetadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        submittedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        downloadedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        /** Successful-submission estimate in `costUnit`; may be fractional USD. */
+        cost: z.ZodDefault<z.ZodNumber>;
+        /** Unit for `cost`. Defaults preserve pre-unit PixelLab lockfiles. */
+        costUnit: z.ZodDefault<z.ZodEnum<["generations", "usd", "free"]>>;
+        /** Which provider produced this. Absent on entries written before providers. */
+        provider: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "processing" | "review" | "selected" | "downloaded" | "download-failed" | "failed";
+        generator: "1dir" | "map" | "pixflux" | "tiles";
+        tileFeature: string | null;
+        prompt: string;
+        width: number;
+        height: number;
+        styleId: string;
+        assetId: string;
+        specHash: string;
+        jobId: string | null;
+        reviewObjectId: string | null;
+        objectId: string | null;
+        candidateIndex: number | null;
+        error: string | null;
+        sourceUrl: string | null;
+        sourceUrls: {
+            url: string;
+            role?: string | undefined;
+        }[];
+        outputs: {
+            path: string;
+            sha256: string;
+            role?: string | undefined;
+        }[];
+        providerMetadata: Record<string, Record<string, unknown>>;
+        submittedAt: string | null;
+        downloadedAt: string | null;
+        cost: number;
+        costUnit: "generations" | "usd" | "free";
+        provider: string;
+    }, {
+        generator: "1dir" | "map" | "pixflux" | "tiles";
+        prompt: string;
+        width: number;
+        height: number;
+        styleId: string;
+        assetId: string;
+        specHash: string;
+        status?: "pending" | "processing" | "review" | "selected" | "downloaded" | "download-failed" | "failed" | undefined;
+        tileFeature?: string | null | undefined;
+        jobId?: string | null | undefined;
+        reviewObjectId?: string | null | undefined;
+        objectId?: string | null | undefined;
+        candidateIndex?: number | null | undefined;
+        error?: string | null | undefined;
+        sourceUrl?: string | null | undefined;
+        sourceUrls?: {
+            url: string;
+            role?: string | undefined;
+        }[] | undefined;
+        outputs?: {
+            path: string;
+            sha256: string;
+            role?: string | undefined;
+        }[] | undefined;
+        providerMetadata?: Record<string, Record<string, unknown>> | undefined;
+        submittedAt?: string | null | undefined;
+        downloadedAt?: string | null | undefined;
+        cost?: number | undefined;
+        costUnit?: "generations" | "usd" | "free" | undefined;
+        provider?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    entries: Record<string, {
+        status: "pending" | "processing" | "review" | "selected" | "downloaded" | "download-failed" | "failed";
+        generator: "1dir" | "map" | "pixflux" | "tiles";
+        tileFeature: string | null;
+        prompt: string;
+        width: number;
+        height: number;
+        styleId: string;
+        assetId: string;
+        specHash: string;
+        jobId: string | null;
+        reviewObjectId: string | null;
+        objectId: string | null;
+        candidateIndex: number | null;
+        error: string | null;
+        sourceUrl: string | null;
+        sourceUrls: {
+            url: string;
+            role?: string | undefined;
+        }[];
+        outputs: {
+            path: string;
+            sha256: string;
+            role?: string | undefined;
+        }[];
+        providerMetadata: Record<string, Record<string, unknown>>;
+        submittedAt: string | null;
+        downloadedAt: string | null;
+        cost: number;
+        costUnit: "generations" | "usd" | "free";
+        provider: string;
+    }>;
+    version: 2;
+}, {
+    entries: Record<string, {
+        generator: "1dir" | "map" | "pixflux" | "tiles";
+        prompt: string;
+        width: number;
+        height: number;
+        styleId: string;
+        assetId: string;
+        specHash: string;
+        status?: "pending" | "processing" | "review" | "selected" | "downloaded" | "download-failed" | "failed" | undefined;
+        tileFeature?: string | null | undefined;
+        jobId?: string | null | undefined;
+        reviewObjectId?: string | null | undefined;
+        objectId?: string | null | undefined;
+        candidateIndex?: number | null | undefined;
+        error?: string | null | undefined;
+        sourceUrl?: string | null | undefined;
+        sourceUrls?: {
+            url: string;
+            role?: string | undefined;
+        }[] | undefined;
+        outputs?: {
+            path: string;
+            sha256: string;
+            role?: string | undefined;
+        }[] | undefined;
+        providerMetadata?: Record<string, Record<string, unknown>> | undefined;
+        submittedAt?: string | null | undefined;
+        downloadedAt?: string | null | undefined;
+        cost?: number | undefined;
+        costUnit?: "generations" | "usd" | "free" | undefined;
+        provider?: string | undefined;
+    }>;
+    version: 2;
+}>;
+type LockEntry = z.infer<typeof LockEntrySchema>;
+type Lock = z.infer<typeof LockSchema>;
+type LockOutput = LockEntry["outputs"][number];
+/**
+ * Parses a lockfile, rejecting anything that is not v2.
+ *
+ * There is deliberately no migration path. Both consuming projects were
+ * onboarded after v2 landed, so a v1 file would be a corruption or a
+ * hand-edit rather than a legacy artifact — better to fail loudly than to
+ * quietly reinterpret it.
+ */
+declare function parseLock(raw: unknown): Lock;
+/** The file a consumer means when it says "the asset" — the first output. */
+declare function primaryOutput(entry: LockEntry): LockOutput | null;
+/** Lock entries are keyed `<styleId>/<assetId>`, which makes styles a namespace. */
+declare function lockKey(styleId: string, assetId: string): string;
+/** A manifest entry resolved against its style — everything needed to generate. */
+interface ResolvedSpec {
+    /** Absolute directory containing the manifest; excluded from the spec hash. */
+    root: string;
+    styleId: string;
+    assetId: string;
+    generator: Generator;
+    prompt: string;
+    width: number;
+    height: number;
+    view: string;
+    size: number;
+    styleImagePaths: string[];
+    outFile: string;
+    /**
+     * Manifest-relative path of committed art that stands in for generated
+     * output; excluded from the spec hash. Set only when the asset declares
+     * `source`, which also means it needs no lock entry.
+     */
+    source?: string;
+    tags: string[];
+    specHash: string;
+    cost: number;
+    costUnit: "generations" | "usd" | "free";
+    candidates: number;
+    outline?: string;
+    shading?: string;
+    detail?: string;
+    seed?: number;
+    /** Forced palette hex values; empty unless the style sets one. */
+    palette: string[];
+    /** `pixflux` only — strip the generated background. Defaults to true. */
+    noBackground: boolean;
+    /** `tiles` generator only — see StyleSchema for what each one means. */
+    tileSize?: number;
+    tileType?: string;
+    tileView?: string;
+    tileFeature?: string;
+    outlineMode?: string;
+}
+
+declare const MAX_RETRIES = 4;
+declare const MAX_DOWNLOAD_BYTES: number;
+declare function shouldRetry(status: number): boolean;
+/** Exponential backoff with jitter, so parallel workers don't retry in lockstep. */
+declare function backoffMs(attempt: number): number;
+/** Supports both Retry-After forms: seconds and an HTTP date. */
+declare function retryAfterMs(value: string | null, now?: number): number | null;
+interface Balance {
+    usd: number;
+    generations: number;
+    total: number;
+    plan: string;
+}
+interface PixelLabObject {
+    id: string;
+    name: string | null;
+    prompt: string;
+    size: {
+        width: number;
+        height: number;
+    };
+    directions: number;
+    created_at: string;
+    view: string | null;
+    preview_url?: string | null;
+    rotation_urls?: Record<string, string | null> | null;
+    /** Populated only while status === "review". Index order is what select-frames expects. */
+    frame_urls?: string[] | null;
+    tags: string[];
+    status: string | null;
+    progress_percent?: number | null;
+    eta_seconds?: number | null;
+}
+/**
+ * A tiles-pro job. Unlike an object or a map object there is no `status`
+ * field: GET /tiles-pro/{id} answers 423 while the set is still drawing and
+ * 200 with `storage_urls` once it is done, so the HTTP code IS the status.
+ */
+interface TilesPro {
+    /** Keyed `tile_0`, `tile_1`, ... Index order is load-bearing for a
+     *  connectable set (`tile_feature`), where a consumer slices by index. */
+    storage_urls: Record<string, string>;
+    kind: string | null;
+    tile_rules?: Record<string, unknown> | null;
+}
+interface MapObject {
+    object_id: string;
+    status: string;
+    description: string | null;
+    width: number | null;
+    height: number | null;
+    download_url: string | null;
+}
+declare class PixelLabError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+declare class PixelLabClient {
+    private readonly apiKey;
+    private readonly timeoutMs;
+    constructor(apiKey: string, timeoutMs?: number);
+    /**
+     * Retries only what is safe to retry: transport failures, 429, and 5xx.
+     * A 4xx other than 429 is a bad request and retrying it just wastes time.
+     *
+     * POSTs that create objects are included, which is a deliberate trade: the
+     * failure mode of not retrying (a dropped asset in a 65-item run) is more
+     * common than the failure mode of retrying (a duplicate object), and a
+     * duplicate is visible and free to delete whereas a silent gap is neither.
+     */
+    private request;
+    balance(): Promise<Balance>;
+    /**
+     * Square objects that persist indefinitely.
+     *
+     * `size` and `styleImages` are mutually exclusive at the API level: when style
+     * images are supplied the largest one dictates the output size. So style
+     * references must already be at the target resolution — a 128px reference
+     * silently produces 128px output and a different candidate count.
+     */
+    create1Direction(args: {
+        description: string;
+        size?: number;
+        view?: string;
+        styleImages?: ResolvedStyleImage[];
+        itemDescriptions?: string[];
+    }): Promise<{
+        object_id: string;
+        status: string;
+        n_frames: number;
+    }>;
+    /**
+     * Arbitrary width x height. Returns a single result — no selection step.
+     *
+     * These AUTO-DELETE AFTER 8 HOURS, so `fetch` must run in the same session as
+     * `submit`. The pipeline warns when a map-object entry is older than that.
+     */
+    createMapObject(args: {
+        description: string;
+        width: number;
+        height: number;
+        view?: string;
+        outline?: string;
+        shading?: string;
+        detail?: string;
+        seed?: number;
+    }): Promise<{
+        object_id: string;
+        status: string;
+    }>;
+    /**
+     * Draws a whole tile set in one call — many variations, or a connectable
+     * set when `tileFeature` is given.
+     *
+     * `styleImages` here is NOT the shape `create-1-direction-object` uses.
+     * TilesProStyleImage is flat — `{base64, width, height}`, all three
+     * required — where 1dir wants `{type, base64, format}`. Confirmed against
+     * the OpenAPI schema; sending 1dir's shape is rejected as an extra field.
+     *
+     * Passing style images also makes the API ignore `tileType` and `tileView`
+     * and copy the reference's tile geometry instead.
+     */
+    createTilesPro(args: {
+        description: string;
+        tileSize?: number;
+        tileType?: string;
+        tileView?: string;
+        tileFeature?: string;
+        outlineMode?: string;
+        seed?: number;
+        styleImages?: {
+            base64: string;
+            width: number;
+            height: number;
+        }[];
+    }): Promise<{
+        tile_id: string;
+        background_job_id: string;
+        status: string;
+    }>;
+    /** Throws PixelLabError(423) while the set is still drawing — see TilesPro. */
+    getTilesPro(tileId: string): Promise<TilesPro>;
+    /**
+     * Synchronous single-image generation. Returns the PNG inline rather than a
+     * job id, and is the only endpoint that honours a forced palette —
+     * `color_image` on /map-objects returns a 500 whatever the payload shape.
+     */
+    createImagePixflux(args: {
+        description: string;
+        width: number;
+        height: number;
+        noBackground?: boolean;
+        paletteSwatchBase64?: string;
+        seed?: number;
+    }): Promise<{
+        png: Buffer;
+        usage: unknown;
+    }>;
+    getObject(objectId: string): Promise<PixelLabObject>;
+    getMapObject(objectId: string): Promise<MapObject>;
+    listObjects(limit?: number, offset?: number): Promise<{
+        objects: PixelLabObject[];
+        total: number;
+    }>;
+    /** Walks the whole account. Used by `adopt` to reconcile orphaned objects. */
+    iterateObjects(pageSize?: number): AsyncGenerator<PixelLabObject>;
+    /**
+     * Promotes chosen candidates to standalone objects, each with its own id.
+     * The review parent survives until nothing is left in it, so the returned
+     * `created_object_ids` — not the parent id — is what should be recorded.
+     */
+    selectFrames(objectId: string, indices: number[], commonTag?: string): Promise<{
+        created_object_ids?: string[];
+    }>;
+    /** Irreversible. Only reached via `purge`, behind an explicit confirmation. */
+    deleteObject(objectId: string): Promise<unknown>;
+    dismissReview(objectId: string): Promise<unknown>;
+    /** Free and synchronous. Replaces the full tag set — include tags you want to keep. */
+    setTags(objectId: string, tags: string[]): Promise<unknown>;
+    /** Storage URLs are public; no auth header, and sending one can break the CDN request. */
+    download(url: string): Promise<Buffer>;
+}
+declare function clientFromEnv(): PixelLabClient;
+
+/**
+ * What a provider charges in. Cost is not universally "generations": PixelLab
+ * bills a subscription quota, OpenAI bills dollars per image, a local model
+ * bills nothing. `plan` prints the unit alongside the number so the figure is
+ * never silently misread, and `--budget` is interpreted in the active unit.
+ */
+type CostUnit = "generations" | "usd" | "free";
+interface CostEstimate {
+    unit: CostUnit;
+    amount: number;
+    /**
+     * How many candidates one call returns. This is a provider property, not a
+     * universal truth — PixelLab's `1dir` returns up to 64 for a single fixed
+     * price, whereas a per-image provider returns one and charges N times for N.
+     * The "generate small, pick from many" strategy only pays off where this is
+     * greater than 1 at no extra cost.
+     */
+    candidates: number;
+}
+/** Runtime guard for third-party adapters before estimates influence a budget. */
+declare function validateCostEstimate(providerId: string, value: unknown): CostEstimate;
+interface OutputSource {
+    url: string;
+    /** Stable semantic/index role used in filenames and lockfile outputs. */
+    role?: string;
+}
+interface PollContext {
+    /** Distinguishes structural tile sets from independent tile candidates. */
+    tileFeature?: string;
+}
+/** Provider-owned, JSON-serializable details needed by downstream exporters. */
+type ProviderMetadata = Record<string, unknown>;
+/** Terminal and non-terminal states a queued job can be observed in. */
+type JobState = {
+    status: "processing";
+    progressPercent?: number | null;
+    etaSeconds?: number | null;
+} | {
+    status: "review";
+    candidateUrls: string[];
+} | {
+    status: "ready";
+    objectId: string;
+    /** Kept for compatibility with single-output provider implementations. */
+    sourceUrl: string | null;
+    /** Present for structural multi-output results. */
+    sources?: OutputSource[];
+    /** Preserved under the provider's namespace in the lockfile. */
+    metadata?: ProviderMetadata;
+} | {
+    status: "failed";
+    error: string;
+};
+/** A previously generated asset as the provider reports it. */
+interface RemoteAsset {
+    id: string;
+    prompt: string;
+    width: number;
+    height: number;
+    createdAt: string;
+    previewUrl: string | null;
+    tags: string[];
+    status: string;
+}
+interface BalanceInfo {
+    unit: CostUnit;
+    remaining: number;
+    total?: number;
+    plan?: string;
+}
+interface BalanceChange {
+    unit: CostUnit;
+    before: number;
+    after: number;
+    /** Provider-reported quota/currency consumed between the two readings. */
+    spent: number;
+    /** Quota/currency added between readings, e.g. a refill during the run. */
+    credited: number;
+}
+/** Compare two provider readings without ever combining incompatible units. */
+declare function measureBalanceChange(before: BalanceInfo, after: BalanceInfo): BalanceChange | null;
+/**
+ * Submission constraints a backend enforces upstream, in its own units —
+ * `submit` has no business knowing these numbers itself.
+ */
+interface RateLimit {
+    /** Minimum time between successive submissions, global across the account. */
+    spacingMs: number;
+    /** Background jobs allowed in flight at once. */
+    maxInFlight: number;
+}
+/**
+ * Used when a provider doesn't declare `rateLimit()` — conservative enough
+ * not to be a real constraint for a provider that has none of its own, and
+ * overridable per run via `submit`'s own options regardless.
+ */
+declare const DEFAULT_RATE_LIMIT: RateLimit;
+/**
+ * A backend that turns a resolved spec into image bytes.
+ *
+ * Everything above this interface — the manifest, the lockfile, plan diffing,
+ * salvage, the contact sheets — is provider-agnostic. Everything that knows a
+ * URL shape or an auth header lives below it.
+ *
+ * The optional members are genuinely optional capabilities rather than
+ * convenience: a provider with no queryable asset list cannot support `adopt`
+ * or `salvage`, and the CLI reports that rather than failing obscurely.
+ */
+interface Provider {
+    readonly id: string;
+    /** False for a generator this backend cannot express (e.g. non-square). */
+    supports(generator: Generator): boolean;
+    /** Never performs I/O — `plan` must stay free and offline. */
+    estimate(spec: ResolvedSpec): CostEstimate;
+    /** This backend's own submission constraints. Falls back to
+     *  `DEFAULT_RATE_LIMIT` when absent — see that constant's doc. */
+    rateLimit?(): RateLimit;
+    submit(spec: ResolvedSpec, styleImages: ResolvedStyleImage[]): Promise<{
+        jobId: string;
+    }>;
+    poll(jobId: string, generator: Generator, context?: PollContext): Promise<JobState>;
+    /**
+     * Promote one candidate from a review-status job to a standalone asset.
+     * Only meaningful where `estimate().candidates > 1`.
+     *
+     * `generator` is passed because "promote" is not universal: PixelLab's
+     * frame-based generators create a new account object, while a tiles
+     * variation is already a finished image and there is nothing to promote.
+     * A provider that treats every candidate alike can ignore it.
+     */
+    selectCandidate(jobId: string, index: number, commonTag?: string, generator?: Generator): Promise<{
+        objectId: string;
+        sourceUrl: string | null;
+    }>;
+    /** Storage URLs are usually public; implementations should not send auth. */
+    download(url: string): Promise<Buffer>;
+    balance(): Promise<BalanceInfo>;
+    /** Free-form labels on the remote asset. Absent if unsupported. */
+    setTags?(objectId: string, tags: string[]): Promise<void>;
+    /** Walk every asset on the account. Required by `adopt` and `salvage`. */
+    list?(): AsyncGenerator<RemoteAsset>;
+    /** Irreversible. Only reached via `purge`, behind explicit confirmation. */
+    delete?(assetId: string): Promise<void>;
+}
+declare class UnsupportedCapabilityError extends Error {
+    constructor(providerId: string, capability: string);
+}
+/** Narrowing helpers so call sites fail with a clear message, not `undefined is not a function`. */
+declare function requireList(provider: Provider): NonNullable<Provider["list"]>;
+declare function requireDelete(provider: Provider): NonNullable<Provider["delete"]>;
+declare function formatCost(unit: CostUnit, amount: number): string;
+
+/**
+ * PixelLab, the reference implementation.
+ *
+ * All PixelLab-specific knowledge lives here: the three generators and their
+ * very different pricing, the review/candidate flow, the fact that a map
+ * object's job record expires while its image does not, and that pixflux
+ * returns bytes inline instead of a job id.
+ */
+declare class PixelLabProvider implements Provider {
+    private readonly client;
+    readonly id = "pixellab";
+    constructor(client: PixelLabClient);
+    static fromEnv(): PixelLabProvider;
+    /** Public storage URLs and the local content cache do not require API auth. */
+    static forDownloads(): PixelLabProvider;
+    /** Capability and cost estimation only; makes no network request itself. */
+    static forOffline(): PixelLabProvider;
+    supports(generator: Generator): boolean;
+    /** PixelLab's own constraints: submissions must be >2s apart, and
+     *  background jobs in flight are capped by subscription tier (Tier 1=8,
+     *  Tier 2=10, Tier 3=20) — 8 is the safe floor across every tier. */
+    rateLimit(): RateLimit;
+    /**
+     * Where synchronous pixflux results are parked between `submit` and `fetch`.
+     *
+     * pixflux returns the PNG inline rather than a job id, but the pipeline is
+     * built around submit → poll → fetch running as separate commands. Writing
+     * the bytes to a known path keeps that model intact: the "job id" is the
+     * filename, polling is an existence check, and downloading is a file read.
+     */
+    private static cacheDir;
+    estimate(spec: ResolvedSpec): CostEstimate;
+    submit(spec: ResolvedSpec, styleImages: ResolvedStyleImage[]): Promise<{
+        jobId: string;
+    }>;
+    poll(jobId: string, generator: Generator, context?: PollContext): Promise<JobState>;
+    /**
+     * Map objects need their own path because the `/map-objects/{id}` record is
+     * deleted upstream roughly 8 hours after creation while the image survives in
+     * the objects collection. Verified: a March 2026 sprite still resolves from
+     * `/objects` four months on, with `/map-objects` returning 404 for the same
+     * id. So a 404 here is not evidence the work is lost.
+     */
+    private pollMap;
+    /**
+     * Tiles report progress through the HTTP status: 423 while drawing, 200 with
+     * `storage_urls` once finished. There is no `status` field to read and no
+     * progress percentage on offer, so "processing" here carries no ETA.
+     */
+    private pollTiles;
+    selectCandidate(jobId: string, index: number, commonTag?: string, generator?: Generator): Promise<{
+        objectId: string;
+        sourceUrl: string | null;
+    }>;
+    download(url: string): Promise<Buffer>;
+    balance(): Promise<BalanceInfo>;
+    setTags(objectId: string, tags: string[]): Promise<void>;
+    list(): AsyncGenerator<RemoteAsset>;
+    delete(assetId: string): Promise<void>;
+}
+
+/**
+ * An in-memory Provider for tests.
+ *
+ * This exists because the stages that spend money — submit, poll, fetch — were
+ * the only ones without coverage, and four of the five real bugs found so far
+ * lived in them. A fake at this seam exercises the actual state machine,
+ * including the review/candidate path, without a network or an API key.
+ *
+ * Deliberately configurable in the ways that broke things for real: how many
+ * candidates come back, whether a job fails, and whether the queue is observed
+ * as still processing before it settles.
+ */
+interface FakeOptions {
+    /** Candidates per call. >1 routes through review, as PixelLab's 1dir does. */
+    candidates?: number;
+    /** Polls to report `processing` before settling. Exercises the poll loop. */
+    processingPolls?: number;
+    /** Asset ids that should fail instead of completing. */
+    failAssets?: Set<string>;
+    /** Simulate a provider with no listing capability (adopt/salvage unavailable). */
+    supportsList?: boolean;
+    costUnit?: BalanceInfo["unit"];
+    startingBalance?: number;
+}
+interface FakeJob {
+    jobId: string;
+    spec: ResolvedSpec;
+    pollsRemaining: number;
+    candidates: number;
+    failed: boolean;
+    selectedIndex: number | null;
+    objectId: string | null;
+}
+/** A valid 1x1 PNG, so `fetch`'s signature check passes on fake output. */
+declare const FAKE_PNG: Buffer<ArrayBuffer>;
+declare class FakeProvider implements Provider {
+    private readonly opts;
+    readonly id = "fake";
+    readonly jobs: Map<string, FakeJob>;
+    readonly assets: Map<string, RemoteAsset>;
+    readonly tags: Map<string, string[]>;
+    readonly deleted: string[];
+    /** Every submit, in order — lets a test assert on call count and spacing. */
+    readonly submissions: {
+        jobId: string;
+        assetId: string;
+        at: number;
+    }[];
+    private counter;
+    private balanceRemaining;
+    constructor(opts?: FakeOptions);
+    supports(generator: Generator): boolean;
+    estimate(spec: ResolvedSpec): CostEstimate;
+    submit(spec: ResolvedSpec): Promise<{
+        jobId: string;
+    }>;
+    poll(jobId: string): Promise<JobState>;
+    selectCandidate(jobId: string, index: number, commonTag?: string): Promise<{
+        objectId: string;
+        sourceUrl: string | null;
+    }>;
+    download(url: string): Promise<Buffer>;
+    balance(): Promise<BalanceInfo>;
+    setTags(objectId: string, tags: string[]): Promise<void>;
+    /**
+     * Assigned in the constructor rather than declared as a method, so a test can
+     * model a provider that genuinely lacks listing (making `adopt` and `salvage`
+     * unavailable) instead of one that throws.
+     */
+    list?: () => AsyncGenerator<RemoteAsset>;
+    private listImpl;
+    delete(assetId: string): Promise<void>;
+    /** Seed a pre-existing remote asset, for adopt / salvage tests. */
+    seed(asset: Partial<RemoteAsset> & {
+        id: string;
+    }): RemoteAsset;
+    private register;
+}
+
+interface LoadedManifest {
+    manifest: Manifest;
+    /** Directory the manifest lives in. All relative paths resolve against it. */
+    root: string;
+    path: string;
+}
+declare function loadManifest(manifestPath: string): Promise<LoadedManifest>;
+/**
+ * Expands the manifest into one concrete spec per (style, asset) pair. This is
+ * where a style becomes a namespace: adding a style re-derives the entire asset
+ * set under a separate output root and separate lock keys, which is what makes
+ * a whole-collection restyle a one-flag operation.
+ */
+declare function resolveSpecs(loaded: LoadedManifest, filter?: {
+    styles?: string[];
+    assets?: string[];
+    /** Optional provider makes offline plan cost/candidate estimates adapter-owned. */
+    provider?: Pick<Provider, "supports" | "estimate" | "id">;
+}): Promise<ResolvedSpec[]>;
+/** Reference image bytes and measured dimensions, in manifest order. */
+declare function resolveStyleImages(loaded: LoadedManifest, styleId: string): Promise<ResolvedStyleImage[]>;
+/** Retained for callers that only need the encoded bytes. */
+declare function styleImagesBase64(loaded: LoadedManifest, styleId: string): Promise<string[]>;
+/** Reads dimensions without decoding pixel data. */
+declare function imageMetadata(buf: Buffer): Pick<ResolvedStyleImage, "width" | "height" | "format"> | null;
+
+/**
+ * The lockfile is the record that maps a spec to the PixelLab object that
+ * satisfies it and the file on disk that came from it. It is written after
+ * every state transition — including immediately after submitting, before the
+ * job is awaited — so an interrupted run never loses track of paid-for work.
+ */
+declare function loadLock(lockPath: string): Promise<Lock>;
+/** Atomic write — a crash mid-save must not leave a truncated lockfile. */
+declare function saveLock(lockPath: string, lock: Lock): Promise<void>;
+declare function upsert(lock: Lock, key: string, patch: Partial<LockEntry>): LockEntry;
+/**
+ * Drop a lock entry, and record the removal so the next save honours it.
+ *
+ * Deleting from `lock.entries` alone does nothing: `writeLockWhileHeld` merges
+ * onto whatever is on disk, so the entry is read back and restored. Callers
+ * that need an entry gone must come through here. Returns false when the key
+ * was not present, so a caller can tell a no-op from a removal.
+ */
+declare function remove(lock: Lock, key: string): boolean;
+/** Recorded successful-submission estimates, kept separate by provider unit. */
+declare function spendByUnit(lock: Lock): Record<CostUnit, number>;
+/** @deprecated Prefer spendByUnit; summing unlike provider units is unsafe. */
+declare function totalSpend(lock: Lock, unit?: CostUnit): number;
+
+declare function sha256(data: Buffer | string): string;
+declare function sha256File(path: string): Promise<string>;
+/**
+ * Identity of a spec: everything that would change the generated image.
+ * Project root, `outFile`, `source`, and `tags` are deliberately excluded —
+ * moving a checkout, renaming the destination, swapping the committed art a
+ * `mount` places, or retagging should not regenerate art.
+ *
+ * Generator-specific parameters are hashed only where they apply, and are
+ * left `undefined` otherwise so `JSON.stringify` drops the key entirely.
+ * That matters: adding a field unconditionally rewrites the hash of every
+ * spec in every existing lockfile, and each one then reports as `stale` and
+ * invites a full regeneration of art that never changed. Adding `palette`
+ * unconditionally did exactly that once already.
+ */
+declare function specHash(spec: Omit<ResolvedSpec, "specHash" | "root" | "outFile" | "source" | "tags">, styleImageHashes: string[]): string;
+
+/** One lockfile output with the identity consumers should expose publicly. */
+interface ResolvedOutput extends LockOutput {
+    assetId: string;
+    /** Stable within a style's atlas or report. Single-output assets keep their old id. */
+    id: string;
+    index: number;
+    absolutePath: string;
+}
+/** Store generated paths relative to the manifest so committed locks survive a clone/move. */
+declare function portableOutputPath(file: string, manifestDir: string): string;
+/** Resolve a portable lock path against the manifest, never the process cwd. */
+declare function resolveOutputPath(recordedPath: string, manifestDir: string): string;
+/** Deterministic current destination for one provider output. */
+declare function expectedOutputPath(spec: ResolvedSpec, role: string | undefined, index: number, total: number): string;
+/** Resolve one recorded output from the current manifest-owned destination. */
+declare function currentOutputPath(output: Pick<LockOutput, "path" | "role">, spec: ResolvedSpec, index: number, total: number): string;
+/** Resolve an entry member using the complete source-set order when available. */
+declare function currentEntryOutputPath(entry: LockEntry, spec: ResolvedSpec, index: number): string;
+/**
+ * Rebase legacy absolute output paths onto this checkout and canonicalize all
+ * selected entries in memory. Persistence remains the caller's decision.
+ */
+declare function normalizeLockOutputPaths(lock: Lock, specs: ResolvedSpec[]): number;
+/** The fallback role used when a provider returns several unnamed outputs. */
+declare function fallbackOutputRole(index: number): string;
+/**
+ * Gives every output a stable, collision-resistant consumer id.
+ *
+ * A conventional one-file asset remains `grass`, preserving existing atlas
+ * lookups. A structural set becomes `grass/tile-00`, `grass/tile-01`, … so no
+ * downstream command has to silently pretend its first file is the whole set.
+ */
+declare function outputId(assetId: string, output: Pick<LockOutput, "role">, index: number, total: number): string;
+/** Resolve every output recorded for one manifest asset, preserving lock order. */
+declare function resolveEntryOutputs(entry: LockEntry, assetId: string, manifestDir: string): ResolvedOutput[];
+/** Resolve an entry using its current spec, including cross-checkout v2 migration. */
+declare function resolveSpecEntryOutputs(entry: LockEntry, spec: ResolvedSpec): ResolvedOutput[];
+/** Resolve all outputs for a style in deterministic asset-id order. */
+declare function resolveStyleOutputs(lock: Lock, styleId: string, manifestDir: string): ResolvedOutput[];
+type OutputSelection = {
+    ok: true;
+    output: LockOutput;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Select the one output needed by a single-cell consumer such as `mount`.
+ * Multi-output sets are deliberately ambiguous unless the manifest names a
+ * role; choosing index zero is silent data loss disguised as convenience.
+ */
+declare function selectEntryOutput(entry: LockEntry, role?: string): OutputSelection;
+/** Lock outputs for a resolved spec, or its conventional path before adoption. */
+declare function resolveSpecOutputs(spec: ResolvedSpec, lock: Lock | undefined, manifestDir: string): ResolvedOutput[];
+
+interface ArtifactFile {
+    path: string;
+    data: string | Uint8Array;
+}
+interface ArtifactBundleResult {
+    changed: string[];
+    unchanged: string[];
+}
+interface ArtifactBundleOptions {
+    /** @internal Failure-injection hook used to verify staging cleanup. */
+    beforeStage?: (destination: string, index: number) => void | Promise<void>;
+    /** @internal Failure-injection hook used to verify rollback behavior. */
+    beforePromote?: (destination: string, index: number) => void | Promise<void>;
+    /** @internal Durable transaction journal used by the managed writer. */
+    recoveryFile?: string;
+    /** @internal Failure-injection hook used to simulate a crash after commit. */
+    afterCommit?: () => void | Promise<void>;
+}
+interface ManagedArtifactBundleOptions extends ArtifactBundleOptions {
+    /** Explicitly replace unowned or manually modified destinations. */
+    force?: boolean;
+}
+interface ArtifactSource {
+    id: string;
+    path: string;
+    sha256: string | null;
+    included: boolean;
+}
+interface ArtifactProvenance {
+    kind: "pack" | "mount" | "tileset";
+    sources: ArtifactSource[];
+    /** Every non-source input that can change the derived bytes. */
+    options: unknown;
+}
+interface ArtifactBundleManifest {
+    format: "pixelkiln-artifact-bundle";
+    version: 1;
+    kind: ArtifactProvenance["kind"];
+    fingerprint: string;
+    sources: ArtifactSource[];
+    options: unknown;
+    outputs: Array<{
+        path: string;
+        sha256: string;
+    }>;
+}
+interface ArtifactVerification {
+    current: boolean;
+    fingerprintValid: boolean;
+    changedSources: string[];
+    changedOutputs: string[];
+}
+/** Build the deterministic companion metadata written beside a derived bundle. */
+declare function createArtifactBundleManifest(manifestPath: string, outputs: ArtifactFile[], provenance: ArtifactProvenance): ArtifactBundleManifest;
+/** Add deterministic provenance metadata to a related set of generated files. */
+declare function withArtifactManifest(manifestPath: string, outputs: ArtifactFile[], provenance: ArtifactProvenance): ArtifactFile[];
+/**
+ * Persist a generated bundle while protecting files not demonstrably owned by
+ * its existing companion manifest. Byte-identical legacy files are adopted
+ * without rewriting; `force` is required to take over anything else.
+ */
+declare function writeManagedArtifactBundle(manifestPath: string, outputs: ArtifactFile[], provenance: ArtifactProvenance, options?: ManagedArtifactBundleOptions): Promise<ArtifactBundleResult>;
+/** Verify stored provenance and source/output hashes without rebuilding output. */
+declare function verifyArtifactBundle(manifestPath: string): Promise<ArtifactVerification>;
+/**
+ * Write a related set of generated files without leaving a partial bundle
+ * after an ordinary write failure.
+ *
+ * All changed members are staged before any destination is replaced. If an
+ * ordinary filesystem error interrupts promotion, prior files are restored.
+ * Byte-identical members are not rewritten.
+ */
+declare function writeArtifactBundle(files: ArtifactFile[], options?: ArtifactBundleOptions): Promise<ArtifactBundleResult>;
+
+type PlanState = "ok" | "missing" | "untracked" | "stale" | "orphaned" | "in-flight" | "recoverable" | "failed";
+interface PlanItem {
+    spec: ResolvedSpec;
+    key: string;
+    state: PlanState;
+    reason: string;
+}
+interface Plan {
+    items: PlanItem[];
+    /** Items that would incur provider cost if the plan were executed. */
+    actionable: PlanItem[];
+    cost: number;
+    costUnit: CostUnit;
+    candidates: number;
+}
+/**
+ * Diffs the manifest against the lockfile and the files on disk. Nothing here
+ * touches the network, so it is safe to run constantly — it is the cheap
+ * "what would this cost me?" question that should precede every real run.
+ */
+declare function buildPlan(specs: ResolvedSpec[], lock: Lock, opts?: {
+    force?: boolean;
+}): Promise<Plan>;
+declare function summarize(plan: Plan): Record<PlanState, number>;
+
+interface PaletteEntry {
+    r: number;
+    g: number;
+    b: number;
+    /** Share of opaque pixels using this colour, 0-1. */
+    weight: number;
+}
+
+/**
+ * Perceptual-ish distance between two colours, 0-255ish.
+ *
+ * "Redmean" — a cheap weighting that tracks human perception far better than
+ * raw RGB euclidean and needs no colour-space conversion or dependency. Good
+ * enough to rank outliers, which is all this is for; it is not colourimetry.
+ */
+declare function colorDistance(a: {
+    r: number;
+    g: number;
+    b: number;
+}, b: {
+    r: number;
+    g: number;
+    b: number;
+}): number;
+/**
+ * How far an asset's palette sits from a reference palette.
+ *
+ * For each colour in the asset, weighted by how much of the image it covers,
+ * take the distance to its nearest reference colour. An asset built entirely
+ * from on-style colours scores ~0; one introducing a foreign hue scores high
+ * in proportion to how much of the image that hue occupies.
+ */
+declare function paletteDistance(asset: PaletteEntry[], reference: PaletteEntry[]): number;
+/** Merge many palettes into one, summing weights for repeated colours. */
+declare function mergePalettes(palettes: PaletteEntry[][], topN?: number): PaletteEntry[];
+interface AssetAudit {
+    assetId: string;
+    /** Present when this is one member of a structural multi-output asset. */
+    outputRole?: string;
+    /** Stable report/atlas identity: assetId for one output, assetId/role for many. */
+    id: string;
+    file: string;
+    width: number;
+    height: number;
+    /** Distance from the style's reference palette. Higher is more off-style. */
+    paletteDistance: number;
+    /** Share of the canvas that is transparent. Very low suggests a baked background. */
+    transparency: number;
+    /** Distinct opaque colours. Very high suggests photo-like rendering, not pixel art. */
+    colorCount: number;
+    palette: PaletteEntry[];
+}
+interface StyleAudit {
+    styleId: string;
+    /** True when the reference came from the style's own styleImages. */
+    referenceFromStyleImages: boolean;
+    reference: PaletteEntry[];
+    assets: AssetAudit[];
+    missing: string[];
+    unreadable: string[];
+}
+interface AuditThresholds {
+    /** Absolute palette-distance ceiling. Omit to rely on relative outliers. */
+    maxDistance?: number;
+    /** Minimum transparent share of the canvas, from 0 to 1. */
+    minTransparency?: number;
+    /** Maximum number of distinct opaque colors. */
+    maxColors?: number;
+    /** Relative outlier cutoff. Defaults to 1.5 standard deviations. */
+    sigma?: number;
+}
+interface AuditViolation {
+    id: string;
+    reasons: string[];
+}
+interface AuditEvaluation {
+    safe: boolean;
+    thresholds: Required<Pick<AuditThresholds, "sigma">> & Omit<AuditThresholds, "sigma">;
+    outliers: string[];
+    violations: AuditViolation[];
+    missing: string[];
+    unreadable: string[];
+}
+/**
+ * Measures how consistently a style's assets actually hold together.
+ *
+ * This exists to answer "is this variant working?" with a number instead of an
+ * eyeball. Measured on a real neon trial, prose alone carried the style on
+ * subjects with no strong inherent colour but was ignored on ones that had
+ * some — a chocolate bar stayed brown, a camera stayed grey. Those are exactly
+ * the assets this ranks to the top, before another 57 are generated to match.
+ *
+ * Reference palette comes from the style's `styleImages` when set, since those
+ * are the declared intent. Otherwise the assets are compared against their own
+ * collective palette, which still surfaces outliers but cannot tell you the
+ * whole set has drifted together.
+ */
+declare function auditStyle(loaded: LoadedManifest, specs: ResolvedSpec[], styleId: string, lock?: Lock): Promise<StyleAudit>;
+/** Assets more than `sigma` standard deviations off the mean distance. */
+declare function outliers(audit: StyleAudit, sigma?: number): AssetAudit[];
+/** Turn an audit into a stable CI decision without hiding the underlying measurements. */
+declare function evaluateAudit(audit: StyleAudit, thresholds?: AuditThresholds): AuditEvaluation;
+declare function hex(c: {
+    r: number;
+    g: number;
+    b: number;
+}): string;
+
+interface ContentCacheIssue {
+    name: string;
+    reason: string;
+}
+interface ContentCacheHealth {
+    path: string;
+    exists: boolean;
+    files: number;
+    bytes: number;
+    valid: number;
+    referenced: number;
+    unreferenced: string[];
+    missingReferenced: string[];
+    invalid: ContentCacheIssue[];
+}
+interface RemoteHashCacheHealth {
+    path: string;
+    exists: boolean;
+    entries: number;
+    valid: number;
+    invalidIds: string[];
+    error: string | null;
+}
+interface CacheHealthReport {
+    safe: boolean;
+    content: ContentCacheHealth;
+    remoteHashes: RemoteHashCacheHealth;
+    removed: {
+        contentFiles: number;
+        remoteHashEntries: number;
+        resetRemoteHashCache: boolean;
+    };
+}
+interface CacheHealthOptions {
+    /** Remove invalid and unreferenced content, plus invalid remote hash entries. */
+    prune?: boolean;
+}
+/**
+ * Inspect both local caches without contacting the provider.
+ *
+ * Content PNGs are project-local and keyed by lockfile SHA, so orphaned bytes
+ * can be removed safely. The object-hash cache is account-wide: this function
+ * validates its schema and hashes but never removes an object merely because
+ * the current project does not reference it. `adopt` owns that live-ID prune,
+ * because only it has walked the complete provider account.
+ */
+declare function inspectCaches(lock: Lock, lockPath: string, options?: CacheHealthOptions): Promise<CacheHealthReport>;
+
+interface PackedSource {
+    id: string;
+    /** Absolute source path. Artifact manifests make it relative to themselves. */
+    path: string;
+    /** Null when the source could not be read. */
+    sha256: string | null;
+    /** False when the source was present but could not be decoded or selected. */
+    included: boolean;
+}
+interface PackedFrame {
+    /** Asset id, so a consumer can look a sprite up by name rather than index. */
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface PackedSheet {
+    png: Buffer;
+    atlas: {
+        style: string;
+        sheet: {
+            width: number;
+            height: number;
+        };
+        /** Uniform cell the grid was laid out on. Frames may be smaller. */
+        cell: {
+            width: number;
+            height: number;
+        };
+        columns: number;
+        frames: PackedFrame[];
+    };
+    /** Assets skipped because their file was missing or unreadable. */
+    skipped: {
+        id: string;
+        reason: string;
+    }[];
+    /** Inputs and their exact bytes, for deterministic derived-artifact provenance. */
+    sources: PackedSource[];
+}
+/**
+ * Composites one style's sprites into a single sheet plus a frame atlas.
+ *
+ * A grid rather than a bin-packer. Every sprite in a style shares a generator
+ * and a size, so rectangles are near-uniform and the gain from tight packing
+ * is a few percent of area — not worth the loss of a stable, predictable
+ * layout. A grid also means a frame's position is derivable from its index,
+ * which matters when someone is reading the sheet by eye to debug it.
+ *
+ * The cell is the largest sprite in the set. Assets can override width/height
+ * individually, so assuming uniformity would silently clip the odd one out.
+ * Smaller sprites are placed at the cell's top-left and their real dimensions
+ * recorded, rather than being centred: centring would bake half-pixel offsets
+ * into odd-sized differences, and a consumer that ignores the atlas and slices
+ * on the cell grid still gets a correct — if padded — sprite.
+ */
+interface SpriteInput {
+    /** The name this sprite is looked up by in the atlas. */
+    id: string;
+    /** Absolute path to the PNG. */
+    path: string;
+}
+/**
+ * Validates and resolves the JSON contract behind `pack --inputs`.
+ *
+ * A plain function rather than inline in the CLI so it is testable without
+ * spawning the binary: `main()` in cli.ts runs at module load and is not
+ * exported, so anything left inline there has no seam a test can reach. This
+ * is also the only place that needs to know the file is JSON at all — once it
+ * returns, everything downstream just deals in `SpriteInput[]`.
+ *
+ * `entry.path` resolves relative to `inputsFilePath`'s directory, not the
+ * process's cwd, so a caller can write the JSON into a scratch directory
+ * without rewriting every entry to be absolute. An already-absolute
+ * `entry.path` passes through unchanged, since `path.resolve` discards
+ * earlier segments once it hits one.
+ */
+declare function resolvePackInputs(raw: unknown, inputsFilePath: string): SpriteInput[];
+/**
+ * The packing primitive: an explicit list of sprites in, one sheet out.
+ *
+ * Separate from `packStyle` because the lockfile is not the only way to decide
+ * what belongs on a sheet. A consumer may draw from several manifests, or key
+ * frames by its own vocabulary rather than by pixelkiln asset ids — heybud's
+ * review-form icons do both. Keeping the pixel work here and the "which files,
+ * called what" decision at the call site avoids teaching this module about
+ * anyone else's naming.
+ */
+declare function packSprites(inputs: SpriteInput[], options?: {
+    columns?: number;
+    order?: "id" | "input";
+}): PackedSheet;
+declare function packStyle(lock: Lock, styleId: string, manifestDir: string, options?: {
+    columns?: number;
+    outputRoles?: string[];
+    primaryOnly?: boolean;
+}): PackedSheet;
+interface MountPlacement extends SpriteInput {
+    /** Grid cell this sprite owns, as [column, row]. */
+    cell: [number, number];
+}
+interface MountedSheet {
+    png: Buffer;
+    atlas: {
+        style: string;
+        sheet: {
+            width: number;
+            height: number;
+        };
+        cell: {
+            width: number;
+            height: number;
+        };
+        frames: PackedFrame[];
+    };
+    skipped: {
+        id: string;
+        reason: string;
+    }[];
+    /** Inputs and their exact bytes, for deterministic derived-artifact provenance. */
+    sources: PackedSource[];
+    /** True when an existing sheet was composited into rather than replaced. */
+    overBase: boolean;
+}
+/**
+ * Places sprites at *declared* grid cells, optionally into an existing sheet.
+ *
+ * The sibling of `packSprites`, for the case its layout rules cannot serve.
+ * `packSprites` derives position from index and sorts by asset id so the sheet
+ * is byte-stable — excellent when pixelkiln owns the whole sheet, and fatal
+ * when it does not. A consumer whose atlas coordinates are already load-bearing
+ * (a tile engine naming tiles by cell, a scene file storing cell indices in
+ * saved data) cannot accept a layout that moves when an asset is added or
+ * renamed: every existing reference would silently point at different art.
+ *
+ * So here the caller declares the cell and pixelkiln honours it. Two
+ * consequences worth stating:
+ *
+ *   - **Only declared cells are touched.** With a `base` sheet, every other
+ *     pixel survives byte-for-byte, so a hand-authored sheet can be part
+ *     generated and part drawn without the generated half claiming the file.
+ *   - **A cell is replaced, not blended.** The sprite owns its cell, so the
+ *     cell is cleared first. Compositing instead would make a regenerated
+ *     tile show through to whatever it replaced, and the residue would be
+ *     invisible until it shipped.
+ *
+ * Sprites larger than the cell are a declaration error, not something to crop
+ * silently — cropping would produce a sheet that looks right in isolation and
+ * is wrong at every seam.
+ */
+declare function mountSprites(placements: MountPlacement[], options: {
+    cellWidth: number;
+    cellHeight: number;
+    basePng?: Buffer;
+}): MountedSheet;
+/**
+ * `mountSprites` driven by the lockfile and the manifest's `mount` block.
+ *
+ * The manifest is the source of cells rather than the lockfile: a cell is a
+ * declaration about where art belongs, not a record of what was generated, and
+ * it has to be readable and editable before anything has been generated at all.
+ */
+declare function mountStyle(lock: Lock, styleId: string, manifestDir: string, mount: {
+    base?: string;
+    cellWidth: number;
+    cellHeight: number;
+}, cells: Record<string, [number, number]>, sources?: Record<string, string>, outputRoles?: Record<string, string>): MountedSheet;
+
+type TilesetFormat = "generic" | "tiled" | "godot";
+interface NormalizedTileRules {
+    ruleType: "edge" | "corner" | "outline";
+    arity: 4 | 6;
+    connectivity?: "same" | "other";
+    terrains: string[];
+    /** Provider tile index to adjacency mask. Tiles absent here are stamp-only. */
+    masks: Record<number, number>;
+    raw: Record<string, unknown>;
+}
+interface GenericTileset {
+    format: "pixelkiln-tileset";
+    version: 1;
+    name: string;
+    style: string;
+    asset: string;
+    image: string;
+    tile: {
+        width: number;
+        height: number;
+    };
+    sheet: {
+        width: number;
+        height: number;
+        columns: number;
+    };
+    tiles: Array<{
+        id: number;
+        /** Original provider index; can differ from id when stamp-only keys leave gaps. */
+        sourceIndex: number;
+        role: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        bitmask?: number;
+        stampOnly: boolean;
+    }>;
+    /** Complete provider object, even when its rule family is not normalized yet. */
+    providerRules: Record<string, unknown> | null;
+    rules: NormalizedTileRules | null;
+}
+interface TilesetExport {
+    png: Buffer;
+    extension: ".json" | ".tsj" | ".tres";
+    document: string;
+    generic: GenericTileset;
+    sources: PackedSource[];
+}
+interface TilesetExportOptions {
+    format: TilesetFormat;
+    manifestDir: string;
+    imageName: string;
+    columns?: number;
+}
+/** Parse the deliberately open provider schema into the stable export subset. */
+declare function normalizeTileRules(raw: unknown): NormalizedTileRules | null;
+/** Build an atlas plus generic, Tiled TSJ, or Godot 4 TileSet metadata. */
+declare function exportTileset(entry: LockEntry, spec: ResolvedSpec, options: TilesetExportOptions): TilesetExport;
+
+interface SubmitOptions {
+    maxInFlight?: number;
+    spacingMs?: number;
+    /** How often to re-check occupied background-job slots. */
+    slotPollMs?: number;
+    /** Stop waiting for an unreadable/stuck slot instead of hanging forever. */
+    slotTimeoutMs?: number;
+    /** Refuse to submit if the run would exceed this much, in the provider's unit. */
+    budget?: number;
+    onProgress?: (msg: string) => void;
+}
+interface SubmitResult {
+    submitted: number;
+    failed: number;
+    /** Successful-submission estimates in `unit`. */
+    spent: number;
+    unit: CostUnit;
+}
+declare function submit(provider: Provider, loaded: LoadedManifest, items: PlanItem[], lock: Lock, lockPath: string, opts?: SubmitOptions): Promise<SubmitResult>;
+
+interface PollOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+    onProgress?: (msg: string) => void;
+    specs?: ResolvedSpec[];
+}
+interface PollResult {
+    review: number;
+    completed: number;
+    failed: number;
+    stillRunning: number;
+}
+/**
+ * Advances every unfinished lock entry to its settled state.
+ *
+ * Safe to run repeatedly and safe to interrupt — all state lives in the
+ * lockfile, so a re-run picks up exactly where the last one stopped. Provider
+ * quirks (a job record that expires before its image does, review-status
+ * candidate lists) are the provider's problem, not this loop's.
+ */
+declare function poll(provider: Provider, lock: Lock, lockPath: string, opts?: PollOptions): Promise<PollResult>;
+
+interface FetchResult {
+    downloaded: number;
+    skipped: number;
+    failed: number;
+}
+/**
+ * Downloads every selected object to its manifest-defined path and records the
+ * file hash. The hash is what lets `plan` tell "untouched" from "edited by
+ * hand" on later runs, so a manual retouch is never silently clobbered. The
+ * same hash keys a local content cache, allowing `restore` to outlive a
+ * provider's temporary storage URL.
+ */
+declare function fetchAssets(provider: Provider, specs: ResolvedSpec[], lock: Lock, lockPath: string, opts?: {
+    onProgress?: (msg: string) => void;
+    concurrency?: number;
+    repair?: boolean;
+    /** Content-addressed PNG cache. Defaults beside the lockfile; false disables it. */
+    cacheDir?: string | false;
+}): Promise<FetchResult>;
+/**
+ * Applies the manifest's tags to each generated object upstream. Tagging is
+ * free and synchronous, and it makes the account itself queryable — the thing
+ * that was missing when 350 objects accumulated with no way to tell which 65
+ * were the keepers.
+ */
+declare function pushTags(provider: Provider, specs: ResolvedSpec[], lock: Lock, opts?: {
+    onProgress?: (msg: string) => void;
+}): Promise<number>;
+
+type DoctorLevel = "ok" | "warning" | "error";
+interface DoctorCheck {
+    id: string;
+    level: DoctorLevel;
+    message: string;
+}
+interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+interface DoctorOptions {
+    provider?: Provider;
+    /** Skip provider connectivity while retaining every local check. */
+    offline?: boolean;
+    apiKeyPresent?: boolean;
+}
+/**
+ * Checks the whole project without changing it. Loading/resolving the manifest
+ * and loading the lock happen before this function, so schema, style-image,
+ * filter, and output-collision validation have already passed if it runs.
+ */
+declare function doctor(loaded: LoadedManifest, specs: ResolvedSpec[], lock: Lock, lockPath: string, opts?: DoctorOptions): Promise<DoctorReport>;
+
+interface AdoptResult {
+    scanned: number;
+    matched: number;
+    unmatchedLocal: string[];
+    /** Objects on the account that correspond to no local file — safe to delete. */
+    unmatchedRemote: RemoteAsset[];
+    ambiguous: string[];
+}
+/**
+ * Reconciles an account full of previously generated objects against the files
+ * already committed in the repo, and writes the mapping into the lockfile.
+ *
+ * Matching is by exact SHA-256 of the image bytes. That was verified to hold:
+ * a file downloaded from PixelLab storage is byte-identical to the copy sitting
+ * in the repo, so a hash match is proof of provenance rather than a guess. No
+ * fuzzy prompt matching is involved and nothing is regenerated.
+ */
+declare function adopt(provider: Provider, specs: ResolvedSpec[], lock: Lock, lockPath: string, opts?: {
+    onProgress?: (msg: string) => void;
+    concurrency?: number;
+    noCache?: boolean;
+}): Promise<AdoptResult>;
+/** Applies manifest tags to every adopted object so the account becomes filterable. */
+declare function tagAdopted(provider: Provider, specs: ResolvedSpec[], lock: Lock, opts?: {
+    onProgress?: (msg: string) => void;
+}): Promise<number>;
+
+interface PickResult {
+    selected: number;
+    skipped: number;
+}
+/**
+ * Serves the contact sheet on localhost, waits for the selections to be
+ * applied, then shuts down.
+ *
+ * Selections are committed to PixelLab (`select-frames` promotes the chosen
+ * candidate to its own object and drops the rest) and written to the lockfile
+ * before the browser gets its response, so a closed tab never loses a choice.
+ */
+declare function runPicker(provider: Provider, lock: Lock, lockPath: string, opts?: {
+    port?: number;
+    open?: boolean;
+    onProgress?: (msg: string) => void;
+}): Promise<PickResult>;
+
+interface SheetGroup {
+    key: string;
+    assetId: string;
+    styleId: string;
+    prompt: string;
+    reviewObjectId: string;
+    frameUrls: string[];
+    size: number;
+}
+/**
+ * A contact sheet for choosing among generated candidates.
+ *
+ * This is the only step that needs human judgement, so it is optimised for one
+ * thing: deciding fast. Candidates render at 4x with a transparency
+ * checkerboard and a true-size swatch beside them, because a pixel icon that
+ * looks good enlarged can still be unreadable at its real size. Keyboard-first,
+ * one row per asset, and the page posts back and closes itself.
+ */
+declare function renderSheet(groups: SheetGroup[]): string;
+
+/** Minimal PNG header read — avoids pulling in an image library just for dimensions. */
+declare function pngSize(buf: Buffer): {
+    width: number;
+    height: number;
+} | null;
+/** Path segment → a stable, readable asset id. */
+declare function slugify(value: string): string;
+interface ScannedAsset {
+    id: string;
+    category: string;
+    file: string;
+    width: number;
+    height: number;
+}
+/**
+ * Scans an existing asset tree and produces manifest entries for it.
+ *
+ * Prompts are left empty on purpose. For a project whose art already exists,
+ * the accurate prompts are the ones actually used upstream — `adopt
+ * --write-prompts` recovers those from the matched objects rather than having
+ * anyone invent plausible-looking replacements.
+ */
+declare function scanAssets(root: string, opts?: {
+    exclude?: string[];
+}): Promise<{
+    assets: ScannedAsset[];
+    skipped: string[];
+}>;
+declare function buildManifest(name: string, styleId: string, generator: Generator, outDir: string, scanned: ScannedAsset[]): Manifest;
+
+/**
+ * Objects on the account that no known lockfile claims.
+ *
+ * The point of this is recovery, not cleanup. An account accumulates work that
+ * was generated, paid for, and never landed in a repo — alternate takes,
+ * abandoned experiments, whole categories that were explored and forgotten.
+ * Measured on one account: 190 of 361 objects were unclaimed, and a visual
+ * sample showed usable character portraits, tree variants, terrain tiles, and
+ * UI icons rather than rejects.
+ *
+ * Correctness here depends entirely on being given EVERY lockfile. One account
+ * is shared across projects, so an incomplete claim set makes another project's
+ * shipped art look like an orphan.
+ */
+declare function loadClaims(lockPaths: string[]): Promise<Set<string>>;
+interface Orphan {
+    id: string;
+    prompt: string;
+    width: number;
+    height: number;
+    createdAt: string;
+    previewUrl: string;
+    tags: string[];
+}
+declare function findOrphans(provider: Provider, claimed: Set<string>, opts?: {
+    onProgress?: (msg: string) => void;
+}): Promise<{
+    orphans: Orphan[];
+    total: number;
+}>;
+/**
+ * Which manifest style, if any, an orphan's prompt was generated from.
+ *
+ * A manifest with only one style skips the pattern check entirely — there is
+ * nothing to disambiguate, and a style with an empty prefix/suffix (common
+ * for single-style projects that don't template their prompts, like a
+ * `map`-generator asset pack) would otherwise match nothing at all. This is
+ * a routing decision ("where would salvage import this"), not a claim that
+ * the content is genuinely this project's — see `groupOrphansByStyle`'s
+ * `siblings` param for that distinction, which single-style manifests need
+ * and multi-style ones get from the plain pattern check already.
+ */
+declare function matchOrphanStyle(prompt: string, manifest: Manifest): string | null;
+/** A sibling project's manifest, consulted only to recognise its own style
+ *  patterns — never as an import target. */
+interface SiblingManifest {
+    /** How to refer to this sibling in output — a project directory name, typically. */
+    label: string;
+    manifest: Manifest;
+}
+interface OrphanGroups {
+    /** styleId → its matched orphans, in manifest style order. */
+    matched: Map<string, Orphan[]>;
+    /** Orphans that matched no style anywhere known — this manifest or any sibling. */
+    unmatched: Orphan[];
+    /** "<sibling label>: <styleId>" → orphans that confidently matched a
+     *  SIBLING's own pattern instead of this manifest's — excluded from
+     *  `matched` even where this manifest would otherwise have swallowed them
+     *  by default (a single-style manifest with nothing of its own to check
+     *  against). Empty unless `siblings` was passed to `groupOrphansByStyle`. */
+    elsewhere: Map<string, Orphan[]>;
+}
+/**
+ * Splits orphans by the style that most likely produced them.
+ *
+ * `salvage` used to hand a single `--style` to a whole session regardless of
+ * how many the orphan pool actually spanned, so importing anything wrong
+ * silently mislabeled it under the first style in the manifest. Grouping
+ * first lets the caller run one correctly-scoped session per style instead.
+ *
+ * A single-style manifest has no pattern of its own to filter by, so by
+ * default everything routes to that one style — correct for a genuinely
+ * single-project account, wrong for a shared one where the orphan pool is
+ * mostly a sibling's art. Passing that sibling's manifest via `siblings` (its
+ * lockfile sits beside it, by the same convention `--lock` defaults from
+ * `--manifest`) lets a confident match against ITS pattern win instead,
+ * pulling those orphans out of `matched` and into `elsewhere` even though
+ * this manifest would otherwise have claimed them.
+ */
+declare function groupOrphansByStyle(orphans: Orphan[], manifest: Manifest, siblings?: SiblingManifest[]): OrphanGroups;
+declare function idFromPrompt(prompt: string, taken: Set<string>): string;
+type SalvageAction = "import" | "keep" | "discard";
+interface SalvageDecision {
+    id: string;
+    action: SalvageAction;
+}
+/**
+ * Tags are the durable record of a decision. They are free and synchronous, and
+ * unlike a local file they survive on the account itself — so a later salvage
+ * run from a different machine sees what was already triaged.
+ *
+ * `discard` deliberately only tags. Deleting is a separate, explicit command.
+ */
+declare function applyTags(provider: Provider, decisions: SalvageDecision[], existing: Map<string, string[]>, opts?: {
+    onProgress?: (msg: string) => void;
+}): Promise<{
+    tagged: number;
+    failed: number;
+}>;
+
+interface SalvageResult {
+    imported: number;
+    kept: number;
+    discarded: number;
+    failed: number;
+}
+/**
+ * Serves the triage sheet and applies decisions.
+ *
+ * `import` is the only action that touches local state: it downloads the image,
+ * writes a manifest asset and a lock entry, so a recovered sprite becomes a
+ * first-class tracked asset rather than a loose file. `keep` and `discard` only
+ * write tags upstream — no object is ever deleted here.
+ */
+declare function runSalvage(provider: Provider, orphans: Orphan[], ctx: {
+    manifestPath: string;
+    manifest: Manifest;
+    styleId: string;
+    importDir: string;
+    lock: Lock;
+    lockPath: string;
+}, opts?: {
+    port?: number;
+    open?: boolean;
+    onProgress?: (msg: string) => void;
+}): Promise<SalvageResult>;
+
+interface SalvageSheetContext {
+    /** The style every "import" on this page will be tagged and routed under. */
+    styleId: string;
+    /** Where an import lands, shown so the page answers "where does this go"
+     *  without anyone needing to go check the manifest. */
+    importDir: string;
+}
+/**
+ * Triage sheet for unclaimed account objects.
+ *
+ * Optimised for volume: a couple of hundred items, most of which get a
+ * one-keystroke verdict. Everything defaults to no decision, so closing the tab
+ * changes nothing, and `discard` only ever writes a tag — deletion is a
+ * separate command that has to be asked for by name.
+ *
+ * `salvage` opens one tab per matched style in sequence (grouping — see
+ * pipeline/salvage.ts), and every one of them used to render the exact same
+ * generic title. With several left open across styles there was no way to
+ * tell them apart short of squinting at which images loaded. The tab title
+ * and header now name the style the page is actually scoped to.
+ */
+declare function renderSalvageSheet(orphans: Orphan[], ctx?: SalvageSheetContext): string;
+
+export { type AdoptResult, type ArtifactBundleManifest, type ArtifactBundleOptions, type ArtifactBundleResult, type ArtifactFile, type ArtifactProvenance, type ArtifactSource, type ArtifactVerification, type Asset, type AssetAudit, AssetSchema, type AuditEvaluation, type AuditThresholds, type AuditViolation, type Balance, type BalanceChange, type BalanceInfo, type CacheHealthOptions, type CacheHealthReport, type ContentCacheHealth, type ContentCacheIssue, type CostEstimate, type CostUnit, DEFAULT_RATE_LIMIT, type DoctorCheck, type DoctorLevel, type DoctorOptions, type DoctorReport, FAKE_PNG, type FakeOptions, FakeProvider, type FetchResult, type Generator, GeneratorSchema, type GenericTileset, type JobState, type LoadedManifest, type Lock, type LockEntry, LockEntrySchema, type LockOutput, LockSchema, MAX_DOWNLOAD_BYTES, MAX_RETRIES, type ManagedArtifactBundleOptions, type Manifest, ManifestSchema, type MapObject, type MountPlacement, type MountedSheet, type NormalizedTileRules, type Orphan, type OrphanGroups, type OutputSelection, type OutputSource, type PackedFrame, type PackedSheet, type PackedSource, type PickResult, PixelLabClient, PixelLabError, type PixelLabObject, PixelLabProvider, type Plan, type PlanItem, type PlanState, type PollContext, type PollOptions, type PollResult, type Provider, type ProviderMetadata, type RateLimit, type RemoteAsset, type RemoteHashCacheHealth, type ResolvedOutput, type ResolvedSpec, type ResolvedStyleImage, type SalvageAction, type SalvageResult, type ScannedAsset, type SheetGroup, type SiblingManifest, type SpriteInput, type Style, type StyleAudit, StyleSchema, type SubmitOptions, type SubmitResult, type TilesPro, type TilesetExport, type TilesetExportOptions, type TilesetFormat, UnsupportedCapabilityError, adopt, applyTags, auditStyle, backoffMs, buildManifest, buildPlan, candidateCount, clientFromEnv, colorDistance, countNumberedDescriptions, createArtifactBundleManifest, currentEntryOutputPath, currentOutputPath, doctor, evaluateAudit, expectedOutputPath, exportTileset, fallbackOutputRole, fetchAssets, findOrphans, formatCost, generationCost, groupOrphansByStyle, hex, idFromPrompt, imageMetadata, inspectCaches, loadClaims, loadLock, loadManifest, lockKey, matchOrphanStyle, measureBalanceChange, mergePalettes, mountSprites, mountStyle, normalizeLockOutputPaths, normalizeTileRules, outliers, outputId, packSprites, packStyle, paletteDistance, parseLock, pngSize, poll, portableOutputPath, primaryOutput, pushTags, remove, renderSalvageSheet, renderSheet, requireDelete, requireList, resolveEntryOutputs, resolveOutputPath, resolvePackInputs, resolveSpecEntryOutputs, resolveSpecOutputs, resolveSpecs, resolveStyleImages, resolveStyleOutputs, retryAfterMs, runPicker, runSalvage, saveLock, scanAssets, selectEntryOutput, sha256, sha256File, shouldRetry, slugify, specHash, spendByUnit, styleImagesBase64, submit, summarize, tagAdopted, tileFeatureOutputCount, tileVariationCount, tilesCost, totalSpend, upsert, validateCostEstimate, verifyArtifactBundle, withArtifactManifest, writeArtifactBundle, writeManagedArtifactBundle };