@nodaro/shared 3.60.1 → 3.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/dist/{chunk-DS2TOM32.js → chunk-43TGSZRJ.js} +27 -3
  2. package/dist/chunk-43TGSZRJ.js.map +1 -0
  3. package/dist/{chunk-RRPPXZ36.cjs → chunk-4KYLNTR7.cjs} +4 -4
  4. package/dist/{chunk-RRPPXZ36.cjs.map → chunk-4KYLNTR7.cjs.map} +1 -1
  5. package/dist/{chunk-HDHLZK7C.cjs → chunk-5I4T4QR5.cjs} +5 -5
  6. package/dist/{chunk-HDHLZK7C.cjs.map → chunk-5I4T4QR5.cjs.map} +1 -1
  7. package/dist/{chunk-DQIJPDHC.cjs → chunk-5XRRENHD.cjs} +11 -11
  8. package/dist/{chunk-DQIJPDHC.cjs.map → chunk-5XRRENHD.cjs.map} +1 -1
  9. package/dist/{chunk-LN3EVFRS.js → chunk-673E4KYC.js} +5 -5
  10. package/dist/{chunk-LN3EVFRS.js.map → chunk-673E4KYC.js.map} +1 -1
  11. package/dist/{chunk-CIOXUPCJ.cjs → chunk-7ARKVJTN.cjs} +12 -12
  12. package/dist/{chunk-CIOXUPCJ.cjs.map → chunk-7ARKVJTN.cjs.map} +1 -1
  13. package/dist/{chunk-MHY47BLL.js → chunk-7WGKP3EU.js} +4 -4
  14. package/dist/{chunk-MHY47BLL.js.map → chunk-7WGKP3EU.js.map} +1 -1
  15. package/dist/{chunk-KOLC7AF2.js → chunk-A3FHTSLB.js} +99 -14
  16. package/dist/chunk-A3FHTSLB.js.map +1 -0
  17. package/dist/{chunk-6Q6SI7AG.js → chunk-B6BG3LV2.js} +3 -3
  18. package/dist/{chunk-6Q6SI7AG.js.map → chunk-B6BG3LV2.js.map} +1 -1
  19. package/dist/{chunk-SCYBGTX6.js → chunk-C77F4ZTL.js} +3 -3
  20. package/dist/{chunk-SCYBGTX6.js.map → chunk-C77F4ZTL.js.map} +1 -1
  21. package/dist/{chunk-IV6IDECY.js → chunk-EWS2VFO4.js} +4 -4
  22. package/dist/{chunk-IV6IDECY.js.map → chunk-EWS2VFO4.js.map} +1 -1
  23. package/dist/{chunk-A6HRY3WF.cjs → chunk-F5YEMSNK.cjs} +102 -13
  24. package/dist/chunk-F5YEMSNK.cjs.map +1 -0
  25. package/dist/{chunk-5HK5Z5OB.cjs → chunk-FMXFHJWX.cjs} +4 -4
  26. package/dist/{chunk-5HK5Z5OB.cjs.map → chunk-FMXFHJWX.cjs.map} +1 -1
  27. package/dist/{chunk-GWBQ3GPO.cjs → chunk-FQXRYPCX.cjs} +27 -22
  28. package/dist/chunk-FQXRYPCX.cjs.map +1 -0
  29. package/dist/{chunk-ICDLYU4I.js → chunk-HGI2VKIV.js} +8 -8
  30. package/dist/{chunk-ICDLYU4I.js.map → chunk-HGI2VKIV.js.map} +1 -1
  31. package/dist/{chunk-EN2YI5TV.js → chunk-IRQ3SPX7.js} +3 -3
  32. package/dist/{chunk-EN2YI5TV.js.map → chunk-IRQ3SPX7.js.map} +1 -1
  33. package/dist/{chunk-5Y42RIGY.cjs → chunk-IVXSNW2B.cjs} +8 -8
  34. package/dist/{chunk-5Y42RIGY.cjs.map → chunk-IVXSNW2B.cjs.map} +1 -1
  35. package/dist/{chunk-W4M7TNXG.cjs → chunk-JHTT2V4A.cjs} +39 -39
  36. package/dist/{chunk-W4M7TNXG.cjs.map → chunk-JHTT2V4A.cjs.map} +1 -1
  37. package/dist/{chunk-VYQ25YQF.js → chunk-KHZAQGRP.js} +3 -3
  38. package/dist/{chunk-VYQ25YQF.js.map → chunk-KHZAQGRP.js.map} +1 -1
  39. package/dist/{chunk-G6GMY5BC.js → chunk-LLOIAGFB.js} +9 -4
  40. package/dist/chunk-LLOIAGFB.js.map +1 -0
  41. package/dist/{chunk-AZGONXWV.js → chunk-MOMFX32D.js} +4 -4
  42. package/dist/{chunk-AZGONXWV.js.map → chunk-MOMFX32D.js.map} +1 -1
  43. package/dist/{chunk-BXNPO3PL.cjs → chunk-MQZRQ5LM.cjs} +8 -8
  44. package/dist/{chunk-BXNPO3PL.cjs.map → chunk-MQZRQ5LM.cjs.map} +1 -1
  45. package/dist/chunk-NCOGGRRP.cjs +27 -0
  46. package/dist/{chunk-G7ZYZQKO.cjs.map → chunk-NCOGGRRP.cjs.map} +1 -1
  47. package/dist/{chunk-AXT7YNOR.cjs → chunk-NJVOJXBS.cjs} +43 -43
  48. package/dist/{chunk-AXT7YNOR.cjs.map → chunk-NJVOJXBS.cjs.map} +1 -1
  49. package/dist/{chunk-SKFJIFEV.cjs → chunk-RQ4F3AJH.cjs} +21 -21
  50. package/dist/{chunk-SKFJIFEV.cjs.map → chunk-RQ4F3AJH.cjs.map} +1 -1
  51. package/dist/{chunk-HYBACFYW.js → chunk-RUHKBEFF.js} +4 -4
  52. package/dist/{chunk-HYBACFYW.js.map → chunk-RUHKBEFF.js.map} +1 -1
  53. package/dist/{chunk-URLDVK67.js → chunk-SCMTN57Y.js} +3 -3
  54. package/dist/{chunk-URLDVK67.js.map → chunk-SCMTN57Y.js.map} +1 -1
  55. package/dist/{chunk-JKZVRKN3.js → chunk-UARGJ5IZ.js} +6 -6
  56. package/dist/chunk-UARGJ5IZ.js.map +1 -0
  57. package/dist/{chunk-6AJOTEVC.js → chunk-VOWJCUMR.js} +3 -3
  58. package/dist/{chunk-6AJOTEVC.js.map → chunk-VOWJCUMR.js.map} +1 -1
  59. package/dist/{chunk-5G23AJBU.cjs → chunk-XUJC6GHE.cjs} +6 -6
  60. package/dist/{chunk-5G23AJBU.cjs.map → chunk-XUJC6GHE.cjs.map} +1 -1
  61. package/dist/{chunk-GNPJ2JLE.cjs → chunk-XZKFZMRT.cjs} +6 -6
  62. package/dist/{chunk-GNPJ2JLE.cjs.map → chunk-XZKFZMRT.cjs.map} +1 -1
  63. package/dist/{chunk-KJZVQIN4.js → chunk-ZDBPQBAA.js} +3 -3
  64. package/dist/{chunk-KJZVQIN4.js.map → chunk-ZDBPQBAA.js.map} +1 -1
  65. package/dist/{chunk-HOKWJXHA.cjs → chunk-ZFJN23V4.cjs} +29 -2
  66. package/dist/chunk-ZFJN23V4.cjs.map +1 -0
  67. package/dist/{chunk-HNEF2N5C.cjs → chunk-ZLDFPVVI.cjs} +5 -5
  68. package/dist/{chunk-HNEF2N5C.cjs.map → chunk-ZLDFPVVI.cjs.map} +1 -1
  69. package/dist/{chunk-BDXXOEBZ.cjs → chunk-ZNM2LW3D.cjs} +47 -47
  70. package/dist/chunk-ZNM2LW3D.cjs.map +1 -0
  71. package/dist/{chunk-YHVEZVAO.js → chunk-ZZGQRRN7.js} +4 -4
  72. package/dist/{chunk-YHVEZVAO.js.map → chunk-ZZGQRRN7.js.map} +1 -1
  73. package/dist/entries/apps.cjs +42 -42
  74. package/dist/entries/apps.js +7 -7
  75. package/dist/entries/credits.cjs +151 -151
  76. package/dist/entries/credits.d.cts +8 -4
  77. package/dist/entries/credits.d.ts +8 -4
  78. package/dist/entries/credits.js +7 -7
  79. package/dist/entries/llm-models.d.cts +1 -1
  80. package/dist/entries/llm-models.d.ts +1 -1
  81. package/dist/entries/model-catalog.cjs +94 -78
  82. package/dist/entries/model-catalog.d.cts +2 -2
  83. package/dist/entries/model-catalog.d.ts +2 -2
  84. package/dist/entries/model-catalog.js +4 -4
  85. package/dist/entries/models.cjs +293 -293
  86. package/dist/entries/models.d.cts +3 -3
  87. package/dist/entries/models.d.ts +3 -3
  88. package/dist/entries/models.js +4 -4
  89. package/dist/entries/nodes.cjs +206 -206
  90. package/dist/entries/nodes.d.cts +1 -1
  91. package/dist/entries/nodes.d.ts +1 -1
  92. package/dist/entries/nodes.js +8 -8
  93. package/dist/entries/pipeline.cjs +152 -152
  94. package/dist/entries/pipeline.d.cts +1 -1
  95. package/dist/entries/pipeline.d.ts +1 -1
  96. package/dist/entries/pipeline.js +3 -3
  97. package/dist/entries/ugc.cjs +71 -71
  98. package/dist/entries/ugc.js +4 -4
  99. package/dist/entries/video.cjs +117 -117
  100. package/dist/entries/video.js +4 -4
  101. package/dist/entries/workflow.cjs +110 -98
  102. package/dist/entries/workflow.d.cts +28 -2
  103. package/dist/entries/workflow.d.ts +28 -2
  104. package/dist/entries/workflow.js +1 -1
  105. package/dist/index.cjs +1212 -1184
  106. package/dist/index.d.cts +3 -3
  107. package/dist/index.d.ts +3 -3
  108. package/dist/index.js +18 -18
  109. package/dist/{model-catalog-D6Es7VG-.d.ts → model-catalog-BgSvskgY.d.cts} +52 -1
  110. package/dist/{model-catalog-D6Es7VG-.d.cts → model-catalog-BgSvskgY.d.ts} +52 -1
  111. package/dist/{model-constants-22k3fjp1.d.cts → model-constants-DHd9jwQ7.d.cts} +6 -1
  112. package/dist/{model-constants-22k3fjp1.d.ts → model-constants-DHd9jwQ7.d.ts} +6 -1
  113. package/package.json +1 -1
  114. package/src/__tests__/gpt-image-2-6.test.ts +7 -0
  115. package/src/__tests__/image-mask-mode.test.ts +34 -1
  116. package/src/__tests__/mask-edit-follows-source.test.ts +150 -0
  117. package/src/credit-identifiers.ts +8 -4
  118. package/src/entries/model-catalog.ts +4 -0
  119. package/src/entries/workflow.ts +1 -0
  120. package/src/model-catalog.ts +157 -11
  121. package/src/model-constants.ts +12 -2
  122. package/src/node-execution-state.ts +3 -1
  123. package/src/wired-image-size.ts +55 -0
  124. package/dist/chunk-A6HRY3WF.cjs.map +0 -1
  125. package/dist/chunk-BDXXOEBZ.cjs.map +0 -1
  126. package/dist/chunk-DS2TOM32.js.map +0 -1
  127. package/dist/chunk-G6GMY5BC.js.map +0 -1
  128. package/dist/chunk-G7ZYZQKO.cjs +0 -27
  129. package/dist/chunk-GWBQ3GPO.cjs.map +0 -1
  130. package/dist/chunk-HOKWJXHA.cjs.map +0 -1
  131. package/dist/chunk-JKZVRKN3.js.map +0 -1
  132. package/dist/chunk-KOLC7AF2.js.map +0 -1
