@nodaro/shared 3.6.0 → 3.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/normalize-model-input.test.ts

@@ -76,6 +76,38 @@ describe("normalizeModelInput", () => {
     expect(normalizeModelInput("gpt-image-2", { aspectRatio: "1:1", resolution: "4K" }).resolution).toBe("2K")
   })
 
+  // GPT Image 2.5 is NOT GPT Image 2. Its KIE docs
+  // (docs.kie.ai/market/gpt/gpt-image-2-5-*) state no aspect_ratio x resolution
+  // restriction, so the cross-field block above must NOT be widened to these
+  // ids "for consistency" — doing so would silently downgrade a paid 4K render
+  // to 1K. If GPT Image 2.5 ever documents such a limit, add it deliberately
+  // and change this test in the same commit.
+  it.each([
+    "gpt-image-2-5-flare",
+    "gpt-image-2-5-flare-i2i",
+    "gpt-image-2-5-sunburst",
+    "gpt-image-2-5-sunburst-i2i",
+  ])("%s has NO cross-field aspect-ratio x resolution rule", (modelId) => {
+    const auto4k = normalizeModelInput(modelId, { aspectRatio: "auto", resolution: "4K" })
+    expect(auto4k.resolution).toBe("4K")
+    expect(auto4k.adjustments).toEqual([])
+
+    const square4k = normalizeModelInput(modelId, { aspectRatio: "1:1", resolution: "4K" })
+    expect(square4k.resolution).toBe("4K")
+    expect(square4k.adjustments).toEqual([])
+  })
+
+  // The four ratios 2.5 introduced are new to the platform vocabulary; the snap
+  // must accept them rather than rewrite them to a neighbour.
+  it.each(["27:16", "16:27", "9:8", "8:9", "21:9", "3:2"])(
+    "gpt-image-2.5 keeps the newly-added ratio %s",
+    (ratio) => {
+      const out = normalizeModelInput("gpt-image-2-5-flare", { aspectRatio: ratio })
+      expect(out.aspectRatio).toBe(ratio)
+      expect(out.adjustments).toEqual([])
+    },
+  )
+
   it("passes unknown model ids through untouched (the Zod enum owns those)", () => {
     const out = normalizeModelInput("totally-fake-model", { aspectRatio: "21:9" })
     expect(out.aspectRatio).toBe("21:9")

package/src/__tests__/scene3d-render-pricing.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect } from "vitest"
+import {
+  PRO3D_RENDER_QUALITY_PROFILES,
+  RENDER_VIDEO_CREDIT_ID,
+  SCENE3D_LIMITS,
+  SCENE3D_RENDER_BASE_MAX_PX,
+  SCENE3D_RENDER_TIERS,
+  SCENE3D_RENDER_TIER_MULTIPLIERS,
+  SCENE3D_RENDER_XLARGE_MIN_AREA_PX,
+  pro3DRenderFrameUnit,
+  renderVideoCreditId,
+  scene3DRenderTier,
+  scene3DRenderTierCredits,
+} from "../index.js"
+
+/** The three reference frames the tiers are anchored to (PR #1328). */
+const REFERENCE_FRAMES = {
+  base: { width: 1920, height: 1080 },
+  large: { width: 2560, height: 1440 },
+  xlarge: { width: 2560, height: 2560 },
+} as const
+
+describe("scene3DRenderTier", () => {
+  it("places each reference frame in its own tier", () => {
+    for (const [tier, frame] of Object.entries(REFERENCE_FRAMES)) {
+      expect(scene3DRenderTier(frame.width, frame.height)).toBe(tier)
+    }
+  })
+
+  it("holds every pre-cap frame at the base price, square ones included", () => {
+    // The promise of the 1920 gate: raising maxDimensionPx never reprices a
+    // frame that was already renderable. 1920x1920 has the SAME pixel count as
+    // 2560x1440 and is still base — area only decides ABOVE the gate.
+    expect(scene3DRenderTier(1920, 1080)).toBe("base")
+    expect(scene3DRenderTier(1080, 1920)).toBe("base")
+    expect(scene3DRenderTier(1920, 1920)).toBe("base")
+    expect(scene3DRenderTier(1680, 720)).toBe("base")
+    expect(SCENE3D_RENDER_BASE_MAX_PX).toBe(1920)
+  })
+
+  it("tiers every aspect the 2560 cap makes reachable", () => {
+    expect(scene3DRenderTier(2560, 1440)).toBe("large") // 16:9
+    expect(scene3DRenderTier(1440, 2560)).toBe("large") // 9:16
+    expect(scene3DRenderTier(2560, 1097)).toBe("large") // 21:9
+    expect(scene3DRenderTier(2048, 2560)).toBe("xlarge") // 4:5
+    expect(scene3DRenderTier(2560, 2560)).toBe("xlarge") // 1:1
+  })
+
+  it("splits large from xlarge at the midpoint of the two upper reference frames", () => {
+    const midpoint = (REFERENCE_FRAMES.large.width * REFERENCE_FRAMES.large.height + REFERENCE_FRAMES.xlarge.width * REFERENCE_FRAMES.xlarge.height) / 2
+    expect(SCENE3D_RENDER_XLARGE_MIN_AREA_PX).toBe(midpoint)
+    // One pixel either side of the boundary, at a width past the gate.
+    expect(scene3DRenderTier(2560, 2000)).toBe("large") // 5,120,000 exactly
+    expect(scene3DRenderTier(2560, 2001)).toBe("xlarge") // 5,122,560
+  })
+
+  it("is base for anything that is not a pair of positive finite numbers", () => {
+    expect(scene3DRenderTier(undefined, undefined)).toBe("base")
+    expect(scene3DRenderTier("2560", "2560")).toBe("base")
+    expect(scene3DRenderTier(Number.NaN, 2560)).toBe("base")
+    expect(scene3DRenderTier(Infinity, 2560)).toBe("base")
+    expect(scene3DRenderTier(0, 2560)).toBe("base")
+    expect(scene3DRenderTier(-2560, -2560)).toBe("base")
+  })
+
+  it("covers the whole admissible range with a declared tier", () => {
+    const max = SCENE3D_LIMITS.maxDimensionPx
+    for (const w of [SCENE3D_LIMITS.minDimensionPx, 640, 1920, 1921, 2048, max]) {
+      for (const h of [SCENE3D_LIMITS.minDimensionPx, 640, 1920, 1921, 2048, max]) {
+        expect(SCENE3D_RENDER_TIERS).toContain(scene3DRenderTier(w, h))
+      }
+    }
+  })
+})
+
+describe("scene3DRenderTierCredits", () => {
+  it("is the declared ratio, rounded up", () => {
+    // The worked examples the public docs print, from the built-in base of 50.
+    expect(scene3DRenderTierCredits(50, "base")).toBe(50)
+    expect(scene3DRenderTierCredits(50, "large")).toBe(75)
+    expect(scene3DRenderTierCredits(50, "xlarge")).toBe(125)
+  })
+
+  it("never rounds a tier down below the base render it multiplies", () => {
+    for (const base of [1, 3, 7, 15, 33, 50, 137]) {
+      for (const tier of SCENE3D_RENDER_TIERS) {
+        expect(scene3DRenderTierCredits(base, tier)).toBeGreaterThanOrEqual(base)
+        expect(scene3DRenderTierCredits(base, tier)).toBe(
+          Math.ceil(base * SCENE3D_RENDER_TIER_MULTIPLIERS[tier]),
+        )
+      }
+    }
+  })
+
+  it("keeps the ladder monotonic", () => {
+    expect(SCENE3D_RENDER_TIER_MULTIPLIERS.base).toBe(1)
+    expect(SCENE3D_RENDER_TIER_MULTIPLIERS.large).toBeGreaterThan(SCENE3D_RENDER_TIER_MULTIPLIERS.base)
+    expect(SCENE3D_RENDER_TIER_MULTIPLIERS.xlarge).toBeGreaterThan(SCENE3D_RENDER_TIER_MULTIPLIERS.large)
+  })
+})
+
+describe("renderVideoCreditId", () => {
+  it("keeps the bare identifier for a base-sized 3D scene plan", () => {
+    expect(renderVideoCreditId({ planType: "3d-scene", plan: { width: 1920, height: 1080 } })).toBe(
+      RENDER_VIDEO_CREDIT_ID,
+    )
+  })
+
+  it("names the tier for a plan past the 1920 gate", () => {
+    expect(renderVideoCreditId({ planType: "3d-scene", plan: { width: 2560, height: 1440 } })).toBe(
+      "render-video:3d-large",
+    )
+    expect(renderVideoCreditId({ planType: "3d-scene", plan: { width: 2560, height: 2560 } })).toBe(
+      "render-video:3d-xlarge",
+    )
+  })
+
+  it("leaves every non-3D render on the flat identifier", () => {
+    // scene-graph admits frames up to 3840 today at the flat price; tiering it
+    // would raise the price of work people already run.
+    expect(renderVideoCreditId({ planType: "scene-graph", plan: { width: 3840, height: 2160 } })).toBe(
+      RENDER_VIDEO_CREDIT_ID,
+    )
+    expect(renderVideoCreditId({ planType: "lottie-graphic", plan: { width: 2560, height: 2560 } })).toBe(
+      RENDER_VIDEO_CREDIT_ID,
+    )
+    expect(renderVideoCreditId({ template: "slideshow", aspectRatio: "16:9" })).toBe(RENDER_VIDEO_CREDIT_ID)
+  })
+
+  it("answers the flat identifier for anything unparseable", () => {
+    expect(renderVideoCreditId(undefined)).toBe(RENDER_VIDEO_CREDIT_ID)
+    expect(renderVideoCreditId(null)).toBe(RENDER_VIDEO_CREDIT_ID)
+    expect(renderVideoCreditId("3d-scene")).toBe(RENDER_VIDEO_CREDIT_ID)
+    expect(renderVideoCreditId({ planType: "3d-scene" })).toBe(RENDER_VIDEO_CREDIT_ID)
+    expect(renderVideoCreditId({ planType: "3d-scene", plan: "{}" })).toBe(RENDER_VIDEO_CREDIT_ID)
+    expect(renderVideoCreditId({ planType: "3d-scene", plan: {} })).toBe(RENDER_VIDEO_CREDIT_ID)
+  })
+})
+
+describe("pro3DRenderFrameUnit", () => {
+  it("keeps the configured spelling for base-sized frames", () => {
+    for (const quality of PRO3D_RENDER_QUALITY_PROFILES) {
+      expect(pro3DRenderFrameUnit(quality)).toBe(`pro-3d-render:render-frame:${quality}`)
+      expect(pro3DRenderFrameUnit(quality, "base")).toBe(`pro-3d-render:render-frame:${quality}`)
+    }
+  })
+
+  it("suffixes the tier for a frame past the gate", () => {
+    expect(pro3DRenderFrameUnit("standard", "large")).toBe("pro-3d-render:render-frame:standard:large")
+    expect(pro3DRenderFrameUnit("standard", "xlarge")).toBe("pro-3d-render:render-frame:standard:xlarge")
+  })
+
+  it("produces one distinct unit per tier", () => {
+    const units = new Set(SCENE3D_RENDER_TIERS.map((tier) => pro3DRenderFrameUnit("standard", tier)))
+    expect(units.size).toBe(SCENE3D_RENDER_TIERS.length)
+  })
+})

package/src/__tests__/scene3d-v2.test.ts

@@ -108,7 +108,10 @@ describe("scene3d v2 — v1 is untouched", () => {
     expect(SCENE3D_LIMITS.maxObjects).toBe(100)
     expect(SCENE3D_LIMITS.maxKeyframes).toBe(240)
     expect(SCENE3D_LIMITS.maxHierarchyDepth).toBe(8)
-    expect(SCENE3D_LIMITS.maxDimensionPx).toBe(1920)
+    // Widened from 1920 deliberately (measured, both versions together) —
+    // every other v1 bound above is still frozen.
+    expect(SCENE3D_LIMITS.maxDimensionPx).toBe(2560)
+    expect(SCENE3D_V2_LIMITS.maxDimensionPx).toBe(SCENE3D_LIMITS.maxDimensionPx)
     expect(SCENE3D_LIMITS.maxReferences).toBe(8)
   })
 

package/src/image-overlay-layers.ts

@@ -16,6 +16,16 @@
  */
 import { z } from "zod"
 
+/** The nine points a layer attaches to on the base image. THE definition —
+ *  the route's Zod, the compositor, the canvas, the SDK and the CLI all read
+ *  this one (it used to be spelled out separately in each). */
+export const OVERLAY_ANCHORS = [
+  "top-left", "top", "top-right",
+  "left", "center", "right",
+  "bottom-left", "bottom", "bottom-right",
+] as const
+export type OverlayAnchor = (typeof OVERLAY_ANCHORS)[number]
+
 export const OVERLAY_LAYER_KINDS = ["image", "text", "qr", "shape"] as const
 export type OverlayLayerKind = (typeof OVERLAY_LAYER_KINDS)[number]
 

package/src/index.ts

@@ -1066,6 +1066,9 @@ export * from "./scene3d-v2-resources.js"
 export * from "./scene3d-camera-track.js"
 // --- 3D Render Pro: one durable operation, scene + video in one result ---
 export * from "./pro-3d-render.js"
+// --- Scene3D render pricing: which frame-size tier a render settles at.
+//     The SHAPE of the price (tier, multiplier, identifier); never a rate. ---
+export * from "./scene3d-render-pricing.js"
 
 // --- transient studio keys — the public share read strips them ---
 export {

package/src/model-catalog.ts

@@ -233,6 +233,15 @@ const KONTEXT_RATIOS = ["1:1", "16:9", "9:16", "4:3", "3:4", "21:9"] as const
 const GROK_RATIOS = ["1:1", "16:9", "9:16", "3:2", "2:3"] as const
 const GPT_IMAGE_RATIOS = ["1:1", "3:2", "2:3"] as const
 const GPT_IMAGE_2_RATIOS = ["auto", "1:1", "16:9", "9:16", "4:3", "3:4"] as const
+// GPT Image 2.5 (Flare + Sunburst) widen the set to thirteen — the GPT Image 2
+// six plus 3:2/2:3, ultra-wide 21:9/27:16, ultra-tall 16:27 and near-square
+// 9:8/8:9 (docs.kie.ai/market/gpt/gpt-image-2-5-*). Unlike GPT Image 2, the 2.5
+// docs state NO aspect-ratio x resolution restriction, so no cross-field
+// constraint is registered for these ids in normalizeModelInput below.
+const GPT_IMAGE_2_5_RATIOS = [
+  "auto", "1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16",
+  "21:9", "27:16", "16:27", "9:8", "8:9",
+] as const
 const IMAGEN4_RATIOS = ["1:1", "16:9", "9:16", "4:3", "3:4"] as const
 const IDEOGRAM_RATIOS = ["1:1", "16:9", "9:16", "4:3", "3:4"] as const
 const SEEDREAM_RATIOS = ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "21:9"] as const
@@ -591,6 +600,103 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
     ],
   },
 
