@nodaro/prompts 1.0.1

package/src/__tests__/catalog-gapfill.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest"
+import { LENSES } from "../lens.js"
+import { MATERIALS } from "../materials.js"
+import { MOODS } from "../mood.js"
+
+/**
+ * Cinematography catalog gap-fill (Seedance doctrine sources): probe + CCTV
+ * lenses, subsurface material, relieved mood, and physical-externalization
+ * enrichment of the core emotion hints (official BytePlus table: emotions as
+ * externalized physical detail, never abstract words).
+ *
+ * The locale matrix below guards that the NEW ids ship with all 11 locale
+ * sidecars — the global completeness check only verifies files exist, not
+ * per-entry coverage, so without this a new entry silently falls back to
+ * English in 11 locales.
+ */
+const LOCALES = ["ar", "de", "es", "fr", "he", "hi", "ja", "ko", "pt-BR", "ru", "zh-CN"] as const
+const NEW_IDS: Record<string, string[]> = {
+  lens: ["probe", "cctv"],
+  materials: ["subsurface"],
+  mood: ["relieved"],
+}
+
+describe("catalog gap-fill entries", () => {
+  it("English catalogs carry the new entries with prompt hints", () => {
+    for (const id of NEW_IDS.lens!) {
+      const e = LENSES.find((l) => l.id === id)
+      expect(e, id).toBeDefined()
+      expect(e!.promptHint.length).toBeGreaterThan(20)
+    }
+    expect(MATERIALS.find((m) => m.id === "subsurface")?.promptHint).toContain("subsurface scattering")
+    expect(MOODS.find((m) => m.id === "relieved")?.promptHint).toContain("long breath")
+  })
+
+  it("core emotion hints carry physical externalization (doctrine table)", () => {
+    const hint = (id: string) => MOODS.find((m) => m.id === id)?.promptHint ?? ""
+    expect(hint("sad")).toContain("shoulders trembling")
+    expect(hint("joyful")).toContain("corners of the mouth")
+    expect(hint("angry")).toContain("fists clenched")
+    expect(hint("anxious")).toContain("eyes darting")
+  })
+
+  it.each(LOCALES)("locale %s has all new ids in its sidecars", async (locale) => {
+    for (const [catalog, ids] of Object.entries(NEW_IDS)) {
+      const mod = (await import(`../../../shared/src/i18n/${catalog}.${locale}.ts`)) as {
+        default: Record<string, { label?: string }>
+      }
+      for (const id of ids) {
+        expect(mod.default[id]?.label, `${catalog}.${locale}: ${id}`).toBeTruthy()
+      }
+    }
+  })
+})

