@nodaro/shared 3.9.0 → 3.11.0

package/src/__tests__/video-frame-fit.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from "vitest"
+import {
+  computeFrameFitPlan,
+  resolveFrameFitAspect,
+  resolveFrameDelivery,
+  minimalRatioDimensions,
+  centreCropToAspect,
+  parseAspectToken,
+  FRAME_FIT_STRETCH_TOLERANCE,
+} from "../video-frame-fit.js"
+import { resolveOutputCanvas, measuredCanvasCombinations } from "../video-output-canvas.js"
+
+/** The image behind every number in this file: a 1K 9:16 GPT image. */
+const GPT_1K = { sourceWidth: 940, sourceHeight: 1672 }
+
+describe("measured output canvases", () => {
+  it("answers the combinations we measured, case-insensitively on resolution", () => {
+    expect(resolveOutputCanvas("seedance-2-5", "720p", "9:16")).toEqual([720, 1280])
+    expect(resolveOutputCanvas("minimax-h3", "768P", "9:16")).toEqual([768, 1344])
+    expect(resolveOutputCanvas("minimax-h3", "2K", "16:9")).toEqual([2560, 1440])
+  })
+
+  it("keeps the 2.0 family apart from 2.5 at 480p — they really do differ", () => {
+    expect(resolveOutputCanvas("seedance-2-5", "480p", "16:9")).toEqual([854, 480])
+    expect(resolveOutputCanvas("seedance-2-fast", "480p", "16:9")).toEqual([864, 496])
+  })
+
+  it("answers undefined for anything never measured", () => {
+    expect(resolveOutputCanvas("seedance-2-5", "4k", "9:16")).toBeUndefined()
+    expect(resolveOutputCanvas("kling-3.0", "720p", "16:9")).toBeUndefined()
+    expect(resolveOutputCanvas(undefined, "720p", "9:16")).toBeUndefined()
+  })
+
+  it("stores only even, positive dimensions", () => {
+    for (const { provider, resolution, aspect, canvas } of measuredCanvasCombinations()) {
+      const where = `${provider} ${resolution} ${aspect}`
+      expect(canvas[0] % 2, where).toBe(0)
+      expect(canvas[1] % 2, where).toBe(0)
+      expect(canvas[0] > 0 && canvas[1] > 0, where).toBe(true)
+    }
+  })
+
+  it("does not claim a canvas whose ratio is wildly off the label", () => {
+    // H3's 768P 9:16 really is 0.5714 — a 1.6% lie we keep on purpose. Anything
+    // further out is a typo, not a provider quirk.
+    for (const { provider, resolution, aspect, canvas } of measuredCanvasCombinations()) {
+      const label = parseAspectToken(aspect)
+      if (label === undefined) continue
+      const actual = canvas[0] / canvas[1]
+      expect(Math.abs(actual - label) / label, `${provider} ${resolution} ${aspect}`).toBeLessThan(0.06)
+    }
+  })
+})
+
+describe("aspect resolution", () => {
+  it("uses an explicit ratio as-is", () => {
+    expect(resolveFrameFitAspect({ provider: "seedance-2-5", requestedAspect: "16:9", ...GPT_1K })).toBe("16:9")
+  })
+
+  it("snaps adaptive and Auto to the model's nearest listed ratio", () => {
+    // 940x1672 = 0.5622, which is 9:16 to within 0.05%.
+    expect(resolveFrameFitAspect({ provider: "seedance-2-5", requestedAspect: "adaptive", ...GPT_1K })).toBe("9:16")
+    expect(resolveFrameFitAspect({ provider: "seedance-2-5", requestedAspect: "Auto", ...GPT_1K })).toBe("9:16")
+    expect(resolveFrameFitAspect({ provider: "seedance-2-5", requestedAspect: undefined, sourceWidth: 1920, sourceHeight: 1080 })).toBe("16:9")
+  })
+
+  it("gives up when the model declares no ratios", () => {
+    expect(resolveFrameFitAspect({ provider: "not-a-model", requestedAspect: "adaptive", ...GPT_1K })).toBeUndefined()
+  })
+})
+
+describe("computeFrameFitPlan", () => {
+  it("resizes the 1K image to the measured canvas — the case that fixed the snap", () => {
+    const plan = computeFrameFitPlan({
+      fit: "resolution", provider: "seedance-2-5", resolution: "720p", aspect: "9:16", ...GPT_1K,
+    })
+    expect(plan).toEqual({ width: 720, height: 1280, reason: "resolution" })
+  })
+
+  it("targets H3's real 768x1344 canvas rather than a true 9:16", () => {
+    const plan = computeFrameFitPlan({
+      fit: "resolution", provider: "minimax-h3", resolution: "768P", aspect: "9:16", ...GPT_1K,
+    })
+    expect(plan?.width).toBe(768)
+    expect(plan?.height).toBe(1344)
+    expect(plan?.crop).toBeUndefined()   // 1.6% gap is inside the tolerance → stretch
+  })
+
+  it("does nothing when the frame is already the canvas", () => {
+    expect(computeFrameFitPlan({
+      fit: "resolution", provider: "seedance-2-5", resolution: "720p", aspect: "9:16",
+      sourceWidth: 720, sourceHeight: 1280,
+    })).toBeNull()
+  })
+
+  it("does nothing in original mode, whatever the size", () => {
+    expect(computeFrameFitPlan({
+      fit: "original", provider: "seedance-2-5", resolution: "720p", aspect: "9:16", ...GPT_1K,
+    })).toBeNull()
+  })
+
+  it("degrades resolution → ratio when the combination was never measured", () => {
+    const plan = computeFrameFitPlan({
+      fit: "resolution", provider: "seedance-2-5", resolution: "4k", aspect: "16:9",
+      sourceWidth: 1000, sourceHeight: 1000,
+    })
+    // No 4k canvas on file, so it falls back to the minimal change that makes 16:9.
+    expect(plan?.reason).toBe("ratio")
+    expect(plan!.width / plan!.height).toBeCloseTo(16 / 9, 2)
+  })
+
+  it("degrades to nothing when neither a canvas nor an aspect can be resolved", () => {
+    expect(computeFrameFitPlan({
+      fit: "resolution", provider: "not-a-model", resolution: "720p", aspect: undefined, ...GPT_1K,
+    })).toBeNull()
+  })
+
+  it("stretches inside the tolerance and crops outside it", () => {
+    // 4% off 9:16 — inside 5%, so a plain stretch, no crop.
+    const inside = computeFrameFitPlan({
+      fit: "ratio", provider: "seedance-2-5", resolution: "720p", aspect: "9:16",
+      sourceWidth: 1000, sourceHeight: 1710,
+    })
+    expect(Math.abs(1000 / 1710 - 9 / 16) / (9 / 16)).toBeLessThan(FRAME_FIT_STRETCH_TOLERANCE)
+    expect(inside?.crop).toBeUndefined()
+
+    // A square photo into 9:16 is a 78% gap — crop first, never squash.
+    const outside = computeFrameFitPlan({
+      fit: "resolution", provider: "seedance-2-5", resolution: "720p", aspect: "9:16",
+      sourceWidth: 1024, sourceHeight: 1024,
+    })
+    expect(outside).toMatchObject({ width: 720, height: 1280, reason: "resolution" })
+    expect(outside?.crop).toEqual({ left: 224, top: 0, width: 576, height: 1024 })
+    expect(outside!.crop!.width / outside!.crop!.height).toBeCloseTo(9 / 16, 3)
+  })
+
+  it("produces even dimensions (yuv420p rejects odd ones)", () => {
+    const plan = computeFrameFitPlan({
+      fit: "ratio", provider: "seedance-2-5", resolution: "720p", aspect: "16:9",
+      sourceWidth: 1001, sourceHeight: 667,
+    })
+    expect(plan!.width % 2).toBe(0)
+    expect(plan!.height % 2).toBe(0)
+  })
+})
+
+describe("geometry helpers", () => {
+  it("minimalRatioDimensions keeps the long side and moves the short one", () => {
+    // 940 wide is 9:16 at 1671.1 tall, which rounds back to the image's own
+    // 1672 — the 1K GPT image really is 9:16 to the nearest even pixel, so
+    // "match ratio" alone would leave it untouched (and the snap would stay).
+    expect(minimalRatioDimensions(940, 1672, 9 / 16)).toEqual({ width: 940, height: 1672 })
+    expect(minimalRatioDimensions(1920, 1000, 16 / 9)).toEqual({ width: 1920, height: 1080 })
+  })
+
+  it("centreCropToAspect drops the overhang evenly", () => {
+    expect(centreCropToAspect(1024, 1024, 9 / 16)).toEqual({ left: 224, top: 0, width: 576, height: 1024 })
+    expect(centreCropToAspect(1000, 1000, 16 / 9)).toEqual({ left: 0, top: 219, width: 1000, height: 562 })
+  })
+
+  it("parseAspectToken reads the tokens the catalog uses", () => {
+    expect(parseAspectToken("16:9")).toBeCloseTo(16 / 9, 6)
+    expect(parseAspectToken("9:16")).toBeCloseTo(9 / 16, 6)
+    expect(parseAspectToken("adaptive")).toBeUndefined()
+    expect(parseAspectToken(undefined)).toBeUndefined()
+  })
+})
+
+describe("frame delivery", () => {
+  it("sends the Seedance 2.0 family as references and everything else as frames", () => {
+    const ref = { requested: "auto" as const, supportsReferenceImages: true }
+    expect(resolveFrameDelivery({ provider: "seedance-2-fast", ...ref })).toBe("reference")
+    expect(resolveFrameDelivery({ provider: "seedance-2", ...ref })).toBe("reference")
+    expect(resolveFrameDelivery({ provider: "seedance-2-mini", ...ref })).toBe("reference")
+    expect(resolveFrameDelivery({ provider: "seedance-2-5", ...ref })).toBe("frame")
+    expect(resolveFrameDelivery({ provider: "wan-3", ...ref })).toBe("frame")
+    expect(resolveFrameDelivery({ provider: "veo3.1", ...ref })).toBe("frame")
+  })
+
+  it("honours an explicit choice", () => {
+    expect(resolveFrameDelivery({ provider: "seedance-2-fast", requested: "frame", supportsReferenceImages: true })).toBe("frame")
+    expect(resolveFrameDelivery({ provider: "veo3.1", requested: "reference", supportsReferenceImages: true })).toBe("reference")
+  })
+
+  it("never asks for reference delivery on a model that takes no references", () => {
+    expect(resolveFrameDelivery({ provider: "seedance-2-fast", requested: "auto", supportsReferenceImages: false })).toBe("frame")
+    expect(resolveFrameDelivery({ provider: "wan-i2v", requested: "reference", supportsReferenceImages: false })).toBe("frame")
+  })
+})