+  "gpt-image-2-5-flare": {
+    id: "gpt-image-2-5-flare",
+    kind: "image",
+    modes: ["t2i"] as const,
+    family: "OpenAI",
+    label: "GPT Image 2.5 Flare",
+    series: "GPT Image",
+    description: "Fast everyday GPT Image 2.5 - higher quality than GPT Image 2 at about half the latency. The default of the pair: social and creator content, campaign variants, thumbnails, rapid iteration, high-volume work.",
+    useCases: ["typography", "high-res", "general", "draft"],
+    features: ["reference-image"],
+    aspectRatios: GPT_IMAGE_2_5_RATIOS,
+    resolutions: ["1K", "2K", "4K"],
+    pricing: [
+      { identifier: "gpt-image-2-5-flare", credits: 15, note: "1K default" },
+      { identifier: "gpt-image-2-5-flare:2K", credits: 25, note: "2K" },
+      { identifier: "gpt-image-2-5-flare:4K", credits: 40, note: "4K" },
+    ],
+    valueLabels: {
+      "3:2": "3:2 (Landscape)", "2:3": "2:3 (Portrait)",
+      "27:16": "27:16 (Ultra-wide)", "16:27": "16:27 (Ultra-tall)",
+      "9:8": "9:8 (Near-square)", "8:9": "8:9 (Near-square)",
+    },
+    safetyFilter: { stochastic: true, fallback: "nano-banana-pro" },
+  },
+  "gpt-image-2-5-flare-i2i": {
+    id: "gpt-image-2-5-flare-i2i",
+    kind: "image",
+    modes: ["i2i"] as const,
+    family: "OpenAI",
+    label: "GPT Image 2.5 Flare (I2I)",
+    series: "GPT Image",
+    description: "Fast GPT Image 2.5 edits (up to 16 source images) - the default when you are iterating rather than finishing.",
+    useCases: ["edit", "high-res"],
+    features: ["reference-image"],
+    aspectRatios: GPT_IMAGE_2_5_RATIOS,
+    resolutions: ["1K", "2K", "4K"],
+    pricing: [
+      { identifier: "gpt-image-2-5-flare-i2i", credits: 15, note: "1K default" },
+      { identifier: "gpt-image-2-5-flare-i2i:2K", credits: 25, note: "2K" },
+      { identifier: "gpt-image-2-5-flare-i2i:4K", credits: 40, note: "4K" },
+    ],
+    valueLabels: {
+      "3:2": "3:2 (Landscape)", "2:3": "2:3 (Portrait)",
+      "27:16": "27:16 (Ultra-wide)", "16:27": "16:27 (Ultra-tall)",
+      "9:8": "9:8 (Near-square)", "8:9": "8:9 (Near-square)",
+    },
+    safetyFilter: { stochastic: true, fallback: "nano-banana-pro" },
+  },
+  "gpt-image-2-5-sunburst": {
+    id: "gpt-image-2-5-sunburst",
+    kind: "image",
+    modes: ["t2i"] as const,
+    family: "OpenAI",
+    label: "GPT Image 2.5 Sunburst",
+    series: "GPT Image",
+    description: "Precision GPT Image 2.5 - trades generation time for tighter control and detail fidelity. Pick it for brand-sensitive and production work: packaging, diagrams, ecommerce retouching, polished campaign creative.",
+    useCases: ["typography", "high-res", "general"],
+    features: ["reference-image"],
+    aspectRatios: GPT_IMAGE_2_5_RATIOS,
+    resolutions: ["1K", "2K", "4K"],
+    pricing: [
+      { identifier: "gpt-image-2-5-sunburst", credits: 15, note: "1K default" },
+      { identifier: "gpt-image-2-5-sunburst:2K", credits: 25, note: "2K" },
+      { identifier: "gpt-image-2-5-sunburst:4K", credits: 40, note: "4K" },
+    ],
+    valueLabels: {
+      "3:2": "3:2 (Landscape)", "2:3": "2:3 (Portrait)",
+      "27:16": "27:16 (Ultra-wide)", "16:27": "16:27 (Ultra-tall)",
+      "9:8": "9:8 (Near-square)", "8:9": "8:9 (Near-square)",
+    },
+    safetyFilter: { stochastic: true, fallback: "nano-banana-pro" },
+  },
+  "gpt-image-2-5-sunburst-i2i": {
+    id: "gpt-image-2-5-sunburst-i2i",
+    kind: "image",
+    modes: ["i2i"] as const,
+    family: "OpenAI",
+    label: "GPT Image 2.5 Sunburst (I2I)",
+    series: "GPT Image",
+    description: "Precision GPT Image 2.5 edits (up to 16 source images) - the most controlled edit in the GPT family, at the cost of a longer run.",
+    useCases: ["edit", "high-res"],
+    features: ["reference-image"],
+    aspectRatios: GPT_IMAGE_2_5_RATIOS,
+    resolutions: ["1K", "2K", "4K"],
+    pricing: [
+      { identifier: "gpt-image-2-5-sunburst-i2i", credits: 15, note: "1K default" },
+      { identifier: "gpt-image-2-5-sunburst-i2i:2K", credits: 25, note: "2K" },
+      { identifier: "gpt-image-2-5-sunburst-i2i:4K", credits: 40, note: "4K" },
+    ],
+    valueLabels: {
+      "3:2": "3:2 (Landscape)", "2:3": "2:3 (Portrait)",
+      "27:16": "27:16 (Ultra-wide)", "16:27": "16:27 (Ultra-tall)",
+      "9:8": "9:8 (Near-square)", "8:9": "8:9 (Near-square)",
+    },
+    safetyFilter: { stochastic: true, fallback: "nano-banana-pro" },
+  },
+
   // ── Ideogram ──
   // Ideogram models use a `rendering_speed` (TURBO / BALANCED / QUALITY)
   // dimension that's distinct from the `quality` lever — frontend exposes