@@ -310,6 +310,21 @@ interface ModelCatalogEntry {
310
310
  * as before. "auto" stays in `aspectRatios`, so every menu still offers it.
311
311
  */
312
312
  autoAspectFromSourceImage?: true;
313
+ /**
314
+ * The pixel size (width, height) this model renders at each aspect ratio and
315
+ * size, from the provider's own table, for a PNG, JPEG or WebP. Read where a
316
+ * run's size is chosen from its photo's size (`maskEditMatchesSource`).
317
+ */
318
+ outputSizes?: Readonly<Record<string, Readonly<Record<string, readonly [number, number]>>>>;
319
+ /**
320
+ * A masked edit on this model follows its photo: the result is pasted back
321
+ * onto the photo at the photo's own size, so the run keeps the photo's shape
322
+ * ("auto", whatever ratio it names) and renders at the size of `outputSizes`
323
+ * whose long side is nearest the photo's, priced at that size
324
+ * (`normalizeModelInput` with `context.masked`; `resolutionNearestSource`).
325
+ * With the photo's size unknown, the size asked is kept.
326
+ */
327
+ maskEditMatchesSource?: true;
313
328
  resolutions?: readonly string[];
314
329
  /**
315
330
  * The aspect ratios at which this model renders fewer sizes than
@@ -591,9 +606,45 @@ interface ModelInputContext {
591
606
  * resolve "auto" on a model without a native auto, or whose own auto does
592
607
  * not keep the photo's shape (`autoAspectFromSourceImage`); absent or
593
608
  * unusable means the size is unknown and "auto" snaps the way it always has.
609
+ * Also read by a masked edit on a model whose result follows its photo
610
+ * (`maskEditMatchesSource`): it decides the ratio and the size.
594
611
  */
595
612
  sourceImage?: SourceImageSize;
613
+ /** The request carries an inpainting mask (`maskUrl`). */
614
+ masked?: boolean;
596
615
  }
