@agent-native/core 0.90.2 → 0.90.4

package/corpus/templates/analytics/changelog/2026-07-07-session-replays-load-sooner-show-clearer-activity-timelines-.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-07
+---
+
+Session replays load sooner, show clearer activity timelines, and keep Dev Tools fast on large recordings.

package/corpus/templates/assets/actions/_preset-skeleton-validation.ts

@@ -25,8 +25,11 @@ export async function assertPresetSkeletonAssetsValid(input: {
     skeleton.mask?.type === "asset" && typeof skeleton.mask.assetId === "string"
       ? skeleton.mask.assetId
       : "";
-  if (!backgroundAssetId || !maskAssetId) return;
+  if (!backgroundAssetId) return;
 
+  const assetIds = maskAssetId
+    ? [backgroundAssetId, maskAssetId]
+    : [backgroundAssetId];
   const rows = await input.db
     .select({
       id: schema.assets.id,
@@ -35,18 +38,15 @@ export async function assertPresetSkeletonAssetsValid(input: {
       height: schema.assets.height,
     })
     .from(schema.assets)
-    .where(inArray(schema.assets.id, [backgroundAssetId, maskAssetId]));
+    .where(inArray(schema.assets.id, assetIds));
   const background = rows.find((asset: any) => asset.id === backgroundAssetId);
+  if (!background || background.libraryId !== input.libraryId) {
+    throw new Error("Skeleton image must belong to this asset library.");
+  }
+  if (!maskAssetId) return;
   const mask = rows.find((asset: any) => asset.id === maskAssetId);
-  if (
-    !background ||
-    !mask ||
-    background.libraryId !== input.libraryId ||
-    mask.libraryId !== input.libraryId
-  ) {
-    throw new Error(
-      "Skeleton image and mask must belong to this asset library.",
-    );
+  if (!mask || mask.libraryId !== input.libraryId) {
+    throw new Error("Skeleton mask must belong to this asset library.");
   }
   if (
     typeof background.width !== "number" ||

package/corpus/templates/assets/actions/generate-image.ts

@@ -30,9 +30,11 @@ import {
   compositeLogo,
   maskFromManualMaskAlpha,
   maskFromPlateAlpha,
+  prepareGptImage2SkeletonInpaintImages,
 } from "../server/lib/image-processing.js";
 import { nowIso, parseJson, stringifyJson } from "../server/lib/json.js";
 import {
+  aspectRatioValue,
   clampCutoutAspectRatio,
   normalizePresetSkeletonSpec,
   skeletonUsesCanonicalLogo,
@@ -350,13 +352,21 @@ export default defineAction({
       isSkeletonCutout &&
       Boolean(skeletonAssets?.backgroundAsset) &&
       resolvedModel === "gpt-image-2";
+    const skeletonInpaint = useSkeletonInpaint
+      ? await inpaintReferencesForSkeleton(skeletonAssets)
+      : null;
     const resolvedAspectRatio =
-      isSkeletonCutout && !useSkeletonInpaint
-        ? clampCutoutAspectRatio({
-            aspectRatio: outputAspectRatio,
-            supported: supportedAspectRatiosForModel("gpt-image-1"),
-          })
-        : outputAspectRatio;
+      useSkeletonInpaint && skeletonInpaint
+        ? closestSupportedAspectRatioForSize(
+            skeletonInpaint.size,
+            supportedAspectRatiosForModel("gpt-image-2"),
+          )
+        : isSkeletonCutout
+          ? clampCutoutAspectRatio({
+              aspectRatio: outputAspectRatio,
+              supported: supportedAspectRatiosForModel("gpt-image-1"),
+            })
+          : outputAspectRatio;
     if (
       isSkeletonCutout &&
       !useSkeletonInpaint &&
@@ -386,7 +396,7 @@ export default defineAction({
       : "";
     let references: ReferenceForGeneration[];
     if (useSkeletonInpaint) {
-      references = await inpaintReferencesForSkeleton(skeletonAssets);
+      references = skeletonInpaint?.references ?? [];
     } else {
       const backgroundPlateReference =
         backgroundPlateReferenceForSkeleton(skeletonAssets);
@@ -839,7 +849,10 @@ function backgroundPlateReferenceForSkeleton(
 
 async function inpaintReferencesForSkeleton(
   skeletonAssets: LoadedSkeletonAssets | null,
-): Promise<ReferenceForGeneration[]> {
+): Promise<{
+  references: ReferenceForGeneration[];
+  size: { width: number; height: number };
+}> {
   if (
     !skeletonAssets?.backgroundAsset ||
     !skeletonAssets.backgroundAssetId ||
@@ -853,26 +866,49 @@ async function inpaintReferencesForSkeleton(
         plate: skeletonAssets.backgroundAsset,
       })
     : await maskFromPlateAlpha(skeletonAssets.backgroundAsset);
-  return [
-    {
-      id: skeletonAssets.backgroundAssetId,
-      role: "edit_target",
-      category: "skeleton",
-      mimeType: skeletonAssets.backgroundMimeType,
-      data: skeletonAssets.backgroundAsset.toString("base64"),
-      selectionReason: "explicit",
-    },
-    {
-      id:
-        skeletonAssets.maskAssetId ??
-        `${skeletonAssets.backgroundAssetId}:mask`,
-      role: "mask",
-      category: "skeleton",
-      mimeType: "image/png",
-      data: mask.toString("base64"),
-      selectionReason: "explicit",
-    },
-  ];
+  const prepared = await prepareGptImage2SkeletonInpaintImages({
+    plate: skeletonAssets.backgroundAsset,
+    mask,
+  });
+  return {
+    size: prepared.size,
+    references: [
+      {
+        id: skeletonAssets.backgroundAssetId,
+        role: "edit_target",
+        category: "skeleton",
+        mimeType: prepared.resized
+          ? "image/png"
+          : skeletonAssets.backgroundMimeType,
+        data: prepared.plate.toString("base64"),
+        selectionReason: "explicit",
+      },
+      {
+        id:
+          skeletonAssets.maskAssetId ??
+          `${skeletonAssets.backgroundAssetId}:mask`,
+        role: "mask",
+        category: "skeleton",
+        mimeType: "image/png",
+        data: prepared.mask.toString("base64"),
+        selectionReason: "explicit",
+      },
+    ],
+  };
+}
+
+function closestSupportedAspectRatioForSize(
+  size: { width: number; height: number },
+  supported: readonly AspectRatio[],
+): AspectRatio {
+  const target = size.width / size.height;
+  return (
+    [...supported].sort(
+      (left, right) =>
+        Math.abs(aspectRatioValue(left) - target) -
+        Math.abs(aspectRatioValue(right) - target),
+    )[0] ?? "1:1"
+  );
 }
 
 type LoadedSkeletonAssets = {

package/corpus/templates/assets/app/components/generation/GenerationResults.tsx

@@ -44,7 +44,7 @@ function variantStateKey(threadId: string | null) {
 // STALE_IMAGE_RUN_MS in refresh-generation-run, so a slow-but-healthy run (e.g.
 // gpt-image-2) is not flagged "interrupted" and flipped to an error slot before
 // its finished image arrives.
-const STALE_PENDING_RUN_MS = 6 * 60 * 1000;
+const STALE_PENDING_RUN_MS = 10 * 60 * 1000;
 
 function slotTime(slot: AssetVariantState["slots"][number]): number {
   const raw = slot.createdAt ?? slot.updatedAt ?? "";

package/corpus/templates/assets/app/routes/brand-kits.$id_.presets.$presetId.tsx

@@ -107,6 +107,12 @@ const NO_COLLECTION = "__none__";
 const NO_SKELETON_BACKGROUND = "__none__";
 const NO_SKELETON_MASK = "__none__";
 
+function usesSkeletonInpaintMode(
+  form: Pick<PresetFormState, "model" | "skeletonContentMode">,
+) {
+  return form.skeletonContentMode === "cutout" && form.model === "gpt-image-2";
+}
+
 export function meta() {
   return [{ title: messagesByLocale["en-US"].routeTitles.generationPreset }];
 }
@@ -147,7 +153,7 @@ function buildSkeletonSpec(
     ...(previous?.foreground ?? []).filter(
       (layer) => layer.source !== "canonicalLogo",
     ),
-    ...(form.skeletonLogo
+    ...(form.skeletonLogo && !usesSkeletonInpaintMode(form)
       ? [logoLayerFromPlacement(form.skeletonLogoPlacement)]
       : []),
   ];
@@ -957,7 +963,7 @@ export default function GenerationPresetEditorRoute() {
               </span>
             </span>
           </label>
-          <div className="grid gap-4 rounded-md border border-border p-4">
+          <div className="grid min-w-0 gap-4 rounded-md border border-border p-4">
             <label
               htmlFor="preset-skeleton-enabled"
               className={cn("flex items-start gap-3", readOnly && "opacity-70")}
@@ -981,7 +987,7 @@ export default function GenerationPresetEditorRoute() {
               </span>
             </label>
             {form.skeletonEnabled ? (
-              <div className="grid gap-4 sm:grid-cols-2">
+              <div className="grid min-w-0 gap-4 sm:grid-cols-2">
                 <div className="grid gap-2">
                   <FieldLabel>{t("brandKitDetail.contentMode")}</FieldLabel>
                   <Select
@@ -1004,9 +1010,9 @@ export default function GenerationPresetEditorRoute() {
                     </SelectContent>
                   </Select>
                 </div>
-                <div className="grid gap-3 sm:col-span-2">
+                <div className="grid min-w-0 gap-3 sm:col-span-2">
                   <FieldLabel>{t("brandKitDetail.skeletonImage")}</FieldLabel>
-                  <div className="grid gap-3 sm:grid-cols-[minmax(0,1fr)_16rem]">
+                  <div className="grid min-w-0 gap-3 md:grid-cols-[minmax(12rem,1fr)_minmax(12rem,16rem)]">
                     <button
                       type="button"
                       className={cn(
@@ -1029,7 +1035,7 @@ export default function GenerationPresetEditorRoute() {
                         </span>
                       )}
                     </button>
-                    <div className="grid content-start gap-2">
+                    <div className="grid min-w-0 content-start gap-2">
                       <input
                         ref={skeletonFileInputRef}
                         type="file"
@@ -1043,7 +1049,7 @@ export default function GenerationPresetEditorRoute() {
                       <Button
                         type="button"
                         variant="outline"
-                        className="gap-2"
+                        className="w-full min-w-0 gap-2"
                         disabled={readOnly || skeletonUploadPending}
                         onClick={() => skeletonFileInputRef.current?.click()}
                       >
@@ -1052,9 +1058,11 @@ export default function GenerationPresetEditorRoute() {
                         ) : (
                           <IconUpload className="h-4 w-4" />
                         )}
-                        {skeletonUploadPending
-                          ? t("brandKitDetail.uploadingSkeletonImage")
-                          : t("brandKitDetail.uploadSkeletonImage")}
+                        <span className="min-w-0 truncate">
+                          {skeletonUploadPending
+                            ? t("brandKitDetail.uploadingSkeletonImage")
+                            : t("brandKitDetail.uploadSkeletonImage")}
+                        </span>
                       </Button>
                       <Select
                         value={
@@ -1064,7 +1072,7 @@ export default function GenerationPresetEditorRoute() {
                         disabled={readOnly || !skeletonBackgroundAssets.length}
                         onValueChange={updateSkeletonBackgroundAsset}
                       >
-                        <SelectTrigger>
+                        <SelectTrigger className="min-w-0">
                           <SelectValue
                             placeholder={t(
                               "brandKitDetail.chooseSkeletonImage",
@@ -1090,9 +1098,9 @@ export default function GenerationPresetEditorRoute() {
                 </div>
                 {form.skeletonContentMode === "cutout" &&
                 form.model === "gpt-image-2" ? (
-                  <div className="grid gap-3 sm:col-span-2">
+                  <div className="grid min-w-0 gap-3 sm:col-span-2">
                     <FieldLabel>{t("brandKitDetail.skeletonMask")}</FieldLabel>
-                    <div className="grid gap-3 sm:grid-cols-[minmax(0,1fr)_16rem]">
+                    <div className="grid min-w-0 gap-3 md:grid-cols-[minmax(12rem,1fr)_minmax(12rem,16rem)]">
                       <button
                         type="button"
                         className={cn(
@@ -1119,7 +1127,7 @@ export default function GenerationPresetEditorRoute() {
                           </span>
                         )}
                       </button>
-                      <div className="grid content-start gap-2">
+                      <div className="grid min-w-0 content-start gap-2">
                         <input
                           ref={skeletonMaskFileInputRef}
                           type="file"
@@ -1133,7 +1141,7 @@ export default function GenerationPresetEditorRoute() {
                         <Button
                           type="button"
                           variant="outline"
-                          className="gap-2"
+                          className="w-full min-w-0 gap-2"
                           disabled={readOnly || skeletonMaskUploadPending}
                           onClick={() =>
                             skeletonMaskFileInputRef.current?.click()
@@ -1144,9 +1152,11 @@ export default function GenerationPresetEditorRoute() {
                           ) : (
                             <IconUpload className="h-4 w-4" />
                           )}
-                          {skeletonMaskUploadPending
-                            ? t("brandKitDetail.uploadingSkeletonMask")
-                            : t("brandKitDetail.uploadSkeletonMask")}
+                          <span className="min-w-0 truncate">
+                            {skeletonMaskUploadPending
+                              ? t("brandKitDetail.uploadingSkeletonMask")
+                              : t("brandKitDetail.uploadSkeletonMask")}
+                          </span>
                         </Button>
                         <Select
                           value={form.skeletonMaskAssetId || NO_SKELETON_MASK}
@@ -1155,7 +1165,7 @@ export default function GenerationPresetEditorRoute() {
                           }
                           onValueChange={updateSkeletonMaskAsset}
                         >
-                          <SelectTrigger>
+                          <SelectTrigger className="min-w-0">
                             <SelectValue
                               placeholder={t(
                                 "brandKitDetail.chooseSkeletonMask",
@@ -1207,61 +1217,68 @@ export default function GenerationPresetEditorRoute() {
                     </span>
                   </label>
                 ) : null}
-                <label
-                  htmlFor="preset-skeleton-logo"
-                  className={cn(
-                    "flex items-start gap-3 rounded-md border border-border p-3",
-                    readOnly && "opacity-70",
-                  )}
-                >
-                  <Checkbox
-                    id="preset-skeleton-logo"
-                    checked={form.skeletonLogo}
-                    disabled={readOnly || !library?.canonicalLogoAssetId}
-                    onCheckedChange={(checked) =>
-                      updateForm({ skeletonLogo: checked === true })
-                    }
-                    className="mt-0.5"
-                  />
-                  <span className="grid gap-1">
-                    <span className="text-sm font-medium leading-none">
-                      {t("brandKitDetail.placeLogoInSkeleton")}
-                    </span>
-                    <span className="text-xs text-muted-foreground">
-                      {t("brandKitDetail.placeLogoInSkeletonHint")}
-                    </span>
-                  </span>
-                </label>
-                <div className="grid gap-2">
-                  <FieldLabel>{t("brandKitDetail.logoPlacement")}</FieldLabel>
-                  <Select
-                    value={form.skeletonLogoPlacement}
-                    disabled={readOnly || !form.skeletonLogo}
-                    onValueChange={(value) =>
-                      updateForm({
-                        skeletonLogoPlacement: value as SkeletonLogoPlacement,
-                      })
-                    }
-                  >
-                    <SelectTrigger>
-                      <SelectValue />
-                    </SelectTrigger>
-                    <SelectContent>
-                      <SelectItem value="upper-right">
-                        {t("brandKitDetail.upperRight")}
-                      </SelectItem>
-                      <SelectItem value="upper-left">
-                        {t("brandKitDetail.upperLeft")}
-                      </SelectItem>
-                      <SelectItem value="lower-right">
-                        {t("brandKitDetail.lowerRight")}
-                      </SelectItem>
-                      <SelectItem value="lower-left">
-                        {t("brandKitDetail.lowerLeft")}
-                      </SelectItem>
-                    </SelectContent>
-                  </Select>
-                </div>
+                {!usesSkeletonInpaintMode(form) ? (
+                  <>
+                    <label
+                      htmlFor="preset-skeleton-logo"
+                      className={cn(
+                        "flex items-start gap-3 rounded-md border border-border p-3",
+                        readOnly && "opacity-70",
+                      )}
+                    >
+                      <Checkbox
+                        id="preset-skeleton-logo"
+                        checked={form.skeletonLogo}
+                        disabled={readOnly || !library?.canonicalLogoAssetId}
+                        onCheckedChange={(checked) =>
+                          updateForm({ skeletonLogo: checked === true })
+                        }
+                        className="mt-0.5"
+                      />
+                      <span className="grid gap-1">
+                        <span className="text-sm font-medium leading-none">
+                          {t("brandKitDetail.placeLogoInSkeleton")}
+                        </span>
+                        <span className="text-xs text-muted-foreground">
+                          {t("brandKitDetail.placeLogoInSkeletonHint")}
+                        </span>
+                      </span>
+                    </label>
+                    <div className="grid gap-2">
+                      <FieldLabel>
+                        {t("brandKitDetail.logoPlacement")}
+                      </FieldLabel>
+                      <Select
+                        value={form.skeletonLogoPlacement}
+                        disabled={readOnly || !form.skeletonLogo}
+                        onValueChange={(value) =>
+                          updateForm({
+                            skeletonLogoPlacement:
+                              value as SkeletonLogoPlacement,
+                          })
+                        }
+                      >
+                        <SelectTrigger>
+                          <SelectValue />
+                        </SelectTrigger>
+                        <SelectContent>
+                          <SelectItem value="upper-right">
+                            {t("brandKitDetail.upperRight")}
+                          </SelectItem>
+                          <SelectItem value="upper-left">
+                            {t("brandKitDetail.upperLeft")}
+                          </SelectItem>
+                          <SelectItem value="lower-right">
+                            {t("brandKitDetail.lowerRight")}
+                          </SelectItem>
+                          <SelectItem value="lower-left">
+                            {t("brandKitDetail.lowerLeft")}
+                          </SelectItem>
+                        </SelectContent>
+                      </Select>
+                    </div>
+                  </>
+                ) : null}
               </div>
             ) : null}
           </div>

package/corpus/templates/assets/server/lib/generation.ts

@@ -642,7 +642,11 @@ export async function generateWithManagedImageProvider(
     const shouldFallback =
       err instanceof BuilderImageGenerationError &&
       [401, 402, 403, 429, 503, 504].includes(err.status ?? 0);
-    if (shouldFallback && (await isManualImageGenerationConfigured())) {
+    if (
+      shouldFallback &&
+      input.mode !== "edit" &&
+      (await isManualImageGenerationConfigured())
+    ) {
       logGeneration("builder.fallback_to_manual", {
         model: input.model,
         status:
@@ -652,7 +656,7 @@ export async function generateWithManagedImageProvider(
       return generateWithManualImageProvider(input);
     }
     if (shouldFallback && err instanceof BuilderImageGenerationError) {
-      throw createBuilderImageGenerationFallbackError(err);
+      throw createBuilderImageGenerationFallbackError(err, input);
     }
     throw err;
   }
@@ -660,12 +664,15 @@ export async function generateWithManagedImageProvider(
 
 function createBuilderImageGenerationFallbackError(
   err: BuilderImageGenerationError,
+  input?: GenerateProviderInput,
 ): Error {
-  const message = builderImageGenerationFallbackMessage(err);
+  const message = builderImageGenerationFallbackMessage(err, input);
   if ([401, 402, 403].includes(err.status ?? 0)) {
     return new FeatureNotConfiguredError({
       requiredCredential:
-        err.status === 401 ? "BUILDER_PRIVATE_KEY" : "GEMINI_API_KEY",
+        input?.mode === "edit" || err.status === 401
+          ? "BUILDER_PRIVATE_KEY"
+          : "GEMINI_API_KEY",
       builderConnectUrl: "/_agent-native/builder/connect",
       byokDocsUrl: "https://aistudio.google.com/apikey",
       message,
@@ -676,8 +683,26 @@ function createBuilderImageGenerationFallbackError(
 
 function builderImageGenerationFallbackMessage(
   err: BuilderImageGenerationError,
+  input?: GenerateProviderInput,
 ): string {
   const detail = err.detail ? `: ${err.detail}` : ".";
+  if (input?.mode === "edit") {
+    switch (err.status) {
+      case 401:
+        return `Masked skeleton inpainting needs Builder.io connected or reconnected${err.detail ? ` (${err.detail})` : ""}. Open Settings and click Connect Builder.io; manual OpenAI or Gemini fallback cannot pass image-edit masks.`;
+      case 402:
+        return `Builder.io is connected, but this Builder space cannot use managed image generation credits${detail} Masked skeleton inpainting cannot use manual OpenAI or Gemini fallback because it must pass an image-edit mask.`;
+      case 403:
+        return `Builder.io is connected, but this Builder space does not have access to managed image generation${detail} Ask a space admin to enable access or reconnect to a different Builder space; manual fallback cannot pass image-edit masks.`;
+      case 429:
+        return `Builder-managed masked inpainting is rate limited right now${detail} Retry shortly; manual OpenAI or Gemini fallback cannot pass image-edit masks.`;
+      case 503:
+      case 504:
+        return `Builder-managed masked inpainting is temporarily unavailable${detail} Retry shortly; manual OpenAI or Gemini fallback cannot pass image-edit masks.`;
+      default:
+        return `Builder-managed masked inpainting failed${detail} Retry with Builder-managed image generation; manual OpenAI or Gemini fallback cannot pass image-edit masks.`;
+    }
+  }
   switch (err.status) {
     case 401:
       return `Image generation needs Builder.io connected or reconnected${err.detail ? ` (${err.detail})` : ""}. Open Settings and click Connect Builder.io, or expand the Asset generation setup step and add an OpenAI or Gemini API key as the manual fallback.`;

package/corpus/templates/assets/server/lib/image-processing.ts

@@ -130,6 +130,137 @@ export async function maskFromManualMaskAlpha(input: {
   });
 }
 
+const GPT_IMAGE_2_EDIT_SIZE_MULTIPLE = 16;
+const GPT_IMAGE_2_EDIT_MIN_PIXELS = 655_360;
+const GPT_IMAGE_2_EDIT_MAX_PIXELS = 8_294_400;
+const GPT_IMAGE_2_EDIT_MAX_SIDE = 3840;
+const GPT_IMAGE_2_EDIT_MAX_RATIO = 3;
+
+export async function prepareGptImage2SkeletonInpaintImages(input: {
+  plate: Buffer;
+  mask: Buffer;
+}): Promise<{
+  plate: Buffer;
+  mask: Buffer;
+  size: { width: number; height: number };
+  resized: boolean;
+}> {
+  const metadata = await sharp(input.plate, { failOn: "none" }).metadata();
+  const width = metadata.width ?? 0;
+  const height = metadata.height ?? 0;
+  if (!width || !height) {
+    throw new Error(
+      "Skeleton inpainting background plate dimensions are invalid.",
+    );
+  }
+  const size = gptImage2EditSizeForPlate({ width, height });
+  const resized = size.width !== width || size.height !== height;
+  if (!resized) {
+    return { plate: input.plate, mask: input.mask, size, resized };
+  }
+  return {
+    plate: await sharp(input.plate, { failOn: "none" })
+      .rotate()
+      .resize({ width: size.width, height: size.height, fit: "fill" })
+      .png()
+      .toBuffer(),
+    mask: await sharp(input.mask, { failOn: "none" })
+      .resize({ width: size.width, height: size.height, fit: "fill" })
+      .png()
+      .toBuffer(),
+    size,
+    resized,
+  };
+}
+
+function gptImage2EditSizeForPlate(input: { width: number; height: number }): {
+  width: number;
+  height: number;
+} {
+  if (isValidGptImage2EditSize(input)) return input;
+  const ratio =
+    Math.max(input.width, input.height) / Math.min(input.width, input.height);
+  if (ratio > GPT_IMAGE_2_EDIT_MAX_RATIO) {
+    throw new Error(
+      "gpt-image-2 skeleton inpainting requires a background plate aspect ratio no wider or taller than 3:1.",
+    );
+  }
+
+  const pixels = input.width * input.height;
+  let scale = 1;
+  if (pixels < GPT_IMAGE_2_EDIT_MIN_PIXELS) {
+    scale = Math.sqrt(GPT_IMAGE_2_EDIT_MIN_PIXELS / pixels);
+  } else if (pixels > GPT_IMAGE_2_EDIT_MAX_PIXELS) {
+    scale = Math.sqrt(GPT_IMAGE_2_EDIT_MAX_PIXELS / pixels);
+  }
+  scale = Math.min(
+    scale,
+    GPT_IMAGE_2_EDIT_MAX_SIDE / Math.max(input.width, input.height),
+  );
+
+  for (let attempt = 0; attempt < 200; attempt += 1) {
+    const candidate = {
+      width: roundToMultiple(
+        input.width * scale,
+        GPT_IMAGE_2_EDIT_SIZE_MULTIPLE,
+      ),
+      height: roundToMultiple(
+        input.height * scale,
+        GPT_IMAGE_2_EDIT_SIZE_MULTIPLE,
+      ),
+    };
+    if (isValidGptImage2EditSize(candidate)) return candidate;
+    const candidatePixels = candidate.width * candidate.height;
+    if (
+      candidatePixels < GPT_IMAGE_2_EDIT_MIN_PIXELS ||
+      candidate.width % GPT_IMAGE_2_EDIT_SIZE_MULTIPLE !== 0 ||
+      candidate.height % GPT_IMAGE_2_EDIT_SIZE_MULTIPLE !== 0
+    ) {
+      scale *= 1.01;
+    } else {
+      scale *= 0.99;
+    }
+  }
+
+  throw new Error(
+    "Unable to prepare a valid gpt-image-2 skeleton inpainting size.",
+  );
+}
+
+function isValidGptImage2EditSize(input: {
+  width: number;
+  height: number;
+}): boolean {
+  if (!Number.isInteger(input.width) || !Number.isInteger(input.height)) {
+    return false;
+  }
+  if (input.width <= 0 || input.height <= 0) return false;
+  if (Math.max(input.width, input.height) > GPT_IMAGE_2_EDIT_MAX_SIDE) {
+    return false;
+  }
+  if (
+    input.width % GPT_IMAGE_2_EDIT_SIZE_MULTIPLE !== 0 ||
+    input.height % GPT_IMAGE_2_EDIT_SIZE_MULTIPLE !== 0
+  ) {
+    return false;
+  }
+  if (
+    Math.max(input.width, input.height) / Math.min(input.width, input.height) >
+    GPT_IMAGE_2_EDIT_MAX_RATIO
+  ) {
+    return false;
+  }
+  const pixels = input.width * input.height;
+  return (
+    pixels >= GPT_IMAGE_2_EDIT_MIN_PIXELS &&
+    pixels <= GPT_IMAGE_2_EDIT_MAX_PIXELS
+  );
+}
+
+function roundToMultiple(value: number, multiple: number): number {
+  return Math.max(multiple, Math.round(value / multiple) * multiple);
+}
+
 async function maskFromAlphaChannel(input: {
   image: Buffer;
   expectedSize?: { width: number; height: number };