@hiper2d/ai-agents 0.4.2 → 0.5.0

package/README.md

@@ -74,6 +74,32 @@ Transcribe (`VOICE_MODEL_CONSTANTS`, prices in `VOICE_MODEL_PRICING`). The `voic
 direction works for both providers: OpenAI takes it as instructions, Gemini gets it folded
 into the prompt ("Say gravely: …").
 
+### Images and portrait sheets (`@hiper2d/ai-agents/images`)
+
+A separate entry for hosts that draw pictures. `generateImage` is one Gemini image call
+that reports its cost; `drawPortraitSheet` draws a whole cast as one grid of bust
+portraits and cuts it into one 3:4 card per character — one image call whether the cast
+is three or sixteen, all in one consistent style. The divider lines the model draws are
+read off the pixels (rows drift), and the kept sheet plus per-card framing let the host
+re-cut any card later at a new crop. The library never imports sharp: pass your own
+instance in, so text-only consumers pull in nothing native.
+
+```ts
+import { drawPortraitSheet, cutCard } from '@hiper2d/ai-agents/images';
+
+const sharp = (await import('sharp')).default;
+const { portraits, sheet, costUSD } = await drawPortraitSheet(googleKey, sharp, {
+    purpose: 'a social deduction game',
+    setting: { title: 'Harbor of Glass', description: 'A rain-soaked port city of lantern-lit canals.' },
+    artStyle: 'ink and watercolor',
+    cells: cast.map(c => ({ key: c.id, label: c.name, prompt: `(${c.gender}) "${c.name}" — ${c.look}` })),
+});
+// portraits[i].jpeg is a 600x800 card, portraits[i].framing says where it sits on sheet.jpeg
+```
+
+The pure geometry (`fitFraming`, `circleFocus`, `focusToBackground`, …) is safe in a
+browser bundle for reframe editors and avatar renderers.
+
 ### Budget control
 
 Per-subject spend caps (a user, a tenant, a job) over UTC day and month windows. Pure and

package/dist/images.d.mts

@@ -0,0 +1,326 @@
+/**
+ * Shared shapes for the portrait-sheet pipeline. Coordinates are SHEET pixels unless
+ * stated otherwise; a card is portrait 3:4 and the circle inside it is card-relative.
+ */
+/** A rectangle in image pixels (sharp's `extract` shape). */
+interface ImageRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+interface ImageSize {
+    width: number;
+    height: number;
+}
+/** The round avatar inside a card. `x` and `d` are fractions of the card's width,
+ * `y` a fraction of its height. */
+interface AvatarCircle {
+    x: number;
+    y: number;
+    d: number;
+}
+/** Where a portrait comes from on its sheet: the card cut and the circle in it. */
+interface AvatarFraming {
+    card: ImageRect;
+    circle: AvatarCircle;
+}
+/** The portion of an image to display, as fractions of its width/height. */
+interface ImageFocus {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+declare const CARD_ASPECT: number;
+declare const CARD_WIDTH_PX = 600;
+declare const CARD_HEIGHT_PX = 800;
+declare const DEFAULT_AVATAR_CIRCLE: AvatarCircle;
+declare const MIN_CARD_HEIGHT_FRACTION = 0.12;
+/** One character on a portrait sheet. */
+interface PortraitCell {
+    /** Stable id the caller stores the crop under; never drawn into the image. */
+    key: string;
+    /** Character name, for logs and prompt guidance; never drawn into the image. */
+    label: string;
+    /** One-line visual description for this cell (gender, name, appearance). */
+    prompt: string;
+}
+/** A card cut from a drawn sheet. */
+interface PortraitSlice {
+    key: string;
+    label: string;
+    jpeg: Buffer;
+    /** The framing the slicer chose: the card on the sheet and the default circle. */
+    framing: AvatarFraming;
+}
+/** The kept sheet: the grid image itself (re-encoded), its size and the cells
+ * the cards were cut from — enough to re-cut any card later at a new framing. */
+interface DrawnSheet {
+    jpeg: Buffer;
+    width: number;
+    height: number;
+    cells: ImageRect[];
+    /** false = no divider lines were found and the cells are the equal split of the
+     * requested grid; true = the cells between the lines the model actually drew. */
+    detected: boolean;
+}
+interface GeneratedImage {
+    buffer: Buffer;
+    costUSD: number;
+}
+/**
+ * The slice of sharp's API the pipeline uses. The library never imports sharp — a
+ * native module the host installs and passes in (`(await import('sharp')).default`) —
+ * so text-only consumers pull in nothing new.
+ */
+type SharpLike = (input: Buffer) => {
+    resize(options: {
+        width: number;
+        withoutEnlargement?: boolean;
+    }): SharpPipeline;
+    resize(width: number, height: number): SharpPipeline;
+    greyscale(): SharpPipeline;
+    extract(rect: ImageRect): SharpPipeline;
+    jpeg(options: {
+        quality: number;
+        mozjpeg?: boolean;
+    }): SharpPipeline;
+    raw(): SharpPipeline;
+    toBuffer(): Promise<Buffer>;
+    toBuffer(options: {
+        resolveWithObject: true;
+    }): Promise<{
+        data: Buffer;
+        info: {
+            width: number;
+            height: number;
+        };
+    }>;
+    metadata(): Promise<{
+        width?: number;
+        height?: number;
+    }>;
+};
+type SharpPipeline = ReturnType<SharpLike>;
+
+/** Largest 3:4 card that fits a cell, centered horizontally and top-aligned:
+ * portraits are busts with the head near the top, so the top edge is the
+ * anchor that keeps the face in. */
+declare function cardInCell(cell: ImageRect): ImageRect;
+declare function defaultFraming(cell: ImageRect): AvatarFraming;
+/** Keeps the circle inside its card. */
+declare function fitCircle(circle: AvatarCircle): AvatarCircle;
+/** Snaps a card to a valid 3:4 rectangle inside the sheet, at least the
+ * minimum size. Width is the free variable; height follows the aspect. */
+declare function fitCard(card: ImageRect, sheet: ImageSize): ImageRect;
+declare function fitFraming(framing: AvatarFraming, sheet: ImageSize): AvatarFraming;
+/** True when the framing is a well-formed object with finite numbers. Shape
+ * only — call fitFraming for the geometric bounds. */
+declare function isFramingShape(value: unknown): value is AvatarFraming;
+/** The circle as a focus on the CARD image itself (a stored card cut). */
+declare function circleFocus(circle: AvatarCircle): ImageFocus;
+/** The card as a focus on its sheet. */
+declare function cardFocus(card: ImageRect, sheet: ImageSize): ImageFocus;
+/** The circle as a focus on the SHEET (card and circle composed) — how a preset
+ * mannequin renders straight off a static sheet. */
+declare function circleFocusOnSheet(framing: AvatarFraming, sheet: ImageSize): ImageFocus;
+/** CSS `background-size` / `background-position` that shows exactly `focus`
+ * of an image inside a box. */
+declare function focusToBackground(focus: ImageFocus): {
+    backgroundSize: string;
+    backgroundPosition: string;
+};
+
+/**
+ * Finds the cells of a drawn portrait sheet from its pixels.
+ *
+ * The prompt asks for equal cells separated by thin dark divider lines, but
+ * the model draws the lines where it likes: on a correctly drawn 4x4 sheet
+ * the rows measured 497 / 485 / 428 / 382 px where equal splits assumed 448
+ * (2026-09-02), so fixed-interval slicing cut lower rows through the previous
+ * character's chest. The lines themselves are crisp — near-black across the
+ * full width — so they are easy to find, and the cells between them are the
+ * real ones. Columns have always measured exact; rows drift.
+ *
+ * Pure over a greyscale byte plane so it is testable without sharp.
+ */
+interface GreyPlane {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+interface SheetGrid {
+    cells: ImageRect[];
+    cols: number;
+    rows: number;
+    detected: boolean;
+}
+interface Run {
+    start: number;
+    end: number;
+}
+/** Divider runs across the whole plane: row lines over the full width,
+ * column lines over the full height. */
+declare function findDividers(plane: GreyPlane): {
+    rows: Run[];
+    cols: Run[];
+};
+declare function equalSplitGrid(width: number, height: number, cols: number, rows: number): SheetGrid;
+/**
+ * The sheet's cells. Read off the divider lines the model drew whenever they
+ * form a plausible grid, even when that grid differs from the cols x rows
+ * that were asked for — the model keeps row-major order, so the drawn cells
+ * still map to the characters in sequence. Row lines are found over the
+ * full width; column lines are found PER ROW BAND, because the model has
+ * drawn rows with different column layouts (and a column line that stops
+ * short of the last row). A band without lines of its own borrows the
+ * layout of the band above it. The equal split of the requested grid is the
+ * last resort when no lines are found at all (the caller logs it; the kept
+ * sheet lets the owner reframe by hand either way).
+ */
+declare function detectSheetGrid(plane: GreyPlane, cols: number, rows: number): SheetGrid;
+/** What findDividers saw, for the mismatch log line. */
+declare function describeDividers(plane: GreyPlane): string;
+
+/**
+ * Image-generation models: platform-side, never user-selected. Prices per 1M tokens
+ * from ai.google.dev/gemini-api/docs/pricing (2026-08). Image output bills ~1120 tokens
+ * per image regardless of resolution, so one image ≈ $0.067 — fewer calls, not lower
+ * resolution, is what minimizes cost.
+ */
+declare const IMAGE_MODEL_CONSTANTS: {
+    readonly GEMINI_FLASH_IMAGE: "gemini-3.1-flash-image";
+};
+type ImageModelId = typeof IMAGE_MODEL_CONSTANTS[keyof typeof IMAGE_MODEL_CONSTANTS];
+interface ImageModelPricing {
+    imageOutputPricePerM: number;
+    textInputPricePerM: number;
+}
+declare const IMAGE_MODEL_PRICING: Record<ImageModelId, ImageModelPricing>;
+declare const DEFAULT_IMAGE_MODEL: ImageModelId;
+/** Cost of one image call from the usage Gemini reports. */
+declare function calculateImageCost(model: ImageModelId, imageOutputTokens: number, textInputTokens: number): number;
+
+type ImageAspectRatio = '1:1' | '3:4' | '4:3' | '3:2' | '2:3' | '16:9' | '9:16';
+interface GenerateImageOptions {
+    /** Labeled reference JPEGs (an established scene, character portraits) that
+     * anchor the drawing to a known style, place or faces. */
+    references?: {
+        label: string;
+        jpeg: Buffer;
+    }[];
+    imageSize?: '1K' | '2K';
+    model?: ImageModelId;
+    /** Test seam / custom transport; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * One image-model call on Gemini's Interactions API. Pure — no auth, no billing —
+ * and the result reports its cost so the host decides whom to charge. Cost is per
+ * IMAGE, not per pixel (a 1K and a 2K image both bill ~1120 output tokens).
+ */
+declare function generateImage(apiKey: string, prompt: string, aspectRatio: ImageAspectRatio, opts?: GenerateImageOptions): Promise<GeneratedImage>;
+
+/**
+ * Portrait sheets: one image-model call draws a whole cast as a grid of bust
+ * portraits, and the grid is cut into one card per character. One call costs the
+ * same whether it draws one face or sixteen, so this is the cheap way to give
+ * every character in a game a portrait in a single consistent style.
+ *
+ * Nothing here touches storage or billing: the host stores the cards and the kept
+ * sheet (so a card can be re-cut later at a new framing) and charges whoever it
+ * likes for `costUSD`. sharp is passed in, never imported.
+ */
+/**
+ * Grid dimensions by cell count on the 4:3 canvas. Cells must come out
+ * square-to-portrait: asked for 4x4 (landscape 600x448 cells) the model redrew the
+ * sheet as 4x3, 6x3 and once as an irregular two-layout sheet — every time towards
+ * taller cells. 5x3 keeps 480x597 cells for 13-15; 17 cells get 6x3 (400x600, 2:3,
+ * one of the shapes the model volunteered). Never 4x4: it silently cut a 17-cell
+ * cast to 16.
+ */
+declare function gridFor(cells: number): {
+    cols: number;
+    rows: number;
+};
+declare const DEFAULT_FILLER_PROMPT = "\"Stranger\" \u2014 an anonymous hooded figure fitting the setting, face hidden in shadow";
+/**
+ * Pads a cast out to a full grid: the model draws exactly cols x rows cells, so the
+ * spare ones get an anonymous filler that is drawn and discarded.
+ */
+declare function padCells(cells: PortraitCell[], fillerPrompt?: string): {
+    cells: PortraitCell[];
+    cols: number;
+    rows: number;
+    realCount: number;
+};
+interface PortraitSheetPrompt {
+    cells: PortraitCell[];
+    cols: number;
+    rows: number;
+    /** What the sheet is for, e.g. "a social deduction game" — one noun phrase. */
+    purpose: string;
+    /** The world the characters live in: a title and a short description. */
+    setting: {
+        title: string;
+        description: string;
+    };
+    /** Player-chosen art direction, already sanitized by the host. Replaces the
+     * model's free choice of style. */
+    artStyle?: string;
+}
+/**
+ * The sheet prompt. The wording is load-bearing: equal cells with thin dark
+ * divider lines are what the slicer finds, one flat muted background per cell keeps
+ * the lines detectable in any art style, and the no-text rule is repeated because
+ * the model otherwise typesets names and bios into the image.
+ */
+declare function buildPortraitSheetPrompt(spec: PortraitSheetPrompt): string;
+declare const SHEET_MAX_WIDTH = 2400;
+declare const SHEET_JPEG_QUALITY = 85;
+declare const SHEET_MAX_BASE64_BYTES = 900000;
+/** Why a sheet's cells did not come out as requested; the host decides how loudly to log. */
+interface SheetMismatch {
+    kind: 'no-dividers' | 'different-grid';
+    message: string;
+    detail: Record<string, unknown>;
+}
+interface SliceSheetOptions {
+    onMismatch?: (mismatch: SheetMismatch) => void;
+    /** Long edge the sheet is normalized to before cutting; defaults to SHEET_MAX_WIDTH. */
+    maxWidth?: number;
+}
+/**
+ * Cuts the cards out of a drawn sheet and keeps the sheet. Cells come from the
+ * divider lines the model drew (equal split as a last resort); each card is the
+ * largest 3:4 rectangle in its cell, top-anchored, with the default circle — the
+ * framing the host can let a user move later.
+ */
+declare function sliceSheet(sharp: SharpLike, raw: Buffer, cells: PortraitCell[], count: number, cols: number, rows: number, opts?: SliceSheetOptions): Promise<{
+    slices: PortraitSlice[];
+    sheet: DrawnSheet;
+}>;
+/** Cuts one card out of a stored sheet at the given framing. */
+declare function cutCard(sharp: SharpLike, sheet: Buffer, card: ImageRect): Promise<Buffer>;
+interface DrawPortraitSheetSpec extends Omit<PortraitSheetPrompt, 'cols' | 'rows'> {
+    /** Prompt for the cells that pad the cast out to a full grid. */
+    fillerPrompt?: string;
+}
+interface DrawPortraitSheetOptions extends SliceSheetOptions {
+    image?: Pick<GenerateImageOptions, 'model' | 'imageSize' | 'fetchImpl'>;
+}
+interface DrawnPortraitSheet {
+    portraits: PortraitSlice[];
+    sheet: DrawnSheet;
+    /** What the image call cost, reported for the host's billing. */
+    costUSD: number;
+}
+/**
+ * The whole pipeline: lay the cast out on a grid, draw it in one call, cut the
+ * cards. Filler cells are drawn and discarded; `portraits` has exactly one entry
+ * per input cell, in order.
+ */
+declare function drawPortraitSheet(apiKey: string, sharp: SharpLike, spec: DrawPortraitSheetSpec, opts?: DrawPortraitSheetOptions): Promise<DrawnPortraitSheet>;
+
+export { type AvatarCircle, type AvatarFraming, CARD_ASPECT, CARD_HEIGHT_PX, CARD_WIDTH_PX, DEFAULT_AVATAR_CIRCLE, DEFAULT_FILLER_PROMPT, DEFAULT_IMAGE_MODEL, type DrawPortraitSheetOptions, type DrawPortraitSheetSpec, type DrawnPortraitSheet, type DrawnSheet, type GenerateImageOptions, type GeneratedImage, type GreyPlane, IMAGE_MODEL_CONSTANTS, IMAGE_MODEL_PRICING, type ImageAspectRatio, type ImageFocus, type ImageModelId, type ImageModelPricing, type ImageRect, type ImageSize, MIN_CARD_HEIGHT_FRACTION, type PortraitCell, type PortraitSheetPrompt, type PortraitSlice, SHEET_JPEG_QUALITY, SHEET_MAX_BASE64_BYTES, SHEET_MAX_WIDTH, type SharpLike, type SharpPipeline, type SheetGrid, type SheetMismatch, type SliceSheetOptions, buildPortraitSheetPrompt, calculateImageCost, cardFocus, cardInCell, circleFocus, circleFocusOnSheet, cutCard, defaultFraming, describeDividers, detectSheetGrid, drawPortraitSheet, equalSplitGrid, findDividers, fitCard, fitCircle, fitFraming, focusToBackground, generateImage, gridFor, isFramingShape, padCells, sliceSheet };

package/dist/images.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Shared shapes for the portrait-sheet pipeline. Coordinates are SHEET pixels unless
+ * stated otherwise; a card is portrait 3:4 and the circle inside it is card-relative.
+ */
+/** A rectangle in image pixels (sharp's `extract` shape). */
+interface ImageRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+interface ImageSize {
+    width: number;
+    height: number;
+}
+/** The round avatar inside a card. `x` and `d` are fractions of the card's width,
+ * `y` a fraction of its height. */
+interface AvatarCircle {
+    x: number;
+    y: number;
+    d: number;
+}
+/** Where a portrait comes from on its sheet: the card cut and the circle in it. */
+interface AvatarFraming {
+    card: ImageRect;
+    circle: AvatarCircle;
+}
+/** The portion of an image to display, as fractions of its width/height. */
+interface ImageFocus {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+declare const CARD_ASPECT: number;
+declare const CARD_WIDTH_PX = 600;
+declare const CARD_HEIGHT_PX = 800;
+declare const DEFAULT_AVATAR_CIRCLE: AvatarCircle;
+declare const MIN_CARD_HEIGHT_FRACTION = 0.12;
+/** One character on a portrait sheet. */
+interface PortraitCell {
+    /** Stable id the caller stores the crop under; never drawn into the image. */
+    key: string;
+    /** Character name, for logs and prompt guidance; never drawn into the image. */
+    label: string;
+    /** One-line visual description for this cell (gender, name, appearance). */
+    prompt: string;
+}
+/** A card cut from a drawn sheet. */
+interface PortraitSlice {
+    key: string;
+    label: string;
+    jpeg: Buffer;
+    /** The framing the slicer chose: the card on the sheet and the default circle. */
+    framing: AvatarFraming;
+}
+/** The kept sheet: the grid image itself (re-encoded), its size and the cells
+ * the cards were cut from — enough to re-cut any card later at a new framing. */
+interface DrawnSheet {
+    jpeg: Buffer;
+    width: number;
+    height: number;
+    cells: ImageRect[];
+    /** false = no divider lines were found and the cells are the equal split of the
+     * requested grid; true = the cells between the lines the model actually drew. */
+    detected: boolean;
+}
+interface GeneratedImage {
+    buffer: Buffer;
+    costUSD: number;
+}
+/**
+ * The slice of sharp's API the pipeline uses. The library never imports sharp — a
+ * native module the host installs and passes in (`(await import('sharp')).default`) —
+ * so text-only consumers pull in nothing new.
+ */
+type SharpLike = (input: Buffer) => {
+    resize(options: {
+        width: number;
+        withoutEnlargement?: boolean;
+    }): SharpPipeline;
+    resize(width: number, height: number): SharpPipeline;
+    greyscale(): SharpPipeline;
+    extract(rect: ImageRect): SharpPipeline;
+    jpeg(options: {
+        quality: number;
+        mozjpeg?: boolean;
+    }): SharpPipeline;
+    raw(): SharpPipeline;
+    toBuffer(): Promise<Buffer>;
+    toBuffer(options: {
+        resolveWithObject: true;
+    }): Promise<{
+        data: Buffer;
+        info: {
+            width: number;
+            height: number;
+        };
+    }>;
+    metadata(): Promise<{
+        width?: number;
+        height?: number;
+    }>;
+};
+type SharpPipeline = ReturnType<SharpLike>;
+
+/** Largest 3:4 card that fits a cell, centered horizontally and top-aligned:
+ * portraits are busts with the head near the top, so the top edge is the
+ * anchor that keeps the face in. */
+declare function cardInCell(cell: ImageRect): ImageRect;
+declare function defaultFraming(cell: ImageRect): AvatarFraming;
+/** Keeps the circle inside its card. */
+declare function fitCircle(circle: AvatarCircle): AvatarCircle;
+/** Snaps a card to a valid 3:4 rectangle inside the sheet, at least the
+ * minimum size. Width is the free variable; height follows the aspect. */
+declare function fitCard(card: ImageRect, sheet: ImageSize): ImageRect;
+declare function fitFraming(framing: AvatarFraming, sheet: ImageSize): AvatarFraming;
+/** True when the framing is a well-formed object with finite numbers. Shape
+ * only — call fitFraming for the geometric bounds. */
+declare function isFramingShape(value: unknown): value is AvatarFraming;
+/** The circle as a focus on the CARD image itself (a stored card cut). */
+declare function circleFocus(circle: AvatarCircle): ImageFocus;
+/** The card as a focus on its sheet. */
+declare function cardFocus(card: ImageRect, sheet: ImageSize): ImageFocus;
+/** The circle as a focus on the SHEET (card and circle composed) — how a preset
+ * mannequin renders straight off a static sheet. */
+declare function circleFocusOnSheet(framing: AvatarFraming, sheet: ImageSize): ImageFocus;
+/** CSS `background-size` / `background-position` that shows exactly `focus`
+ * of an image inside a box. */
+declare function focusToBackground(focus: ImageFocus): {
+    backgroundSize: string;
+    backgroundPosition: string;
+};
+
+/**
+ * Finds the cells of a drawn portrait sheet from its pixels.
+ *
+ * The prompt asks for equal cells separated by thin dark divider lines, but
+ * the model draws the lines where it likes: on a correctly drawn 4x4 sheet
+ * the rows measured 497 / 485 / 428 / 382 px where equal splits assumed 448
+ * (2026-09-02), so fixed-interval slicing cut lower rows through the previous
+ * character's chest. The lines themselves are crisp — near-black across the
+ * full width — so they are easy to find, and the cells between them are the
+ * real ones. Columns have always measured exact; rows drift.
+ *
+ * Pure over a greyscale byte plane so it is testable without sharp.
+ */
+interface GreyPlane {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+interface SheetGrid {
+    cells: ImageRect[];
+    cols: number;
+    rows: number;
+    detected: boolean;
+}
+interface Run {
+    start: number;
+    end: number;
+}
+/** Divider runs across the whole plane: row lines over the full width,
+ * column lines over the full height. */
+declare function findDividers(plane: GreyPlane): {
+    rows: Run[];
+    cols: Run[];
+};
+declare function equalSplitGrid(width: number, height: number, cols: number, rows: number): SheetGrid;
+/**
+ * The sheet's cells. Read off the divider lines the model drew whenever they
+ * form a plausible grid, even when that grid differs from the cols x rows
+ * that were asked for — the model keeps row-major order, so the drawn cells
+ * still map to the characters in sequence. Row lines are found over the
+ * full width; column lines are found PER ROW BAND, because the model has
+ * drawn rows with different column layouts (and a column line that stops
+ * short of the last row). A band without lines of its own borrows the
+ * layout of the band above it. The equal split of the requested grid is the
+ * last resort when no lines are found at all (the caller logs it; the kept
+ * sheet lets the owner reframe by hand either way).
+ */
+declare function detectSheetGrid(plane: GreyPlane, cols: number, rows: number): SheetGrid;
+/** What findDividers saw, for the mismatch log line. */
+declare function describeDividers(plane: GreyPlane): string;
+
+/**
+ * Image-generation models: platform-side, never user-selected. Prices per 1M tokens
+ * from ai.google.dev/gemini-api/docs/pricing (2026-08). Image output bills ~1120 tokens
+ * per image regardless of resolution, so one image ≈ $0.067 — fewer calls, not lower
+ * resolution, is what minimizes cost.
+ */
+declare const IMAGE_MODEL_CONSTANTS: {
+    readonly GEMINI_FLASH_IMAGE: "gemini-3.1-flash-image";
+};
+type ImageModelId = typeof IMAGE_MODEL_CONSTANTS[keyof typeof IMAGE_MODEL_CONSTANTS];
+interface ImageModelPricing {
+    imageOutputPricePerM: number;
+    textInputPricePerM: number;
+}
+declare const IMAGE_MODEL_PRICING: Record<ImageModelId, ImageModelPricing>;
+declare const DEFAULT_IMAGE_MODEL: ImageModelId;
+/** Cost of one image call from the usage Gemini reports. */
+declare function calculateImageCost(model: ImageModelId, imageOutputTokens: number, textInputTokens: number): number;
+
+type ImageAspectRatio = '1:1' | '3:4' | '4:3' | '3:2' | '2:3' | '16:9' | '9:16';
+interface GenerateImageOptions {
+    /** Labeled reference JPEGs (an established scene, character portraits) that
+     * anchor the drawing to a known style, place or faces. */
+    references?: {
+        label: string;
+        jpeg: Buffer;
+    }[];
+    imageSize?: '1K' | '2K';
+    model?: ImageModelId;
+    /** Test seam / custom transport; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * One image-model call on Gemini's Interactions API. Pure — no auth, no billing —
+ * and the result reports its cost so the host decides whom to charge. Cost is per
+ * IMAGE, not per pixel (a 1K and a 2K image both bill ~1120 output tokens).
+ */
+declare function generateImage(apiKey: string, prompt: string, aspectRatio: ImageAspectRatio, opts?: GenerateImageOptions): Promise<GeneratedImage>;
+
+/**
+ * Portrait sheets: one image-model call draws a whole cast as a grid of bust
+ * portraits, and the grid is cut into one card per character. One call costs the
+ * same whether it draws one face or sixteen, so this is the cheap way to give
+ * every character in a game a portrait in a single consistent style.
+ *
+ * Nothing here touches storage or billing: the host stores the cards and the kept
+ * sheet (so a card can be re-cut later at a new framing) and charges whoever it
+ * likes for `costUSD`. sharp is passed in, never imported.
+ */
+/**
+ * Grid dimensions by cell count on the 4:3 canvas. Cells must come out
+ * square-to-portrait: asked for 4x4 (landscape 600x448 cells) the model redrew the
+ * sheet as 4x3, 6x3 and once as an irregular two-layout sheet — every time towards
+ * taller cells. 5x3 keeps 480x597 cells for 13-15; 17 cells get 6x3 (400x600, 2:3,
+ * one of the shapes the model volunteered). Never 4x4: it silently cut a 17-cell
+ * cast to 16.
+ */
+declare function gridFor(cells: number): {
+    cols: number;
+    rows: number;
+};
+declare const DEFAULT_FILLER_PROMPT = "\"Stranger\" \u2014 an anonymous hooded figure fitting the setting, face hidden in shadow";
+/**
+ * Pads a cast out to a full grid: the model draws exactly cols x rows cells, so the
+ * spare ones get an anonymous filler that is drawn and discarded.
+ */
+declare function padCells(cells: PortraitCell[], fillerPrompt?: string): {
+    cells: PortraitCell[];
+    cols: number;
+    rows: number;
+    realCount: number;
+};
+interface PortraitSheetPrompt {
+    cells: PortraitCell[];
+    cols: number;
+    rows: number;
+    /** What the sheet is for, e.g. "a social deduction game" — one noun phrase. */
+    purpose: string;
+    /** The world the characters live in: a title and a short description. */
+    setting: {
+        title: string;
+        description: string;
+    };
+    /** Player-chosen art direction, already sanitized by the host. Replaces the
+     * model's free choice of style. */
+    artStyle?: string;
+}
+/**
+ * The sheet prompt. The wording is load-bearing: equal cells with thin dark
+ * divider lines are what the slicer finds, one flat muted background per cell keeps
+ * the lines detectable in any art style, and the no-text rule is repeated because
+ * the model otherwise typesets names and bios into the image.
+ */
+declare function buildPortraitSheetPrompt(spec: PortraitSheetPrompt): string;
+declare const SHEET_MAX_WIDTH = 2400;
+declare const SHEET_JPEG_QUALITY = 85;
+declare const SHEET_MAX_BASE64_BYTES = 900000;
+/** Why a sheet's cells did not come out as requested; the host decides how loudly to log. */
+interface SheetMismatch {
+    kind: 'no-dividers' | 'different-grid';
+    message: string;
+    detail: Record<string, unknown>;
+}
+interface SliceSheetOptions {
+    onMismatch?: (mismatch: SheetMismatch) => void;
+    /** Long edge the sheet is normalized to before cutting; defaults to SHEET_MAX_WIDTH. */
+    maxWidth?: number;
+}
+/**
+ * Cuts the cards out of a drawn sheet and keeps the sheet. Cells come from the
+ * divider lines the model drew (equal split as a last resort); each card is the
+ * largest 3:4 rectangle in its cell, top-anchored, with the default circle — the
+ * framing the host can let a user move later.
+ */
+declare function sliceSheet(sharp: SharpLike, raw: Buffer, cells: PortraitCell[], count: number, cols: number, rows: number, opts?: SliceSheetOptions): Promise<{
+    slices: PortraitSlice[];
+    sheet: DrawnSheet;
+}>;
+/** Cuts one card out of a stored sheet at the given framing. */
+declare function cutCard(sharp: SharpLike, sheet: Buffer, card: ImageRect): Promise<Buffer>;
+interface DrawPortraitSheetSpec extends Omit<PortraitSheetPrompt, 'cols' | 'rows'> {
+    /** Prompt for the cells that pad the cast out to a full grid. */
+    fillerPrompt?: string;
+}
+interface DrawPortraitSheetOptions extends SliceSheetOptions {
+    image?: Pick<GenerateImageOptions, 'model' | 'imageSize' | 'fetchImpl'>;
+}
+interface DrawnPortraitSheet {
+    portraits: PortraitSlice[];
+    sheet: DrawnSheet;
+    /** What the image call cost, reported for the host's billing. */
+    costUSD: number;
+}
+/**
+ * The whole pipeline: lay the cast out on a grid, draw it in one call, cut the
+ * cards. Filler cells are drawn and discarded; `portraits` has exactly one entry
+ * per input cell, in order.
+ */
+declare function drawPortraitSheet(apiKey: string, sharp: SharpLike, spec: DrawPortraitSheetSpec, opts?: DrawPortraitSheetOptions): Promise<DrawnPortraitSheet>;
+
+export { type AvatarCircle, type AvatarFraming, CARD_ASPECT, CARD_HEIGHT_PX, CARD_WIDTH_PX, DEFAULT_AVATAR_CIRCLE, DEFAULT_FILLER_PROMPT, DEFAULT_IMAGE_MODEL, type DrawPortraitSheetOptions, type DrawPortraitSheetSpec, type DrawnPortraitSheet, type DrawnSheet, type GenerateImageOptions, type GeneratedImage, type GreyPlane, IMAGE_MODEL_CONSTANTS, IMAGE_MODEL_PRICING, type ImageAspectRatio, type ImageFocus, type ImageModelId, type ImageModelPricing, type ImageRect, type ImageSize, MIN_CARD_HEIGHT_FRACTION, type PortraitCell, type PortraitSheetPrompt, type PortraitSlice, SHEET_JPEG_QUALITY, SHEET_MAX_BASE64_BYTES, SHEET_MAX_WIDTH, type SharpLike, type SharpPipeline, type SheetGrid, type SheetMismatch, type SliceSheetOptions, buildPortraitSheetPrompt, calculateImageCost, cardFocus, cardInCell, circleFocus, circleFocusOnSheet, cutCard, defaultFraming, describeDividers, detectSheetGrid, drawPortraitSheet, equalSplitGrid, findDividers, fitCard, fitCircle, fitFraming, focusToBackground, generateImage, gridFor, isFramingShape, padCells, sliceSheet };