616
+ /**
617
+ * True when a masked request on `modelId` follows its photo
618
+ * (`maskEditMatchesSource`): its ratio and size come from the photo's size.
619
+ */
620
+ declare function maskEditMatchesSource(modelId: string | undefined, masked: unknown): boolean;
621
+ /**
622
+ * True when the photo's size can change what a request on `modelId` sends:
623
+ * "auto" that keeps the photo's shape (`autoAspectNeedsSourceImage`), or a
624
+ * masked edit that follows its photo (`maskEditMatchesSource`). A caller that
625
+ * has to fetch the size asks this first.
626
+ */
627
+ declare function sourceImageSizeNeeded(modelId: string | undefined, aspectRatio: unknown, masked: unknown): boolean;
628
+ /**
629
+ * The size a MASKED request on `modelId` runs, and is priced, at once its
630
+ * photo's size is known — what `normalizeModelInput` sends for it. For an
631
+ * estimate that knows the photo's size (the editor's badge, a workflow
632
+ * estimate). `undefined` when the model does not follow its photo
633
+ * (`maskEditMatchesSource`) or the size is unusable: the caller keeps its own.
634
+ */
635
+ declare function maskedEditResolution(modelId: string, levers: {
636
+ aspectRatio?: unknown;
637
+ resolution?: unknown;
638
+ background?: unknown;
639
+ outputFormat?: unknown;
640
+ }, sourceImage: SourceImageSize | undefined): string | undefined;
641
+ /**
642
+ * The size of `modelId` whose rendered long side, at `aspectRatio`, is nearest
643
+ * the photo's long side (`outputSizes`; nearest by ratio, so 1500 px is nearer
644
+ * 2048 than 1024; a tie goes to the larger size). `undefined` when the model
645
+ * has no size table for that ratio or the photo's size is unusable.
646
+ */
647
+ declare function resolutionNearestSource(modelId: string, aspectRatio: unknown, source: SourceImageSize | undefined): string | undefined;
597
648
  /** True for the "auto" aspect token in any case or padding. */
598
649
  declare function isAutoAspectToken(value: unknown): boolean;
599
650
  /**
@@ -833,4 +884,4 @@ declare function modelIdsByKindMode(kind: ModelKind | null, modes: readonly Mode
833
884
  includeHidden?: boolean;
834
885
  }): [string, ...string[]];
835
886
 
836
- export { modelsWithFeature as $, creditRangesAll as A, defaultResolutionFor as B, durationsByMode as C, fitAspectRatioToModel as D, getAspectRatioOptions as E, getCreditRange as F, getDurationsForModel as G, getModel as H, IMAGE_GIF_FRAME_SIZE as I, getQualityOptions as J, getResolutionOptions as K, type LabeledOption as L, MASKLESS_OUTPUT_FORMATS as M, type NormalizedModelInput as N, groupByFamily as O, type PriceVariant as P, groupByKindAndFamily as Q, hasFeature as R, SPEECH_UNIT_PRICE_NOTE as S, TRANSPARENT_OUTPUT_FORMATS as T, isAutoAspectToken as U, type ValidationField as V, isModelMakerId as W, listModels as X, modelIdsByKindMode as Y, modelMakerOf as Z, modelTakesSeed as _, IMAGE_OUTPUT_FORMAT_LABELS as a, nearestCatalogAspectRatio as a0, normalizeModelInput as a1, normalizeVideoRequestParams as a2, outputFormatOptionsByKind as a3, qualityOptionsByKind as a4, resolutionAtAspectRatio as a5, resolutionOptionsByKind as a6, resolutionsAtAspectRatio as a7, svgLevelOptionsByKind as a8, validateModelInput as a9, IMAGE_SVG_LEVEL_LABELS as b, MODEL_CATALOG as c, MODEL_INPUT_ADJUSTMENT_FIELDS as d, MODEL_KINDS as e, MODEL_MAKERS as f, MODEL_RECOMMENDATIONS as g, type ModelCatalogEntry as h, type ModelInputAdjustment as i, type ModelInputAdjustmentField as j, type ModelInputContext as k, type ModelKind as l, type ModelMaker as m, type ModelMakerId as n, type ModelMenuOption as o, type ModelMode as p, type ModelRecommendation as q, type ModelValidationIssue as r, type NormalizedVideoRequest as s, type SourceImageSize as t, type TtsCapabilities as u, type TtsSettingLever as v, aspectRatioOptionsByKind as w, autoAspectNeedsSourceImage as x, backgroundOptionsByKind as y, buildModelMenu as z };
887
+ export { modelMakerOf as $, creditRangesAll as A, defaultResolutionFor as B, durationsByMode as C, fitAspectRatioToModel as D, getAspectRatioOptions as E, getCreditRange as F, getDurationsForModel as G, getModel as H, IMAGE_GIF_FRAME_SIZE as I, getQualityOptions as J, getResolutionOptions as K, type LabeledOption as L, MASKLESS_OUTPUT_FORMATS as M, type NormalizedModelInput as N, groupByFamily as O, type PriceVariant as P, groupByKindAndFamily as Q, hasFeature as R, SPEECH_UNIT_PRICE_NOTE as S, TRANSPARENT_OUTPUT_FORMATS as T, isAutoAspectToken as U, type ValidationField as V, isModelMakerId as W, listModels as X, maskEditMatchesSource as Y, maskedEditResolution as Z, modelIdsByKindMode as _, IMAGE_OUTPUT_FORMAT_LABELS as a, modelTakesSeed as a0, modelsWithFeature as a1, nearestCatalogAspectRatio as a2, normalizeModelInput as a3, normalizeVideoRequestParams as a4, outputFormatOptionsByKind as a5, qualityOptionsByKind as a6, resolutionAtAspectRatio as a7, resolutionNearestSource as a8, resolutionOptionsByKind as a9, resolutionsAtAspectRatio as aa, sourceImageSizeNeeded as ab, svgLevelOptionsByKind as ac, validateModelInput as ad, IMAGE_SVG_LEVEL_LABELS as b, MODEL_CATALOG as c, MODEL_INPUT_ADJUSTMENT_FIELDS as d, MODEL_KINDS as e, MODEL_MAKERS as f, MODEL_RECOMMENDATIONS as g, type ModelCatalogEntry as h, type ModelInputAdjustment as i, type ModelInputAdjustmentField as j, type ModelInputContext as k, type ModelKind as l, type ModelMaker as m, type ModelMakerId as n, type ModelMenuOption as o, type ModelMode as p, type ModelRecommendation as q, type ModelValidationIssue as r, type NormalizedVideoRequest as s, type SourceImageSize as t, type TtsCapabilities as u, type TtsSettingLever as v, aspectRatioOptionsByKind as w, autoAspectNeedsSourceImage as x, backgroundOptionsByKind as y, buildModelMenu as z };
@@ -823,7 +823,12 @@ type VoiceDesignModel = typeof VOICE_DESIGN_MODELS[number];
823
823
  * (`backend/src/providers/elevenlabs/voice-design.ts`) can't drift.
824
824
  */
825
825
  declare const DEFAULT_VOICE_DESIGN_MODEL: VoiceDesignModel;
826
- /** I2I providers that support mask-based inpainting */
826
+ /**
827
+ * I2I providers that take an inpainting mask (`maskUrl`, white = the area to
828
+ * change, black = keep) as the model's own mask. The provider converts the
829
+ * mask into the form its model reads. Every catalog entry listing the
830
+ * `"mask"` feature (`/v1/models`, MCP `list_models`) is one of these.
831
+ */
827
832
  declare const I2I_MASK_SUPPORT: Set<string>;
828
833
  /**
829
834
  * Mask edit tier per image-gen provider (single source of truth for inpaint).
@@ -823,7 +823,12 @@ type VoiceDesignModel = typeof VOICE_DESIGN_MODELS[number];
823
823
  * (`backend/src/providers/elevenlabs/voice-design.ts`) can't drift.
824
824
  */
825
825
  declare const DEFAULT_VOICE_DESIGN_MODEL: VoiceDesignModel;
