@tanstack/ai-gemini 0.23.0 → 0.24.0

package/dist/esm/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","names":[],"sources":["../../src/usage.ts"],"sourcesContent":["import { buildBaseUsage } from '@tanstack/ai'\nimport type { TokenUsage } from '@tanstack/ai'\nimport type {\n  GenerateContentResponseUsageMetadata,\n  ModalityTokenCount,\n} from '@google/genai'\n\n/**\n * Flattened modality token counts for normalized usage reporting.\n * Maps Gemini's ModalityTokenCount array to individual fields.\n */\nexport interface FlattenedModalityTokens {\n  /** Text tokens */\n  textTokens?: number\n  /** Image tokens */\n  imageTokens?: number\n  /** Audio tokens */\n  audioTokens?: number\n  /** Video tokens */\n  videoTokens?: number\n  /** Document tokens (e.g. PDF inputs) */\n  documentTokens?: number\n}\n\n/**\n * Flattens Gemini's ModalityTokenCount array into individual token fields.\n * Extracts TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT modality counts into a\n * normalized structure.\n */\nexport function flattenModalityTokenCounts(\n  modalities?: Array<ModalityTokenCount>,\n): FlattenedModalityTokens {\n  if (!modalities || modalities.length === 0) {\n    return {}\n  }\n\n  const result: FlattenedModalityTokens = {}\n\n  for (const item of modalities) {\n    if (!item.modality || item.tokenCount === undefined) {\n      continue\n    }\n\n    const modality = item.modality.toUpperCase()\n    const count = item.tokenCount\n\n    switch (modality) {\n      case 'TEXT':\n        result.textTokens = (result.textTokens ?? 0) + count\n        break\n      case 'IMAGE':\n        result.imageTokens = (result.imageTokens ?? 0) + count\n        break\n      case 'AUDIO':\n        result.audioTokens = (result.audioTokens ?? 0) + count\n        break\n      case 'VIDEO':\n        result.videoTokens = (result.videoTokens ?? 0) + count\n        break\n      case 'DOCUMENT':\n        result.documentTokens = (result.documentTokens ?? 0) + count\n        break\n    }\n  }\n\n  return result\n}\n\n/**\n * Checks if a FlattenedModalityTokens object has any values set.\n */\nexport function hasModalityTokens(tokens: FlattenedModalityTokens): boolean {\n  return (\n    tokens.textTokens !== undefined ||\n    tokens.imageTokens !== undefined ||\n    tokens.audioTokens !== undefined ||\n    tokens.videoTokens !== undefined ||\n    tokens.documentTokens !== undefined\n  )\n}\n\n/**\n * Gemini-specific provider usage details.\n * These fields are unique to Gemini and placed in providerUsageDetails.\n */\nexport type GeminiProviderUsageDetails = {\n  /**\n   * The traffic type for this request.\n   * Can indicate whether request was handled by different service tiers.\n   */\n  trafficType?: string\n  /**\n   * Number of tokens in the results from tool executions,\n   * which are provided back to the model as input.\n   */\n  toolUsePromptTokenCount?: number\n  /**\n   * Detailed breakdown by modality of the token counts from\n   * the results of tool executions.\n   */\n  toolUsePromptTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n  /**\n   * Detailed breakdown of cache tokens by modality.\n   * More granular than the normalized cachedTokens field.\n   */\n  cacheTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n}\n\n/**\n * Build normalized TokenUsage from Gemini's usageMetadata.\n * Handles modality breakdowns and thinking tokens. Returns `undefined` when the\n * provider reported no usage metadata, so callers omit the field rather than\n * fabricating zeroed totals.\n */\nexport function buildGeminiUsage(\n  usageMetadata: GenerateContentResponseUsageMetadata | undefined | null,\n): TokenUsage<GeminiProviderUsageDetails> | undefined {\n  if (!usageMetadata) return undefined\n\n  const promptTokens = usageMetadata.promptTokenCount ?? 0\n  const completionTokens = usageMetadata.candidatesTokenCount ?? 0\n\n  const result = buildBaseUsage<GeminiProviderUsageDetails>({\n    promptTokens: promptTokens,\n    completionTokens: completionTokens,\n    totalTokens:\n      usageMetadata.totalTokenCount ?? promptTokens + completionTokens,\n  })\n\n  // Add prompt token details\n  // Flatten modality breakdown for prompt\n  const promptModalities = flattenModalityTokenCounts(\n    usageMetadata.promptTokensDetails,\n  )\n  const cachedTokens = usageMetadata.cachedContentTokenCount\n\n  const promptTokensDetails = {\n    ...(hasModalityTokens(promptModalities) ? promptModalities : {}),\n    ...(cachedTokens !== undefined && cachedTokens > 0 ? { cachedTokens } : {}),\n  }\n\n  // Add completion token details\n  // Flatten modality breakdown for candidates (output)\n  const completionModalities = flattenModalityTokenCounts(\n    usageMetadata.candidatesTokensDetails,\n  )\n  const thoughtsTokens = usageMetadata.thoughtsTokenCount\n\n  const completionTokensDetails = {\n    ...(hasModalityTokens(completionModalities) ? completionModalities : {}),\n    // Map thoughtsTokenCount to reasoningTokens for consistency with OpenAI\n    ...(thoughtsTokens !== undefined && thoughtsTokens > 0\n      ? { reasoningTokens: thoughtsTokens }\n      : {}),\n  }\n\n  // Add provider-specific details\n  const providerDetails: GeminiProviderUsageDetails = {\n    ...(usageMetadata.trafficType\n      ? { trafficType: usageMetadata.trafficType }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokenCount !== undefined &&\n    usageMetadata.toolUsePromptTokenCount > 0\n      ? { toolUsePromptTokenCount: usageMetadata.toolUsePromptTokenCount }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokensDetails &&\n    usageMetadata.toolUsePromptTokensDetails.length > 0\n      ? {\n          toolUsePromptTokensDetails:\n            usageMetadata.toolUsePromptTokensDetails.map((item) => ({\n              modality: item.modality || 'UNKNOWN',\n              tokenCount: item.tokenCount ?? 0,\n            })),\n        }\n      : {}),\n    ...(usageMetadata.cacheTokensDetails &&\n    usageMetadata.cacheTokensDetails.length > 0\n      ? {\n          cacheTokensDetails: usageMetadata.cacheTokensDetails.map((item) => ({\n            modality: item.modality || 'UNKNOWN',\n            tokenCount: item.tokenCount ?? 0,\n          })),\n        }\n      : {}),\n  }\n\n  // Add prompt token details if available\n  if (Object.keys(promptTokensDetails).length > 0) {\n    result.promptTokensDetails = promptTokensDetails\n  }\n  // Add provider details if available\n  if (Object.keys(providerDetails).length > 0) {\n    result.providerUsageDetails = providerDetails\n  }\n  // Add completion token details if available\n  if (Object.keys(completionTokensDetails).length > 0) {\n    result.completionTokensDetails = completionTokensDetails\n  }\n\n  return result\n}\n"],"mappings":";;;;;;;AA6BA,SAAgB,2BACd,YACyB;CACzB,IAAI,CAAC,cAAc,WAAW,WAAW,GACvC,OAAO,CAAC;CAGV,MAAM,SAAkC,CAAC;CAEzC,KAAK,MAAM,QAAQ,YAAY;EAC7B,IAAI,CAAC,KAAK,YAAY,KAAK,eAAe,KAAA,GACxC;EAGF,MAAM,WAAW,KAAK,SAAS,YAAY;EAC3C,MAAM,QAAQ,KAAK;EAEnB,QAAQ,UAAR;GACE,KAAK;IACH,OAAO,cAAc,OAAO,cAAc,KAAK;IAC/C;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,kBAAkB,OAAO,kBAAkB,KAAK;IACvD;EACJ;CACF;CAEA,OAAO;AACT;;;;AAKA,SAAgB,kBAAkB,QAA0C;CAC1E,OACE,OAAO,eAAe,KAAA,KACtB,OAAO,gBAAgB,KAAA,KACvB,OAAO,gBAAgB,KAAA,KACvB,OAAO,gBAAgB,KAAA,KACvB,OAAO,mBAAmB,KAAA;AAE9B;;;;;;;AAyCA,SAAgB,iBACd,eACoD;CACpD,IAAI,CAAC,eAAe,OAAO,KAAA;CAE3B,MAAM,eAAe,cAAc,oBAAoB;CACvD,MAAM,mBAAmB,cAAc,wBAAwB;CAE/D,MAAM,SAAS,eAA2C;EAC1C;EACI;EAClB,aACE,cAAc,mBAAmB,eAAe;CACpD,CAAC;CAID,MAAM,mBAAmB,2BACvB,cAAc,mBAChB;CACA,MAAM,eAAe,cAAc;CAEnC,MAAM,sBAAsB;EAC1B,GAAI,kBAAkB,gBAAgB,IAAI,mBAAmB,CAAC;EAC9D,GAAI,iBAAiB,KAAA,KAAa,eAAe,IAAI,EAAE,aAAa,IAAI,CAAC;CAC3E;CAIA,MAAM,uBAAuB,2BAC3B,cAAc,uBAChB;CACA,MAAM,iBAAiB,cAAc;CAErC,MAAM,0BAA0B;EAC9B,GAAI,kBAAkB,oBAAoB,IAAI,uBAAuB,CAAC;EAEtE,GAAI,mBAAmB,KAAA,KAAa,iBAAiB,IACjD,EAAE,iBAAiB,eAAe,IAClC,CAAC;CACP;CAGA,MAAM,kBAA8C;EAClD,GAAI,cAAc,cACd,EAAE,aAAa,cAAc,YAAY,IACzC,CAAC;EACL,GAAI,cAAc,4BAA4B,KAAA,KAC9C,cAAc,0BAA0B,IACpC,EAAE,yBAAyB,cAAc,wBAAwB,IACjE,CAAC;EACL,GAAI,cAAc,8BAClB,cAAc,2BAA2B,SAAS,IAC9C,EACE,4BACE,cAAc,2BAA2B,KAAK,UAAU;GACtD,UAAU,KAAK,YAAY;GAC3B,YAAY,KAAK,cAAc;EACjC,EAAE,EACN,IACA,CAAC;EACL,GAAI,cAAc,sBAClB,cAAc,mBAAmB,SAAS,IACtC,EACE,oBAAoB,cAAc,mBAAmB,KAAK,UAAU;GAClE,UAAU,KAAK,YAAY;GAC3B,YAAY,KAAK,cAAc;EACjC,EAAE,EACJ,IACA,CAAC;CACP;CAGA,IAAI,OAAO,KAAK,mBAAmB,CAAC,CAAC,SAAS,GAC5C,OAAO,sBAAsB;CAG/B,IAAI,OAAO,KAAK,eAAe,CAAC,CAAC,SAAS,GACxC,OAAO,uBAAuB;CAGhC,IAAI,OAAO,KAAK,uBAAuB,CAAC,CAAC,SAAS,GAChD,OAAO,0BAA0B;CAGnC,OAAO;AACT"}
+{"version":3,"file":"usage.js","names":[],"sources":["../../src/usage.ts"],"sourcesContent":["import { buildBaseUsage } from '@tanstack/ai'\nimport type { TokenUsage } from '@tanstack/ai'\nimport type {\n  GenerateContentResponseUsageMetadata,\n  ModalityTokenCount,\n} from '@google/genai'\n\n/**\n * Flattened modality token counts for normalized usage reporting.\n * Maps Gemini's ModalityTokenCount array to individual fields.\n */\nexport interface FlattenedModalityTokens {\n  /** Text tokens */\n  textTokens?: number\n  /** Image tokens */\n  imageTokens?: number\n  /** Audio tokens */\n  audioTokens?: number\n  /** Video tokens */\n  videoTokens?: number\n  /** Document tokens (e.g. PDF inputs) */\n  documentTokens?: number\n}\n\n/**\n * Flattens Gemini's ModalityTokenCount array into individual token fields.\n * Extracts TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT modality counts into a\n * normalized structure.\n */\nexport function flattenModalityTokenCounts(\n  modalities?: Array<ModalityTokenCount>,\n): FlattenedModalityTokens {\n  if (!modalities || modalities.length === 0) {\n    return {}\n  }\n\n  const result: FlattenedModalityTokens = {}\n\n  for (const item of modalities) {\n    if (!item.modality || item.tokenCount === undefined) {\n      continue\n    }\n\n    const modality = item.modality.toUpperCase()\n    const count = item.tokenCount\n\n    switch (modality) {\n      case 'TEXT':\n        result.textTokens = (result.textTokens ?? 0) + count\n        break\n      case 'IMAGE':\n        result.imageTokens = (result.imageTokens ?? 0) + count\n        break\n      case 'AUDIO':\n        result.audioTokens = (result.audioTokens ?? 0) + count\n        break\n      case 'VIDEO':\n        result.videoTokens = (result.videoTokens ?? 0) + count\n        break\n      case 'DOCUMENT':\n        result.documentTokens = (result.documentTokens ?? 0) + count\n        break\n    }\n  }\n\n  return result\n}\n\n/**\n * Checks if a FlattenedModalityTokens object has any values set.\n */\nexport function hasModalityTokens(tokens: FlattenedModalityTokens): boolean {\n  return (\n    tokens.textTokens !== undefined ||\n    tokens.imageTokens !== undefined ||\n    tokens.audioTokens !== undefined ||\n    tokens.videoTokens !== undefined ||\n    tokens.documentTokens !== undefined\n  )\n}\n\n/**\n * Gemini-specific provider usage details.\n * These fields are unique to Gemini and placed in providerUsageDetails.\n */\nexport type GeminiProviderUsageDetails = {\n  /**\n   * The traffic type for this request.\n   * Can indicate whether request was handled by different service tiers.\n   */\n  trafficType?: string\n  /**\n   * Number of tokens in the results from tool executions,\n   * which are provided back to the model as input.\n   */\n  toolUsePromptTokenCount?: number\n  /**\n   * Detailed breakdown by modality of the token counts from\n   * the results of tool executions.\n   */\n  toolUsePromptTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n  /**\n   * Detailed breakdown of cache tokens by modality.\n   * More granular than the normalized cachedTokens field.\n   */\n  cacheTokensDetails?: Array<{\n    modality: string\n    tokenCount: number\n  }>\n}\n\n/**\n * Build normalized TokenUsage from Gemini's usageMetadata.\n * Handles modality breakdowns and thinking tokens. Returns `undefined` when the\n * provider reported no usage metadata, so callers omit the field rather than\n * fabricating zeroed totals.\n */\nexport function buildGeminiUsage(\n  usageMetadata: GenerateContentResponseUsageMetadata | undefined | null,\n): TokenUsage<GeminiProviderUsageDetails> | undefined {\n  if (!usageMetadata) return undefined\n\n  const promptTokens = usageMetadata.promptTokenCount ?? 0\n  const completionTokens = usageMetadata.candidatesTokenCount ?? 0\n\n  const result = buildBaseUsage<GeminiProviderUsageDetails>({\n    promptTokens: promptTokens,\n    completionTokens: completionTokens,\n    totalTokens:\n      usageMetadata.totalTokenCount ?? promptTokens + completionTokens,\n  })\n\n  // Add prompt token details\n  // Flatten modality breakdown for prompt\n  const promptModalities = flattenModalityTokenCounts(\n    usageMetadata.promptTokensDetails,\n  )\n  const cachedTokens = usageMetadata.cachedContentTokenCount\n\n  const promptTokensDetails = {\n    ...(hasModalityTokens(promptModalities) ? promptModalities : {}),\n    ...(cachedTokens !== undefined && cachedTokens > 0 ? { cachedTokens } : {}),\n  }\n\n  // Add completion token details\n  // Flatten modality breakdown for candidates (output)\n  const completionModalities = flattenModalityTokenCounts(\n    usageMetadata.candidatesTokensDetails,\n  )\n  const thoughtsTokens = usageMetadata.thoughtsTokenCount\n\n  const completionTokensDetails = {\n    ...(hasModalityTokens(completionModalities) ? completionModalities : {}),\n    // Map thoughtsTokenCount to reasoningTokens for consistency with OpenAI\n    ...(thoughtsTokens !== undefined && thoughtsTokens > 0\n      ? { reasoningTokens: thoughtsTokens }\n      : {}),\n  }\n\n  // Add provider-specific details\n  const providerDetails: GeminiProviderUsageDetails = {\n    ...(usageMetadata.trafficType\n      ? { trafficType: usageMetadata.trafficType }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokenCount !== undefined &&\n    usageMetadata.toolUsePromptTokenCount > 0\n      ? { toolUsePromptTokenCount: usageMetadata.toolUsePromptTokenCount }\n      : {}),\n    ...(usageMetadata.toolUsePromptTokensDetails &&\n    usageMetadata.toolUsePromptTokensDetails.length > 0\n      ? {\n          toolUsePromptTokensDetails:\n            usageMetadata.toolUsePromptTokensDetails.map((item) => ({\n              modality: item.modality || 'UNKNOWN',\n              tokenCount: item.tokenCount ?? 0,\n            })),\n        }\n      : {}),\n    ...(usageMetadata.cacheTokensDetails &&\n    usageMetadata.cacheTokensDetails.length > 0\n      ? {\n          cacheTokensDetails: usageMetadata.cacheTokensDetails.map((item) => ({\n            modality: item.modality || 'UNKNOWN',\n            tokenCount: item.tokenCount ?? 0,\n          })),\n        }\n      : {}),\n  }\n\n  // Add prompt token details if available\n  if (Object.keys(promptTokensDetails).length > 0) {\n    result.promptTokensDetails = promptTokensDetails\n  }\n  // Add provider details if available\n  if (Object.keys(providerDetails).length > 0) {\n    result.providerUsageDetails = providerDetails\n  }\n  // Add completion token details if available\n  if (Object.keys(completionTokensDetails).length > 0) {\n    result.completionTokensDetails = completionTokensDetails\n  }\n\n  return result\n}\n"],"mappings":";;;;;;;AA6BA,SAAgB,2BACd,YACyB;CACzB,IAAI,CAAC,cAAc,WAAW,WAAW,GACvC,OAAO,CAAC;CAGV,MAAM,SAAkC,CAAC;CAEzC,KAAK,MAAM,QAAQ,YAAY;EAC7B,IAAI,CAAC,KAAK,YAAY,KAAK,eAAe,KAAA,GACxC;EAGF,MAAM,WAAW,KAAK,SAAS,YAAY;EAC3C,MAAM,QAAQ,KAAK;EAEnB,QAAQ,UAAR;GACE,KAAK;IACH,OAAO,cAAc,OAAO,cAAc,KAAK;IAC/C;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK;IACH,OAAO,eAAe,OAAO,eAAe,KAAK;IACjD;GACF,KAAK,YACH,OAAO,kBAAkB,OAAO,kBAAkB,KAAK;EAE3D;CACF;CAEA,OAAO;AACT;;;;AAKA,SAAgB,kBAAkB,QAA0C;CAC1E,OACE,OAAO,eAAe,KAAA,KACtB,OAAO,gBAAgB,KAAA,KACvB,OAAO,gBAAgB,KAAA,KACvB,OAAO,gBAAgB,KAAA,KACvB,OAAO,mBAAmB,KAAA;AAE9B;;;;;;;AAyCA,SAAgB,iBACd,eACoD;CACpD,IAAI,CAAC,eAAe,OAAO,KAAA;CAE3B,MAAM,eAAe,cAAc,oBAAoB;CACvD,MAAM,mBAAmB,cAAc,wBAAwB;CAE/D,MAAM,SAAS,eAA2C;EAC1C;EACI;EAClB,aACE,cAAc,mBAAmB,eAAe;CACpD,CAAC;CAID,MAAM,mBAAmB,2BACvB,cAAc,mBAChB;CACA,MAAM,eAAe,cAAc;CAEnC,MAAM,sBAAsB;EAC1B,GAAI,kBAAkB,gBAAgB,IAAI,mBAAmB,CAAC;EAC9D,GAAI,iBAAiB,KAAA,KAAa,eAAe,IAAI,EAAE,aAAa,IAAI,CAAC;CAC3E;CAIA,MAAM,uBAAuB,2BAC3B,cAAc,uBAChB;CACA,MAAM,iBAAiB,cAAc;CAErC,MAAM,0BAA0B;EAC9B,GAAI,kBAAkB,oBAAoB,IAAI,uBAAuB,CAAC;EAEtE,GAAI,mBAAmB,KAAA,KAAa,iBAAiB,IACjD,EAAE,iBAAiB,eAAe,IAClC,CAAC;CACP;CAGA,MAAM,kBAA8C;EAClD,GAAI,cAAc,cACd,EAAE,aAAa,cAAc,YAAY,IACzC,CAAC;EACL,GAAI,cAAc,4BAA4B,KAAA,KAC9C,cAAc,0BAA0B,IACpC,EAAE,yBAAyB,cAAc,wBAAwB,IACjE,CAAC;EACL,GAAI,cAAc,8BAClB,cAAc,2BAA2B,SAAS,IAC9C,EACE,4BACE,cAAc,2BAA2B,KAAK,UAAU;GACtD,UAAU,KAAK,YAAY;GAC3B,YAAY,KAAK,cAAc;EACjC,EAAE,EACN,IACA,CAAC;EACL,GAAI,cAAc,sBAClB,cAAc,mBAAmB,SAAS,IACtC,EACE,oBAAoB,cAAc,mBAAmB,KAAK,UAAU;GAClE,UAAU,KAAK,YAAY;GAC3B,YAAY,KAAK,cAAc;EACjC,EAAE,EACJ,IACA,CAAC;CACP;CAGA,IAAI,OAAO,KAAK,mBAAmB,CAAC,CAAC,SAAS,GAC5C,OAAO,sBAAsB;CAG/B,IAAI,OAAO,KAAK,eAAe,CAAC,CAAC,SAAS,GACxC,OAAO,uBAAuB;CAGhC,IAAI,OAAO,KAAK,uBAAuB,CAAC,CAAC,SAAS,GAChD,OAAO,0BAA0B;CAGnC,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-gemini",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Google Gemini adapter for TanStack AI chat, images, speech, audio generation, and structured outputs.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -59,13 +59,13 @@
     "@tanstack/ai-utils": "^0.4.0"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.44.1"
+    "@tanstack/ai": "^0.45.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.0.14",
-    "vite": "^8.1.4",
+    "@vitest/coverage-v8": "4.1.10",
+    "vite": "^8.2.1",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.44.1"
+    "@tanstack/ai": "0.45.0"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/image.ts

@@ -7,18 +7,20 @@ import {
 } from '../utils'
 import { buildGeminiUsage } from '../usage'
 import {
+  isGeminiNativeImageModel,
   parseNativeImageSize,
   sizeToAspectRatio,
   validateImageSize,
   validateNumberOfImages,
   validatePrompt,
 } from '../image/image-provider-options'
-import type { GEMINI_IMAGE_MODELS } from '../model-meta'
+import type { GeminiImageModels } from '../model-meta'
 import type {
+  GeminiAnyImageProviderOptions,
   GeminiImageModelInputModalitiesByName,
   GeminiImageModelProviderOptionsByName,
   GeminiImageModelSizeByName,
-  GeminiImageProviderOptions,
+  GeminiNativeImageProviderOptions,
 } from '../image/image-provider-options'
 import type {
   GeneratedImage,
@@ -35,6 +37,7 @@ import type {
   GenerateImagesConfig,
   GenerateImagesResponse,
   GoogleGenAI,
+  ImageConfig,
   Part,
 } from '@google/genai'
 import type { GeminiClientConfig } from '../utils/client'
@@ -45,7 +48,7 @@ import type { GeminiClientConfig } from '../utils/client'
 export interface GeminiImageConfig extends GeminiClientConfig {}
 
 /** Model type for Gemini Image */
-export type GeminiImageModel = (typeof GEMINI_IMAGE_MODELS)[number]
+export type GeminiImageModel = GeminiImageModels
 
 /**
  * Gemini Image Generation Adapter
@@ -65,7 +68,7 @@ export class GeminiImageAdapter<
   TModel extends GeminiImageModel,
 > extends BaseImageAdapter<
   TModel,
-  GeminiImageProviderOptions,
+  GeminiAnyImageProviderOptions,
   GeminiImageModelProviderOptionsByName,
   GeminiImageModelSizeByName,
   GeminiImageModelInputModalitiesByName
@@ -75,7 +78,7 @@ export class GeminiImageAdapter<
 
   // Type-only property - never assigned at runtime
   declare '~types': {
-    providerOptions: GeminiImageProviderOptions
+    providerOptions: GeminiAnyImageProviderOptions
     modelProviderOptionsByName: GeminiImageModelProviderOptionsByName
     modelSizeByName: GeminiImageModelSizeByName
     modelInputModalitiesByName: GeminiImageModelInputModalitiesByName
@@ -89,7 +92,7 @@ export class GeminiImageAdapter<
   }
 
   async generateImages(
-    options: ImageGenerationOptions<GeminiImageProviderOptions>,
+    options: ImageGenerationOptions<GeminiAnyImageProviderOptions>,
   ): Promise<ImageGenerationResult> {
     const { model, logger } = options
 
@@ -121,7 +124,7 @@ export class GeminiImageAdapter<
         )
       }
 
-      if (this.isGeminiImageModel(model)) {
+      if (isGeminiNativeImageModel(model)) {
         return await this.generateWithGeminiApi(options, resolved)
       }
 
@@ -155,29 +158,40 @@ export class GeminiImageAdapter<
     }
   }
 
-  private isGeminiImageModel(model: string): boolean {
-    return model.startsWith('gemini-')
-  }
-
   private async generateWithGeminiApi(
-    options: ImageGenerationOptions<GeminiImageProviderOptions>,
+    options: ImageGenerationOptions<GeminiNativeImageProviderOptions>,
     resolved: ResolvedMediaPrompt,
   ): Promise<ImageGenerationResult> {
     const { model, size, numberOfImages, modelOptions } = options
 
     const parsedSize = size ? parseNativeImageSize(size) : undefined
 
-    // GeminiImageProviderOptions is Imagen-shaped — most fields
-    // (personGeneration, safetyFilterLevel, addWatermark, outputMimeType,
-    // outputCompressionQuality, guidanceScale, enhancePrompt,
-    // includeSafetyAttributes, includeRaiReason, outputGcsUri, labels,
-    // negativePrompt, language) are only valid on GenerateImagesConfig and
-    // would be rejected by the Gemini-native generateContent path. Pick only
-    // the fields that are valid on GenerateContentConfig instead of spreading
-    // the whole options object.
-    const nativeConfig: GenerateContentConfig = {}
-    if (modelOptions?.seed !== undefined) {
-      nativeConfig.seed = modelOptions.seed
+    // The portable `size` option is the baseline; modelOptions.imageConfig is
+    // the provider escape hatch and wins per field, so a caller passing only
+    // `imageConfig.imageSize` keeps the aspectRatio derived from `size`.
+    const imageConfig: ImageConfig = {
+      ...(parsedSize?.aspectRatio && { aspectRatio: parsedSize.aspectRatio }),
+      ...(parsedSize?.resolution && { imageSize: parsedSize.resolution }),
+      ...modelOptions?.imageConfig,
+    }
+
+    // Named picks, never a wholesale spread: the Imagen-shaped fields of
+    // GeminiImageProviderOptions (personGeneration, safetyFilterLevel,
+    // addWatermark, outputMimeType, …) are only valid on GenerateImagesConfig
+    // and would be rejected by generateContent. Picking by name means no
+    // Imagen field can reach this path even if one slips past the per-model
+    // provider-options map.
+    const nativeConfig: GenerateContentConfig = {
+      ...(modelOptions?.seed !== undefined && { seed: modelOptions.seed }),
+      ...(modelOptions?.safetySettings !== undefined && {
+        safetySettings: modelOptions.safetySettings,
+      }),
+      ...(modelOptions?.thinkingConfig !== undefined && {
+        thinkingConfig: modelOptions.thinkingConfig,
+      }),
+      ...(modelOptions?.systemInstruction !== undefined && {
+        systemInstruction: modelOptions.systemInstruction,
+      }),
     }
 
     const config: GenerateContentConfig = {
@@ -186,16 +200,7 @@ export class GeminiImageAdapter<
       // IMPORTANT: responseModalities is a protected default — set it AFTER
       // nativeConfig so nothing can silently disable image output.
       responseModalities: ['TEXT', 'IMAGE'],
-      ...(parsedSize && {
-        imageConfig: {
-          ...(parsedSize.aspectRatio && {
-            aspectRatio: parsedSize.aspectRatio,
-          }),
-          ...(parsedSize.resolution && {
-            imageSize: parsedSize.resolution,
-          }),
-        },
-      }),
+      ...(Object.keys(imageConfig).length > 0 && { imageConfig }),
     }
 
     const contents = this.buildContents(resolved, numberOfImages)
@@ -321,7 +326,7 @@ export class GeminiImageAdapter<
   }
 
   private buildImagenConfig(
-    options: ImageGenerationOptions<GeminiImageProviderOptions>,
+    options: ImageGenerationOptions<GeminiAnyImageProviderOptions>,
   ): GenerateImagesConfig {
     const { size, numberOfImages, modelOptions } = options
 
@@ -329,11 +334,62 @@ export class GeminiImageAdapter<
     // vendor `GenerateImagesConfig` fields are `field?: T` (no `| undefined`),
     // so we can only assign the property when we actually have a value.
     const sizeAspectRatio = size ? sizeToAspectRatio(size) : undefined
+
+    // Named picks, never a wholesale spread — the mirror image of the native
+    // path below. A native-only field (safetySettings, thinkingConfig,
+    // imageConfig, systemInstruction) belongs to GenerateContentConfig and is
+    // rejected by generateImages with 400 INVALID_ARGUMENT, so it must not be
+    // able to reach here even when the caller's `modelOptions` was typed
+    // against both shapes at once (e.g. an adapter inferred from a union of
+    // model names).
     return {
       numberOfImages: numberOfImages ?? 1,
-      // Map size to aspect ratio if provided (modelOptions.aspectRatio will override)
+      // Map size to aspect ratio if provided; modelOptions.aspectRatio,
+      // picked after it, overrides.
       ...(sizeAspectRatio !== undefined && { aspectRatio: sizeAspectRatio }),
-      ...modelOptions,
+      ...(modelOptions?.aspectRatio !== undefined && {
+        aspectRatio: modelOptions.aspectRatio,
+      }),
+      ...(modelOptions?.personGeneration !== undefined && {
+        personGeneration: modelOptions.personGeneration,
+      }),
+      ...(modelOptions?.safetyFilterLevel !== undefined && {
+        safetyFilterLevel: modelOptions.safetyFilterLevel,
+      }),
+      ...(modelOptions?.seed !== undefined && { seed: modelOptions.seed }),
+      ...(modelOptions?.addWatermark !== undefined && {
+        addWatermark: modelOptions.addWatermark,
+      }),
+      ...(modelOptions?.language !== undefined && {
+        language: modelOptions.language,
+      }),
+      ...(modelOptions?.negativePrompt !== undefined && {
+        negativePrompt: modelOptions.negativePrompt,
+      }),
+      ...(modelOptions?.outputMimeType !== undefined && {
+        outputMimeType: modelOptions.outputMimeType,
+      }),
+      ...(modelOptions?.outputCompressionQuality !== undefined && {
+        outputCompressionQuality: modelOptions.outputCompressionQuality,
+      }),
+      ...(modelOptions?.guidanceScale !== undefined && {
+        guidanceScale: modelOptions.guidanceScale,
+      }),
+      ...(modelOptions?.enhancePrompt !== undefined && {
+        enhancePrompt: modelOptions.enhancePrompt,
+      }),
+      ...(modelOptions?.includeSafetyAttributes !== undefined && {
+        includeSafetyAttributes: modelOptions.includeSafetyAttributes,
+      }),
+      ...(modelOptions?.includeRaiReason !== undefined && {
+        includeRaiReason: modelOptions.includeRaiReason,
+      }),
+      ...(modelOptions?.outputGcsUri !== undefined && {
+        outputGcsUri: modelOptions.outputGcsUri,
+      }),
+      ...(modelOptions?.labels !== undefined && {
+        labels: modelOptions.labels,
+      }),
     }
   }
 
@@ -392,6 +448,18 @@ export class GeminiImageAdapter<
   }
 }
 
+/** @deprecated Shut down 2026-06-25. Use `gemini-3.1-flash-image`. */
+export function createGeminiImage(
+  model: 'gemini-3.1-flash-image-preview',
+  apiKey: string,
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<'gemini-3.1-flash-image-preview'>
+/** @deprecated Shut down 2026-06-25. Use `gemini-3-pro-image`. */
+export function createGeminiImage(
+  model: 'gemini-3-pro-image-preview',
+  apiKey: string,
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<'gemini-3-pro-image-preview'>
 /**
  * Creates a Gemini image adapter with explicit API key.
  * Type resolution happens here at the call site.
@@ -411,6 +479,11 @@ export class GeminiImageAdapter<
  * });
  * ```
  */
+export function createGeminiImage<TModel extends GeminiImageModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<TModel>
 export function createGeminiImage<TModel extends GeminiImageModel>(
   model: TModel,
   apiKey: string,
@@ -419,6 +492,16 @@ export function createGeminiImage<TModel extends GeminiImageModel>(
   return new GeminiImageAdapter({ apiKey, ...config }, model)
 }
 
+/** @deprecated Shut down 2026-06-25. Use `gemini-3.1-flash-image`. */
+export function geminiImage(
+  model: 'gemini-3.1-flash-image-preview',
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<'gemini-3.1-flash-image-preview'>
+/** @deprecated Shut down 2026-06-25. Use `gemini-3-pro-image`. */
+export function geminiImage(
+  model: 'gemini-3-pro-image-preview',
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<'gemini-3-pro-image-preview'>
 /**
  * Creates a Gemini image adapter with automatic API key detection from environment variables.
  * Type resolution happens here at the call site.
@@ -443,6 +526,10 @@ export function createGeminiImage<TModel extends GeminiImageModel>(
  * });
  * ```
  */
+export function geminiImage<TModel extends GeminiImageModel>(
+  model: TModel,
+  config?: Omit<GeminiImageConfig, 'apiKey'>,
+): GeminiImageAdapter<TModel>
 export function geminiImage<TModel extends GeminiImageModel>(
   model: TModel,
   config?: Omit<GeminiImageConfig, 'apiKey'>,

package/src/image/image-provider-options.ts

@@ -1,12 +1,24 @@
 import type { GeminiImageModels } from '../model-meta'
 import type {
+  ContentUnion,
+  ImageConfig,
   ImagePromptLanguage,
   PersonGeneration,
   SafetyFilterLevel,
+  SafetySetting,
+  ThinkingConfig,
 } from '@google/genai'
 
 // Re-export SDK types so users can use them directly
-export type { ImagePromptLanguage, PersonGeneration, SafetyFilterLevel }
+export type {
+  ContentUnion,
+  ImageConfig,
+  ImagePromptLanguage,
+  PersonGeneration,
+  SafetyFilterLevel,
+  SafetySetting,
+  ThinkingConfig,
+}
 
 /**
  * Gemini Imagen aspect ratio options
@@ -121,11 +133,80 @@ export interface GeminiImageProviderOptions {
 }
 
 /**
- * Model-specific provider options mapping
- * Currently all Imagen models use the same options structure
+ * Provider options for Gemini native image models (Nano Banana and friends).
+ *
+ * These models are served by `generateContent`, not `generateImages`, so they
+ * are configured by @google/genai's `GenerateContentConfig` — a different
+ * shape from the Imagen-only {@link GeminiImageProviderOptions} above. Only
+ * the `GenerateContentConfig` fields with clear image-generation semantics are
+ * surfaced; sampling knobs (`temperature`, `topK`, …) and chat-only plumbing
+ * (`tools`, `responseSchema`, …) are deliberately left out.
+ *
+ * `responseModalities` is intentionally absent: the adapter always requests
+ * `['TEXT', 'IMAGE']`, and letting a caller override it would silently disable
+ * image output on an image-generation call.
+ */
+export interface GeminiNativeImageProviderOptions {
+  /**
+   * Optional seed for reproducible image generation
+   * When the same seed is used with the same prompt and settings,
+   * you should get similar (though not identical) results
+   */
+  seed?: number
+
+  /**
+   * Per-category safety thresholds applied to the request
+   * Each entry pairs a HarmCategory with a HarmBlockThreshold
+   */
+  safetySettings?: Array<SafetySetting>
+
+  /**
+   * Controls the model's internal reasoning before it emits an image
+   * Use to raise or disable the thinking budget on models that support it
+   */
+  thinkingConfig?: ThinkingConfig
+
+  /**
+   * Native image output controls. Merged over the values derived from the
+   * portable `size` option, so fields set here win per field while the rest
+   * of `size` is preserved.
+   *
+   * Only `aspectRatio` and `imageSize` are accepted on the Gemini Developer
+   * API. Other SDK `ImageConfig` keys throw on this surface.
+   */
+  imageConfig?: GeminiNativeImageConfig
+
+  /**
+   * System-level instructions that steer the model for the whole request,
+   * e.g. a house art direction applied on top of the per-call prompt
+   */
+  systemInstruction?: ContentUnion
+}
+
+/**
+ * Every provider-option field this adapter understands, across both API
+ * paths. Used as the adapter's base (model-agnostic) option type; the
+ * per-model map below is what narrows a given model to the half that
+ * actually applies to it.
+ */
+export type GeminiAnyImageProviderOptions = GeminiImageProviderOptions &
+  GeminiNativeImageProviderOptions
+
+/**
+ * Model-specific provider options mapping.
+ * Gemini native image models go through `generateContent` and take
+ * `GenerateContentConfig` fields; Imagen models go through `generateImages`
+ * and take `GenerateImagesConfig` fields. Mirrors the native/Imagen split in
+ * {@link GeminiImageModelSizeByName} and
+ * {@link GeminiImageModelInputModalitiesByName}.
  */
 export type GeminiImageModelProviderOptionsByName = {
-  [K in GeminiImageModels]: GeminiImageProviderOptions
+  [K in GeminiNativeImageModels]: GeminiNativeImageProviderOptions
+} & {
+  [K in Exclude<
+    GeminiImageModels,
+    GeminiNativeImageModels
+  >]: GeminiImageProviderOptions
 }
 
 /**
@@ -145,47 +226,157 @@ export type GeminiImageSize =
   | '1080x1920'
 
 /**
- * Aspect ratios supported by Gemini native image models (via generateContent API).
- * Matches the SDK's ImageConfig.aspectRatio values.
+ * The ten aspect ratios every Gemini native image model accepts.
+ *
+ * Note `9:21` is deliberately absent: it exists only on Vertex / Cloud and is
+ * rejected by the Gemini API (`generateContent`), which is the surface this
+ * adapter targets.
+ *
+ * @see https://ai.google.dev/gemini-api/docs/image-generation
  */
-export type GeminiNativeImageAspectRatio =
+export type GeminiStandardImageAspectRatio =
   | '1:1'
   | '2:3'
   | '3:2'
   | '3:4'
   | '4:3'
+  | '4:5'
+  | '5:4'
   | '9:16'
   | '16:9'
   | '21:9'
 
 /**
- * Resolution tiers for Gemini native image models.
- * Matches the SDK's ImageConfig.imageSize values.
+ * The ten standard ratios plus the four extreme banner/strip ratios that only
+ * the Gemini 3.1 Flash Image models accept — 14 values, matching the
+ * `generateContent` `ImageConfig.aspectRatio` field union.
+ *
+ * @see https://ai.google.dev/api/generate-content
+ */
+export type GeminiExtendedImageAspectRatio =
+  | GeminiStandardImageAspectRatio
+  | '1:4'
+  | '4:1'
+  | '1:8'
+  | '8:1'
+
+/**
+ * Sizes for `gemini-3.1-flash-image` (and its shut-down `-preview` alias):
+ * all 14 aspect ratios at 512 / 1K / 2K / 4K. `512` is the wire token for the
+ * 0.5K tier — not `512px`, and the `K` is case-sensitive (`1k` is rejected).
+ */
+export type Gemini31FlashImageSize =
+  `${GeminiExtendedImageAspectRatio}_${'512' | '1K' | '2K' | '4K'}`
+
+/**
+ * Sizes for `gemini-3.1-flash-lite-image`: all 14 aspect ratios, 1K only.
+ * 2K and 4K are unsupported on this model.
+ *
+ * The four banner ratios (`1:4`, `4:1`, `1:8`, `8:1`) come from the Cloud
+ * model page. The Gemini API page states a count of 14 but does not list them.
+ *
+ * @see https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/3-1-flash-lite-image
+ * @see https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-lite-image
+ */
+export type Gemini31FlashLiteImageSize = `${GeminiExtendedImageAspectRatio}_1K`
+
+/**
+ * Sizes for `gemini-3-pro-image` (and its shut-down `-preview` alias): the ten
+ * standard aspect ratios at 1K / 2K / 4K. Pro has no 512 tier and none of the
+ * extreme banner ratios on the Gemini API.
+ */
+export type Gemini3ProImageSize =
+  `${GeminiStandardImageAspectRatio}_${'1K' | '2K' | '4K'}`
+
+/**
+ * Sizes for `gemini-2.5-flash-image`: a bare aspect ratio with no resolution
+ * suffix, e.g. `'16:9'`. Google documents no `image_size` value or default for
+ * this model — it emits a single fixed 1024px-class output — so the adapter
+ * sends `imageConfig.aspectRatio` and omits `imageSize` entirely rather than
+ * guessing a tier the API never documented.
  */
-export type GeminiNativeImageResolution = '1K' | '2K' | '4K'
+export type Gemini25FlashImageSize = GeminiStandardImageAspectRatio
 
 /**
- * Template literal size type for Gemini native image models: "16:9_4K", "1:1_2K", etc.
+ * `imageConfig` fields the Gemini Developer API accepts on `generateContent`.
+ * Other `@google/genai` `ImageConfig` keys (`personGeneration`,
+ * `outputMimeType`, and more) throw on this surface.
+ */
+export type GeminiNativeImageConfig = {
+  aspectRatio?: GeminiExtendedImageAspectRatio
+  imageSize?: '512' | '1K' | '2K' | '4K'
+}
+
+/**
+ * Any size accepted by any Gemini native image model. Prefer the per-model
+ * narrowing in {@link GeminiImageModelSizeByName} — this union is the widest
+ * possible set and accepts combinations no single model supports.
  */
 export type GeminiNativeImageSize =
-  `${GeminiNativeImageAspectRatio}_${GeminiNativeImageResolution}`
+  | Gemini31FlashImageSize
+  | Gemini31FlashLiteImageSize
+  | Gemini3ProImageSize
+  | Gemini25FlashImageSize
 
 /**
  * Gemini native image models that use the generateContent API path.
- * These models support template literal sizes (aspectRatio_resolution).
+ * These models take an aspect-ratio-based size rather than Imagen's
+ * WIDTHxHEIGHT pixel strings.
+ *
+ * This array is the single source of truth for the native/Imagen split: the
+ * `GeminiNativeImageModels` union and the per-model option/size/modality maps
+ * all derive from it. The `satisfies` clause makes a typo (or a name that
+ * is not a known image model) a build error rather than a phantom key on every
+ * per-model map.
+ *
+ * It is also the single source of truth for the adapter's runtime routing
+ * — see {@link isGeminiNativeImageModel}. Adding a new `gemini-*` image model
+ * means adding it here as well as to `GEMINI_IMAGE_MODELS` in model-meta.
+ * Until it is listed here it routes to the Imagen API instead and fails
+ * loudly on the first call, rather than silently taking the wrong option
+ * shape.
  */
+export const GEMINI_NATIVE_IMAGE_MODELS = [
+  'gemini-3.1-flash-image',
+  'gemini-3.1-flash-image-preview',
+  'gemini-3.1-flash-lite-image',
+  'gemini-3-pro-image',
+  'gemini-3-pro-image-preview',
+  'gemini-2.5-flash-image',
+] as const satisfies ReadonlyArray<GeminiImageModels>
+
 export type GeminiNativeImageModels =
-  | 'gemini-3.1-flash-image-preview'
-  | 'gemini-3.1-flash-lite-image'
-  | 'gemini-3-pro-image-preview'
-  | 'gemini-2.5-flash-image'
+  (typeof GEMINI_NATIVE_IMAGE_MODELS)[number]
+
+const NATIVE_IMAGE_MODEL_NAMES: ReadonlySet<string> = new Set(
+  GEMINI_NATIVE_IMAGE_MODELS,
+)
 
 /**
- * Model-specific size options mapping.
- * Gemini native image models use template literal sizes, Imagen models use pixel sizes.
+ * Runtime counterpart to {@link GeminiNativeImageModels} — decides which of
+ * the two Gemini image APIs a model goes to.
+ *
+ * Membership in {@link GEMINI_NATIVE_IMAGE_MODELS}, not a `gemini-` prefix
+ * test, so the runtime route and the type-level split cannot drift apart. An
+ * id this package does not know about reaches the Imagen endpoint and fails
+ * there, which is the intended signal to add the model here rather than to
+ * have it silently take the native path with Imagen-shaped option types.
+ */
+export function isGeminiNativeImageModel(model: string): boolean {
+  return NATIVE_IMAGE_MODEL_NAMES.has(model)
+}
+
+/**
+ * Model-specific size options mapping. Each native model gets its own ratio ×
+ * resolution set (they genuinely differ); Imagen models use pixel sizes.
  */
 export type GeminiImageModelSizeByName = {
-  [K in GeminiNativeImageModels]: GeminiNativeImageSize
+  'gemini-3.1-flash-image': Gemini31FlashImageSize
+  'gemini-3.1-flash-image-preview': Gemini31FlashImageSize
+  'gemini-3.1-flash-lite-image': Gemini31FlashLiteImageSize
+  'gemini-3-pro-image': Gemini3ProImageSize
+  'gemini-3-pro-image-preview': Gemini3ProImageSize
+  'gemini-2.5-flash-image': Gemini25FlashImageSize
 } & {
   [K in Exclude<GeminiImageModels, GeminiNativeImageModels>]: GeminiImageSize
 }
@@ -309,13 +500,23 @@ export function validatePrompt(options: {
 
 /**
  * Parses a Gemini native image size string into its components.
- * Format: "aspectRatio_resolution" e.g. "16:9_4K" → { aspectRatio: "16:9", resolution: "4K" }
+ *
+ * Format: `"aspectRatio_resolution"`, e.g. `"16:9_4K"` →
+ * `{ aspectRatio: "16:9", resolution: "4K" }`.
+ *
+ * The resolution suffix is optional: `gemini-2.5-flash-image` takes a bare
+ * aspect ratio (`"16:9"` → `{ aspectRatio: "16:9" }`) because Google documents
+ * no `image_size` for it, and the caller must then omit `imageSize` from the
+ * request rather than substituting a default.
  */
 export function parseNativeImageSize(
   size: string,
-): { aspectRatio: string; resolution: string } | undefined {
-  const match = size.match(/^(\d+:\d+)_(.+)$/)
+): { aspectRatio: string; resolution?: string } | undefined {
+  const match = size.match(/^(\d+:\d+)(?:_(.+))?$/)
   const [, aspectRatio, resolution] = match ?? []
-  if (aspectRatio === undefined || resolution === undefined) return undefined
-  return { aspectRatio, resolution }
+  if (aspectRatio === undefined) return undefined
+  return {
+    aspectRatio,
+    ...(resolution !== undefined && { resolution }),
+  }
 }