package/src/__tests__/video-ref-limits.test.ts

@@ -57,11 +57,20 @@ describe("VIDEO_REF_LIMITS_BY_PROVIDER ⇄ MODEL_CATALOG drift guard", () => {
 })
 
 describe("VIDEO_REF_LIMITS_BY_PROVIDER caps for the newly-covered models", () => {
-  it("VEO family carries images:3 (the REFERENCE_2_VIDEO slice cap in kie/video.ts)", () => {
-    expect(VIDEO_REF_LIMITS_BY_PROVIDER["veo3"]).toEqual({ images: 3 })
+  it("the ref-capable VEO SKUs carry images:3 (the REFERENCE_2_VIDEO slice cap in kie/video.ts)", () => {
     expect(VIDEO_REF_LIMITS_BY_PROVIDER["veo3.1"]).toEqual({ images: 3 })
     expect(VIDEO_REF_LIMITS_BY_PROVIDER["veo3_lite"]).toEqual({ images: 3 })
   })
+
+  it("veo3 (VEO 3.1 QUALITY) carries NO cap — KIE serves reference-to-video on Fast/Lite only", () => {
+    // Its own words on a production job (2026-09-04, app-reports lane G):
+    // "Reference to video only supports the Veo Fast model and Veo Lite
+    // model." Until 2026-09-15 this entry claimed images:3, so every
+    // reference-carrying Quality run was a 422 after the credits were
+    // reserved. Absent ⇒ 0 everywhere the map is read.
+    expect(VIDEO_REF_LIMITS_BY_PROVIDER["veo3"]).toBeUndefined()
+    expect(MODEL_CATALOG["veo3"]?.features).not.toContain("reference-image")
+  })
   it("kling-3-omni and grok-i2v carry images:7", () => {
     expect(VIDEO_REF_LIMITS_BY_PROVIDER["kling-3-omni"]).toEqual({ images: 7 })
     expect(VIDEO_REF_LIMITS_BY_PROVIDER["grok-i2v"]).toEqual({ images: 7 })

package/src/catalog-projection.ts

@@ -1,3 +1,4 @@
+import type { CharacterMotionMetadata } from "./character-motion-metadata.js"
 /**
  * Tag-free, policy-free wire shape for the `GET /v1/catalogs` projection — the
  * server-driven, pack-composed catalog view thin clients render their own
@@ -21,6 +22,8 @@ export interface ProjectedCatalogOption {
    */
   term?: string
   icon?: string
+  /** Authored Character Motion prerequisites and sequence state. Missing means unknown. */
+  motion?: CharacterMotionMetadata
 }
 
 export interface ProjectedCatalogDimension {

package/src/character-motion-metadata.ts

@@ -0,0 +1,19 @@
+/** Structural public catalog API metadata. Authored values remain in @nodaro/prompts. */
+export interface CharacterMotionMetadata {
+  /** Search terms, including previous display names. IDs remain stable. */
+  readonly aliases?: readonly string[]
+  /** Hidden from new choices; saved workflows still resolve this entry. */
+  readonly deprecated?: true
+  readonly replacementId?: string
+  /** Authored prerequisites; omission is unknown, never a compatibility claim. */
+  readonly requires?: readonly string[]
+  readonly startPose?: "standing" | "seated" | "floor" | "any"
+  readonly endPose?: "standing" | "seated" | "floor" | "any"
+  readonly endVisibility?: "in-frame" | "out-of-frame"
+  readonly handsAfter?: "free" | "occupied" | "holding-partner"
+  readonly needsFreeHands?: true
+  readonly kind?: "single" | "compound"
+  readonly fixedPace?: true
+  /** Non-human/dependent recipient substituted through the Partner handle. */
+  readonly counterpart?: string
+}

package/src/credit-identifiers.ts

@@ -15,7 +15,7 @@ import {
   RESOLUTION_DURATION_PRICING,
   VEO_RESOLUTION_TIERED_PROVIDERS,
   VIDEO_DURATION_TIERS,
-  PRICING_DEFAULT_DURATION_SEC,
+  pricedOutputDurationSec,
   PRICING_DEFAULT_RESOLUTION,
   MOTION_DURATION_TIERS,
   T2I_TO_I2I_VARIANT,
@@ -27,8 +27,44 @@ import {
   normalizeWan3Resolution,
   getVideoAudioCapability,
 } from "./model-constants.js"
-import { isFlux2Model } from "./flux2-pricing.js"
-import { MODEL_CATALOG, normalizeModelInput, type ModelInputAdjustment } from "./model-catalog.js"
+import { isFlux2Model, FLUX2_RES_MP, type Flux2Model } from "./flux2-pricing.js"
+import { MODEL_CATALOG, normalizeModelInput, defaultResolutionFor, type ModelInputAdjustment } from "./model-catalog.js"
+
+/**
+ * The megapixel tier a Flux 2 credit identifier is keyed on, for ANY incoming
+ * `resolution` value.
+ *
+ * Flux 2 is the only family whose identifier INTERPOLATES the resolution
+ * instead of matching it against a known set, and its callers are not
+ * guaranteed to hand it a Flux 2 value:
+ *   - the multi-provider cost preview prices one node's data against EVERY
+ *     selected provider (`frontend/src/ee/hooks/use-providers-credits-sum.ts`),
+ *     so a node whose `resolution` is "2K" (the flux / nano-banana-pro value
+ *     space) reaches this branch verbatim;
+ *   - node data written straight into workflow JSON by an agent, an import or
+ *     a template never ran the config panel's provider-change fail-safe.
+ * Interpolating that produced the off-grid id `flux-2-pro:2KMP:0ref`, which no
+ * pricing row can answer — every cost badge 503'd `price_not_configured`
+ * (18 production app-reports, 2026-09-07..14).
+ *
+ * A value off the grid snaps to the model's DEFAULT tier — the same `preferred`
+ * value `normalizeModelInput` uses — so the preview asks for exactly the id the
+ * route will reserve (both routes and the orchestrator normalize through
+ * `resolveNormalizedImageGen` first, which makes this snap a no-op for them).
+ * An ABSENT resolution keeps its long-standing meaning ("this caller has no
+ * resolution dimension at all") and stays on 1 MP rather than moving to the
+ * model default, which would silently re-price every resolution-less node.
+ */
+function flux2MegapixelTier(model: Flux2Model, resolution?: string): string {
+  const bare = (v: string) => v.replace(/\s*MP$/i, "").trim()
+  const raw = typeof resolution === "string" ? bare(resolution) : ""
+  if (raw === "") return "1"
+  // Numeric match so "2.0"/" 2 MP" land on the same grid point as "2", and the
+  // GRID's own spelling is what gets emitted — returning the caller's "2.0"
+  // would build ":2.0MP:", another id no pricing row carries.
+  const tier = FLUX2_RES_MP.find((t) => Number(t) === Number(raw))
+  return tier ?? bare(defaultResolutionFor(model) ?? "1 MP")
+}
 
 /**
  * Compute composite model identifier for variable credit pricing.
@@ -54,8 +90,7 @@ export function buildCreditModelIdentifier(
   // their cost formula charges per input MP, so the reserved identifier must
   // reflect refs (there is no metered true-up to correct an under-reserved tier).
   if (isFlux2Model(provider)) {
-    const mp = (resolution ?? "1 MP").replace(/\s*MP$/i, "").trim()
-    return `${provider}:${mp}MP:${Math.min(referenceImageCount ?? 0, 8)}ref`
+    return `${provider}:${flux2MegapixelTier(provider, resolution)}MP:${Math.min(referenceImageCount ?? 0, 8)}ref`
   }
   if (HIGH_QUALITY_PROVIDERS.has(provider) && quality === "high") {
     return `${provider}:high`
@@ -329,10 +364,10 @@ export function buildVideoCreditModelIdentifier(
 
   // A named-provider request with NO duration renders the model's own default
   // (kie/models.ts extraParams), so price that default — not the global 5s —
-  // for providers whose per-second tiers wouldn't snap 5 up to it (minimax-h3).
-  const durationFallback = PRICING_DEFAULT_DURATION_SEC[effectiveProvider] ?? 5
-  const parsed = typeof duration === "string" ? parseInt(duration, 10) : (duration ?? durationFallback)
-  const durationSec = Number.isNaN(parsed) ? durationFallback : parsed
+  // for providers whose per-second tiers wouldn't snap 5 up to it
+  // (minimax-h3, seedance-2-5). One helper, shared with the dynamic
+  // reference-video reservations, so the tier and the scaled reserve agree.
+  const durationSec = pricedOutputDurationSec(effectiveProvider, duration)
   const tiers = VIDEO_DURATION_TIERS[effectiveProvider]
   if (!tiers) return effectiveProvider