826
- /** I2I providers that support mask-based inpainting */
826
+ /**
827
+ * I2I providers that take an inpainting mask (`maskUrl`, white = the area to
828
+ * change, black = keep) as the model's own mask. The provider converts the
829
+ * mask into the form its model reads. Every catalog entry listing the
830
+ * `"mask"` feature (`/v1/models`, MCP `list_models`) is one of these.
831
+ */
827
832
  declare const I2I_MASK_SUPPORT: Set<string>;
828
833
  /**
829
834
  * Mask edit tier per image-gen provider (single source of truth for inpaint).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodaro/shared",
3
- "version": "3.60.1",
3
+ "version": "3.61.0",
4
4
  "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -208,6 +208,13 @@ describe("GPT Image 2.6: the images a run sends", () => {
208
208
  expect(gptImage26EstimatedImages(edit, { referenceImageUrl: A }, 0)).toBe(2)
209
209
  })
210
210
 
211
+ it("a mask is not an input image: neither a painted one nor a wired one is counted", () => {
212
+ const edit = "gpt-image-2-6-flare-i2i"
213
+ const wires = [{ target: "n", targetHandle: "image" }, { target: "n", targetHandle: "mask" }]
214
+ expect(countImageInputEdges(wires, "n")).toBe(0)
215
+ expect(gptImage26EstimatedImages(edit, { maskUrl: A }, countImageInputEdges(wires, "n"))).toBe(1)
216
+ })
217
+
211
218
  it("wires count reference images, identity nodes and every image wire after the source, for this node only", () => {
212
219
  const edges = [
213
220
  { target: "n", targetHandle: "references" },
@@ -1,6 +1,7 @@
1
1
  import { describe, it, expect } from "vitest"
2
- import { IMAGE_GEN_PROVIDERS } from "../model-constants.js"
2
+ import { I2I_MASK_SUPPORT, IMAGE_GEN_PROVIDERS, MODIFY_IMAGE_PROVIDERS } from "../model-constants.js"
3
3
  import { IMAGE_MASK_MODE } from "../model-constants.js"
4
+ import { MODEL_CATALOG } from "../model-catalog.js"
4
5
 
5
6
  describe("IMAGE_MASK_MODE", () => {
6
7
  it("has an entry for every image-gen provider (completeness invariant)", () => {
@@ -14,3 +15,35 @@ describe("IMAGE_MASK_MODE", () => {
14
15
  for (const v of values) expect(["prompt", "composite"]).toContain(v)
15
16
  })
16
17
  })
18
+
19
+ describe("I2I_MASK_SUPPORT (the image-to-image models that take a mask of their own)", () => {
20
+ it("lists GPT Image 2.6 Flare and Sunburst edits beside Ideogram Edit and FLUX Fill", () => {
21
+ expect([...I2I_MASK_SUPPORT].sort()).toEqual([
22
+ "flux-fill",
23
+ "gpt-image-2-6-flare-i2i",
24
+ "gpt-image-2-6-sunburst-i2i",
25
+ "ideogram-edit",
26
+ ])
27
+ })
28
+
29
+ it("leaves out the GPT Image edits that take no mask", () => {
30
+ for (const id of ["gpt-image-2-6-economy-i2i", "gpt-image-2-5-flare-i2i", "gpt-image-2-5-sunburst-i2i", "gpt-image-2-i2i"]) {
31
+ expect(I2I_MASK_SUPPORT.has(id)).toBe(false)
32
+ }
33
+ })
34
+
35
+ it("names only models /v1/image-to-image takes", () => {
36
+ expect([...I2I_MASK_SUPPORT].filter((id) => !(MODIFY_IMAGE_PROVIDERS as readonly string[]).includes(id))).toEqual([])
37
+ })
38
+
39
+ // One way only: FLUX Fill takes a mask but has no catalog entry.
40
+ it("holds every catalog entry that lists the mask feature", () => {
41
+ const listed = Object.values(MODEL_CATALOG).filter((m) => m.features?.includes("mask")).map((m) => m.id)
42
+ expect(listed.filter((id) => !I2I_MASK_SUPPORT.has(id))).toEqual([])
43
+ })
44
+
45
+ it("is listed with the mask feature by every catalog entry it names", () => {
46
+ const inCatalog = [...I2I_MASK_SUPPORT].filter((id) => MODEL_CATALOG[id] !== undefined)
47
+ expect(inCatalog.filter((id) => !MODEL_CATALOG[id]!.features?.includes("mask"))).toEqual([])
48
+ })
49
+ })
@@ -0,0 +1,150 @@
1
+ import { describe, expect, it } from "vitest"
2
+ import { MODEL_CATALOG, maskEditMatchesSource, normalizeModelInput, resolutionNearestSource, sourceImageSizeNeeded } from "../model-catalog.js"
3
+ import { resolveNormalizedImageGen } from "../credit-identifiers.js"
4
+ import { I2I_MASK_SUPPORT } from "../model-constants.js"
5
+ import { nodeIsMasked, wiredImageSize } from "../wired-image-size.js"
6
+
7
+ /**
8
+ * A masked GPT Image 2.6 edit follows its photo: the result is pasted back onto
9
+ * the photo at the photo's own size, so the run keeps the photo's shape and is
10
+ * rendered, and priced, at the size nearest the photo.
11
+ */
12
+ const FOLLOWING = ["gpt-image-2-6-flare-i2i", "gpt-image-2-6-sunburst-i2i"] as const
13
+ const PHOTO_1K_PORTRAIT = { width: 768, height: 1024 }
14
+ const PHOTO_4000_PORTRAIT = { width: 3000, height: 4000 }
15
+
16
+ describe("the catalog", () => {
17
+ it("only GPT Image 2.6 Flare's and Sunburst's edits follow their photo", () => {
18
+ const declared = Object.values(MODEL_CATALOG).filter((m) => m.maskEditMatchesSource).map((m) => m.id).sort()
19
+ expect(declared).toEqual([...FOLLOWING])
20
+ })
21
+
22
+ it("each such model takes a mask, and has a size for every ratio it lists at every size", () => {
23
+ for (const id of FOLLOWING) {
24
+ const m = MODEL_CATALOG[id]!
25
+ expect(I2I_MASK_SUPPORT.has(id)).toBe(true)
26
+ for (const ratio of m.aspectRatios!.filter((r) => r !== "auto")) {
27
+ for (const size of m.resolutions!) expect(m.outputSizes?.[ratio]?.[size], `${id} ${ratio} ${size}`).toBeDefined()
28
+ }
29
+ }
30
+ })
31
+
32
+ it("the table is the provider's: 1:1 at 4K is 2880 square, 9:16 at 4K 2160x3840", () => {
33
+ const sizes = MODEL_CATALOG["gpt-image-2-6-flare-i2i"]!.outputSizes!
34
+ expect(sizes["1:1"]!["4K"]).toEqual([2880, 2880])
35
+ expect(sizes["9:16"]!["4K"]).toEqual([2160, 3840])
36
+ expect(sizes["3:4"]!["1K"]).toEqual([768, 1024])
37
+ })
38
+ })
39
+
40
+ describe("maskEditMatchesSource / sourceImageSizeNeeded", () => {
41
+ it("is true only with a mask, on a model that follows its photo", () => {
42
+ expect(maskEditMatchesSource("gpt-image-2-6-flare-i2i", true)).toBe(true)
43
+ expect(maskEditMatchesSource("gpt-image-2-6-flare-i2i", false)).toBe(false)
44
+ expect(maskEditMatchesSource("ideogram-edit", true)).toBe(false)
45
+ expect(maskEditMatchesSource("gpt-image-2-6-economy-i2i", true)).toBe(false)
46
+ })
47
+
48
+ it("a masked 2.6 edit needs the photo's size even when it names a ratio", () => {
49
+ expect(sourceImageSizeNeeded("gpt-image-2-6-flare-i2i", "16:9", true)).toBe(true)
50
+ expect(sourceImageSizeNeeded("gpt-image-2-6-flare-i2i", "16:9", false)).toBe(false)
51
+ expect(sourceImageSizeNeeded("gpt-image-2-6-flare-i2i", "auto", false)).toBe(true)
52
+ })
53
+ })
54
+
55
+ describe("resolutionNearestSource", () => {
56
+ it("picks the size whose long side is nearest the photo's", () => {
57
+ expect(resolutionNearestSource("gpt-image-2-6-flare-i2i", "3:4", PHOTO_1K_PORTRAIT)).toBe("1K")
58
+ expect(resolutionNearestSource("gpt-image-2-6-flare-i2i", "3:4", PHOTO_4000_PORTRAIT)).toBe("4K")
59
+ expect(resolutionNearestSource("gpt-image-2-6-flare-i2i", "3:4", { width: 1536, height: 2048 })).toBe("2K")
60
+ // Nearest by ratio: 1500 px is nearer 2048 than 1024.
61
+ expect(resolutionNearestSource("gpt-image-2-6-flare-i2i", "1:1", { width: 1500, height: 1500 })).toBe("2K")
62
+ })
63
+
64
+ it("is undefined with no size, an unknown ratio or a model without a table", () => {
65
+ expect(resolutionNearestSource("gpt-image-2-6-flare-i2i", "3:4", undefined)).toBeUndefined()
66
+ expect(resolutionNearestSource("gpt-image-2-6-flare-i2i", "auto", PHOTO_1K_PORTRAIT)).toBeUndefined()
67
+ expect(resolutionNearestSource("gpt-image-2-6-flare-i2i", "constructor", PHOTO_1K_PORTRAIT)).toBeUndefined()
68
+ expect(resolutionNearestSource("gpt-image-2-i2i", "3:4", PHOTO_1K_PORTRAIT)).toBeUndefined()
69
+ })
70
+ })
71
+
72
+ describe("normalizeModelInput: a masked edit that follows its photo", () => {
73
+ for (const id of FOLLOWING) {
74
+ it(`${id}: a 1K photo with a 4K request runs, and is priced, at 1K`, () => {
75
+ const n = normalizeModelInput(id, { aspectRatio: "auto", resolution: "4K" }, { sourceImage: PHOTO_1K_PORTRAIT, masked: true })
76
+ expect(n.aspectRatio).toBe("3:4")
77
+ expect(n.resolution).toBe("1K")
78
+ expect(n.adjustments).toContainEqual(expect.objectContaining({ field: "resolution", from: "4K", to: "1K" }))
79
+ const priced = resolveNormalizedImageGen({ provider: id, aspectRatio: "auto", resolution: "4K", refCount: 1, sourceImage: PHOTO_1K_PORTRAIT, masked: true })
80
+ expect(priced.identifier).toBe(`${id}:medium:1K:1ref`)
81
+ expect(priced.resolution).toBe("1K")
82
+ })
83
+
84
+ it(`${id}: a 4000 px photo with a 1K request runs, and is priced, at 4K`, () => {
85
+ const priced = resolveNormalizedImageGen({ provider: id, aspectRatio: "auto", resolution: "1K", refCount: 1, sourceImage: PHOTO_4000_PORTRAIT, masked: true })
86
+ expect(priced.identifier).toBe(`${id}:medium:4K:1ref`)
87
+ expect(priced.adjustments).toContainEqual(expect.objectContaining({ field: "resolution", from: "1K", to: "4K" }))
88
+ })
89
+
90
+ it(`${id}: a named 16:9 on a 3:4 photo runs 3:4, and says so`, () => {
91
+ const n = normalizeModelInput(id, { aspectRatio: "16:9", resolution: "1K" }, { sourceImage: PHOTO_1K_PORTRAIT, masked: true })
92
+ expect(n.aspectRatio).toBe("3:4")
93
+ expect(n.adjustments).toContainEqual(expect.objectContaining({ field: "aspectRatio", from: "16:9", to: "3:4" }))
94
+ expect(n.adjustments.find((a) => a.field === "aspectRatio")!.reason).toContain("masked edit")
95
+ })
96
+
97
+ it(`${id}: no ratio named also keeps the photo's shape`, () => {
98
+ const n = normalizeModelInput(id, { resolution: "2K" }, { sourceImage: { width: 2048, height: 1536 }, masked: true })
99
+ expect(n.aspectRatio).toBe("4:3")
100
+ expect(n.resolution).toBe("2K")
101
+ expect(n.adjustments).toEqual([])
102
+ })
103
+
104
+ it(`${id}: with the photo's size unknown, the ratio is "auto" and the size asked is kept`, () => {
105
+ const n = normalizeModelInput(id, { aspectRatio: "16:9", resolution: "4K" }, { masked: true })
106
+ expect(n.aspectRatio).toBe("auto")
107
+ expect(n.resolution).toBe("4K")
108
+ expect(n.adjustments).toEqual([expect.objectContaining({ field: "aspectRatio", from: "16:9", to: "auto" })])
109
+ })
110
+
111
+ it(`${id}: without a mask, the ratio and the size asked are kept`, () => {
112
+ const n = normalizeModelInput(id, { aspectRatio: "16:9", resolution: "4K" }, { sourceImage: PHOTO_1K_PORTRAIT })
113
+ expect(n.aspectRatio).toBe("16:9")
114
+ expect(n.resolution).toBe("4K")
115
+ expect(n.adjustments).toEqual([])
116
+ })
117
+
118
+ it(`${id}: a transparent background still renders at 1K`, () => {
119
+ const n = normalizeModelInput(id, { aspectRatio: "auto", resolution: "1K", background: "transparent" }, { sourceImage: PHOTO_4000_PORTRAIT, masked: true })
120
+ expect(n.resolution).toBe("1K")
121
+ })
122
+ }
123
+
124
+ it("another mask model keeps the ratio and the size it names", () => {
125
+ const n = normalizeModelInput("gpt-image-2-6-economy-i2i", { aspectRatio: "16:9" }, { sourceImage: PHOTO_1K_PORTRAIT, masked: true })
126
+ expect(n.aspectRatio).toBe("16:9")
127
+ })
128
+ })
129
+
130
+ describe("wiredImageSize / nodeIsMasked (what an estimate knows of the photo)", () => {
131
+ const nodes = [
132
+ { id: "gen", data: { generatedResults: [{ width: 1024, height: 1024 }, { width: 768, height: 1024 }], activeResultIndex: 1 } },
133
+ { id: "up", data: { width: 4000, height: 3000 } },
134
+ { id: "none", data: {} },
135
+ { id: "n", data: {} },
136
+ ]
137
+ it("reads the shown result's size, else the node's own, from the node wired into `image`", () => {
138
+ expect(wiredImageSize("n", nodes, [{ source: "gen", target: "n", targetHandle: "image" }])).toEqual({ width: 768, height: 1024 })
139
+ expect(wiredImageSize("n", nodes, [{ source: "up", target: "n", targetHandle: "image" }])).toEqual({ width: 4000, height: 3000 })
140
+ expect(wiredImageSize("n", nodes, [{ source: "none", target: "n", targetHandle: "image" }])).toBeUndefined()
141
+ // A mask or another input is not the photo.
142
+ expect(wiredImageSize("n", nodes, [{ source: "up", target: "n", targetHandle: "mask" }])).toBeUndefined()
143
+ })
144
+
145
+ it("a node is masked by its own maskUrl or a wire into `mask`", () => {
146
+ expect(nodeIsMasked("n", { maskUrl: "https://m.png" }, [])).toBe(true)
147
+ expect(nodeIsMasked("n", {}, [{ source: "gm", target: "n", targetHandle: "mask" }])).toBe(true)
148
+ expect(nodeIsMasked("n", {}, [{ source: "x", target: "n", targetHandle: "image" }])).toBe(false)
149
+ })
150
+ })
@@ -289,10 +289,12 @@ export function imageFormatInputOf(source: object): { outputFormat?: string; gif
289
289
  *
290
290
  * `sourceImage` is the size of the photo the request transforms or is drawn
291
291
  * from (an image-to-image / edit source, or Generate Image's first wired
292
- * reference). It only decides "auto" on a model without a native auto, and the
292
+ * reference). It decides "auto" on a model without a native auto, and the
293
293
  * ratio is not a pricing dimension on any such model (pinned across the catalog
294
- * by `auto-aspect-source.test.ts`), so a CHECK that runs before the size is
295
- * known prices the same identifier as the DEBIT that knows it.
294
+ * by `auto-aspect-source.test.ts`). With `masked` on a model whose masked edit
295
+ * follows its photo (`maskEditMatchesSource`) it also decides the SIZE, a
296
+ * pricing dimension: the CHECK and the DEBIT must then both be given it (the
297
+ * image-to-image route reads it once, before its credit check).
296
298
  */
