@nodaro/shared 1.4.1

package/src/__tests__/character-aspect-defaults.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from "vitest"
+import {
+  CHARACTER_ASPECT_DEFAULTS,
+  CHARACTER_ASPECT_OPTIONS,
+  isCharacterAspectRatio,
+  resolveCharacterAspectRatio,
+} from "../character-aspect-defaults.js"
+
+describe("CHARACTER_ASPECT_OPTIONS", () => {
+  it("exposes exactly the 4 supported values in canonical order", () => {
+    expect(CHARACTER_ASPECT_OPTIONS).toEqual(["1:1", "3:4", "16:9", "9:16"])
+  })
+})
+
+describe("isCharacterAspectRatio", () => {
+  it("accepts every option in the registry", () => {
+    for (const ar of CHARACTER_ASPECT_OPTIONS) {
+      expect(isCharacterAspectRatio(ar)).toBe(true)
+    }
+  })
+
+  it("rejects values outside the union", () => {
+    expect(isCharacterAspectRatio("4:3")).toBe(false)
+    expect(isCharacterAspectRatio("21:9")).toBe(false)
+    expect(isCharacterAspectRatio("")).toBe(false)
+    expect(isCharacterAspectRatio("1:1 ")).toBe(false)
+    expect(isCharacterAspectRatio("1x1")).toBe(false)
+  })
+})
+
+describe("CHARACTER_ASPECT_DEFAULTS", () => {
+  it("matches the per-asset-type spec table", () => {
+    expect(CHARACTER_ASPECT_DEFAULTS).toEqual({
+      portrait: "3:4",
+      expressions: "1:1",
+      poses: "9:16",
+      angles: "3:4",
+      headAngles: "3:4",
+      bodyAngles: "9:16",
+      lighting: "3:4",
+      motions: "9:16",
+    })
+  })
+})
+
+describe("resolveCharacterAspectRatio — precedence", () => {
+  // Spec: explicit > node override > per-asset-type default.
+
+  it("returns the per-asset-type default when neither explicit nor node override is set", () => {
+    expect(resolveCharacterAspectRatio({ assetType: "portrait" })).toBe("3:4")
+    expect(resolveCharacterAspectRatio({ assetType: "expressions" })).toBe("1:1")
+    expect(resolveCharacterAspectRatio({ assetType: "poses" })).toBe("9:16")
+    expect(resolveCharacterAspectRatio({ assetType: "headAngles" })).toBe("3:4")
+    expect(resolveCharacterAspectRatio({ assetType: "bodyAngles" })).toBe("9:16")
+    expect(resolveCharacterAspectRatio({ assetType: "lighting" })).toBe("3:4")
+    expect(resolveCharacterAspectRatio({ assetType: "motions" })).toBe("9:16")
+    expect(resolveCharacterAspectRatio({ assetType: "angles" })).toBe("3:4")
+  })
+
+  it("returns the node override when explicit is not set", () => {
+    expect(
+      resolveCharacterAspectRatio({
+        assetType: "portrait",
+        nodeOverride: "16:9",
+      }),
+    ).toBe("16:9")
+    expect(
+      resolveCharacterAspectRatio({
+        assetType: "expressions",
+        nodeOverride: "9:16",
+      }),
+    ).toBe("9:16")
+  })
+
+  it("returns explicit when set, regardless of node override or default", () => {
+    expect(
+      resolveCharacterAspectRatio({
+        assetType: "portrait",
+        explicit: "1:1",
+        nodeOverride: "16:9",
+      }),
+    ).toBe("1:1")
+    expect(
+      resolveCharacterAspectRatio({
+        assetType: "motions",
+        explicit: "16:9",
+        nodeOverride: "1:1",
+      }),
+    ).toBe("16:9")
+  })
+
+  it("treats null / undefined / empty string as 'not set' at each layer", () => {
+    // explicit null/empty → falls through to nodeOverride
+    expect(
+      resolveCharacterAspectRatio({
+        assetType: "poses",
+        explicit: null,
+        nodeOverride: "1:1",
+      }),
+    ).toBe("1:1")
+    expect(
+      resolveCharacterAspectRatio({
+        assetType: "poses",
+        explicit: "",
+        nodeOverride: "3:4",
+      }),
+    ).toBe("3:4")
+    // node override null/empty → falls through to per-asset default
+    expect(
+      resolveCharacterAspectRatio({
+        assetType: "lighting",
+        explicit: null,
+        nodeOverride: null,
+      }),
+    ).toBe("3:4")
+  })
+
+  it("ignores an invalid (out-of-registry) explicit / node override value", () => {
+    // Invalid explicit value: fall through to node override.
+    expect(
+      resolveCharacterAspectRatio({
+        assetType: "portrait",
+        explicit: "21:9",
+        nodeOverride: "9:16",
+      }),
+    ).toBe("9:16")
+    // Invalid explicit AND invalid node override: fall through to per-asset default.
+    expect(
+      resolveCharacterAspectRatio({
+        assetType: "headAngles",
+        explicit: "21:9",
+        nodeOverride: "4:3",
+      }),
+    ).toBe("3:4")
+  })
+
+  it("treats legacy `angles` alias same as `headAngles`", () => {
+    expect(resolveCharacterAspectRatio({ assetType: "angles" })).toBe(
+      CHARACTER_ASPECT_DEFAULTS.headAngles,
+    )
+  })
+})

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