package/src/model-constants.ts

@@ -44,6 +44,9 @@ export const IMAGE_ASPECT_RATIO_VALUES = [
   // Ultra-wide / ultra-tall banner ratios: Wan 2.7 + Wan 2.7 Pro (8:1, 1:8)
   // and Nano Banana 2 Lite (4:1, 1:4, 8:1, 1:8).
   "4:1", "1:4", "8:1", "1:8",
+  // GPT Image 2.5 (Flare + Sunburst) additions: near-square and ultra-wide/tall
+  // cinema ratios (docs.kie.ai/market/gpt/gpt-image-2-5-*).
+  "27:16", "16:27", "9:8", "8:9",
 ] as const
 
 /** A ratio string the image routes accept (pre-snap vocabulary, not a per-model guarantee). */
@@ -76,6 +79,11 @@ export const MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER: Record<string, number> = {
   "nano-banana-2-lite": 20000, // docs.kie.ai/market/google/nano-banana-2-lite
   "nano-banana-pro": 20000,    // docs.kie.ai/market/google/pro-image-to-image
   "gpt-image-2-i2i": 20000,    // docs.kie.ai/market/gpt/gpt-image-2-image-to-image
+  // GPT Image 2.5 — all four lanes document a 20000-char prompt ceiling.
+  "gpt-image-2-5-flare": 20000,          // docs.kie.ai/market/gpt/gpt-image-2-5-flare-text-to-image
+  "gpt-image-2-5-flare-i2i": 20000,      // docs.kie.ai/market/gpt/gpt-image-2-5-flare-image-to-image
+  "gpt-image-2-5-sunburst": 20000,       // docs.kie.ai/market/gpt/gpt-image-2-5-sunburst-text-to-image
+  "gpt-image-2-5-sunburst-i2i": 20000,   // docs.kie.ai/market/gpt/gpt-image-2-5-sunburst-image-to-image
   // ── lower than the 5000 default (over-send risk if left at default) ──
   "seedream": 3000,            // docs.kie.ai/market/seedream/4-5-text-to-image
   "seedream-edit": 3000,       // docs.kie.ai/market/seedream/4-5-edit
@@ -475,6 +483,8 @@ export const MODELS_WITH_REFERENCE_IMAGE_SUPPORT = new Set([
   // T2I providers that auto-route to their i2i sibling when refs are attached
   "gpt-image",
   "gpt-image-2",
+  "gpt-image-2-5-flare",
+  "gpt-image-2-5-sunburst",
   "grok",
   "grok-2",
   "qwen",
@@ -487,6 +497,8 @@ export const MODELS_WITH_REFERENCE_IMAGE_SUPPORT = new Set([
   "nano-banana-edit",
   "gpt-image-i2i",
   "gpt-image-2-i2i",
+  "gpt-image-2-5-flare-i2i",
+  "gpt-image-2-5-sunburst-i2i",
   "grok-2-i2i",
   "flux-i2i",
   "flux-pro-i2i",
@@ -525,6 +537,8 @@ export const MODELS_WITH_REFERENCE_IMAGE_SUPPORT = new Set([
 export const T2I_TO_I2I_VARIANT: Record<string, string> = {
   "gpt-image": "gpt-image-i2i",
   "gpt-image-2": "gpt-image-2-i2i",
+  "gpt-image-2-5-flare": "gpt-image-2-5-flare-i2i",
+  "gpt-image-2-5-sunburst": "gpt-image-2-5-sunburst-i2i",
   "grok": "grok-i2i",
   // grok-2's t2i takes NO image input; its "i2i" is the segment-map(image_url)
   // → image-edit(task_id) chain in the KIE provider (single reference).
@@ -560,6 +574,8 @@ export const REF_IMAGE_MAX_LIMITS: Record<string, number> = {
   "nano-banana-edit": 8,
   "gpt-image-i2i": 16,
   "gpt-image-2-i2i": 16,
+  "gpt-image-2-5-flare-i2i": 16,
+  "gpt-image-2-5-sunburst-i2i": 16,
   "flux-i2i": 4,
   "flux-pro-i2i": 4,
   "seedream-edit": 16,
@@ -625,6 +641,10 @@ export const VARIABLE_PRICING_MODELS: Record<string, "quality" | "resolution" |
   "gpt-image-i2i": "quality",
   "gpt-image-2": "resolution",
   "gpt-image-2-i2i": "resolution",
+  "gpt-image-2-5-flare": "resolution",
+  "gpt-image-2-5-flare-i2i": "resolution",
+  "gpt-image-2-5-sunburst": "resolution",
+  "gpt-image-2-5-sunburst-i2i": "resolution",
   "nano-banana-pro": "resolution",
   "nano-banana-2": "resolution",
   "flux": "resolution",
@@ -658,6 +678,10 @@ export const RESOLUTION_2K_4K_TIERED_PROVIDERS = new Set([
   "nano-banana-2",
   "gpt-image-2",
   "gpt-image-2-i2i",
+  "gpt-image-2-5-flare",
+  "gpt-image-2-5-flare-i2i",
+  "gpt-image-2-5-sunburst",
+  "gpt-image-2-5-sunburst-i2i",
   "wan-2.7",
   "wan-2.7-pro",
 ])
@@ -680,6 +704,8 @@ export const IMAGE_GEN_PROVIDERS = [
   "grok-2",
   "gpt-image",
   "gpt-image-2",
+  "gpt-image-2-5-flare",
+  "gpt-image-2-5-sunburst",
   "imagen4",
   "imagen4-fast",
   "imagen4-ultra",
@@ -711,6 +737,8 @@ export const IMAGE_I2I_PROVIDERS = [
   "flux-pro-i2i",
   "gpt-image-i2i",
   "gpt-image-2-i2i",
+  "gpt-image-2-5-flare-i2i",
+  "gpt-image-2-5-sunburst-i2i",
   "grok-2-i2i",
   "ideogram-edit",
   "ideogram-remix",
@@ -1250,6 +1278,8 @@ export const IMAGE_MASK_MODE: Record<ImageGenProvider, ImageMaskMode> = {
   "nano-banana-2-lite": "prompt",
   "gpt-image": "prompt",
   "gpt-image-2": "prompt",
+  "gpt-image-2-5-flare": "prompt",
+  "gpt-image-2-5-sunburst": "prompt",
   "seedream": "prompt",
   "seedream-5-lite": "prompt",
   "seedream-5-pro": "prompt",

package/src/node-default-mappings.ts

@@ -167,6 +167,10 @@ const QUALITY_MAP: Record<string, QualityMapping> = {
   "flux-pro-i2i":        { field: "resolution", values: { low: "1K", mid: "2K", high: "2K" } },
   "gpt-image-2":         { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
   "gpt-image-2-i2i":     { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
+  "gpt-image-2-5-flare": { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
+  "gpt-image-2-5-flare-i2i": { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
+  "gpt-image-2-5-sunburst": { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
+  "gpt-image-2-5-sunburst-i2i": { field: "resolution", values: { low: "1K", mid: "2K", high: "4K" } },
   // Image gen — quality-style (medium/high or basic/high)
   "gpt-image":           { field: "quality",    values: { low: "medium", mid: "medium", high: "high" } },
   "gpt-image-i2i":       { field: "quality",    values: { low: "medium", mid: "medium", high: "high" } },

package/src/pipeline-types.ts

@@ -54,6 +54,8 @@ export const PIPELINE_PINNABLE_IMAGE_MODELS = [
   "flux",
   "gpt-image",
   "gpt-image-2",
+  "gpt-image-2-5-flare",
+  "gpt-image-2-5-sunburst",
 ] as const
 export type PipelinePinnableImageModel = (typeof PIPELINE_PINNABLE_IMAGE_MODELS)[number]
 

package/src/pro-3d-render.ts

@@ -271,6 +271,23 @@ export interface Pro3DRenderValidationWarning {
   shotId?: string
 }
 
+/**
+ * One still per shot of the exported composition.
+ *
+ * A render's contact sheet: the frame a shot OPENS on, which is the frame that
+ * says what the shot is of. `shotIndex` is the 0-based position in the v2
+ * composition's `shots` array — a v1 (single-shot) scene has exactly one still,
+ * index 0 at frame 0 — and `frame` is that shot's own first frame in the
+ * composition's frame space, so a caller can line a still up against the MP4
+ * without re-deriving shot boundaries.
+ */
+export interface Pro3DRenderShotStill {
+  shotIndex: number
+  frame: number
+  assetId: string
+  url: string
+}
+
 export interface Pro3DRenderResultMetadata {
   width: number
   height: number
@@ -299,6 +316,12 @@ export interface Pro3DRenderJobOutput {
   scenePlan: Scene3DPlan
   sceneRevisionId: string
   posterAssetId: string
+  /**
+   * One still per shot, ordered by `shotIndex`. Optional and additive: a
+   * runtime that does not render stills yet returns a complete result without
+   * them, and a result that HAS them has one for every shot.
+   */
+  shotStills?: Pro3DRenderShotStill[]
   /** Present when an editable native source was retained for this revision. */
   sourceArtifactId?: string
   validation: {
@@ -324,12 +347,22 @@ export interface Pro3DRenderJobOutput {
  * them to satisfy the schema; a runtime that has not produced them yet simply
  * does not parse as complete, which is the honest answer.
  */
+export const pro3DRenderShotStillSchema = z
+  .object({
+    shotIndex: z.number().int().min(0),
+    frame: z.number().int().min(0),
+    assetId: z.string().min(1),
+    url: z.string().min(1),
+  })
+  .passthrough()
+
 export const pro3DRenderJobOutputSchema = z
   .object({
     videoUrl: z.string().min(1),
     scenePlan: scene3DAnyPlanSchema,
     sceneRevisionId: z.string().min(1),
     posterAssetId: z.string().min(1),
+    shotStills: z.array(pro3DRenderShotStillSchema).optional(),
     sourceArtifactId: z.string().min(1).optional(),
     validation: z
       .object({
@@ -364,6 +397,28 @@ export function isPro3DRenderJobOutput(value: unknown): value is Pro3DRenderJobO
   return pro3DRenderJobOutputSchema.safeParse(value).success
 }
 
+/**
+ * The stills on a result, in shot order — the ONE reader every surface uses.
+ *
+ * Tolerant on purpose: this runs on canvas node data, on a job row read back
+ * from the database and on an MCP result envelope, and in every one of those a
+ * missing or malformed list means "this result has no stills", never "refuse
+ * the whole result". Sorting here is what lets `shotStills[i]` mean shot `i`
+ * at every call site without each one remembering to sort.
+ */
+export function pro3DRenderShotStills(output: unknown): Pro3DRenderShotStill[] {
+  const list = (output as { shotStills?: unknown } | null | undefined)?.shotStills
+  if (!Array.isArray(list)) return []
+  const parsed = list.flatMap((entry) => {
+    const result = pro3DRenderShotStillSchema.safeParse(entry)
+    return result.success
+      ? [{ shotIndex: result.data.shotIndex, frame: result.data.frame,
+          assetId: result.data.assetId, url: result.data.url }]
+      : []
+  })
+  return parsed.sort((a, b) => a.shotIndex - b.shotIndex)
+}
+
 /**
  * The two fields every EXECUTION SURFACE must be able to resolve, whatever
  * else a runtime does or does not attach yet.

package/src/reference-board-templates.ts

@@ -1,6 +1,11 @@
 /** Gen providers for the board: strict subset of IMAGE_GEN_PROVIDERS that
  *  renders legible in-image text + accepts reference conditioning. */
-export const REFERENCE_BOARD_PROVIDERS = ["nano-banana-pro", "gpt-image-2"] as const
+export const REFERENCE_BOARD_PROVIDERS = [
+  "nano-banana-pro",
+  "gpt-image-2",
+  "gpt-image-2-5-flare",
+  "gpt-image-2-5-sunburst",
+] as const
 export type ReferenceBoardProvider = (typeof REFERENCE_BOARD_PROVIDERS)[number]
 
 export type BoardEntityKind = "character" | "location" | "object"