@nodaro/shared 1.4.1

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@nodaro/shared",
+  "version": "1.4.1",
+  "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodaroai/app.nodaro.ai.git",
+    "directory": "packages/shared"
+  },
+  "homepage": "https://github.com/nodaroai/app.nodaro.ai/tree/main/packages/shared#readme",
+  "bugs": "https://github.com/nodaroai/app.nodaro.ai/issues",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "src",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "fast-json-patch": "^3.1.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.2",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/__tests__/__snapshots__/prompt-builder-segments.test.ts.snap

@@ -0,0 +1,65 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > connected references directives 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "Use these references for the output image:
+- Image 1 (background — a stone castle) — use as the background/setting.
+
+Compose them naturally into a single image: a knight at Image 1 (background)",
+  "referenceImageUrls": [
+    "https://example.com/castle.png",
+  ],
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > empty prompt + style 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "
+Style: film noir style, high-contrast black-and-white imagery, deep shadows, venetian-blind lighting and moody 1940s cinema feel",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > negative appended as Avoid (no native field) 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "a knight
+Avoid: blurry, watermark",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > negative native (imagen4) 1`] = `
+{
+  "nativeNegativePrompt": "blurry",
+  "prompt": "a knight",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > plain prompt 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "a knight on a cliff",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > style appended 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "a knight
+Style: cinematic film style, dramatic lighting with cinematic color grading, widescreen aesthetic and film-like depth of field",
+  "referenceImageUrls": undefined,
+}
+`;
+
+exports[`buildImagePrompt characterization (pre/post segment refactor) > produces stable output across the fixture matrix > truncation 1`] = `
+{
+  "nativeNegativePrompt": undefined,
+  "prompt": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "referenceImageUrls": undefined,
+}
+`;

package/src/__tests__/ai-avatar-pricing.test.ts

@@ -0,0 +1,321 @@
+import { describe, it, expect } from "vitest"
+import {
+  AI_AVATAR_MAX_DURATION_SEC,
+  AI_AVATAR_MAX_AUDIO_SEC,
+  AI_AVATAR_DURATION_BUCKETS,
+  AI_AVATAR_AUDIO_FALLBACK_SEC,
+  AI_AVATAR_RESERVE_IDS,
+  aiAvatarReserveCreditId,
+  resolveAiAvatarCreditId,
+  estimateScriptDurationSec,
+  pickAiAvatarBucket,
+} from "../ai-avatar-pricing.js"
+
+// The provider-$ rate table and USD/credit cost formulas (aiAvatarUsdCost,
+// aiAvatarHoldCredits, aiAvatarReserveCeilingUsd) moved to
+// backend/src/lib/pricing/ai-avatar-cost.ts (S5) — their tests live in
+// backend/src/lib/pricing/__tests__/ai-avatar-cost.test.ts. This file covers
+// only the NON-monetary duration-bucketing + credit-id-construction logic
+// that stays in the published package.
+
+describe("estimateScriptDurationSec", () => {
+  it("returns 1 for empty/missing script", () => {
+    expect(estimateScriptDurationSec(undefined)).toBe(1)
+    expect(estimateScriptDurationSec("")).toBe(1)
+  })
+
+  it("ceil-divides by 12 chars/sec at default speed 1", () => {
+    expect(estimateScriptDurationSec("x".repeat(360))).toBe(30)
+    expect(estimateScriptDurationSec("x".repeat(361))).toBe(31)
+  })
+
+  it("minimum is 1 even for very short scripts", () => {
+    expect(estimateScriptDurationSec("hi")).toBe(1)
+  })
+
+  it("slower voiceSpeed produces more seconds (no undercharge)", () => {
+    expect(estimateScriptDurationSec("x".repeat(1200), 1.0)).toBe(100)
+    expect(estimateScriptDurationSec("x".repeat(1200), 0.5)).toBe(200)
+  })
+
+  it("faster voiceSpeed produces fewer seconds", () => {
+    expect(estimateScriptDurationSec("x".repeat(1200), 1.5)).toBe(67)
+  })
+
+  it("clamps voiceSpeed to [0.5, 1.5]", () => {
+    expect(estimateScriptDurationSec("x".repeat(1200), 0.1)).toBe(
+      estimateScriptDurationSec("x".repeat(1200), 0.5),
+    )
+    expect(estimateScriptDurationSec("x".repeat(1200), 2.0)).toBe(
+      estimateScriptDurationSec("x".repeat(1200), 1.5),
+    )
+  })
+
+  it("5000-char script at voiceSpeed 0.5 fits within 900s bucket", () => {
+    const duration = estimateScriptDurationSec("x".repeat(5000), 0.5)
+    expect(duration).toBeLessThanOrEqual(900)
+    expect(pickAiAvatarBucket(duration)).toBe(900)
+  })
+})
+
+describe("AI_AVATAR_DURATION_BUCKETS (fine-grained low end)", () => {
+  it("has 10 buckets: 5/10/15/30/60/120/240/360/600/900s", () => {
+    expect([...AI_AVATAR_DURATION_BUCKETS]).toEqual([5, 10, 15, 30, 60, 120, 240, 360, 600, 900])
+  })
+})
+
+describe("pickAiAvatarBucket", () => {
+  it("picks the smallest bucket >= sec (fine low end)", () => {
+    expect(pickAiAvatarBucket(1)).toBe(5)
+    expect(pickAiAvatarBucket(5)).toBe(5)
+    expect(pickAiAvatarBucket(6)).toBe(10)
+    expect(pickAiAvatarBucket(10)).toBe(10)
+    expect(pickAiAvatarBucket(11)).toBe(15)
+    expect(pickAiAvatarBucket(15)).toBe(15)
+    expect(pickAiAvatarBucket(16)).toBe(30)
+    expect(pickAiAvatarBucket(30)).toBe(30)
+    expect(pickAiAvatarBucket(31)).toBe(60)
+    expect(pickAiAvatarBucket(60)).toBe(60)
+    expect(pickAiAvatarBucket(61)).toBe(120)
+    expect(pickAiAvatarBucket(120)).toBe(120)
+    expect(pickAiAvatarBucket(121)).toBe(240)
+    expect(pickAiAvatarBucket(240)).toBe(240)
+    expect(pickAiAvatarBucket(241)).toBe(360)
+    expect(pickAiAvatarBucket(360)).toBe(360)
+    expect(pickAiAvatarBucket(361)).toBe(600)
+    expect(pickAiAvatarBucket(600)).toBe(600)
+    expect(pickAiAvatarBucket(601)).toBe(900)
+    expect(pickAiAvatarBucket(900)).toBe(900)
+  })
+
+  it("falls back to max bucket (900) when sec exceeds all buckets", () => {
+    expect(pickAiAvatarBucket(901)).toBe(900)
+    expect(pickAiAvatarBucket(9999)).toBe(900)
+  })
+})
+
+describe("aiAvatarReserveCreditId", () => {
+  it("builds correct bucketed composite IDs", () => {
+    expect(aiAvatarReserveCreditId("avatar-iv", "720p", 5)).toBe("heygen-avatar-iv:720p:5s")
+    expect(aiAvatarReserveCreditId("avatar-iv", "720p", 15)).toBe("heygen-avatar-iv:720p:15s")
+    expect(aiAvatarReserveCreditId("avatar-iv", "720p", 900)).toBe("heygen-avatar-iv:720p:900s")
+    expect(aiAvatarReserveCreditId("avatar-iv", "1080p", 60)).toBe("heygen-avatar-iv:1080p:60s")
+    expect(aiAvatarReserveCreditId("avatar-iv", "4k", 120)).toBe("heygen-avatar-iv:4k:120s")
+    expect(aiAvatarReserveCreditId("avatar-v", "720p", 30)).toBe("heygen-avatar-v:720p:30s")
+    expect(aiAvatarReserveCreditId("avatar-v", "1080p", 240)).toBe("heygen-avatar-v:1080p:240s")
+    expect(aiAvatarReserveCreditId("avatar-v", "4k", 900)).toBe("heygen-avatar-v:4k:900s")
+  })
+})
+
+describe("resolveAiAvatarCreditId", () => {
+  it("text mode: uses script length to pick bucket", () => {
+    // 360 chars → 30s → bucket 30
+    expect(resolveAiAvatarCreditId({ speechMode: "text", script: "x".repeat(360) }))
+      .toBe("heygen-avatar-iv:720p:30s")
+  })
+
+  it("text mode: short script lands in the fine low-end bucket", () => {
+    // 120 chars → ceil(120/12)=10s → bucket 10
+    expect(resolveAiAvatarCreditId({ speechMode: "text", script: "x".repeat(120) }))
+      .toBe("heygen-avatar-iv:720p:10s")
+    // 50 chars → ceil(50/12)=5s → bucket 5
+    expect(resolveAiAvatarCreditId({ speechMode: "text", script: "x".repeat(50) }))
+      .toBe("heygen-avatar-iv:720p:5s")
+  })
+
+  it("text mode with slow voiceSpeed: 1200 chars at 0.5× → 200s → bucket 240s", () => {
+    expect(
+      resolveAiAvatarCreditId({ speechMode: "text", script: "x".repeat(1200), voiceSpeed: 0.5 }),
+    ).toBe("heygen-avatar-iv:720p:240s")
+  })
+
+  it("text mode: 5000-char script at 0.5× → bucket 900s (worst-case coverage)", () => {
+    expect(
+      resolveAiAvatarCreditId({ speechMode: "text", script: "x".repeat(5000), voiceSpeed: 0.5 }),
+    ).toBe("heygen-avatar-iv:720p:900s")
+  })
+
+  it("audio mode WITHOUT probe: modest 120s default (NOT 900s)", () => {
+    expect(resolveAiAvatarCreditId({ speechMode: "audio" }))
+      .toBe("heygen-avatar-iv:720p:120s")
+  })
+
+  it("audio mode WITH __probedDurationSec: buckets by the probed length", () => {
+    // 15s probed audio → bucket 15s (the user-reported scenario)
+    expect(resolveAiAvatarCreditId({ speechMode: "audio", __probedDurationSec: 15 }))
+      .toBe("heygen-avatar-iv:720p:15s")
+    // 7.3s probed → ceil = 8 → bucket 10s
+    expect(resolveAiAvatarCreditId({ speechMode: "audio", __probedDurationSec: 7.3 }))
+      .toBe("heygen-avatar-iv:720p:10s")
+    // 200s probed → bucket 240s
+    expect(resolveAiAvatarCreditId({ speechMode: "audio", __probedDurationSec: 200 }))
+      .toBe("heygen-avatar-iv:720p:240s")
+    // probed > 600 (the audio cap) → bucket 600s, NOT 900s. The worker trims
+    // audio to AI_AVATAR_MAX_AUDIO_SEC, so the reserve caps at the 600s bucket.
+    expect(resolveAiAvatarCreditId({ speechMode: "audio", __probedDurationSec: 1200 }))
+      .toBe("heygen-avatar-iv:720p:600s")
+  })
+
+  it("audio mode: invalid/zero probe falls back to the modest default", () => {
+    expect(resolveAiAvatarCreditId({ speechMode: "audio", __probedDurationSec: 0 }))
+      .toBe("heygen-avatar-iv:720p:120s")
+    expect(resolveAiAvatarCreditId({ speechMode: "audio", __probedDurationSec: -5 }))
+      .toBe("heygen-avatar-iv:720p:120s")
+    expect(resolveAiAvatarCreditId({ speechMode: "audio", __probedDurationSec: NaN }))
+      .toBe("heygen-avatar-iv:720p:120s")
+  })
+
+  it("missing speechMode: modest 120s default", () => {
+    expect(resolveAiAvatarCreditId({})).toBe("heygen-avatar-iv:720p:120s")
+    expect(resolveAiAvatarCreditId(undefined)).toBe("heygen-avatar-iv:720p:120s")
+  })
+
+  it("resolves valid engine + resolution", () => {
+    expect(resolveAiAvatarCreditId({ engine: "avatar-v", resolution: "1080p", speechMode: "audio", __probedDurationSec: 30 }))
+      .toBe("heygen-avatar-v:1080p:30s")
+    expect(resolveAiAvatarCreditId({ engine: "avatar-iv", resolution: "4k", speechMode: "audio", __probedDurationSec: 30 }))
+      .toBe("heygen-avatar-iv:4k:30s")
+  })
+
+  it("falls back engine to avatar-iv on invalid value", () => {
+    expect(resolveAiAvatarCreditId({ engine: "bogus", speechMode: "audio" }))
+      .toBe("heygen-avatar-iv:720p:120s")
+    expect(resolveAiAvatarCreditId({ engine: "avatar-iii", speechMode: "audio" }))
+      .toBe("heygen-avatar-iv:720p:120s")
+  })
+
+  it("falls back resolution to 720p on invalid value", () => {
+    expect(resolveAiAvatarCreditId({ engine: "avatar-v", resolution: "360p", speechMode: "audio" }))
+      .toBe("heygen-avatar-v:720p:120s")
+  })
+
+  it("falls back both to defaults when both are invalid", () => {
+    expect(resolveAiAvatarCreditId({ engine: "bogus", resolution: "360p", speechMode: "audio" }))
+      .toBe("heygen-avatar-iv:720p:120s")
+  })
+
+  it("image source mode: bills at avatar-iv rate even when engine is avatar-v", () => {
+    expect(
+      resolveAiAvatarCreditId({
+        avatarSource: "image",
+        engine: "avatar-v",
+        resolution: "1080p",
+        speechMode: "audio",
+        __probedDurationSec: 30,
+      }),
+    ).toBe("heygen-avatar-iv:1080p:30s")
+  })
+
+  it("image source mode: text-mode buckets by script length at the avatar-iv rate", () => {
+    expect(
+      resolveAiAvatarCreditId({
+        avatarSource: "image",
+        engine: "avatar-v",
+        speechMode: "text",
+        script: "x".repeat(360),
+      }),
+    ).toBe("heygen-avatar-iv:720p:30s")
+  })
+
+  it("always resolves to a member of AI_AVATAR_RESERVE_IDS (no 503 trap)", () => {
+    const probes = [undefined, 0, 1, 7, 15, 30, 90, 200, 901]
+    for (const engine of ["avatar-iv", "avatar-v", "bogus"]) {
+      for (const resolution of ["720p", "1080p", "4k", "360p"]) {
+        for (const probe of probes) {
+          const audioId = resolveAiAvatarCreditId({ engine, resolution, speechMode: "audio", __probedDurationSec: probe })
+          expect(AI_AVATAR_RESERVE_IDS).toContain(audioId)
+        }
+        const textId = resolveAiAvatarCreditId({ engine, resolution, speechMode: "text", script: "x".repeat(2000) })
+        expect(AI_AVATAR_RESERVE_IDS).toContain(textId)
+      }
+    }
+  })
+})
+
+describe("AI_AVATAR_AUDIO_FALLBACK_SEC", () => {
+  it("is a modest 120s (not the 900s top bucket)", () => {
+    expect(AI_AVATAR_AUDIO_FALLBACK_SEC).toBe(120)
+    expect(AI_AVATAR_DURATION_BUCKETS).toContain(AI_AVATAR_AUDIO_FALLBACK_SEC)
+  })
+})
+
+describe("AI_AVATAR_RESERVE_IDS", () => {
+  it("contains exactly 60 unique ids (2 engines × 3 resolutions × 10 buckets)", () => {
+    expect(AI_AVATAR_RESERVE_IDS).toHaveLength(60)
+    expect(new Set(AI_AVATAR_RESERVE_IDS).size).toBe(60)
+  })
+
+  it("contains all expected bucket variants for avatar-iv:720p", () => {
+    for (const b of AI_AVATAR_DURATION_BUCKETS) {
+      expect(AI_AVATAR_RESERVE_IDS).toContain(`heygen-avatar-iv:720p:${b}s`)
+    }
+  })
+
+  it("contains all expected bucket variants for avatar-v:4k", () => {
+    for (const b of AI_AVATAR_DURATION_BUCKETS) {
+      expect(AI_AVATAR_RESERVE_IDS).toContain(`heygen-avatar-v:4k:${b}s`)
+    }
+  })
+
+  it("bucket set has 10 entries", () => {
+    expect(AI_AVATAR_DURATION_BUCKETS).toHaveLength(10)
+  })
+})
+
+describe("AI_AVATAR_MAX_DURATION_SEC", () => {
+  it("is 900 seconds (covers 5000-char@0.5× worst-case text)", () => {
+    expect(AI_AVATAR_MAX_DURATION_SEC).toBe(900)
+  })
+})
+
+describe("AI_AVATAR_MAX_AUDIO_SEC — audio-mode hard cap (worker trims + reserve caps)", () => {
+  it("is 600 seconds and is a real bucket", () => {
+    expect(AI_AVATAR_MAX_AUDIO_SEC).toBe(600)
+    expect(AI_AVATAR_DURATION_BUCKETS).toContain(AI_AVATAR_MAX_AUDIO_SEC)
+  })
+
+  it("a 1800s (30-min) probed audio reserves the 600s bucket, NOT 900s", () => {
+    expect(
+      resolveAiAvatarCreditId({
+        speechMode: "audio",
+        engine: "avatar-iv",
+        resolution: "720p",
+        __probedDurationSec: 1800,
+      }),
+    ).toBe("heygen-avatar-iv:720p:600s")
+  })
+
+  it("a 450s probed audio reserves the 600s bucket (under the cap, normal bucket-up)", () => {
+    expect(
+      resolveAiAvatarCreditId({
+        speechMode: "audio",
+        engine: "avatar-iv",
+        resolution: "720p",
+        __probedDurationSec: 450,
+      }),
+    ).toBe("heygen-avatar-iv:720p:600s")
+  })
+
+  it("exactly 600s probed audio stays in the 600s bucket", () => {
+    expect(resolveAiAvatarCreditId({ speechMode: "audio", __probedDurationSec: 600 }))
+      .toBe("heygen-avatar-iv:720p:600s")
+  })
+
+  it("clamps audio across engines/resolutions to the 600s bucket", () => {
+    expect(
+      resolveAiAvatarCreditId({
+        speechMode: "audio",
+        engine: "avatar-v",
+        resolution: "1080p",
+        __probedDurationSec: 3600,
+      }),
+    ).toBe("heygen-avatar-v:1080p:600s")
+  })
+
+  it("does NOT affect text mode — text can still reach the 900s bucket", () => {
+    // 5000 chars at 0.5× → 834s → 900s bucket, unchanged by the audio cap.
+    expect(
+      resolveAiAvatarCreditId({ speechMode: "text", script: "x".repeat(5000), voiceSpeed: 0.5 }),
+    ).toBe("heygen-avatar-iv:720p:900s")
+  })
+})

package/src/__tests__/apply-video-negative-prompt.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest"
+import { applyVideoNegativePrompt, NATIVE_NEGATIVE_VIDEO_PROVIDERS } from "../model-constants.js"
+
+describe("applyVideoNegativePrompt", () => {
+  it("returns prompt unchanged + nativeNegativePrompt when provider is native", () => {
+    const result = applyVideoNegativePrompt("a cat dancing", "blurry, distorted", "kling")
+    expect(result.prompt).toBe("a cat dancing")
+    expect(result.nativeNegativePrompt).toBe("blurry, distorted")
+  })
+
+  it("injects 'Avoid: …' into prompt for non-native providers", () => {
+    const result = applyVideoNegativePrompt("a cat dancing", "blurry, distorted", "wan-animate-move")
+    expect(result.prompt).toBe("a cat dancing\nAvoid: blurry, distorted")
+    expect(result.nativeNegativePrompt).toBeUndefined()
+  })
+
+  it("returns 'Avoid: …' alone when prompt is empty and provider is non-native", () => {
+    const result = applyVideoNegativePrompt("", "blurry", "veo3")
+    expect(result.prompt).toBe("Avoid: blurry")
+    expect(result.nativeNegativePrompt).toBeUndefined()
+  })
+
+  it("returns 'Avoid: …' alone when prompt is undefined", () => {
+    const result = applyVideoNegativePrompt(undefined, "blurry", "veo3")
+    expect(result.prompt).toBe("Avoid: blurry")
+  })
+
+  it("is a no-op when negativePrompt is empty", () => {
+    const result = applyVideoNegativePrompt("a cat", "", "kling")
+    expect(result.prompt).toBe("a cat")
+    expect(result.nativeNegativePrompt).toBeUndefined()
+  })
+
+  it("is a no-op when negativePrompt is whitespace only", () => {
+    const result = applyVideoNegativePrompt("a cat", "   ", "wan-animate-move")
+    expect(result.prompt).toBe("a cat")
+    expect(result.nativeNegativePrompt).toBeUndefined()
+  })
+
+  it("is a no-op when negativePrompt is undefined", () => {
+    const result = applyVideoNegativePrompt("a cat", undefined, "wan-animate-move")
+    expect(result.prompt).toBe("a cat")
+    expect(result.nativeNegativePrompt).toBeUndefined()
+  })
+
+  it("trims surrounding whitespace before sending native", () => {
+    const result = applyVideoNegativePrompt("a cat", "  blurry  ", "kling-3.0")
+    expect(result.nativeNegativePrompt).toBe("blurry")
+  })
+
+  it("includes the Kling family in the native set", () => {
+    for (const p of ["kling", "kling-turbo", "kling-master", "kling-3.0", "kling-3-omni"]) {
+      expect(NATIVE_NEGATIVE_VIDEO_PROVIDERS.has(p)).toBe(true)
+    }
+  })
+
+  it("includes regular Wan in the native set but excludes Wan Animate", () => {
+    expect(NATIVE_NEGATIVE_VIDEO_PROVIDERS.has("wan")).toBe(true)
+    expect(NATIVE_NEGATIVE_VIDEO_PROVIDERS.has("wan-i2v")).toBe(true)
+    expect(NATIVE_NEGATIVE_VIDEO_PROVIDERS.has("wan-animate-move")).toBe(false)
+    expect(NATIVE_NEGATIVE_VIDEO_PROVIDERS.has("wan-animate-replace")).toBe(false)
+  })
+
+  it("excludes VEO / Hailuo / Sora / Bytedance / Grok families", () => {
+    for (const p of [
+      "veo3", "veo3.1", "veo3_lite",
+      "minimax", "hailuo-2.3-pro", "hailuo-2.3", "hailuo-standard",
+      "sora2", "sora2-pro",
+      "bytedance-lite", "bytedance-pro",
+      "grok", "grok-i2v",
+      "seedance", "seedance-2",
+    ]) {
+      expect(NATIVE_NEGATIVE_VIDEO_PROVIDERS.has(p)).toBe(false)
+    }
+  })
+})

package/src/__tests__/attach-columns.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest"
+import { CHARACTER_ATTACH_COLUMNS, OBJECT_ATTACH_COLUMNS, LOCATION_ATTACH_COLUMNS, CREATURE_ATTACH_COLUMNS } from "../entity-asset-types.js"
+
+describe("attach columns include the reference-sheet buckets", () => {
+  it("character gains sheets, detail_closeups, outfit_variations", () => {
+    for (const c of ["sheets", "detail_closeups", "outfit_variations"]) expect(CHARACTER_ATTACH_COLUMNS).toContain(c)
+    // originals preserved
+    for (const c of ["expressions", "poses", "angles", "body_angles", "lighting_variations"]) expect(CHARACTER_ATTACH_COLUMNS).toContain(c)
+  })
+  it("object gains sheets, detail_closeups (NOT outfit_variations)", () => {
+    for (const c of ["sheets", "detail_closeups"]) expect(OBJECT_ATTACH_COLUMNS).toContain(c)
+    expect(OBJECT_ATTACH_COLUMNS).not.toContain("outfit_variations")
+    for (const c of ["angles", "materials", "variations", "motion_clips"]) expect(OBJECT_ATTACH_COLUMNS).toContain(c)
+  })
+  it("location gains sheets, detail_closeups", () => {
+    for (const c of ["sheets", "detail_closeups"]) expect(LOCATION_ATTACH_COLUMNS).toContain(c)
+    for (const c of ["time_of_day", "weather", "seasons", "angles", "lighting", "atmosphere_motions"]) expect(LOCATION_ATTACH_COLUMNS).toContain(c)
+  })
+})
+
+describe("CREATURE_ATTACH_COLUMNS", () => {
+  it("has the worker-attachable creature asset columns (poses, not materials)", () => {
+    expect([...CREATURE_ATTACH_COLUMNS].sort()).toEqual(
+      ["angles", "detail_closeups", "motion_clips", "poses", "sheets", "variations"].sort(),
+    )
+    expect(CREATURE_ATTACH_COLUMNS).not.toContain("materials")
+  })
+})

package/src/__tests__/audio-crossfade-curves.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest"
+import {
+  AUDIO_CROSSFADE_CURVES,
+  AUDIO_CROSSFADE_CURVE_IDS,
+  DEFAULT_AUDIO_CROSSFADE_CURVE_ID,
+  resolveAudioCrossfadeCurve,
+} from "../audio-crossfade-curves.js"
+
+describe("AUDIO_CROSSFADE_CURVES catalog", () => {
+  it("has unique ids and ffmpeg names", () => {
+    const ids = AUDIO_CROSSFADE_CURVES.map((c) => c.id)
+    const ffmpeg = AUDIO_CROSSFADE_CURVES.map((c) => c.ffmpeg)
+    expect(new Set(ids).size).toBe(ids.length)
+    expect(new Set(ffmpeg).size).toBe(ffmpeg.length)
+  })
+
+  it("default id exists in the catalog", () => {
+    expect(AUDIO_CROSSFADE_CURVE_IDS).toContain(DEFAULT_AUDIO_CROSSFADE_CURVE_ID)
+  })
+
+  it("resolveAudioCrossfadeCurve maps known ids to acrossfade names", () => {
+    expect(resolveAudioCrossfadeCurve("linear")).toBe("tri")
+    expect(resolveAudioCrossfadeCurve("equal-power")).toBe("qsin")
+    expect(resolveAudioCrossfadeCurve("smooth")).toBe("hsin")
+    expect(resolveAudioCrossfadeCurve("logarithmic")).toBe("log")
+    expect(resolveAudioCrossfadeCurve("exponential")).toBe("exp")
+  })
+
+  it("resolveAudioCrossfadeCurve falls back to `tri` for undefined or unknown", () => {
+    expect(resolveAudioCrossfadeCurve(undefined)).toBe("tri")
+    expect(resolveAudioCrossfadeCurve("not-a-curve")).toBe("tri")
+  })
+})

package/src/__tests__/build-model-menu.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest"
+import {
+  buildModelMenu,
+  resolutionOptionsByKind,
+  aspectRatioOptionsByKind,
+  durationsByMode,
+} from "../model-catalog.js"
+
+// Real catalog ids (asserted to exist, kinds asserted) — no catalog mocking, so
+// the test pins behavior against the live catalog and the accessor helpers it
+// composes. Expected capabilities are DERIVED from those accessors below so the
+// assertions track catalog changes instead of hardcoding seconds/resolutions.
+const IMG_A = "flux-2-max"
+const IMG_B = "nano-banana-pro"
+const VID = "veo3"
+
+describe("buildModelMenu", () => {
+  it("preserves allowlist order and drops ids absent from the catalog", () => {
+    const rows = buildModelMenu("image", [IMG_A, "does-not-exist", IMG_B])
+    expect(rows.map((r) => r.id)).toEqual([IMG_A, IMG_B])
+  })
+
+  it("drops ids of the wrong kind (a video id under kind: image)", () => {
+    expect(buildModelMenu("image", [VID])).toEqual([])
+  })
+
+  it("derives resolutions / aspectRatios from the kind-scoped accessors", () => {
+    const [row] = buildModelMenu("image", [IMG_B])
+    expect(row.resolutions).toEqual(resolutionOptionsByKind("image")[IMG_B])
+    expect(row.aspectRatios).toEqual(aspectRatioOptionsByKind("image")[IMG_B])
+    // Image models have no i2v/t2v modes → no duration lever.
+    expect(row.durations).toEqual([])
+  })
+
+  it("derives video durations as the sorted-unique i2v+t2v union, mapped to {value,label}", () => {
+    const i2v = durationsByMode("i2v")
+    const t2v = durationsByMode("t2v")
+    const expected = Array.from(new Set([...(i2v[VID] ?? []), ...(t2v[VID] ?? [])]))
+      .sort((a, b) => a - b)
+      .map((n) => ({ value: n, label: `${n}s` }))
+    // Guard the fixture itself: VID must actually carry durations, else the
+    // assertion would pass vacuously on an empty union.
+    expect(expected.length).toBeGreaterThan(0)
+
+    const [row] = buildModelMenu("video", [VID])
+    expect(row.durations).toEqual(expected)
+  })
+
+  it("returns fresh arrays — mutating one row never affects a later call", () => {
+    const first = buildModelMenu("image", [IMG_B])
+    first[0].resolutions.push({ value: "tampered", label: "tampered" })
+    first[0].aspectRatios.push({ value: "tampered", label: "tampered" })
+
+    const second = buildModelMenu("image", [IMG_B])
+    expect(second[0].resolutions).toEqual(resolutionOptionsByKind("image")[IMG_B])
+    expect(second[0].aspectRatios).toEqual(aspectRatioOptionsByKind("image")[IMG_B])
+  })
+})