@@ -0,0 +1,199 @@
+import { describe, it, expect } from "vitest"
+import {
+  characterMentionSlug,
+  parseCharacterMentionToken,
+  findCharacterMentionTokens,
+} from "../character-mention-slug.js"
+
+describe("characterMentionSlug", () => {
+  it("lowercases and dash-separates", () => {
+    expect(characterMentionSlug("Kira")).toBe("kira")
+    expect(characterMentionSlug("Young Kira")).toBe("young-kira")
+  })
+  it("strips non-alphanumeric", () => {
+    expect(characterMentionSlug("Kira O'Brien")).toBe("kira-o-brien")
+    expect(characterMentionSlug("  Smile!  ")).toBe("smile")
+  })
+  it("collapses runs of dashes", () => {
+    expect(characterMentionSlug("a   b---c")).toBe("a-b-c")
+  })
+  it("returns empty for empty input", () => {
+    expect(characterMentionSlug("")).toBe("")
+    expect(characterMentionSlug("   ")).toBe("")
+  })
+})
+
+describe("parseCharacterMentionToken", () => {
+  it("parses @kira:1 as character + index (no variant, no mode)", () => {
+    expect(parseCharacterMentionToken("@kira:1")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: null,
+      usageMode: null,
+    })
+  })
+  it("parses @kira:1:smile with character + index + variant (no mode)", () => {
+    expect(parseCharacterMentionToken("@kira:1:smile")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: "smile",
+      usageMode: null,
+    })
+  })
+  it("parses multi-word character + variant slugs unambiguously", () => {
+    expect(parseCharacterMentionToken("@young-kira:2:soft-smile")).toEqual({
+      characterSlug: "young-kira",
+      imageIndex: 2,
+      variantSlug: "soft-smile",
+      usageMode: null,
+    })
+  })
+  it("accepts multi-digit indices", () => {
+    expect(parseCharacterMentionToken("@kira:12:smile")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 12,
+      variantSlug: "smile",
+      usageMode: null,
+    })
+  })
+  it("rejects bare @kira (no index)", () => {
+    // Format change: the index segment is now required.
+    expect(parseCharacterMentionToken("@kira")).toBeNull()
+  })
+  it("rejects @kira: (trailing colon with no index)", () => {
+    expect(parseCharacterMentionToken("@kira:")).toBeNull()
+  })
+  it("rejects @kira:smile (no index — variant in place of index)", () => {
+    expect(parseCharacterMentionToken("@kira:smile")).toBeNull()
+  })
+  it("rejects @kira:0 (index must be positive)", () => {
+    expect(parseCharacterMentionToken("@kira:0")).toBeNull()
+  })
+  it("returns null for non-mention input", () => {
+    expect(parseCharacterMentionToken("kira:1:smile")).toBeNull()
+    expect(parseCharacterMentionToken("@123")).toBeNull()
+  })
+  it("treats dash-only token as not-a-mention (no index segment)", () => {
+    // Without `:<index>` the parser rejects — no fallback to bare-slug form.
+    expect(parseCharacterMentionToken("@kira-smile")).toBeNull()
+  })
+
+  // -----------------------------------------------------------------------
+  // Usage-mode parsing — 3rd segment ambiguity + 4-part variant+mode form.
+  // -----------------------------------------------------------------------
+
+  it("3-part: @kira:1:face — recognizes a usage-mode keyword as the mode (no variant)", () => {
+    expect(parseCharacterMentionToken("@kira:1:face")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: null,
+      usageMode: "face",
+    })
+  })
+
+  it("3-part: @kira:1:style — same disambiguation for other modes", () => {
+    expect(parseCharacterMentionToken("@kira:1:style")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: null,
+      usageMode: "style",
+    })
+  })
+
+  it("3-part: @kira:1:face-pose — multi-word mode keyword wins over variant", () => {
+    expect(parseCharacterMentionToken("@kira:1:face-pose")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: null,
+      usageMode: "face-pose",
+    })
+  })
+
+  it("3-part: @kira:1:smile — non-mode segment is treated as variant (default mode)", () => {
+    expect(parseCharacterMentionToken("@kira:1:smile")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: "smile",
+      usageMode: null,
+    })
+  })
+
+  it("4-part: @kira:1:smile:face — variant + explicit mode override", () => {
+    expect(parseCharacterMentionToken("@kira:1:smile:face")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: "smile",
+      usageMode: "face",
+    })
+  })
+
+  it("4-part: @kira:1:walking:emotion — different variant + different mode", () => {
+    expect(parseCharacterMentionToken("@kira:1:walking:emotion")).toEqual({
+      characterSlug: "kira",
+      imageIndex: 1,
+      variantSlug: "walking",
+      usageMode: "emotion",
+    })
+  })
+
+  it("4-part: @kira:1:smile:invalid — invalid mode rejects the entire token", () => {
+    expect(parseCharacterMentionToken("@kira:1:smile:invalid")).toBeNull()
+  })
+
+  it("4-part: @kira:1:smile:smile — variant-shaped 4th segment still rejects (must be a mode)", () => {
+    expect(parseCharacterMentionToken("@kira:1:smile:smile")).toBeNull()
+  })
+
+  it("rejects 5-part tokens", () => {
+    expect(parseCharacterMentionToken("@kira:1:smile:face:extra")).toBeNull()
+  })
+
+  it("rejects empty trailing segments", () => {
+    expect(parseCharacterMentionToken("@kira:1:smile:")).toBeNull()
+    expect(parseCharacterMentionToken("@kira:1::face")).toBeNull()
+  })
+})
+
+describe("findCharacterMentionTokens", () => {
+  it("finds all @mentions with index (no mode in slug)", () => {
+    const tokens = findCharacterMentionTokens(
+      "Hi @kira:1:smile, please @adam:2 wave at @kira:3:walking",
+      ["kira", "adam"],
+    )
+    expect(tokens).toEqual([
+      { token: "@kira:1:smile", characterSlug: "kira", imageIndex: 1, variantSlug: "smile", usageMode: null, offset: 3 },
+      { token: "@adam:2", characterSlug: "adam", imageIndex: 2, variantSlug: null, usageMode: null, offset: 25 },
+      { token: "@kira:3:walking", characterSlug: "kira", imageIndex: 3, variantSlug: "walking", usageMode: null, offset: 41 },
+    ])
+  })
+  it("finds 4-part tokens with mode override", () => {
+    const tokens = findCharacterMentionTokens(
+      "@kira:1:smile:face waves at @kira:2:style",
+      ["kira"],
+    )
+    expect(tokens).toEqual([
+      { token: "@kira:1:smile:face", characterSlug: "kira", imageIndex: 1, variantSlug: "smile", usageMode: "face", offset: 0 },
+      { token: "@kira:2:style", characterSlug: "kira", imageIndex: 2, variantSlug: null, usageMode: "style", offset: 28 },
+    ])
+  })
+  it("returns empty for prompt with no @mentions", () => {
+    expect(findCharacterMentionTokens("just a prompt", ["kira"])).toEqual([])
+  })
+  it("ignores @mentions that don't match a known character slug", () => {
+    expect(findCharacterMentionTokens("@unknown:1:thing", ["kira", "adam"])).toEqual([])
+  })
+  it("handles email-like text without false matches", () => {
+    expect(findCharacterMentionTokens("send to user@example.com", ["user"])).toEqual([])
+  })
+  it("does not match bare @kira (no index)", () => {
+    expect(findCharacterMentionTokens("@kira waves", ["kira"])).toEqual([])
+  })
+  it("does not parse a dash-form as a variant token", () => {
+    expect(findCharacterMentionTokens("@kira-smile waves", ["kira"])).toEqual([])
+  })
+  it("4-part with invalid mode is dropped (matches regex but parser rejects)", () => {
+    // The regex matches structurally but `parseCharacterMentionToken` rejects
+    // the 4th segment as an invalid mode, so the token is filtered out.
+    expect(findCharacterMentionTokens("@kira:1:smile:bogus waves", ["kira"])).toEqual([])
+  })
+})