297
299
  export function resolveNormalizedImageGen(opts: {
298
300
  provider: string | undefined
@@ -310,6 +312,8 @@ export function resolveNormalizedImageGen(opts: {
310
312
  refCount: number
311
313
  swapToI2i?: boolean
312
314
  sourceImage?: SourceImageSize
315
+ /** The request carries an inpainting mask: on a model whose masked edit follows its photo, the photo's size decides the ratio and the priced size. */
316
+ masked?: boolean
313
317
  }): NormalizedImageGen {
314
318
  const str = (v: unknown): string | undefined =>
315
319
  typeof v === "string" && v.length > 0 ? v : undefined
@@ -325,7 +329,7 @@ export function resolveNormalizedImageGen(opts: {
325
329
  background: str(opts.background),
326
330
  ...imageFormatInputOf(opts),
327
331
  },
328
- { sourceImage: opts.sourceImage },
332
+ { sourceImage: opts.sourceImage, masked: opts.masked },
329
333
  )
330
334
 
331
335
  return {
@@ -78,6 +78,10 @@ export {
78
78
  defaultResolutionFor,
79
79
  nearestCatalogAspectRatio,
80
80
  autoAspectNeedsSourceImage,
81
+ maskEditMatchesSource,
82
+ sourceImageSizeNeeded,
83
+ resolutionNearestSource,
84
+ maskedEditResolution,
81
85
  isAutoAspectToken,
82
86
  resolutionsAtAspectRatio,
83
87
  resolutionAtAspectRatio,
@@ -145,6 +145,7 @@ export { resolveFieldMappings, resolveLocationFields, type FieldEdgeSource } fro
145
145
  export { resolveNodeRefs, parseNodeRef, canonicalVarName, NODE_REF_PATTERN, RESERVED_TEMPLATE_VARS, extractReferencedLabels, combineSameLabelRefs, refHandleCategory, REF_HANDLE_CATEGORY, REFERENCE_HANDLE_MAP, referenceModalityForHandle, FRAME_TARGET_HANDLES, countImageInputEdges, countRefModalityEdges, REF_TOKEN_NAMESPACE_PREFIXES, classifyRefToken, unresolvedRefTokens } from "../node-refs.js"
146
146
  export type { RefCandidate, ReferenceModality, RefModalityEdge, RefTokenKind } from "../node-refs.js"
147
147
  export { resolveSourceThroughConnectedList } from "../list-source-resolver.js"
148
+ export { wiredImageSize, recordedImageSize, nodeIsMasked, type SizedGraphNode, type SizedGraphEdge } from "../wired-image-size.js"
148
149
  export { zipMergeLists } from "../list-merge.js"
149
150
  export type {
150
151
  WorkflowExport,
@@ -327,6 +327,21 @@ export interface ModelCatalogEntry {
327
327
  * as before. "auto" stays in `aspectRatios`, so every menu still offers it.
328
328
  */
329
329
  autoAspectFromSourceImage?: true
330
+ /**
331
+ * The pixel size (width, height) this model renders at each aspect ratio and
332
+ * size, from the provider's own table, for a PNG, JPEG or WebP. Read where a
333
+ * run's size is chosen from its photo's size (`maskEditMatchesSource`).
334
+ */
335
+ outputSizes?: Readonly<Record<string, Readonly<Record<string, readonly [number, number]>>>>
336
+ /**
337
+ * A masked edit on this model follows its photo: the result is pasted back
338
+ * onto the photo at the photo's own size, so the run keeps the photo's shape
339
+ * ("auto", whatever ratio it names) and renders at the size of `outputSizes`
340
+ * whose long side is nearest the photo's, priced at that size
341
+ * (`normalizeModelInput` with `context.masked`; `resolutionNearestSource`).
342
+ * With the photo's size unknown, the size asked is kept.
343
+ */
344
+ maskEditMatchesSource?: true
330
345
  resolutions?: readonly string[]
331
346
  /**
332
347
  * The aspect ratios at which this model renders fewer sizes than
@@ -550,6 +565,26 @@ const GPT_IMAGE_2_6_RATIOS = [
550
565
  "2:1", "1:2", "21:9", "9:21", "3:1", "1:3",
551
566
  ] as const
552
567
  const GPT_IMAGE_2_6_ECONOMY_RATIOS = ["auto", "1:1", "16:9", "9:16", "3:2", "2:3", "21:9", "4:3"] as const
568
+ // What GPT Image 2.6 Flare and Sunburst render at each ratio and size, for a
569
+ // PNG, JPEG or WebP (the `resolution` table of docs.kie.ai/market/gpt/
570
+ // gpt-image-2-6-{flare,sunburst}-image-to-image, fetched 2026-11-11).
571
+ const GPT_IMAGE_2_6_OUTPUT_SIZES = {
572
+ "1:1": { "1K": [1024, 1024], "2K": [2048, 2048], "4K": [2880, 2880] },
573
+ "3:2": { "1K": [1536, 1024], "2K": [2048, 1360], "4K": [3520, 2336] },
574
+ "2:3": { "1K": [1024, 1536], "2K": [1360, 2048], "4K": [2336, 3520] },
575
+ "4:3": { "1K": [1024, 768], "2K": [2048, 1536], "4K": [3312, 2480] },
576
+ "3:4": { "1K": [768, 1024], "2K": [1536, 2048], "4K": [2480, 3312] },
577
+ "5:4": { "1K": [1280, 1024], "2K": [2560, 2048], "4K": [3216, 2576] },
578
+ "4:5": { "1K": [1024, 1280], "2K": [2048, 2560], "4K": [2576, 3216] },
579
+ "16:9": { "1K": [1536, 864], "2K": [2048, 1152], "4K": [3840, 2160] },
580
+ "9:16": { "1K": [864, 1536], "2K": [1152, 2048], "4K": [2160, 3840] },
581
+ "2:1": { "1K": [2048, 1024], "2K": [2688, 1344], "4K": [3840, 1920] },
582
+ "1:2": { "1K": [1024, 2048], "2K": [1344, 2688], "4K": [1920, 3840] },
583
+ "21:9": { "1K": [2016, 864], "2K": [2688, 1152], "4K": [3840, 1648] },
584
+ "9:21": { "1K": [864, 2016], "2K": [1152, 2688], "4K": [1648, 3840] },
585
+ "3:1": { "1K": [1536, 512], "2K": [3072, 1024], "4K": [3840, 1280] },
586
+ "1:3": { "1K": [512, 1536], "2K": [1024, 3072], "4K": [1280, 3840] },
587
+ } as const satisfies Record<string, Record<string, readonly [number, number]>>
553
588
  const GPT_IMAGE_2_6_VALUE_LABELS = {
554
589
  "3:2": "3:2 (Landscape)", "2:3": "2:3 (Portrait)",
555
590
  "5:4": "5:4 (Near-square)", "4:5": "4:5 (Near-square)",
@@ -1175,11 +1210,13 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
1175
1210
  maker: "openai",
1176
1211
  label: "GPT Image 2.6 Flare (I2I)",
1177
1212
  series: "GPT Image",
1178
- description: "Fast GPT Image 2.6 edits - up to 16 input images, priced per image. Writes PNG, JPEG, WebP, an animated GIF or an SVG. Pick it while iterating.",
1179
- useCases: ["edit", "high-res"],
1180
- features: ["reference-image"],
1213
+ description: "Fast GPT Image 2.6 edits - up to 16 input images, priced per image. Writes PNG, JPEG, WebP, an animated GIF or an SVG. Takes an inpainting mask (PNG, JPEG or WebP; the rest of the picture is kept as it was). Pick it while iterating.",
1214
+ useCases: ["edit", "inpaint", "high-res"],
1215
+ features: ["reference-image", "mask"],
1181
1216
  aspectRatios: GPT_IMAGE_2_6_RATIOS,
1182
1217
  autoAspectFromSourceImage: true,
1218
+ outputSizes: GPT_IMAGE_2_6_OUTPUT_SIZES,
1219
+ maskEditMatchesSource: true,
1183
1220
  resolutions: ["1K", "2K", "4K"],
1184
1221
  qualities: ["auto", "low", "medium", "high", "xhigh", "max"],
1185
1222
  defaultQuality: "medium",
@@ -1283,11 +1320,13 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
1283
1320
  maker: "openai",
1284
1321
  label: "GPT Image 2.6 Sunburst (I2I)",
1285
1322
  series: "GPT Image",
1286
- description: "Precision GPT Image 2.6 edits - up to 16 input images, priced per image. Writes PNG, JPEG, WebP, an animated GIF or an SVG. Pick it for finished, detail-critical edits.",
1287
- useCases: ["edit", "high-res"],
1288
- features: ["reference-image"],
1323
+ description: "Precision GPT Image 2.6 edits - up to 16 input images, priced per image. Writes PNG, JPEG, WebP, an animated GIF or an SVG. Takes an inpainting mask (PNG, JPEG or WebP; the rest of the picture is kept as it was). Pick it for finished, detail-critical edits.",
1324
+ useCases: ["edit", "inpaint", "high-res"],
1325
+ features: ["reference-image", "mask"],
1289
1326
  aspectRatios: GPT_IMAGE_2_6_RATIOS,
1290
1327
  autoAspectFromSourceImage: true,
1328
+ outputSizes: GPT_IMAGE_2_6_OUTPUT_SIZES,
1329
+ maskEditMatchesSource: true,
1291
1330
  resolutions: ["1K", "2K", "4K"],
1292
1331
  qualities: ["auto", "low", "medium", "high", "xhigh", "max"],
1293
1332
  defaultQuality: "medium",
@@ -4183,8 +4222,80 @@ export interface ModelInputContext {
4183
4222
  * resolve "auto" on a model without a native auto, or whose own auto does
4184
4223
  * not keep the photo's shape (`autoAspectFromSourceImage`); absent or
4185
4224
  * unusable means the size is unknown and "auto" snaps the way it always has.
4225
+ * Also read by a masked edit on a model whose result follows its photo
4226
+ * (`maskEditMatchesSource`): it decides the ratio and the size.
4186
4227
  */
4187
4228
  sourceImage?: SourceImageSize
4229
+ /** The request carries an inpainting mask (`maskUrl`). */
4230
+ masked?: boolean
4231
+ }
4232
+
4233
+ /**
4234
+ * True when a masked request on `modelId` follows its photo
4235
+ * (`maskEditMatchesSource`): its ratio and size come from the photo's size.
4236
+ */
4237
+ export function maskEditMatchesSource(modelId: string | undefined, masked: unknown): boolean {
4238
+ return masked === true && !!modelId && MODEL_CATALOG[modelId]?.maskEditMatchesSource === true
4239
+ }
4240
+
4241
+ /**
4242
+ * True when the photo's size can change what a request on `modelId` sends:
4243
+ * "auto" that keeps the photo's shape (`autoAspectNeedsSourceImage`), or a
4244
+ * masked edit that follows its photo (`maskEditMatchesSource`). A caller that
4245
+ * has to fetch the size asks this first.
4246
+ */
4247
+ export function sourceImageSizeNeeded(modelId: string | undefined, aspectRatio: unknown, masked: unknown): boolean {
4248
+ return autoAspectNeedsSourceImage(modelId, aspectRatio) || maskEditMatchesSource(modelId, masked)
4249
+ }
4250
+
4251
+ /**
4252
+ * The size a MASKED request on `modelId` runs, and is priced, at once its
4253
+ * photo's size is known — what `normalizeModelInput` sends for it. For an
4254
+ * estimate that knows the photo's size (the editor's badge, a workflow
4255
+ * estimate). `undefined` when the model does not follow its photo
4256
+ * (`maskEditMatchesSource`) or the size is unusable: the caller keeps its own.
4257
+ */
4258
+ export function maskedEditResolution(
4259
+ modelId: string,
4260
+ levers: { aspectRatio?: unknown; resolution?: unknown; background?: unknown; outputFormat?: unknown },
4261
+ sourceImage: SourceImageSize | undefined,
4262
+ ): string | undefined {
4263
+ if (!maskEditMatchesSource(modelId, true) || !usableSize(sourceImage)) return undefined
4264
+ const str = (v: unknown): string | undefined => (typeof v === "string" && v.length > 0 ? v : undefined)
4265
+ return normalizeModelInput(
4266
+ modelId,
4267
+ { aspectRatio: str(levers.aspectRatio), resolution: str(levers.resolution), background: str(levers.background), outputFormat: str(levers.outputFormat) },
4268
+ { sourceImage, masked: true },
4269
+ ).resolution
4270
+ }
4271
+
4272
+ /**
4273
+ * The size of `modelId` whose rendered long side, at `aspectRatio`, is nearest
4274
+ * the photo's long side (`outputSizes`; nearest by ratio, so 1500 px is nearer
4275
+ * 2048 than 1024; a tie goes to the larger size). `undefined` when the model
4276
+ * has no size table for that ratio or the photo's size is unusable.
4277
+ */
4278
+ export function resolutionNearestSource(
4279
+ modelId: string,
4280
+ aspectRatio: unknown,
4281
+ source: SourceImageSize | undefined,
4282
+ ): string | undefined {
4283
+ const m = MODEL_CATALOG[modelId]
4284
+ const table = m?.outputSizes
4285
+ if (!table || typeof aspectRatio !== "string" || !usableSize(source)) return undefined
4286
+ // Own keys only: a ratio such as "constructor" must not read the prototype.
4287
+ if (!Object.prototype.hasOwnProperty.call(table, aspectRatio)) return undefined
4288
+ const sizes = table[aspectRatio]!
4289
+ const long = Math.max(source.width, source.height)
4290
+ let best: string | undefined
4291
+ let bestDist = Infinity
4292
+ for (const resolution of m.resolutions ?? Object.keys(sizes)) {
4293
+ const px = Object.prototype.hasOwnProperty.call(sizes, resolution) ? sizes[resolution] : undefined
4294
+ if (!px) continue
4295
+ const dist = Math.abs(Math.log(Math.max(px[0], px[1]) / long))
4296
+ if (dist <= bestDist + ASPECT_TIE_EPSILON) { bestDist = dist; best = resolution }
4297
+ }
4298
+ return best
4188
4299
  }
4189
4300
 
4190
4301
  /** True for the "auto" aspect token in any case or padding. */
@@ -4392,12 +4503,31 @@ export function normalizeModelInput(
4392
4503
  out.gifFrameDurationMs = format.levers.gifFrameDurationMs
4393
4504
  out.svgLevel = format.levers.svgLevel
4394
4505
  const gif = format.levers.outputFormat === "gif"
4506
+ // A masked edit that follows its photo runs at "auto" whatever ratio it
4507
+ // names, and at the size nearest the photo (`maskEditMatchesSource`).
4508
+ const followsSource = !gif && maskEditMatchesSource(modelId, context.masked)
4509
+ const askedRatio = followsSource ? "auto" : input.aspectRatio
4395
4510
 
4396
4511
  const sourceRatio =
4397
- !gif && autoAspectNeedsSourceImage(modelId, input.aspectRatio) && usableSize(context.sourceImage)
4512
+ !gif && autoAspectNeedsSourceImage(modelId, askedRatio) && usableSize(context.sourceImage)
4398
4513
  ? nearestCatalogAspectRatio(context.sourceImage.width, context.sourceImage.height, m.aspectRatios ?? [])
4399
4514
  : undefined
4400
- if (gif) {
4515
+ if (followsSource && input.aspectRatio !== undefined && !isAutoAspectToken(input.aspectRatio)) {
4516
+ const to = sourceRatio ?? "auto"
4517
+ if (to !== input.aspectRatio) {
4518
+ adjustments.push({
4519
+ field: "aspectRatio",
4520
+ from: input.aspectRatio,
4521
+ to,
4522
+ reason: sourceRatio !== undefined
4523
+ ? `A masked edit on ${m.label} keeps the photo's shape — using "${sourceRatio}", the supported ratio closest to the source image (${context.sourceImage!.width}x${context.sourceImage!.height}).`
4524
+ : `A masked edit on ${m.label} keeps the photo's shape — using "auto".`,
4525
+ })
4526
+ }
4527
+ out.aspectRatio = to
4528
+ } else if (followsSource && input.aspectRatio === undefined) {
4529
+ out.aspectRatio = sourceRatio ?? "auto"
4530
+ } else if (gif) {
4401
4531
  // A GIF is square, IMAGE_GIF_FRAME_SIZE a frame: neither lever applies.
4402
4532
  // "auto" leaves the shape to the model, and square is its answer.
4403
4533
  if (input.aspectRatio !== undefined && input.aspectRatio !== "1:1" && !isAutoAspectToken(input.aspectRatio)) {
@@ -4409,14 +4539,14 @@ export function normalizeModelInput(
4409
4539
  })
4410
4540
  }
4411
4541
  out.aspectRatio = input.aspectRatio === undefined ? undefined : "1:1"
4412
- } else if (sourceRatio !== undefined && input.aspectRatio !== undefined) {
4542
+ } else if (sourceRatio !== undefined && askedRatio !== undefined) {
4413
4543
  const { width, height } = context.sourceImage!
4414
4544
  const why = m.autoAspectFromSourceImage === true
4415
4545
  ? `${m.label}'s own "auto" does not keep the photo's shape`
4416
4546
  : `${m.label} has no "auto" aspect ratio`
4417
4547
  adjustments.push({
4418
4548
  field: "aspectRatio",
4419
- from: input.aspectRatio,
4549
+ from: input.aspectRatio ?? askedRatio,
4420
4550
  to: sourceRatio,
4421
4551
  reason: `${why} — using "${sourceRatio}", the supported ratio closest to the source image's shape (${width}x${height}).`,
4422
4552
  })
@@ -4424,7 +4554,23 @@ export function normalizeModelInput(
4424
4554
  } else {
4425
4555
  out.aspectRatio = snap("aspectRatio", input.aspectRatio, m.aspectRatios)
4426
4556
  }
4427
- if (gif) {
4557
+ if (followsSource) {
4558
+ // The size whose long side is nearest the photo's: the result is the
4559
+ // photo's own size, so the run is rendered, and priced, near it.
4560
+ const asked = snap("resolution", input.resolution, m.resolutions, defaultResolutionFor(modelId))
4561
+ const nearest = resolutionNearestSource(modelId, out.aspectRatio, context.sourceImage)
4562
+ const from = asked ?? m.defaultResolution ?? m.resolutions?.[0]
4563
+ if (nearest !== undefined && from !== undefined && nearest !== from) {
4564
+ const { width, height } = context.sourceImage!
4565
+ adjustments.push({
4566
+ field: "resolution",
4567
+ from,
4568
+ to: nearest,
4569
+ reason: `A masked edit on ${m.label} is delivered at the photo's own size (${width}x${height}) — rendering at ${nearest}, the size nearest it.`,
4570
+ })
4571
+ }
4572
+ out.resolution = nearest ?? asked
4573
+ } else if (gif) {
4428
4574
  if (input.resolution !== undefined) {
4429
4575
  adjustments.push({
4430
4576
  field: "resolution",
@@ -1820,8 +1820,18 @@ export type VoiceDesignModel = typeof VOICE_DESIGN_MODELS[number]
1820
1820
  */
1821
1821
  export const DEFAULT_VOICE_DESIGN_MODEL: VoiceDesignModel = "eleven_ttv_v3"
1822
1822
 
1823
- /** I2I providers that support mask-based inpainting */
1824
- export const I2I_MASK_SUPPORT = new Set(["ideogram-edit", "flux-fill"])
1823
+ /**
1824
+ * I2I providers that take an inpainting mask (`maskUrl`, white = the area to
1825
+ * change, black = keep) as the model's own mask. The provider converts the
1826
+ * mask into the form its model reads. Every catalog entry listing the
1827
+ * `"mask"` feature (`/v1/models`, MCP `list_models`) is one of these.
1828
+ */
1829
+ export const I2I_MASK_SUPPORT = new Set([
1830
+ "ideogram-edit",
1831
+ "flux-fill",
1832
+ "gpt-image-2-6-flare-i2i",
1833
+ "gpt-image-2-6-sunburst-i2i",
1834
+ ])
1825
1835
 
1826
1836
  /**
1827
1837
  * Mask edit tier per image-gen provider (single source of truth for inpaint).