@nodaro/prompts 1.11.0 → 1.13.0

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

@@ -0,0 +1,374 @@
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+/**
+ * Wired-entity mentions — `@<name-slug>:<index>[:<role>]` for `wired-creature`
+ * and `wired-object`.
+ *
+ * The entity analog of `image-convergence-image.test.ts`, plus the two things
+ * only this leg has: FALLBACK SUPPRESSION (a mentioned entity must not ALSO emit
+ * its trailing canonical phrase — the live bug) and CROSS-KIND PRECEDENCE
+ * (character → location → image → creature → object).
+ *
+ * `referenceFormat` is passed EXPLICITLY on every hybrid case: `packages/prompts`
+ * is env-free (`content-free-contract.test.ts`), so `NODE_ENV=test` only steers
+ * the *callers*, never this package.
+ */
+
+const nessie: ConnectedReference = {
+  id: "cr1", defaultName: "Nessie", source: "wired-creature", url: "https://cdn/nessie.png",
+}
+const chair: ConnectedReference = {
+  id: "ob1", defaultName: "Chair", source: "wired-object", url: "https://cdn/chair.png",
+}
+const kira: ConnectedReference = {
+  id: "c1", defaultName: "Kira", source: "wired-character",
+  url: "https://cdn/kira.png", characterSlug: "kira",
+}
+const library: ConnectedReference = {
+  id: "l1", defaultName: "Old Library", source: "wired-location",
+  url: "https://cdn/library.png", locationSlug: "old-library",
+}
+const town: ConnectedReference = {
+  id: "n1", defaultName: "Town", source: "wired-image", url: "https://cdn/town.png",
+}
+
+/** Count non-overlapping occurrences — the double-render detector. */
+const occurrences = (haystack: string, needle: string): number =>
+  haystack.split(needle).length - 1
+
+describe("wired-entity mentions resolve on the image hybrid path", () => {
+  it("bare @nessie:4 → the SOURCE-default creature phrase, inline, token consumed", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @nessie:4 rising from the lake",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the creature from reference image A")
+    expect(out.prompt).not.toContain("@nessie")
+    expect(out.referenceImageUrls).toEqual(["https://cdn/nessie.png"])
+  })
+
+  it("the phrase renders where the user TYPED it, not appended after the scene", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @nessie:4 rising from the lake",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    // The whole point: bound INSIDE the sentence, so "rising from the lake"
+    // still attaches to the reference rather than to a bare name.
+    expect(out.prompt).toContain("the creature from reference image A rising from the lake")
+  })
+
+  it("SUPPRESSES the trailing canonical fallback for the mentioned ref (the live bug)", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @nessie:4 rising from the lake",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    // Before this leg the same ref rendered TWICE: the name as plain prose in
+    // the body, plus a dangling trailing phrase after the style hints.
+    expect(occurrences(out.prompt, "the creature from reference image A")).toBe(1)
+  })
+
+  it("@nessie:4:markings → the curated creature role", () => {
+    const out = buildImagePrompt({
+      prompt: "a close shot of @nessie:4:markings",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the markings from reference image A")
+    expect(occurrences(out.prompt, "reference image A")).toBe(1)
+  })
+
+  it("@chair:2:material → the curated OBJECT role, fallback suppressed", () => {
+    const out = buildImagePrompt({
+      prompt: "a still life of @chair:2:material",
+      connectedReferences: [chair],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the material from reference image A")
+    expect(out.prompt).not.toContain("the object from reference image A")
+  })
+
+  it("a CUSTOM role passes through verbatim", () => {
+    const out = buildImagePrompt({
+      prompt: "a close shot of @nessie:4:dorsal-fin",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the dorsal-fin from reference image A")
+  })
+
+  it("the node's own defaultRole is the fallback when the token carries none", () => {
+    const out = buildImagePrompt({
+      prompt: "a close shot of @nessie:4",
+      connectedReferences: [{ ...nessie, defaultRole: "anatomy" } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the anatomy from reference image A")
+    expect(out.prompt).not.toContain("the creature from reference image A")
+  })
+
+  it("a token role BEATS the node's defaultRole", () => {
+    const out = buildImagePrompt({
+      prompt: "a close shot of @nessie:4:pose",
+      connectedReferences: [{ ...nessie, defaultRole: "anatomy" } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the pose from reference image A")
+    expect(out.prompt).not.toContain("the anatomy from")
+  })
+
+  it("mentions ONE of two wired entities — the other keeps its trailing canonical", () => {
+    const out = buildImagePrompt({
+      prompt: "@nessie:1 looms over the room",
+      connectedReferences: [nessie, chair],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the creature from reference image A looms over the room")
+    // The unmentioned chair still auto-attaches with its trailing phrase — the
+    // pre-mention behavior, untouched.
+    expect(out.prompt).toContain("the object from reference image B")
+    expect(occurrences(out.prompt, "the creature from reference image A")).toBe(1)
+  })
+
+  it("two mentions of the SAME entity render twice inline but attach ONE URL", () => {
+    const out = buildImagePrompt({
+      prompt: "@nessie:1 circles, then @nessie:1 dives",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(occurrences(out.prompt, "the creature from reference image A")).toBe(2)
+    expect(out.referenceImageUrls).toEqual(["https://cdn/nessie.png"])
+  })
+
+  it("a mention whose slug matches NO wired entity stays literal text", () => {
+    const out = buildImagePrompt({
+      prompt: "a shot of @dragon:1 over the lake",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("@dragon:1")
+    // Nessie was never mentioned, so it keeps its canonical trailing phrase.
+    expect(out.prompt).toContain("the creature from reference image A")
+  })
+})
+
+describe("wired-entity mention locks and element injections", () => {
+  it("~lock forces the creature's identity lock ON, emitted ONCE", () => {
+    const locked = buildImagePrompt({
+      prompt: "@nessie:1 rises",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    const forced = buildImagePrompt({
+      prompt: "@nessie:1~lock rises",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    // `wired-creature` lock wording is OFF by default, so the sentinel is the
+    // only difference between these two prompts.
+    expect(forced.prompt.length).toBeGreaterThan(locked.prompt.length)
+    expect(forced.prompt).not.toContain("~lock")
+    expect(forced.prompt).toContain("reference image A")
+    // The ONCE half: the mention pass emits the lock line INSTEAD of the
+    // suppressed canonical one, never in addition to it. Matched on the stable
+    // prefix of `DEFAULT_LOCK_TEXT["wired-creature"]`, not the em-dashed tail.
+    expect(occurrences(forced.prompt, "Lock the exact identity of the creature")).toBe(1)
+    expect(occurrences(locked.prompt, "Lock the exact identity of the creature")).toBe(0)
+  })
+
+  it("a lock-less mention INHERITS the ref's own lock — emitted ONCE", () => {
+    const out = buildImagePrompt({
+      prompt: "@nessie:1 rises",
+      connectedReferences: [{ ...nessie, identityLock: { enabled: true } } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(occurrences(out.prompt, "Lock the exact identity of the creature")).toBe(1)
+  })
+
+  it("~nolock forces the lock OFF even when the ref itself enables it", () => {
+    const out = buildImagePrompt({
+      prompt: "@nessie:1~nolock rises",
+      connectedReferences: [{ ...nessie, identityLock: { enabled: true } } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).not.toContain("Lock the exact identity of the creature")
+    expect(out.prompt).not.toContain("~nolock")
+    expect(out.prompt).toContain("the creature from reference image A")
+  })
+
+  it("carries the ref's elementInjection ONCE — not once inline and once canonical", () => {
+    const inject = "keep the bioluminescent spines visible"
+    const out = buildImagePrompt({
+      prompt: "@nessie:1 rises",
+      connectedReferences: [{ ...nessie, elementInjection: inject } as ConnectedReference],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(occurrences(out.prompt, inject)).toBe(1)
+  })
+})
+
+describe("cross-kind precedence: character → location → image → creature → object", () => {
+  it("a slug known to a CHARACTER and a CREATURE resolves as the CHARACTER", () => {
+    const twin: ConnectedReference = {
+      id: "cr2", defaultName: "Kira", source: "wired-creature", url: "https://cdn/kira-creature.png",
+    }
+    const out = buildImagePrompt({
+      prompt: "@kira:1 steps forward",
+      connectedReferences: [kira, twin],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    // The character pass spliced the token, so the creature pass saw nothing.
+    expect(out.prompt).toContain("the person from reference image A")
+    expect(out.referenceImageUrls?.[0]).toBe("https://cdn/kira.png")
+    // The creature was never mentioned → it keeps its trailing canonical phrase.
+    expect(out.prompt).toContain("the creature from reference image B")
+  })
+
+  it("a slug known to a LOCATION and a CREATURE resolves as the LOCATION", () => {
+    const twin: ConnectedReference = {
+      id: "cr3", defaultName: "Old Library", source: "wired-creature", url: "https://cdn/lib-creature.png",
+    }
+    const out = buildImagePrompt({
+      prompt: "a shot inside @old-library:1",
+      connectedReferences: [library, twin],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.referenceImageUrls?.[0]).toBe("https://cdn/library.png")
+    expect(out.prompt).not.toContain("@old-library")
+  })
+
+  it("a slug known to an IMAGE and a CREATURE resolves as the IMAGE", () => {
+    const twin: ConnectedReference = {
+      id: "cr4", defaultName: "Town", source: "wired-creature", url: "https://cdn/town-creature.png",
+    }
+    const out = buildImagePrompt({
+      prompt: "a wide shot of @town:1 at dusk",
+      connectedReferences: [town, twin],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    // `wired-image`'s default role is "" → the BARE binding, and the image URL
+    // is the one that got the mention's slot.
+    expect(out.referenceImageUrls?.[0]).toBe("https://cdn/town.png")
+    expect(out.prompt).not.toContain("@town")
+    // The creature was never mentioned → trailing canonical, at its own letter.
+    expect(out.prompt).toContain("the creature from reference image B")
+  })
+
+  it("a slug known to a CREATURE and an OBJECT resolves as the CREATURE", () => {
+    // The tail of the chain, settled by the creature-first slug → ref map.
+    const twinCreature: ConnectedReference = {
+      id: "cr5", defaultName: "Totem", source: "wired-creature", url: "https://cdn/totem-creature.png",
+    }
+    const twinObject: ConnectedReference = {
+      id: "ob5", defaultName: "Totem", source: "wired-object", url: "https://cdn/totem-object.png",
+    }
+    // Object listed FIRST, so ref order cannot be what decides it.
+    const out = buildImagePrompt({
+      prompt: "@totem:1 stands in the clearing",
+      connectedReferences: [twinObject, twinCreature],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the creature from")
+    expect(out.prompt).toContain("stands in the clearing")
+  })
+
+  it("all five kinds in one prompt each bind their own reference", () => {
+    const out = buildImagePrompt({
+      prompt: "@kira:1 walks past @old-library:2 toward @town:3 with @nessie:4 and @chair:5",
+      connectedReferences: [kira, library, town, nessie, chair],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    for (const t of ["@kira", "@old-library", "@town", "@nessie", "@chair"]) {
+      expect(out.prompt).not.toContain(t)
+    }
+    expect(out.referenceImageUrls).toHaveLength(5)
+    // Both entities were mentioned → NO trailing canonical phrases for them.
+    expect(occurrences(out.prompt, "the creature from")).toBe(1)
+    expect(occurrences(out.prompt, "the object from")).toBe(1)
+  })
+})
+
+describe("byte-identity guarantees", () => {
+  const cases: Array<[string, Parameters<typeof buildImagePrompt>[0]]> = [
+    ["mention-free prompt with a wired creature", {
+      prompt: "a wide shot of a lake monster at dusk",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    }],
+    ["mention-free prompt with a wired creature AND object", {
+      prompt: "a still life in a dim room",
+      connectedReferences: [nessie, chair],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    }],
+    ["prompt with an @-token that matches no entity", {
+      prompt: "a shot of @dragon:1 over the lake",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    }],
+    ["no connectedReferences at all", {
+      prompt: "a wide shot of a lake at dusk",
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    }],
+  ]
+
+  // PINNED OUTPUTS. The entity pass is gated on TOKEN presence, so an
+  // unmentioned graph never enters it. These snapshots were VERIFIED against the
+  // pre-leg resolver (the entity wiring reverted, the snapshots kept) and matched
+  // byte-for-byte, so they are a real regression pin and not a recording of
+  // whatever the new code happens to emit. A diff here means the gate leaked.
+  it.each(cases)("%s is unchanged", (_name, config) => {
+    expect(buildImagePrompt(config).prompt).toMatchSnapshot()
+  })
+
+  it("an unmentioned creature still renders its trailing canonical phrase", () => {
+    const out = buildImagePrompt({
+      prompt: "a wide shot of a lake monster at dusk",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the creature from reference image A")
+    expect(out.referenceImageUrls).toEqual(["https://cdn/nessie.png"])
+  })
+
+  it("LEGACY leaves the token literal and attaches the entity exactly as today", () => {
+    const withMention = buildImagePrompt({
+      prompt: "a wide shot of @nessie:4 rising",
+      connectedReferences: [nessie],
+      provider: "nano-banana-pro",
+      referenceFormat: "legacy",
+    })
+    // No hybrid resolver runs under legacy — the token survives as typed.
+    expect(withMention.prompt).toContain("@nessie:4")
+    expect(withMention.referenceImageUrls).toEqual(["https://cdn/nessie.png"])
+  })
+})

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

@@ -45,6 +45,34 @@ describe("location reference converges onto the image hybrid form", () => {
     expect(out.prompt).not.toContain("Use these locations:")
   })
 
+  // A PLACE, NOT A BACKDROP — the `identical` usage mode (which IS
+  // `DEFAULT_LOCATION_USAGE_MODE`, i.e. what a bare `@old-library:1` resolves to)
+  // used to render "the background from reference image A". That is the exact
+  // wording measured on gpt-image-2 to produce cut-out composites, and the reason
+  // `DEFAULT_LABEL_BY_SOURCE["wired-location"]` became "location" on 2026-08-05;
+  // the mode map missed that fix. An EXPLICIT `:background` token still renders
+  // the backdrop wording (pinned in the Phase-D guard below).
+  it("bare @-mention (identical = the default mode) → 'the location from reference image A'", () => {
+    const out = buildImagePrompt({
+      prompt: "@old-library:1 a chase scene",
+      connectedReferences: [library],
+      provider: "nano-banana-pro", referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the location from reference image A")
+    expect(out.prompt).not.toContain("the background from reference image")
+    expect(out.prompt).not.toContain("Use these locations:")
+  })
+
+  it("explicit :identical mode → the same 'the location from …' phrase", () => {
+    const out = buildImagePrompt({
+      prompt: "@old-library:1:identical a chase scene",
+      connectedReferences: [library],
+      provider: "nano-banana-pro", referenceFormat: "hybrid",
+    })
+    expect(out.prompt).toContain("the location from reference image A")
+    expect(out.prompt).not.toContain("the background from reference image")
+  })
+
   it("opt-in identity lock surfaces a lock line; default OFF emits none", () => {
     const locked = buildImagePrompt({
       prompt: "@old-library:1 a chase scene",
@@ -54,7 +82,7 @@ describe("location reference converges onto the image hybrid form", () => {
       } as ConnectedReference],
       provider: "nano-banana-pro", referenceFormat: "hybrid",
     })
-    expect(locked.prompt).toContain("the background from reference image A")
+    expect(locked.prompt).toContain("the location from reference image A")
     expect(locked.prompt).toContain("Lock the exact setting in reference image A.")
 
     const unlocked = buildImagePrompt({

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

@@ -0,0 +1,166 @@
+// Location `defaultRole` (the ref-level hybrid role pick) must be honored by
+// BOTH image location paths — the @-mention resolver (un-roled token) and the
+// canonical fallback (wired, unmentioned) — with the precedence:
+//   token role → token mode → ref defaultRole → defaultUsageMode-derived → "location".
+//
+// `ConnectedReference.defaultRole` is on the wire schema for every source and the
+// character / named-image mention paths have always read it (`resolveDefaultRole`);
+// the location paths read only the usage mode, so a caller's ref-level role was
+// silently dropped. It is the ONLY channel a location has for a custom default
+// role — a location mention's 3rd segment is a bucket/variant or a role, so a
+// caller cannot pin a per-mention role AND keep the canonical image.
+//
+// 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 library: ConnectedReference = {
+  id: "l", defaultName: "Old Library", source: "wired-location",
+  url: "https://cdn/library.png", locationSlug: "old-library",
+}
+
+const build = (prompt: string, over: Partial<ConnectedReference> = {}, hybrid = true) =>
+  buildImagePrompt({
+    provider: "nano-banana-pro",
+    prompt,
+    connectedReferences: [{ ...library, ...over } as ConnectedReference],
+    ...(hybrid ? { referenceFormat: "hybrid" as const } : {}),
+  }).prompt
+
+describe("location @-mention honors the ref defaultRole for un-roled tokens", () => {
+  it("bare '@old-library:1' with defaultRole 'atmosphere' → 'the atmosphere from reference image A'", () => {
+    expect(build("@old-library:1 a chase scene", { defaultRole: "atmosphere" }))
+      .toContain("the atmosphere from reference image A")
+  })
+
+  it("a Custom defaultRole survives verbatim", () => {
+    expect(build("@old-library:1 a chase scene", { defaultRole: "brickwork" }))
+      .toContain("the brickwork from reference image A")
+  })
+
+  it("a multi-word preset slug is normalized to its phrase key, like a token role", () => {
+    expect(build("@old-library:1 a chase scene", { defaultRole: "empty-background" }))
+      .toContain("the background from reference image A (without its foreground objects)")
+  })
+
+  it("an explicit token ROLE still overrides the ref defaultRole", () => {
+    expect(build("@old-library:1:lighting a chase scene", { defaultRole: "atmosphere" }))
+      .toContain("the lighting from reference image A")
+  })
+
+  it("an explicit ROLE-BEARING token MODE still overrides the ref defaultRole", () => {
+    expect(build("@old-library:1:layout a chase scene", { defaultRole: "atmosphere" }))
+      .toContain("the layout from reference image A")
+  })
+
+  it("the other role-bearing mode (style) overrides it too", () => {
+    expect(build("@old-library:1:style a chase scene", { defaultRole: "atmosphere" }))
+      .toContain("the style from reference image A")
+  })
+
+  // `identical` and `none` express no role opinion — `identical` IS
+  // `DEFAULT_LOCATION_USAGE_MODE` (the un-roled state) and the location pill's
+  // `renderText` emits a mode segment whenever the attr is set, so an ungated
+  // mode step would let a round-tripped `@old-library:1:identical` suppress the
+  // ref-level role on the MAJORITY of real tokens. The character chain already
+  // falls through for its directive-only modes (identical / name / none) — this
+  // is the same rule, and `roleBearingLocationMode` runs the same
+  // `presets.includes(...)` test the character resolver and the pill view use.
+  it("a directive-only token mode (:identical) falls THROUGH to the ref defaultRole", () => {
+    expect(build("@old-library:1:identical a chase scene", { defaultRole: "atmosphere" }))
+      .toContain("the atmosphere from reference image A")
+  })
+
+  it("a directive-only token mode (:none) falls THROUGH to the ref defaultRole", () => {
+    expect(build("@old-library:1:none a chase scene", { defaultRole: "atmosphere" }))
+      .toContain("the atmosphere from reference image A")
+  })
+
+  it("matches the character chain: a directive-only segment never beats the ref role", () => {
+    const location = build("@old-library:1:identical a chase scene", { defaultRole: "atmosphere" })
+    const character = buildImagePrompt({
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+      prompt: "@kira:1:identical a chase scene",
+      connectedReferences: [{
+        id: "c", defaultName: "Kira", source: "wired-character",
+        url: "https://cdn/kira.png", characterSlug: "kira", defaultRole: "clothes",
+      }],
+    }).prompt
+    expect(location).toContain("the atmosphere from reference image A")
+    expect(character).toContain("the clothes from reference image A")
+  })
+
+  it("defaultRole beats a legacy defaultUsageMode on the same ref", () => {
+    expect(build("@old-library:1 a chase scene", { defaultRole: "atmosphere", defaultUsageMode: "style" }))
+      .toContain("the atmosphere from reference image A")
+  })
+})
+
+describe("location canonical fallback honors the ref defaultRole", () => {
+  it("unmentioned wired location with defaultRole 'atmosphere' → 'the atmosphere from reference image A'", () => {
+    expect(build("a detective at her desk", { defaultRole: "atmosphere" }))
+      .toContain("the atmosphere from reference image A")
+  })
+
+  // The mention and the canonical paths run ONE role chain, so the same wired
+  // location can never phrase itself one way mentioned and another unmentioned.
+  it("mentioned and unmentioned agree on the phrase for the same ref", () => {
+    const mentioned = build("@old-library:1 a chase scene", { defaultRole: "brickwork" })
+    const unmentioned = build("a chase scene", { defaultRole: "brickwork" })
+    expect(mentioned).toContain("the brickwork from reference image A")
+    expect(unmentioned).toContain("the brickwork from reference image A")
+  })
+})
+
+describe("NO defaultRole → byte-identical to the pre-change derivation", () => {
+  it("bare mention, no ref-level defaults → the source default", () => {
+    expect(build("@old-library:1 a chase scene")).toBe(
+      "the location from reference image A a chase scene",
+    )
+  })
+
+  // Gating step 2 on role-bearing modes changes nothing when there is no
+  // `defaultRole` to fall through to: `:identical` lands on step 4 → the source
+  // default, the same string the ungated step 2 produced.
+  it("':identical' with no ref-level defaults → the source default, unchanged", () => {
+    expect(build("@old-library:1:identical a chase scene")).toBe(
+      "the location from reference image A a chase scene",
+    )
+  })
+
+  it("':none' with no ref-level defaults → the source default, unchanged", () => {
+    expect(build("@old-library:1:none a chase scene")).toBe(
+      "the location from reference image A a chase scene",
+    )
+  })
+
+  it("bare mention with defaultUsageMode 'style' → the mode-derived role, unchanged", () => {
+    expect(build("@old-library:1 a chase scene", { defaultUsageMode: "style" })).toBe(
+      "the style from reference image A a chase scene",
+    )
+  })
+
+  // No mention converged, so the hybrid scene render still capitalizes the
+  // line-initial; the canonical phrase is appended after that pass, lowercase.
+  it("unmentioned, no ref-level defaults → the source default", () => {
+    expect(build("a detective at her desk")).toBe(
+      "A detective at her desk\nthe location from reference image A",
+    )
+  })
+
+  it("unmentioned with defaultUsageMode 'layout' → the mode-derived role, unchanged", () => {
+    expect(build("a detective at her desk", { defaultUsageMode: "layout" as never })).toBe(
+      "A detective at her desk\nthe layout from reference image A",
+    )
+  })
+})
+
+describe("legacy format ignores defaultRole (byte-identical guard)", () => {
+  it("legacy assembly with a defaultRole-carrying location emits no role phrase", () => {
+    const out = build("@old-library:1 a chase scene", { defaultRole: "atmosphere" }, false)
+    expect(out).not.toContain("the atmosphere from reference image A")
+    expect(out).not.toContain("from reference image A")
+  })
+})