package/src/__tests__/character-reference-photo-kinds.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest"
+import {
+  CHARACTER_REFERENCE_PHOTO_KINDS,
+  type CharacterReferencePhotoKind,
+} from "../entity-asset-types.js"
+
+// Guards the single schema-of-record for the 7 identity-foundation kinds now
+// shared across the generate-character/characters route Zod enums, the backend
+// ranking (character-reference-set.ts), and the frontend routing. A change here
+// must be deliberate — it moves every consumer at once.
+describe("CHARACTER_REFERENCE_PHOTO_KINDS", () => {
+  it("is exactly the 7 identity-foundation kinds, in order", () => {
+    expect([...CHARACTER_REFERENCE_PHOTO_KINDS]).toEqual([
+      "frontFace",
+      "sideLeft",
+      "sideRight",
+      "threeQuarterLeft",
+      "threeQuarterRight",
+      "frontBody",
+      "other",
+    ])
+  })
+
+  it("has no duplicates", () => {
+    expect(new Set(CHARACTER_REFERENCE_PHOTO_KINDS).size).toBe(CHARACTER_REFERENCE_PHOTO_KINDS.length)
+  })
+
+  it("type derives from the const (compile-time totality)", () => {
+    const sample: CharacterReferencePhotoKind = CHARACTER_REFERENCE_PHOTO_KINDS[0]
+    expect(CHARACTER_REFERENCE_PHOTO_KINDS).toContain(sample)
+  })
+})

