@nodaro/shared 1.4.1

package/src/__tests__/location-mention-slug.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect } from "vitest"
+import {
+  locationMentionSlug,
+  locationUsageModeLabel,
+  parseLocationMentionToken,
+  findLocationMentionTokens,
+  isLocationUsageMode,
+  LOCATION_USAGE_MODES,
+} from "../location-mention-slug.js"
+
+describe("LOCATION_USAGE_MODES", () => {
+  it("has exactly the 4 spec-mandated modes", () => {
+    expect(LOCATION_USAGE_MODES).toEqual(["identical", "style", "layout", "none"])
+  })
+
+  it("isLocationUsageMode narrows known values", () => {
+    expect(isLocationUsageMode("identical")).toBe(true)
+    expect(isLocationUsageMode("layout")).toBe(true)
+    expect(isLocationUsageMode("face")).toBe(false) // character-only mode
+    expect(isLocationUsageMode("bogus")).toBe(false)
+  })
+})
+
+describe("locationUsageModeLabel", () => {
+  it("returns a human-readable label per mode", () => {
+    expect(locationUsageModeLabel("identical")).toBe("Match exactly")
+    expect(locationUsageModeLabel("style")).toBe("Style / mood only")
+    expect(locationUsageModeLabel("layout")).toBe("Layout / framing only")
+    expect(locationUsageModeLabel("none")).toBe("No textual bias")
+  })
+
+  it("returns a distinct label per mode (no accidental aliasing)", () => {
+    const labels = LOCATION_USAGE_MODES.map(locationUsageModeLabel)
+    const unique = new Set(labels)
+    expect(unique.size).toBe(LOCATION_USAGE_MODES.length)
+  })
+
+  it("covers every entry in LOCATION_USAGE_MODES (exhaustive switch)", () => {
+    for (const m of LOCATION_USAGE_MODES) {
+      const label = locationUsageModeLabel(m)
+      expect(typeof label).toBe("string")
+      expect(label.length).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe("locationMentionSlug", () => {
+  it("lowercases, strips non-alphanumeric, collapses runs", () => {
+    expect(locationMentionSlug("Old Library")).toBe("old-library")
+    expect(locationMentionSlug("Forest at Night!")).toBe("forest-at-night")
+    expect(locationMentionSlug("  Spaceship-3000  ")).toBe("spaceship-3000")
+    expect(locationMentionSlug("___foo___")).toBe("foo")
+  })
+
+  it("returns empty string for inputs that have no alphanumerics", () => {
+    expect(locationMentionSlug("!!!")).toBe("")
+    expect(locationMentionSlug("")).toBe("")
+  })
+})
+
+describe("parseLocationMentionToken", () => {
+  describe("rejection cases", () => {
+    it("returns null for non-@ tokens", () => {
+      expect(parseLocationMentionToken("oldlibrary:1")).toBeNull()
+      expect(parseLocationMentionToken("")).toBeNull()
+    })
+
+    it("returns null for tokens missing the index segment", () => {
+      expect(parseLocationMentionToken("@oldlibrary")).toBeNull()
+    })
+
+    it("returns null for tokens with non-numeric index", () => {
+      expect(parseLocationMentionToken("@oldlibrary:abc")).toBeNull()
+      expect(parseLocationMentionToken("@oldlibrary:0")).toBeNull() // index must be ≥ 1
+    })
+
+    it("returns null for tokens with more than 4 segments", () => {
+      expect(
+        parseLocationMentionToken("@oldlibrary:1:weather/rain:style:extra"),
+      ).toBeNull()
+    })
+
+    it("returns null for malformed slug (uppercase / leading digit)", () => {
+      expect(parseLocationMentionToken("@OldLibrary:1")).toBeNull()
+      expect(parseLocationMentionToken("@3000library:1")).toBeNull()
+    })
+
+    it("returns null for 4-part with no slash in 3rd segment", () => {
+      expect(parseLocationMentionToken("@oldlibrary:1:weather:style")).toBeNull()
+    })
+
+    it("returns null for 4-part with unknown 4th-segment mode", () => {
+      expect(
+        parseLocationMentionToken("@oldlibrary:1:weather/rain:face"),
+      ).toBeNull()
+    })
+
+    it("3-part with a bare non-mode slug parses as a custom ROLE (parser gate removed, F2)", () => {
+      // Widened in the reference-roles F2 follow-up: any valid slash-less,
+      // non-mode 3rd segment is accepted as a role verbatim (previously the
+      // parser preset-gated `foobar` → null). Legacy stays literal via the
+      // resolver's `if (t.role) continue` guard, not the parser.
+      expect(parseLocationMentionToken("@oldlibrary:1:foobar")).toEqual({
+        locationSlug: "oldlibrary",
+        imageIndex: 1,
+        bucket: null,
+        variant: null,
+        usageMode: null,
+        role: "foobar",
+      })
+    })
+  })
+
+  describe("accepted shapes", () => {
+    it("2-part: canonical, default mode", () => {
+      expect(parseLocationMentionToken("@oldlibrary:1")).toEqual({
+        locationSlug: "oldlibrary",
+        imageIndex: 1,
+        bucket: null,
+        variant: null,
+        usageMode: null,
+      })
+    })
+
+    it("3-part bucket/variant", () => {
+      expect(parseLocationMentionToken("@oldlibrary:1:weather/rain")).toEqual({
+        locationSlug: "oldlibrary",
+        imageIndex: 1,
+        bucket: "weather",
+        variant: "rain",
+        usageMode: null,
+      })
+    })
+
+    it("3-part with hyphenated bucket/variant", () => {
+      expect(
+        parseLocationMentionToken("@oldlibrary:1:time-of-day/golden-hour"),
+      ).toEqual({
+        locationSlug: "oldlibrary",
+        imageIndex: 1,
+        bucket: "time-of-day",
+        variant: "golden-hour",
+        usageMode: null,
+      })
+    })
+
+    it("3-part canonical + mode keyword", () => {
+      expect(parseLocationMentionToken("@oldlibrary:1:layout")).toEqual({
+        locationSlug: "oldlibrary",
+        imageIndex: 1,
+        bucket: null,
+        variant: null,
+        usageMode: "layout",
+      })
+    })
+
+    it("4-part bucket/variant + mode override", () => {
+      expect(
+        parseLocationMentionToken("@oldlibrary:1:weather/rain:style"),
+      ).toEqual({
+        locationSlug: "oldlibrary",
+        imageIndex: 1,
+        bucket: "weather",
+        variant: "rain",
+        usageMode: "style",
+      })
+    })
+
+    it("hyphenated location slug", () => {
+      expect(parseLocationMentionToken("@old-library:2:lighting/neon")).toEqual({
+        locationSlug: "old-library",
+        imageIndex: 2,
+        bucket: "lighting",
+        variant: "neon",
+        usageMode: null,
+      })
+    })
+  })
+})
+
+describe("findLocationMentionTokens", () => {
+  it("finds canonical mention against known slug", () => {
+    const tokens = findLocationMentionTokens(
+      "Hero stands in @oldlibrary:1 reading.",
+      ["oldlibrary"],
+    )
+    expect(tokens).toHaveLength(1)
+    expect(tokens[0].token).toBe("@oldlibrary:1")
+    expect(tokens[0].bucket).toBeNull()
+    expect(tokens[0].variant).toBeNull()
+  })
+
+  it("finds bucket/variant mention", () => {
+    const tokens = findLocationMentionTokens(
+      "Set in @oldlibrary:1:weather/rain.",
+      ["oldlibrary"],
+    )
+    expect(tokens).toHaveLength(1)
+    expect(tokens[0].bucket).toBe("weather")
+    expect(tokens[0].variant).toBe("rain")
+  })
+
+  it("finds multiple mentions in one prompt", () => {
+    const tokens = findLocationMentionTokens(
+      "@oldlibrary:1 at dawn, then @forest:2:weather/storm later.",
+      ["oldlibrary", "forest"],
+    )
+    expect(tokens).toHaveLength(2)
+    expect(tokens[0].locationSlug).toBe("oldlibrary")
+    expect(tokens[1].locationSlug).toBe("forest")
+    expect(tokens[1].bucket).toBe("weather")
+    expect(tokens[1].variant).toBe("storm")
+  })
+
+  it("skips tokens whose slug isn't in knownLocationSlugs", () => {
+    const tokens = findLocationMentionTokens(
+      "@kira:1:smile then @oldlibrary:1:weather/rain.",
+      ["oldlibrary"], // kira is a character, not in this set
+    )
+    expect(tokens).toHaveLength(1)
+    expect(tokens[0].locationSlug).toBe("oldlibrary")
+  })
+
+  it("reports the correct offset for each token", () => {
+    const prompt = "in @oldlibrary:1 at"
+    const tokens = findLocationMentionTokens(prompt, ["oldlibrary"])
+    expect(tokens[0].offset).toBe(prompt.indexOf("@"))
+  })
+
+  it("does not match @ preceded by alphanumeric (email-like)", () => {
+    const tokens = findLocationMentionTokens(
+      "tal@oldlibrary:1 visited",
+      ["oldlibrary"],
+    )
+    expect(tokens).toHaveLength(0)
+  })
+
+  it("matches @ at start of prompt", () => {
+    const tokens = findLocationMentionTokens(
+      "@oldlibrary:1 stood empty.",
+      ["oldlibrary"],
+    )
+    expect(tokens).toHaveLength(1)
+    expect(tokens[0].offset).toBe(0)
+  })
+})

package/src/__tests__/locations-coverage-critic-schema.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from "vitest"
+import {
+  LocationsCoverageCriticIssueSchema,
+  LocationsCoverageCriticVerdictSchema,
+} from "../pipeline-types.js"
+
+/**
+ * Regression — Sonnet routinely emits `"location_key": null` for issues
+ * like `redundant_location` that flag a structural problem without
+ * pointing at a specific key. The schema used to be `.optional()` which
+ * accepts `undefined` but NOT `null`, so those emits failed Zod
+ * validation, exhausted the critic retry budget, and killed Stage 1
+ * with `locations_coverage validation failed after 2 attempts:
+ * issues.N.location_key: Expected string, received null`. Documented
+ * in pipeline aa495c75 (2026-05-26).
+ *
+ * Fix: `.nullish()` (= `.optional().nullable()`) accepts undefined OR
+ * null OR string. Mirrors the existing `scene_index` treatment.
+ */
+describe("LocationsCoverageCriticIssueSchema — null location_key tolerance", () => {
+  it("accepts location_key: null on a structural issue", () => {
+    const parsed = LocationsCoverageCriticIssueSchema.safeParse({
+      severity: "warning",
+      issue_type: "redundant_location",
+      description: "Two locations describe the same desert exterior.",
+      suggested_fix: "Merge into one location.",
+      scene_index: null,
+      location_key: null,
+    })
+    expect(parsed.success).toBe(true)
+  })
+
+  it("accepts location_key: undefined (omitted)", () => {
+    const parsed = LocationsCoverageCriticIssueSchema.safeParse({
+      severity: "warning",
+      issue_type: "redundant_location",
+      description: "x",
+      suggested_fix: "y",
+      scene_index: null,
+    })
+    expect(parsed.success).toBe(true)
+  })
+
+  it("accepts location_key: 'some-key' (the original happy path)", () => {
+    const parsed = LocationsCoverageCriticIssueSchema.safeParse({
+      severity: "blocking",
+      issue_type: "orphan_location",
+      description: "Scene 3 references desert_road but it's not in the roster.",
+      suggested_fix: "Add desert_road to plan.locations.",
+      scene_index: 3,
+      location_key: "desert_road",
+    })
+    expect(parsed.success).toBe(true)
+  })
+
+  it("accepts a full verdict with a mix of null + string + omitted location_key", () => {
+    const parsed = LocationsCoverageCriticVerdictSchema.safeParse({
+      verdict: "fail",
+      issues: [
+        {
+          severity: "blocking",
+          issue_type: "orphan_location",
+          description: "x",
+          suggested_fix: "y",
+          scene_index: 1,
+          location_key: "loc1",
+        },
+        {
+          severity: "warning",
+          issue_type: "redundant_location",
+          description: "x",
+          suggested_fix: "y",
+          scene_index: null,
+          location_key: null, // ← used to crash here
+        },
+        {
+          severity: "warning",
+          issue_type: "name_too_similar",
+          description: "x",
+          suggested_fix: "y",
+          scene_index: null,
+          // omitted location_key
+        },
+      ],
+    })
+    expect(parsed.success).toBe(true)
+    if (parsed.success) {
+      expect(parsed.data.issues).toHaveLength(3)
+      expect(parsed.data.issues[1]?.location_key).toBeNull()
+    }
+  })
+})

package/src/__tests__/loop-delimiter.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest"
+import { splitByLoopDelimiter, NO_SPLIT_DELIMITER } from "../loop-delimiter.js"
+
+describe("splitByLoopDelimiter", () => {
+  it("defaults to newline when no columns supplied", () => {
+    expect(splitByLoopDelimiter("a\nb\nc", undefined)).toEqual(["a", "b", "c"])
+  })
+
+  it("defaults to newline when first text column has no splitDelimiter", () => {
+    expect(splitByLoopDelimiter("a\nb", [{ type: "text" }])).toEqual(["a", "b"])
+  })
+
+  it("splits by the configured delimiter", () => {
+    expect(
+      splitByLoopDelimiter("a,b,c", [{ type: "text", splitDelimiter: "," }]),
+    ).toEqual(["a", "b", "c"])
+  })
+
+  it("returns the input as a single item when delimiter is the no-split sentinel", () => {
+    expect(
+      splitByLoopDelimiter("a\nb\nc", [{ type: "text", splitDelimiter: NO_SPLIT_DELIMITER }]),
+    ).toEqual(["a\nb\nc"])
+  })
+
+  it("returns empty array when no-split is selected and input is whitespace", () => {
+    expect(
+      splitByLoopDelimiter("   \n   ", [{ type: "text", splitDelimiter: NO_SPLIT_DELIMITER }]),
+    ).toEqual([])
+  })
+
+  it("ignores non-text columns when picking the splitDelimiter", () => {
+    expect(
+      splitByLoopDelimiter("a;b", [
+        { type: "image", splitDelimiter: "," },
+        { type: "text", splitDelimiter: ";" },
+      ]),
+    ).toEqual(["a", "b"])
+  })
+})

package/src/__tests__/lottie-slots.test.ts

@@ -0,0 +1,245 @@
+import { describe, it, expect } from "vitest"
+import {
+  normalizeLottieLayers,
+  applySlots,
+  describeSlotControl,
+  rgbaArrayToHex,
+  hexToRgbaArray,
+  listSlotSids,
+  humanizeSlotSid,
+  deriveLottieSlotFields,
+  LOTTIE_SLOT_FIELD_PREFIX,
+} from "../lottie-slots.js"
+
+const slots = {
+  primaryColor: { p: { a: 0, k: [1, 0, 0, 1] } }, // canonical: p = property object
+  nameText: { p: "Jane Doe" },                     // raw value form
+}
+
+describe("applySlots", () => {
+  it("replaces a {sid} property with the slot default (property-object p)", () => {
+    const lottie = { layers: [{ shapes: [{ ty: "fl", c: { sid: "primaryColor" } }] }] }
+    const out = applySlots(lottie, slots, {})
+    expect((out as any).layers[0].shapes[0].c).toEqual({ a: 0, k: [1, 0, 0, 1] })
+  })
+
+  it("override wins over default and is wrapped as {a:0,k:value} preserving property-object shape", () => {
+    const lottie = { layers: [{ shapes: [{ ty: "fl", c: { sid: "primaryColor" } }] }] }
+    const out = applySlots(lottie, slots, { primaryColor: [0, 1, 0, 1] })
+    expect((out as any).layers[0].shapes[0].c).toEqual({ a: 0, k: [0, 1, 0, 1] })
+  })
+
+  it("substitutes raw slot values verbatim (text-document position)", () => {
+    // s.t is a RAW STRING position (lottie-web's buildFinalText iterates chars);
+    // the slot's bare-string p must land there unwrapped.
+    const lottie = { layers: [{ t: { d: { k: [{ s: { t: { sid: "nameText" } } }] } } }] }
+    const out = applySlots(lottie, slots, {})
+    expect((out as any).layers[0].t.d.k[0].s.t).toBe("Jane Doe")
+  })
+
+  it("raw override on a raw-default slot substitutes verbatim", () => {
+    const lottie = { layers: [{ t: { d: { k: [{ s: { t: { sid: "nameText" } } }] } } }] }
+    const out = applySlots(lottie, { nameText: { p: "Jane Doe" } }, { nameText: "Ada Lovelace" })
+    const value = (out as any).layers[0].t.d.k[0].s.t
+    expect(value).toBe("Ada Lovelace")
+    expect(typeof value).toBe("string")
+  })
+
+  it("point slot ([x,y] property object) round-trips with an override", () => {
+    const lottie = { layers: [{ shapes: [{ ty: "rc", s: { sid: "barSize" } }] }] }
+    const out = applySlots(lottie, { barSize: { p: { a: 0, k: [360, 6] } } }, { barSize: [400, 8] })
+    expect((out as any).layers[0].shapes[0].s).toEqual({ a: 0, k: [400, 8] })
+  })
+
+  it("override on a missing-slot sid substitutes the raw override verbatim", () => {
+    const lottie = { layers: [{ t: { d: { k: [{ s: { t: { sid: "ghostText" } } }] } } }] }
+    const out = applySlots(lottie, {}, { ghostText: "Ada Lovelace" })
+    expect((out as any).layers[0].t.d.k[0].s.t).toBe("Ada Lovelace")
+  })
+
+  it("missing sid is left untouched", () => {
+    const lottie = { layers: [{ shapes: [{ ty: "fl", c: { sid: "ghost" } }] }] }
+    const out = applySlots(lottie, {}, {})
+    expect((out as any).layers[0].shapes[0].c).toEqual({ sid: "ghost" })
+  })
+
+  it("annotation-form sid node is replaced when the slot exists", () => {
+    const lottie = { layers: [{ shapes: [{ ty: "fl", c: { a: 0, k: [0, 0, 1, 1], sid: "primaryColor" } }] }] }
+    const out = applySlots(lottie, slots, {})
+    expect((out as any).layers[0].shapes[0].c).toEqual({ a: 0, k: [1, 0, 0, 1] })
+  })
+
+  it("reaches sids nested inside precomp assets and arrays", () => {
+    const lottie = { assets: [{ id: "comp_0", layers: [{ shapes: [{ it: [{ ty: "st", c: { sid: "primaryColor" } }] }] }] }] }
+    const out = applySlots(lottie, slots, {})
+    expect((out as any).assets[0].layers[0].shapes[0].it[0].c).toEqual({ a: 0, k: [1, 0, 0, 1] })
+  })
+
+  it("does not mutate any of its inputs", () => {
+    const lottie = { layers: [{ shapes: [{ ty: "fl", c: { sid: "primaryColor" } }] }] }
+    const lottieCopy = structuredClone(lottie)
+    const slotsCopy = structuredClone(slots)
+    const overrides = { primaryColor: [0, 1, 0, 1] }
+    const overridesCopy = structuredClone(overrides)
+    applySlots(lottie, slots, overrides)
+    expect(lottie).toEqual(lottieCopy)
+    expect(slots).toEqual(slotsCopy)
+    expect(overrides).toEqual(overridesCopy)
+  })
+})
+
+describe("describeSlotControl", () => {
+  it("maps RGBA arrays to color (unwrapping property-object p)", () => {
+    expect(describeSlotControl({ p: { a: 0, k: [1, 0, 0, 1] } })).toEqual({ kind: "color", value: [1, 0, 0, 1] })
+  })
+  it("maps strings to text (raw-value p, Amendment 1 bare string)", () => {
+    expect(describeSlotControl({ p: "Jane" })).toEqual({ kind: "text", value: "Jane" })
+  })
+  it("maps numbers to number", () => {
+    expect(describeSlotControl({ p: { a: 0, k: 42 } })).toEqual({ kind: "number", value: 42 })
+  })
+  it("maps 2-vectors to point", () => {
+    expect(describeSlotControl({ p: { a: 0, k: [10, 20] } })).toEqual({ kind: "point", value: [10, 20] })
+  })
+  it("returns null for animated property objects (a:1)", () => {
+    expect(describeSlotControl({ p: { a: 1, k: [{ t: 0, s: [0] }] } })).toBeNull()
+  })
+  it("returns null for unknown shapes and non-objects", () => {
+    expect(describeSlotControl({ p: { foo: "bar" } })).toBeNull()
+    expect(describeSlotControl({ p: [1, 2, 3] })).toBeNull()
+    expect(describeSlotControl(null)).toBeNull()
+    expect(describeSlotControl("nope")).toBeNull()
+  })
+})
+
+describe("color conversion", () => {
+  it("round-trips rgba<->hex", () => {
+    expect(rgbaArrayToHex([1, 0, 0, 1])).toBe("#ff0000")
+    expect(hexToRgbaArray("#ff0000")).toEqual([1, 0, 0, 1])
+    expect(hexToRgbaArray("#00ff0080")).toEqual([0, 1, 0, expect.closeTo(0.5, 1)])
+  })
+  it("emits 8-digit hex when alpha < 1", () => {
+    const hex = rgbaArrayToHex([0, 1, 0, 0.5])
+    expect(hex).toBe("#00ff0080")
+  })
+  it("omits the alpha component when alpha === 1", () => {
+    expect(rgbaArrayToHex([0, 0, 1, 1])).toBe("#0000ff")
+  })
+  it("clamps out-of-range components and lowercases output", () => {
+    expect(rgbaArrayToHex([2, -1, 0.5, 1])).toBe("#ff0080")
+  })
+  it("expands #rgb shorthand", () => {
+    expect(hexToRgbaArray("#f00")).toEqual([1, 0, 0, 1])
+  })
+})
+
+describe("listSlotSids", () => {
+  it("returns manifest sids in insertion order", () => {
+    expect(listSlotSids({ a: { p: 1 }, b: { p: 2 } })).toEqual(["a", "b"])
+  })
+  it("tolerates undefined", () => {
+    expect(listSlotSids(undefined as unknown as Record<string, unknown>)).toEqual([])
+  })
+})
+
+describe("humanizeSlotSid", () => {
+  it("splits camelCase into Title Case", () => {
+    expect(humanizeSlotSid("primaryColor")).toBe("Primary Color")
+  })
+  it("converts snake_case and kebab-case", () => {
+    expect(humanizeSlotSid("bar_size")).toBe("Bar Size")
+    expect(humanizeSlotSid("name-text")).toBe("Name Text")
+  })
+  it("handles a digit boundary and a single word", () => {
+    expect(humanizeSlotSid("color2")).toBe("Color2")
+    expect(humanizeSlotSid("title")).toBe("Title")
+  })
+})
+
+describe("deriveLottieSlotFields", () => {
+  const plan = {
+    planType: "lottie-graphic",
+    slots: {
+      primaryColor: { p: { a: 0, k: [1, 0, 0, 1] } }, // color
+      nameText: { p: "Jane Doe" },                     // text
+      opacity: { p: { a: 0, k: 0.5 } },                // number ≤ 1 → unit slider
+      barWidth: { p: { a: 0, k: 360 } },               // number > 1 → 0..ceil(*2)
+      offset: { p: { a: 0, k: [10, 20] } },            // point → SKIPPED
+    },
+  }
+
+  it("derives one field per non-point slot with prefixed keys + right types/defaults", () => {
+    const fields = deriveLottieSlotFields(plan)
+    // point slot dropped → 4 fields.
+    expect(fields).toHaveLength(4)
+    expect(fields.every((f) => f.key.startsWith(LOTTIE_SLOT_FIELD_PREFIX))).toBe(true)
+
+    const byKey = Object.fromEntries(fields.map((f) => [f.key, f]))
+
+    expect(byKey["slot:primaryColor"]).toMatchObject({
+      label: "Primary Color",
+      type: "color",
+      defaultValue: "#ff0000",
+    })
+    expect(byKey["slot:nameText"]).toMatchObject({
+      label: "Name Text",
+      type: "text",
+      defaultValue: "Jane Doe",
+    })
+    // 0..1 value → unit slider.
+    expect(byKey["slot:opacity"]).toMatchObject({
+      type: "slider",
+      min: 0,
+      max: 1,
+      step: 0.01,
+      defaultValue: 0.5,
+    })
+    // >1 value → 0..ceil(value*2), step 1.
+    expect(byKey["slot:barWidth"]).toMatchObject({
+      type: "slider",
+      min: 0,
+      max: 720,
+      step: 1,
+      defaultValue: 360,
+    })
+    // point slot is intentionally not exposed.
+    expect(byKey["slot:offset"]).toBeUndefined()
+  })
+
+  it("returns [] for an elements (non-lottie) plan", () => {
+    expect(deriveLottieSlotFields({ planType: "elements", slots: { a: { p: "x" } } })).toEqual([])
+  })
+
+  it("returns [] for undefined / empty / non-object slots", () => {
+    expect(deriveLottieSlotFields(undefined)).toEqual([])
+    expect(deriveLottieSlotFields({ planType: "lottie-graphic" })).toEqual([])
+    expect(deriveLottieSlotFields({ planType: "lottie-graphic", slots: {} })).toEqual([])
+  })
+})
+
+describe("normalizeLottieLayers", () => {
+  it("defaults st/sr on root and precomp asset layers, preserving authored values", () => {
+    const doc = {
+      layers: [{ ty: 4, ip: 0, op: 150 }, { ty: 5, ip: 0, op: 150, st: 12, sr: 2 }],
+      assets: [{ id: "pre_0", layers: [{ ty: 4, ip: 0, op: 60 }] }, { id: "img", p: "x" }],
+    } as Record<string, unknown>
+    const out = normalizeLottieLayers(doc)
+    expect(out).toBe(doc) // in-place
+    const layers = doc.layers as Array<Record<string, unknown>>
+    expect(layers[0].st).toBe(0)
+    expect(layers[0].sr).toBe(1)
+    expect(layers[1].st).toBe(12)
+    expect(layers[1].sr).toBe(2)
+    const assetLayers = (doc.assets as Array<Record<string, unknown>>)[0].layers as Array<Record<string, unknown>>
+    expect(assetLayers[0].st).toBe(0)
+    expect(assetLayers[0].sr).toBe(1)
+  })
+
+  it("tolerates non-object input and malformed members", () => {
+    expect(normalizeLottieLayers(null)).toBe(null)
+    expect(normalizeLottieLayers("x")).toBe("x")
+    const doc = { layers: [null, "x", { ty: 4 }] } as Record<string, unknown>
+    normalizeLottieLayers(doc)
+    expect((doc.layers as Array<Record<string, unknown> | null | string>)[2]).toMatchObject({ st: 0, sr: 1 })
+  })
+})

package/src/__tests__/model-catalog-flux2-resolutions.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest"
+import { resolutionOptionsByKind } from "../model-catalog.js"
+
+const FLUX2_MP_VALUES = ["0.5 MP", "1 MP", "2 MP", "4 MP"]
+const FLUX2_MODELS = ["flux-2-klein", "flux-2-pro", "flux-2-max"]
+
+describe("resolutionOptionsByKind('image') — Flux 2 models expose all four MP tiers", () => {
+  const imageResolutions = resolutionOptionsByKind("image")
+
+  for (const model of FLUX2_MODELS) {
+    it(`${model} has all four MP resolution options`, () => {
+      const opts = imageResolutions[model]
+      expect(opts, `${model} missing from resolutionOptionsByKind("image")`).toBeDefined()
+      const values = opts!.map((o) => o.value)
+      for (const mp of FLUX2_MP_VALUES) {
+        expect(values, `${model} missing "${mp}"`).toContain(mp)
+      }
+      expect(values).toHaveLength(4)
+    })
+  }
+})

package/src/__tests__/model-constants-location.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest"
+import { LOCATION_ATMOSPHERE_PROVIDERS, type LocationAtmosphereProvider } from "../model-constants.js"
+
+describe("LOCATION_ATMOSPHERE_PROVIDERS", () => {
+  it("has 6 i2v providers", () => {
+    expect(LOCATION_ATMOSPHERE_PROVIDERS).toEqual([
+      "kling",
+      "kling-turbo",
+      "kling-3.0",
+      "wan-i2v",
+      "wan-2.7-i2v",
+      "seedance-2",
+    ])
+  })
+
+  it("LocationAtmosphereProvider union derives from the constant", () => {
+    const x: LocationAtmosphereProvider = "kling-3.0"
+    expect(LOCATION_ATMOSPHERE_PROVIDERS.includes(x)).toBe(true)
+  })
+})