package/src/__tests__/character-convergence-image.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import { expandExtraRefsToConnectedReferences } from "@nodaro/shared"
+import { resolveVideoReferenceCore } from "../video-reference-resolver.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const victoria: ConnectedReference = {
+  id: "v", defaultName: "Victoria Hayes", source: "wired-character",
+  url: "https://cdn/victoria.png", characterSlug: "victoria-hayes",
+}
+
+describe("character reference converges onto the image hybrid form", () => {
+  it("@-mention with a 'face' role → 'the face from reference image A', no identity-lock by default, no legacy block", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@victoria-hayes:1:face standing on a rooftop",
+      connectedReferences: [victoria],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the face from reference image A standing on a rooftop")
+    expect(out.prompt).not.toContain("Lock the exact identity")
+    expect(out.prompt).not.toContain("Use these characters:")
+    expect(out.referenceImageUrls).toContain("https://cdn/victoria.png")
+  })
+
+  it("identity-lock OFF → phrase only, no lock line", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@victoria-hayes:1:person on a beach",
+      connectedReferences: [{ ...victoria, identityLock: { enabled: false } }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the person from reference image A on a beach")
+    expect(out.prompt).not.toContain("Lock the exact identity")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("elementInjection (held-prop/styling) survives as a scene directive", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@victoria-hayes:1:person in a cafe",
+      connectedReferences: [{ ...victoria, elementInjection: "holding a smartphone" }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the person from reference image A in a cafe")
+    expect(out.prompt.toLowerCase()).toContain("holding a smartphone")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("identity-lock ON (enabled:true) → phrase + lock line", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@victoria-hayes:1:person standing on a rooftop",
+      connectedReferences: [{ ...victoria, identityLock: { enabled: true } }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the person from reference image A")
+    expect(out.prompt).toContain("Lock the exact identity of the person in reference image A")
+  })
+
+  it("unmentioned wired character → canonical hybrid phrase, no auto-lock (default off), no legacy block", () => {
+    const out = buildImagePrompt({
+      prompt: "a cinematic portrait",
+      connectedReferences: [victoria],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the person from reference image A")
+    // identity-lock is opt-in (default OFF) — no lock line unless the ref enables it:
+    expect(out.prompt).not.toContain("Lock the exact identity")
+    expect(out.prompt).not.toContain("Use these characters:")
+    expect(out.referenceImageUrls).toContain("https://cdn/victoria.png")
+  })
+
+  it("unmentioned wired character WITH elementInjection → canonical phrase + elementInjection survives (must NOT be silently dropped), no legacy block", () => {
+    const out = buildImagePrompt({
+      prompt: "a cinematic portrait",
+      connectedReferences: [{ ...victoria, elementInjection: "holding a vintage camera" }],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the person from reference image A")
+    expect(out.prompt.toLowerCase()).toContain("vintage camera")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("hybrid extra-ref attaches its URL and surfaces its description (no regression, no legacy block)", () => {
+    const extra: ConnectedReference = {
+      id: "x", defaultName: "Prop", source: "manual",
+      url: "https://cdn/prop.png", description: "a brass lantern", isExtraRef: true,
+    }
+    const out = buildImagePrompt({
+      prompt: "a still life",
+      connectedReferences: [extra],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.referenceImageUrls).toContain("https://cdn/prop.png")
+    expect(out.prompt.toLowerCase()).toContain("brass lantern")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("first-sight extra-ref character WITH elementInjection → injection survives as a scene directive (must NOT be silently dropped), no legacy block", () => {
+    // A character that appears ONLY as a first-sight extra-ref (not @-mentioned,
+    // not a canonical fallback). `variantSlug` makes it a picked-variant extra,
+    // which is what excludes it from `selectCanonicalFallbackRefs` (`if
+    // (r.variantSlug) continue`) — so `renderExtraRefsHybrid`'s first-sight
+    // branch is the ONLY surface for its `elementInjection`. A wired-character
+    // extra-ref WITHOUT a variantSlug would also be auto-attached by the
+    // canonical fallback (which already surfaces the injection), so it would not
+    // exercise — nor genuinely guard — the extra-ref hole this covers.
+    const kato: ConnectedReference = {
+      id: "k", defaultName: "Kato", source: "wired-character",
+      url: "https://cdn/kato.png", characterSlug: "kato", variantSlug: "alt",
+      isExtraRef: true, elementInjection: "holding a katana",
+      description: "in a dark alley",
+    }
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a cinematic portrait",
+      connectedReferences: [kato],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt.toLowerCase()).toContain("katana")
+    expect(out.referenceImageUrls).toContain("https://cdn/kato.png")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("first-sight extra-ref carrying a role (usageMode) → phrase uses THAT role, not the source default (Reference Roles F3)", () => {
+    // A first-sight character extra whose per-ref usage-mode override ("style",
+    // folded into `defaultUsageMode` by `expandExtraRefsToConnectedReferences`)
+    // is a curated preset → the hybrid phrase must read "the style from …",
+    // aligned UP to the video extras first-sight formula. Before F3 the image
+    // side ALWAYS emitted the source default ("the person from …").
+    const stylist: ConnectedReference = {
+      id: "s", defaultName: "Kira / look", source: "wired-character",
+      url: "https://cdn/kira-look.png", characterSlug: "kira", variantSlug: "look",
+      defaultUsageMode: "style", isExtraRef: true,
+    }
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a portrait",
+      connectedReferences: [stylist],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the style from reference image A")
+    expect(out.prompt).not.toContain("the person from reference image A")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("first-sight extra-ref with NO role → source default phrase (unchanged)", () => {
+    // No usage-mode override + a non-preset variant ("alt") → the source default
+    // ("person"), byte-identical to the pre-F3 behavior for role-less extras.
+    const plain: ConnectedReference = {
+      id: "p", defaultName: "Kira / alt", source: "wired-character",
+      url: "https://cdn/kira-alt.png", characterSlug: "kira", variantSlug: "alt",
+      isExtraRef: true,
+    }
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a portrait",
+      connectedReferences: [plain],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the person from reference image A")
+    expect(out.prompt).not.toContain("Use these characters:")
+  })
+
+  it("INVARIANT: image and video extras roles CONVERGE — both honor the coalesced char-node default via their REAL pipelines (Reference Roles deferred-follow-up)", () => {
+    // Build the extra the way PRODUCTION does — a raw `ExtraRefInput` with NO
+    // per-ref usageMode override — and run it through the REAL pipelines on BOTH
+    // sides (not hand-built ConnectedReferences or a mirrored formula). The char
+    // node's default mode is "style"; the extra carries no per-ref override and a
+    // non-preset picked variant ("look").
+    const CHAR_DEFAULT = "style" as const
+
+    // IMAGE side: `expandExtraRefsToConnectedReferences` coalesces `usageMode` →
+    // char-node default → "identical" into `defaultUsageMode` (always defined for
+    // a char extra — which is why the image call needs no `?? variantSlug`).
+    const expanded = expandExtraRefsToConnectedReferences(
+      [{ url: "https://cdn/kira-look.png", characterSlug: "kira", variantSlug: "look" }],
+      (slug) => (slug === "kira" ? { defaultUsageMode: CHAR_DEFAULT, displayName: "Kira" } : undefined),
+    )
+    expect(expanded).toHaveLength(1)
+    expect(expanded[0].defaultUsageMode).toBe(CHAR_DEFAULT)
+    const imageOut = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a portrait",
+      connectedReferences: expanded,
+      referenceFormat: "hybrid",
+    })
+    expect(imageOut.prompt).toContain("the style from reference image A")
+    expect(imageOut.prompt).not.toContain("the person from reference image A")
+
+    // VIDEO side: the resolver computes the SAME coalesced `effectiveMode`
+    // (`ex.usageMode` → `lookupCharacterBySlug().defaultUsageMode` → "identical")
+    // and now feeds THAT to `firstSightExtraRole`. Same raw extra (no per-ref
+    // override) + same char default → the video first-sight role must ALSO be
+    // "style". This proves convergence through the real video code path, not a
+    // re-derived formula.
+    const videoOut = resolveVideoReferenceCore({
+      prompt: "a portrait",
+      wiredCharRefs: [],
+      extraRefs: [{ url: "https://cdn/kira-look.png", characterSlug: "kira", variantSlug: "look" }],
+      lookupCharacterBySlug: () => ({ characterName: "Kira", defaultUsageMode: CHAR_DEFAULT }),
+      hybridRoles: true,
+    })
+    expect(videoOut.prompt).toContain("the style from @image_1")
+    expect(videoOut.prompt).not.toContain("the person from @image_1")
+
+    // CONVERGENCE: the SAME logical extra yields the SAME role on both surfaces.
+    expect(imageOut.prompt).toContain("the style from reference image A")
+    expect(videoOut.prompt).toContain("the style from @image_1")
+    expect(imageOut.prompt).not.toContain("Use these characters:")
+    expect(videoOut.prompt).not.toContain("Use these characters:")
+  })
+})

package/src/__tests__/character-default-role-image.test.ts

@@ -0,0 +1,167 @@
+// packages/shared/src/__tests__/character-default-role-image.test.ts
+//
+// Character node `defaultRole` (the hybrid role-dropdown pick) must be honored
+// by ALL THREE image resolution paths — canonical fallback (wired, unmentioned),
+// @-mention (un-roled token), and extras (first-sight) — with the precedence:
+//   per-mention token role → node defaultRole → defaultUsageMode-derived → "person".
+// Legacy format ignores `defaultRole` entirely (byte-identical guard).
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const kira: ConnectedReference = {
+  id: "k", defaultName: "Kira", source: "wired-character",
+  url: "https://cdn/kira.png", characterSlug: "kira",
+}
+
+describe("image canonical fallback honors the node defaultRole", () => {
+  it("unmentioned wired character with defaultRole 'clothes' → 'the clothes from reference image A'", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a cinematic portrait",
+      connectedReferences: [{ ...kira, defaultRole: "clothes" }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the clothes from reference image A")
+    expect(out.prompt).not.toContain("the person from reference image A")
+  })
+
+  it("unmentioned wired character with defaultUsageMode 'style' (no defaultRole) → 'the style from …' (node default finally honored)", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a cinematic portrait",
+      connectedReferences: [{ ...kira, defaultUsageMode: "style" }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the style from reference image A")
+    expect(out.prompt).not.toContain("the person from reference image A")
+  })
+
+  it("plain unmentioned wired character (neither field) → 'the person from …' (unchanged)", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a cinematic portrait",
+      connectedReferences: [kira],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the person from reference image A")
+  })
+
+  it("a Custom defaultRole survives verbatim on the canonical path", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a cinematic portrait",
+      connectedReferences: [{ ...kira, defaultRole: "earrings" }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the earrings from reference image A")
+  })
+})
+
+describe("image @-mention honors the node defaultRole for un-roled tokens", () => {
+  it("un-roled '@kira:1' with defaultRole 'hair' → 'the hair from reference image A'", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@kira:1 walking in the rain",
+      connectedReferences: [{ ...kira, defaultRole: "hair" }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the hair from reference image A walking in the rain")
+  })
+
+  it("a per-mention token role still overrides the node defaultRole", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@kira:1:face walking in the rain",
+      connectedReferences: [{ ...kira, defaultRole: "hair" }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the face from reference image A walking in the rain")
+    expect(out.prompt).not.toContain("the hair from")
+  })
+
+  it("un-roled '@kira:1' with only defaultUsageMode 'face' → 'the face from …' (derived fallback)", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@kira:1 at dawn",
+      connectedReferences: [{ ...kira, defaultUsageMode: "face" }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the face from reference image A at dawn")
+  })
+
+  it("un-roled '@kira:1' with defaultUsageMode 'identical' → 'the person from …' (non-preset collapses)", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "@kira:1 at dawn",
+      connectedReferences: [{ ...kira, defaultUsageMode: "identical" }],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the person from reference image A at dawn")
+  })
+})
+
+describe("image extras honor the node defaultRole (first-sight)", () => {
+  it("first-sight character extra with defaultRole 'hair' → 'the hair from reference image A'", () => {
+    // variantSlug makes it a picked-variant extra → excluded from the canonical
+    // fallback, so renderExtraRefsHybrid's first-sight branch is the only surface.
+    const extra: ConnectedReference = {
+      ...kira, id: "x", variantSlug: "look", isExtraRef: true, defaultRole: "hair",
+    }
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a portrait",
+      connectedReferences: [extra],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the hair from reference image A")
+    expect(out.prompt).not.toContain("the person from reference image A")
+  })
+
+  it("extra with defaultUsageMode 'style' and NO defaultRole keeps the derived role (unchanged)", () => {
+    const extra: ConnectedReference = {
+      ...kira, id: "x", variantSlug: "look", isExtraRef: true, defaultUsageMode: "style",
+    }
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a portrait",
+      connectedReferences: [extra],
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the style from reference image A")
+  })
+})
+
+describe("lock-line dedup (same reference locked via two paths)", () => {
+  it("an extra whose URL equals the wired canonical emits the lock line ONCE", () => {
+    // The pair-back letter gate routes a same-URL extra into the first-sight
+    // branch (same letter), which would re-emit an identical {ref}-bound lock
+    // line — the assembler's Set-dedup must collapse it to one.
+    const lock = { enabled: true, text: "Preserve the overall facial likeness of the subject in {ref}." }
+    const canonical: ConnectedReference = { ...kira, identityLock: lock }
+    const sameUrlExtra: ConnectedReference = {
+      ...kira, id: "x", variantSlug: "look", isExtraRef: true, identityLock: lock,
+    }
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a cinematic portrait",
+      connectedReferences: [canonical, sameUrlExtra],
+      referenceFormat: "hybrid",
+    })
+    const occurrences = out.prompt.split("overall facial likeness of the subject in reference image A").length - 1
+    expect(occurrences).toBe(1)
+  })
+})
+
+describe("legacy format ignores defaultRole (byte-identical guard)", () => {
+  it("legacy assembly with a defaultRole-carrying ref emits the legacy block, no role phrase", () => {
+    const out = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a cinematic portrait",
+      connectedReferences: [{ ...kira, defaultRole: "clothes" }],
+      referenceFormat: "legacy",
+    })
+    expect(out.prompt).not.toContain("the clothes from reference image A")
+    expect(out.prompt).toContain("Use these characters:")
+  })
+})

package/src/__tests__/character-default-role-video.test.ts

@@ -0,0 +1,168 @@
+// packages/shared/src/__tests__/character-default-role-video.test.ts
+//
+// Character node `defaultRole` + mapped `identityLock` must be honored by ALL
+// THREE video resolution paths — canonical fallback, @-mention (un-roled
+// token), and extras (first-sight via `CharacterMeta`) — mirroring the image
+// side (character-default-role-image.test.ts) so the surfaces stay converged.
+import { describe, it, expect } from "vitest"
+import { resolveVideoReferenceCore } from "../video-reference-resolver.js"
+import { characterLockToRefLock } from "../identity-lock.js"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const kira = (over: Partial<ConnectedReference> = {}): ConnectedReference => ({
+  id: "k", defaultName: "Kira", source: "wired-character", url: "u-kira", characterSlug: "kira", ...over,
+})
+
+describe("video canonical fallback honors the node defaultRole", () => {
+  it("unmentioned wired character with defaultRole 'clothes' → 'the clothes from @image_1'", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a slow dolly", wiredCharRefs: [kira({ defaultRole: "clothes" })], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the clothes from @image_1")
+    expect(out.prompt).not.toContain("the person from @image_1")
+  })
+
+  it("unmentioned wired character with defaultUsageMode 'style' (no defaultRole) → 'the style from @image_1'", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a slow dolly", wiredCharRefs: [kira({ defaultUsageMode: "style" })], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the style from @image_1")
+    expect(out.prompt).not.toContain("the person from @image_1")
+  })
+
+  it("plain unmentioned wired character → 'the person from @image_1' (unchanged)", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a slow dolly", wiredCharRefs: [kira()], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the person from @image_1")
+  })
+})
+
+describe("video @-mention honors the node defaultRole for un-roled tokens", () => {
+  it("un-roled '@kira:1' with defaultRole 'hair' → 'the hair from @image_1'", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1 walks in", wiredCharRefs: [kira({ defaultRole: "hair" })], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the hair from @image_1 walks in")
+  })
+
+  it("a per-mention token role still overrides the node defaultRole", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1:face walks in", wiredCharRefs: [kira({ defaultRole: "hair" })], hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the face from @image_1 walks in")
+    expect(out.prompt).not.toContain("the hair from")
+  })
+})
+
+describe("video extras honor the node defaultRole + mapped identityLock (CharacterMeta)", () => {
+  it("first-sight extra with meta.defaultRole 'hair' and no per-ref override → 'the hair from @image_1'", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a portrait",
+      wiredCharRefs: [],
+      extraRefs: [{ url: "u-look", characterSlug: "kira", variantSlug: "look" }],
+      lookupCharacterBySlug: () => ({ characterName: "Kira", defaultRole: "hair" }),
+      hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the hair from @image_1")
+    expect(out.prompt).not.toContain("the person from @image_1")
+  })
+
+  it("a per-extra usageMode override suppresses meta.defaultRole", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a portrait",
+      wiredCharRefs: [],
+      extraRefs: [{ url: "u-look", characterSlug: "kira", variantSlug: "look", usageMode: "style" }],
+      lookupCharacterBySlug: () => ({ characterName: "Kira", defaultRole: "hair" }),
+      hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the style from @image_1")
+    expect(out.prompt).not.toContain("the hair from")
+  })
+
+  it("meta.identityLock (node soft mapping) emits the lock line for a first-sight extra; per-extra lock wins when both set", () => {
+    const softLock = characterLockToRefLock("soft")
+    const out = resolveVideoReferenceCore({
+      prompt: "a portrait",
+      wiredCharRefs: [],
+      extraRefs: [{ url: "u-look", characterSlug: "kira", variantSlug: "look" }],
+      lookupCharacterBySlug: () => ({ characterName: "Kira", identityLock: softLock }),
+      hybridRoles: true,
+    })
+    // The node's soft lock is {ref}-bound at emission (binding = @image_1).
+    expect(out.prompt).toContain("overall facial likeness of the subject in @image_1")
+
+    const perExtraOff = resolveVideoReferenceCore({
+      prompt: "a portrait",
+      wiredCharRefs: [],
+      extraRefs: [{
+        url: "u-look", characterSlug: "kira", variantSlug: "look",
+        identityLock: { enabled: false },
+      }],
+      lookupCharacterBySlug: () => ({ characterName: "Kira", identityLock: softLock }),
+      hybridRoles: true,
+    })
+    expect(perExtraOff.prompt).not.toContain("overall facial likeness")
+  })
+})
+
+describe("route-shaped extras (generate-video / text-to-video / MCP adapter contract)", () => {
+  it("a per-extra defaultRole wins even when usageMode carries the COALESCED mode (the route adapter shape)", () => {
+    // The direct-API adapter can only feed the coalesced defaultUsageMode as
+    // `usageMode` (always set for character extras) — which must NOT suppress
+    // the node default when it rides the dedicated per-extra `defaultRole` slot.
+    const out = resolveVideoReferenceCore({
+      prompt: "a portrait",
+      wiredCharRefs: [],
+      extraRefs: [{
+        url: "u-look", characterSlug: "kira", variantSlug: "look",
+        usageMode: "identical", defaultRole: "hair",
+      }],
+      hybridRoles: true,
+    })
+    expect(out.prompt).toContain("the hair from @image_1")
+    expect(out.prompt).not.toContain("the person from @image_1")
+  })
+
+  it("a per-extra identityLock (route CR passthrough) emits the lock line without any meta", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a portrait",
+      wiredCharRefs: [],
+      extraRefs: [{
+        url: "u-look", characterSlug: "kira", variantSlug: "look",
+        usageMode: "identical",
+        identityLock: characterLockToRefLock("strict"),
+      }],
+      hybridRoles: true,
+    })
+    expect(out.prompt).toContain("The facial identity of the subject in @image_1 must match exactly")
+  })
+})
+
+describe("image/video parity for a defaultRole node (convergence pinned)", () => {
+  it("the SAME defaultRole node yields the SAME role phrase on both surfaces", () => {
+    const ref = kira({ url: "https://cdn/kira.png", defaultRole: "clothes" })
+    const imageOut = buildImagePrompt({
+      provider: "nano-banana-pro",
+      prompt: "a cinematic portrait",
+      connectedReferences: [ref],
+      referenceFormat: "hybrid",
+    })
+    const videoOut = resolveVideoReferenceCore({
+      prompt: "a cinematic portrait", wiredCharRefs: [ref], hybridRoles: true,
+    })
+    expect(imageOut.prompt).toContain("the clothes from reference image A")
+    expect(videoOut.prompt).toContain("the clothes from @image_1")
+  })
+})
+
+describe("video legacy ignores defaultRole (byte-identical guard)", () => {
+  it("legacy (hybridRoles: false) with a defaultRole-carrying ref emits the legacy block, no role phrase", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a slow dolly", wiredCharRefs: [kira({ defaultRole: "clothes" })], hybridRoles: false,
+    })
+    expect(out.prompt).not.toContain("the clothes from @image_1")
+    expect(out.prompt).toContain("Use these characters:")
+  })
+})