package/src/__tests__/character-usage-mode.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest"
+import {
+  USAGE_MODES,
+  DEFAULT_USAGE_MODE,
+  isUsageMode,
+  usageModeDirective,
+  usageModeLabel,
+  usageModeIncludesName,
+  type UsageMode,
+} from "../character-usage-mode.js"
+
+describe("USAGE_MODES", () => {
+  it("contains the 8 expected mode keys in canonical order", () => {
+    expect(USAGE_MODES).toEqual([
+      "identical",
+      "face",
+      "face-pose",
+      "pose",
+      "emotion",
+      "style",
+      "name",
+      "none",
+    ])
+  })
+  it("has 'identical' as the default", () => {
+    expect(DEFAULT_USAGE_MODE).toBe("identical")
+    expect(USAGE_MODES).toContain(DEFAULT_USAGE_MODE)
+  })
+})
+
+describe("isUsageMode", () => {
+  it("returns true for every entry in USAGE_MODES", () => {
+    for (const m of USAGE_MODES) {
+      expect(isUsageMode(m)).toBe(true)
+    }
+  })
+  it("returns false for unrecognized strings", () => {
+    expect(isUsageMode("smile")).toBe(false)
+    expect(isUsageMode("walking")).toBe(false)
+    expect(isUsageMode("body")).toBe(false) // pose is "pose", not "body"
+    expect(isUsageMode("FACE")).toBe(false) // case-sensitive
+    expect(isUsageMode("")).toBe(false)
+    expect(isUsageMode("Face-Pose")).toBe(false)
+  })
+  it("returns true for the new 'pose' mode", () => {
+    expect(isUsageMode("pose")).toBe(true)
+  })
+  it("narrows a typed-positive string at compile time", () => {
+    const s: string = "face"
+    if (isUsageMode(s)) {
+      // narrowed
+      const m: UsageMode = s
+      expect(m).toBe("face")
+    } else {
+      throw new Error("expected face to be a usage mode")
+    }
+  })
+})
+
+describe("usageModeDirective", () => {
+  it("emits the identity-lock language for 'identical'", () => {
+    const d = usageModeDirective("identical")
+    // Strengthened directive — the bullet "- … description. The subject must
+    // remain exactly the same person …" reads naturally.
+    expect(d).toMatch(/^The subject must remain exactly the same person/)
+    expect(d).toMatch(/preserve 100% facial identity/i)
+    expect(d).toMatch(/bone structure, skin tone/i)
+  })
+  it("emits face-only language for 'face'", () => {
+    const d = usageModeDirective("face")
+    expect(d).toMatch(/facial features/i)
+    expect(d).toMatch(/expression/i)
+    // Explicitly mentions adopting clothing/hair/posture from the rest of the prompt.
+    expect(d).toMatch(/clothing/i)
+    expect(d).toMatch(/posture/i)
+    expect(d).toMatch(/preserve 100% facial identity/i)
+  })
+  it("emits face + pose language for 'face-pose'", () => {
+    const d = usageModeDirective("face-pose")
+    expect(d).toMatch(/facial features/i)
+    expect(d).toMatch(/body pose/i)
+    expect(d).toMatch(/clothing/i)
+    expect(d).toMatch(/preserve 100% facial identity/i)
+  })
+  it("emits pose-only language for 'pose'", () => {
+    const d = usageModeDirective("pose")
+    expect(d).toMatch(/^Take only the body pose/)
+    // Pose mode must explicitly NOT copy facial identity — the whole point is
+    // borrowing the posture while keeping the rest of the prompt's face/hair.
+    expect(d).toMatch(/do not copy facial identity/i)
+    expect(d).toMatch(/adopt face, clothing, hair/i)
+  })
+  it("emits emotion-only language for 'emotion'", () => {
+    const d = usageModeDirective("emotion")
+    expect(d).toMatch(/emotional expression/i)
+    expect(d).toMatch(/transfer only the emotional cue/i)
+  })
+  it("emits style-only language for 'style'", () => {
+    const d = usageModeDirective("style")
+    expect(d).toMatch(/visual style/i)
+    expect(d).toMatch(/tone/i)
+    expect(d).toMatch(/do not copy the subject's identity/i)
+  })
+  it("returns null for 'name' and 'none' — minimal-intervention modes emit no directive", () => {
+    expect(usageModeDirective("name")).toBeNull()
+    expect(usageModeDirective("none")).toBeNull()
+  })
+  it("returns a distinct directive for every mode that emits one (no accidental aliasing)", () => {
+    // "name" and "none" both intentionally return null — exclude them from
+    // the uniqueness check. Every other mode must produce its own sentence.
+    const speakingModes = USAGE_MODES.filter((m) => m !== "name" && m !== "none")
+    const directives = speakingModes.map((m) => usageModeDirective(m))
+    expect(directives.every((d) => typeof d === "string" && d.length > 0)).toBe(true)
+    const unique = new Set(directives)
+    expect(unique.size).toBe(speakingModes.length)
+  })
+})
+
+describe("usageModeLabel", () => {
+  it("returns a human-readable label per mode", () => {
+    expect(usageModeLabel("identical")).toBe("Identical")
+    expect(usageModeLabel("face")).toBe("Face only")
+    expect(usageModeLabel("face-pose")).toBe("Face + Pose")
+    expect(usageModeLabel("pose")).toBe("Pose only")
+    expect(usageModeLabel("emotion")).toBe("Emotion only")
+    expect(usageModeLabel("style")).toBe("Style only")
+    expect(usageModeLabel("name")).toBe("Name only")
+    expect(usageModeLabel("none")).toBe("None")
+  })
+  it("returns a distinct label per mode", () => {
+    const labels = USAGE_MODES.map(usageModeLabel)
+    const unique = new Set(labels)
+    expect(unique.size).toBe(USAGE_MODES.length)
+  })
+})
+
+describe("usageModeIncludesName", () => {
+  it("returns false ONLY for 'none' — the no-text-bias mode", () => {
+    expect(usageModeIncludesName("none")).toBe(false)
+    // Every other mode keeps the name in the labeled subject (e.g. `Image A
+    // (shira)`) so the model can correlate the position with a named entity.
+    for (const m of USAGE_MODES) {
+      if (m === "none") continue
+      expect(usageModeIncludesName(m)).toBe(true)
+    }
+  })
+})

package/src/__tests__/character-variant-assets.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from "vitest"
+import {
+  CHARACTER_VARIANT_ASSET_BUCKETS,
+  characterVariantAssetArrays,
+  characterSheetRefItems,
+  characterBoardItems,
+  characterMentionableAssetArrays,
+} from "../character-variant-assets.js"
+
+describe("CHARACTER_VARIANT_ASSET_BUCKETS", () => {
+  it("includes the original six image/video-variant buckets", () => {
+    for (const b of ["expressions", "poses", "motions", "angles", "bodyAngles", "lightingVariations"]) {
+      expect(CHARACTER_VARIANT_ASSET_BUCKETS).toContain(b)
+    }
+  })
+
+  it("includes wardrobe (outfitVariations) and detail close-ups — the previously-dropped studio assets", () => {
+    // Regression: studio writes these {name,url}[] buckets but the @-mention /
+    // connected-reference expansion historically hardcoded only the first six,
+    // so wardrobe + close-ups were invisible in the reference picker and @ list.
+    expect(CHARACTER_VARIANT_ASSET_BUCKETS).toContain("outfitVariations")
+    expect(CHARACTER_VARIANT_ASSET_BUCKETS).toContain("detailCloseups")
+  })
+
+  it("has no duplicates", () => {
+    expect(new Set(CHARACTER_VARIANT_ASSET_BUCKETS).size).toBe(CHARACTER_VARIANT_ASSET_BUCKETS.length)
+  })
+})
+
+describe("characterVariantAssetArrays", () => {
+  it("returns one entry per bucket, expanding present arrays", () => {
+    const data = {
+      expressions: [{ name: "smile", url: "https://x/smile.png" }],
+      outfitVariations: [{ name: "red dress", url: "https://x/red.png", description: "evening" }],
+      detailCloseups: [{ name: "eyes", url: "https://x/eyes.png" }],
+      // unrelated field is ignored
+      sourceImageUrl: "https://x/main.png",
+    }
+    const out = characterVariantAssetArrays(data)
+    expect(Object.keys(out).sort()).toEqual([...CHARACTER_VARIANT_ASSET_BUCKETS].sort())
+    expect(out.expressions).toEqual([{ name: "smile", url: "https://x/smile.png" }])
+    expect(out.outfitVariations).toEqual([{ name: "red dress", url: "https://x/red.png", description: "evening" }])
+    expect(out.detailCloseups).toEqual([{ name: "eyes", url: "https://x/eyes.png" }])
+  })
+
+  it("coerces missing / non-array buckets to an empty array", () => {
+    const out = characterVariantAssetArrays({ poses: "not-an-array" as unknown })
+    expect(out.poses).toEqual([])
+    expect(out.expressions).toEqual([])
+    expect(out.outfitVariations).toEqual([])
+  })
+
+  it("tolerates null/undefined input", () => {
+    expect(characterVariantAssetArrays(undefined).expressions).toEqual([])
+    expect(characterVariantAssetArrays(null).motions).toEqual([])
+  })
+})
+
+describe("characterSheetRefItems", () => {
+  it("maps composite reference sheets to {name,url} items (type + skin label)", () => {
+    const sheets = [
+      { id: "s1", type: "turnaround", skin: "studio", url: "https://x/t.png", panelUrls: [] },
+      { id: "s2", type: "variation-board", skin: "cinematic", url: "https://x/v.png", panelUrls: [] },
+    ]
+    expect(characterSheetRefItems(sheets)).toEqual([
+      { name: "turnaround studio", url: "https://x/t.png" },
+      { name: "variation-board cinematic", url: "https://x/v.png" },
+    ])
+  })
+
+  it("drops sheets with no composite url, tolerates non-arrays", () => {
+    expect(characterSheetRefItems([{ type: "detail", url: "" }])).toEqual([])
+    expect(characterSheetRefItems(undefined)).toEqual([])
+    expect(characterSheetRefItems("nope")).toEqual([])
+  })
+})
+
+describe("characterBoardItems", () => {
+  it("returns the boards column", () => {
+    expect(characterBoardItems({ boards: [{ name: "turnaround", url: "https://x/t.png" }] })).toEqual([
+      { name: "turnaround", url: "https://x/t.png" },
+    ])
+  })
+
+  it("surfaces LEGACY shim boards from selectedAssetByVariant (studioBoard / studioBoard:<name>)", () => {
+    const out = characterBoardItems({
+      selectedAssetByVariant: {
+        studioBoard: "https://x/legacy.png",
+        "studioBoard:cinematic": "https://x/cine.png",
+        "expressions:smile": "https://x/smile.png", // not a board key → ignored
+      },
+    })
+    expect(out).toEqual(
+      expect.arrayContaining([
+        { name: "board", url: "https://x/legacy.png" },
+        { name: "cinematic", url: "https://x/cine.png" },
+      ]),
+    )
+    expect(out).toHaveLength(2)
+  })
+
+  it("merges column + shim, column wins on duplicate name", () => {
+    const out = characterBoardItems({
+      boards: [{ name: "cinematic", url: "https://col/cine.png" }],
+      selectedAssetByVariant: {
+        "studioBoard:cinematic": "https://shim/cine.png",
+        "studioBoard:studio": "https://shim/studio.png",
+      },
+    })
+    expect(out.find((b) => b.name === "cinematic")?.url).toBe("https://col/cine.png")
+    expect(out.find((b) => b.name === "studio")?.url).toBe("https://shim/studio.png")
+    expect(out).toHaveLength(2)
+  })
+
+  it("tolerates null/undefined / url-less", () => {
+    expect(characterBoardItems(undefined)).toEqual([])
+    expect(characterBoardItems({})).toEqual([])
+    expect(characterBoardItems({ boards: [{ name: "x", url: "" }] })).toEqual([])
+  })
+})
+
+describe("characterMentionableAssetArrays", () => {
+  it("includes every variant bucket PLUS derived `sheets` and `boards` buckets", () => {
+    const data = {
+      expressions: [{ name: "smile", url: "https://x/s.png" }],
+      sheets: [{ type: "turnaround", skin: "studio", url: "https://x/t.png" }],
+      boards: [{ name: "ref", url: "https://x/b.png" }],
+      selectedAssetByVariant: { "studioBoard:cinematic": "https://x/c.png" },
+    }
+    const out = characterMentionableAssetArrays(data)
+    expect(out.expressions).toHaveLength(1)
+    expect(out.sheets).toEqual([{ name: "turnaround studio", url: "https://x/t.png" }])
+    // boards = column + shim → @-mentionable
+    expect(out.boards).toEqual(
+      expect.arrayContaining([
+        { name: "ref", url: "https://x/b.png" },
+        { name: "cinematic", url: "https://x/c.png" },
+      ]),
+    )
+    for (const b of CHARACTER_VARIANT_ASSET_BUCKETS) expect(out[b]).toBeDefined()
+  })
+})