@nodaro/prompts 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -20,7 +20,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nodaro/shared": "^2.13.0"
+    "@nodaro/shared": "^2.14.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/character-fx-timing-catalogs.test.ts

@@ -0,0 +1,240 @@
+/**
+ * The character-fx node's three timing parameters (position / duration /
+ * intensity) are enumerable catalogs, not free values, so a consumer that can
+ * only send ids — Studio, the SDK, MCP — can offer them without composing any
+ * prompt text of its own. This is the character-fx twin of
+ * `transition-timing-catalogs.test.ts`; the two nodes share ids and shape but
+ * NOT wording, and nothing here may couple them.
+ *
+ * Three properties matter, and each is easy to lose silently:
+ *
+ *  1. The clause the composer INJECTS and the hint the catalog ADVERTISES are
+ *     the same string. They are derived from one array in `character-fx.ts`,
+ *     and these tests fail the moment someone re-introduces a second copy.
+ *  2. The prompt text is exactly what shipped before it was enumerable. The
+ *     parameter-hint golden covers only three of the twelve clauses, so the
+ *     twelve literals are pinned here: a change is a deliberate diff, never a
+ *     side effect.
+ *  3. The dimensions survive the wire projection — `projectAllCatalogs()` is
+ *     what an id-only client actually reads, and a green in-memory catalog
+ *     proves nothing about it.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  CHARACTER_FX_POSITIONS,
+  CHARACTER_FX_DURATIONS,
+  CHARACTER_FX_INTENSITIES,
+  composeCharacterFxHintFromConnections,
+} from "../character-fx.js"
+import { TRANSITION_POSITIONS, TRANSITION_DURATIONS } from "../transitions.js"
+import { PICKER_CATALOGS, projectPickerCatalog, projectAllCatalogs } from "../picker-catalogs.js"
+
+const DIMENSIONS = [
+  ["position", CHARACTER_FX_POSITIONS],
+  ["duration", CHARACTER_FX_DURATIONS],
+  ["intensity", CHARACTER_FX_INTENSITIES],
+] as const
+
+const characterFxCatalog = PICKER_CATALOGS.find((c) => c.nodeType === "character-fx")!
+
+describe("character-fx timing catalogs", () => {
+  // The `CharacterFxPosition` / `Duration` / `Intensity` unions are DERIVED
+  // from these arrays, so nothing at the type level can pin the values
+  // themselves. These are the values the editor dropdowns, the node data, and
+  // every stored workflow already use: changing one is a data migration, not a
+  // rename.
+  it("spells exactly the ids every stored workflow already uses", () => {
+    expect(CHARACTER_FX_POSITIONS.map((o) => o.id)).toEqual([
+      "auto", "start", "middle", "end", "full",
+    ])
+    expect(CHARACTER_FX_DURATIONS.map((o) => o.id)).toEqual([
+      "auto", "instant", "short", "medium", "long",
+    ])
+    expect(CHARACTER_FX_INTENSITIES.map((o) => o.id)).toEqual([
+      "auto", "subtle", "natural", "dynamic", "crazy",
+    ])
+  })
+
+  it("injects exactly the clauses that shipped before the scales were enumerable", () => {
+    // Byte-for-byte the literals the hand-written clause tables carried. This
+    // task was exposure, not authoring: if any of these move, that is a prompt
+    // change for real users and must be its own deliberate diff.
+    expect(CHARACTER_FX_POSITIONS.map((o) => o.promptHint)).toEqual([
+      "",
+      "the effect occurs at the opening of the clip",
+      "the effect occurs in the middle of the clip",
+      "the effect occurs at the end of the clip",
+      "the effect persists for the entire clip",
+    ])
+    expect(CHARACTER_FX_DURATIONS.map((o) => o.promptHint)).toEqual([
+      "",
+      "manifesting instantaneously",
+      "manifesting over approximately 1 second",
+      "manifesting over approximately 2 seconds",
+      "manifesting over approximately 3 seconds",
+    ])
+    expect(CHARACTER_FX_INTENSITIES.map((o) => o.promptHint)).toEqual([
+      "",
+      "with subtle restrained energy and minimal flourish",
+      "with natural unhurried timing",
+      "with dynamic energy and assertive flourish",
+      "with extreme exaggerated energy, wild flourishes, and dramatic distortion",
+    ])
+  })
+
+  it("keeps its own wording — an effect manifests and persists, a transition occurs and spans", () => {
+    // The one constraint that matters most: these scales must never be unified
+    // with the transition ones. Position and duration are worded differently
+    // on purpose, so pointing character-fx at the transition rows fails here.
+    // Intensity is deliberately NOT compared: its three clauses happen to be
+    // identical today, and that is a coincidence, not a shared definition.
+    expect(CHARACTER_FX_POSITIONS.map((o) => o.promptHint)).not.toEqual(
+      TRANSITION_POSITIONS.map((o) => o.promptHint),
+    )
+    expect(CHARACTER_FX_DURATIONS.map((o) => o.promptHint)).not.toEqual(
+      TRANSITION_DURATIONS.map((o) => o.promptHint),
+    )
+  })
+
+  it("carries the timing precision users read off the dropdown", () => {
+    // The editor renders straight from here (its own catalogs, not the
+    // transition ones), so this is the one place the numbers live.
+    expect(CHARACTER_FX_DURATIONS.map((o) => o.label)).toEqual([
+      "Auto", "Instant", "Short (~1s)", "Medium (~2s)", "Long (~3s)",
+    ])
+  })
+
+  it("gives every injecting step a compact term, so compact mode never drops it", () => {
+    // `catalog-terms.test.ts` enforces this globally; pinned here too because
+    // the platform composes timing from `promptHint` in BOTH hint modes, so a
+    // broken `term` would only ever surface on an external compact client.
+    for (const [field, options] of DIMENSIONS) {
+      for (const o of options.slice(1)) {
+        expect(o.term, `${field}/${o.id} needs a compact term`).toBeTruthy()
+      }
+      expect(options[0]!.term, `${field}/auto injects nothing`).toBe("")
+    }
+  })
+
+  it("derives a clause for every non-auto step, so the composer can't index a hole", () => {
+    // The regression this guards: a step present in the catalog but missing
+    // from the clause table made `parts.push(undefined)` render as a dangling
+    // ", " on a prompt that shipped to the provider. Walks the ARRAYS, not a
+    // hardcoded id list, so a step added to a catalog is exercised here too.
+    for (const [field, options] of DIMENSIONS) {
+      for (const o of options.slice(1)) {
+        const composed = composeCharacterFxHintFromConnections("werewolf", [], {
+          [field]: o.id,
+        } as never)
+        expect(composed, `${field}/${o.id} composed a dangling separator`).not.toMatch(/,\s*$/)
+        expect(composed, `${field}/${o.id}`).not.toContain("undefined")
+      }
+    }
+  })
+
+  it("every scale leads with a no-op `auto` that injects nothing", () => {
+    for (const [field, options] of DIMENSIONS) {
+      expect(options[0]!.id, `${field} must lead with auto`).toBe("auto")
+      expect(options[0]!.promptHint, `${field}/auto must inject nothing`).toBe("")
+      // Every other step must actually carry a clause.
+      for (const o of options.slice(1)) {
+        expect(o.promptHint, `${field}/${o.id} needs a promptHint`).not.toBe("")
+      }
+    }
+  })
+
+  it("the composed clause is the catalog's own promptHint, verbatim", () => {
+    // One source of truth: if the composer ever grows a private copy of these
+    // strings, the composed sentence stops containing the advertised hint.
+    for (const o of CHARACTER_FX_POSITIONS.slice(1)) {
+      const composed = composeCharacterFxHintFromConnections("werewolf", [], { position: o.id as never })
+      expect(composed, `position/${o.id}`).toContain(o.promptHint)
+    }
+    for (const o of CHARACTER_FX_DURATIONS.slice(1)) {
+      const composed = composeCharacterFxHintFromConnections("werewolf", [], { duration: o.id as never })
+      expect(composed, `duration/${o.id}`).toContain(o.promptHint)
+    }
+    for (const o of CHARACTER_FX_INTENSITIES.slice(1)) {
+      const composed = composeCharacterFxHintFromConnections("werewolf", [], { intensity: o.id as never })
+      expect(composed, `intensity/${o.id}`).toContain(o.promptHint)
+    }
+  })
+
+  it("the clauses are emitted identically in compact hint mode", () => {
+    // Timing is composed from `promptHint` in BOTH modes — only the effect's
+    // base fragment swaps to its term. Pinned so a compact-mode refactor cannot
+    // quietly start reading `term` for the timing rows.
+    for (const [field, options] of DIMENSIONS) {
+      for (const o of options.slice(1)) {
+        const compact = composeCharacterFxHintFromConnections("werewolf", [], {
+          [field]: o.id,
+        } as never, "compact")
+        expect(compact, `${field}/${o.id} in compact mode`).toContain(o.promptHint)
+      }
+    }
+  })
+
+  it("`auto` adds nothing to the composed sentence", () => {
+    const bare = composeCharacterFxHintFromConnections("werewolf", [])
+    const allAuto = composeCharacterFxHintFromConnections("werewolf", [], { position: "auto", duration: "auto", intensity: "auto" })
+    expect(allAuto).toBe(bare)
+  })
+
+  it("exposes the three dimensions on the character-fx catalog", () => {
+    expect(characterFxCatalog.kind).toBe("single")
+    expect(characterFxCatalog.dimensions?.map((d) => d.field)).toEqual([
+      "position",
+      "duration",
+      "intensity",
+    ])
+  })
+
+  it("keeps the dimensions through the wire projection", () => {
+    const wire = projectPickerCatalog(characterFxCatalog, { detail: "full" })
+
+    // The 57-option effect list is untouched by the addition.
+    expect(wire.options?.length).toBe(characterFxCatalog.options?.length)
+
+    expect(wire.dimensions).toHaveLength(3)
+    for (const [field, options] of DIMENSIONS) {
+      const dim = wire.dimensions?.find((d) => d.field === field)
+      expect(dim, `${field} must reach the wire`).toBeDefined()
+      expect(dim!.options.map((o) => o.id)).toEqual(options.map((o) => o.id))
+      expect(dim!.options.map((o) => o.promptHint)).toEqual(options.map((o) => o.promptHint))
+    }
+  })
+
+  it("field filter narrows a single-dim catalog to one secondary dimension", () => {
+    const wire = projectPickerCatalog(characterFxCatalog, { field: "duration" })
+    expect(wire.options?.length).toBe(characterFxCatalog.options?.length)
+    expect(wire.dimensions?.map((d) => d.field)).toEqual(["duration"])
+  })
+
+  describe("projectAllCatalogs — what an id-only client actually reads", () => {
+    // `GET /v1/catalogs` is built from this call. Both detail levels must carry
+    // the three dimensions with ids and labels; `full` must also carry the
+    // clause, and `compact` must carry the term so a thin client can inject
+    // without a second fetch.
+    for (const detail of ["compact", "full"] as const) {
+      it(`detail=${detail}: three dimensions with ids, labels${detail === "full" ? " and hints" : " and terms"}`, () => {
+        const wire = projectAllCatalogs({ detail }).find((c) => c.nodeType === "character-fx")!
+        expect(wire.detail).toBe(detail)
+        expect(wire.kind).toBe("single")
+        expect(wire.dimensions?.map((d) => d.field)).toEqual(["position", "duration", "intensity"])
+
+        for (const [field, options] of DIMENSIONS) {
+          const dim = wire.dimensions!.find((d) => d.field === field)!
+          expect(dim.label, `${field} label`).toBeTruthy()
+          expect(dim.options.map((o) => o.id)).toEqual(options.map((o) => o.id))
+          expect(dim.options.map((o) => o.label)).toEqual(options.map((o) => o.label))
+          expect(dim.options.map((o) => o.term)).toEqual(options.map((o) => o.term))
+          if (detail === "full") {
+            expect(dim.options.map((o) => o.promptHint)).toEqual(options.map((o) => o.promptHint))
+          } else {
+            for (const o of dim.options) expect(o, `${field}/${o.id} compact`).not.toHaveProperty("promptHint")
+          }
+        }
+      })
+    }
+  })
+})

package/src/__tests__/transition-timing-catalogs.test.ts

@@ -143,9 +143,11 @@ describe("transition timing catalogs", () => {
   })
 
   it("leaves every other single-dim catalog without dimensions", () => {
+    // `character-fx` carries the same three timing fields with its own,
+    // deliberately different wording (see `character-fx-timing-catalogs.test.ts`).
     const singlesWithDims = PICKER_CATALOGS.filter(
       (c) => c.kind === "single" && c.dimensions,
     ).map((c) => c.nodeType)
-    expect(singlesWithDims).toEqual(["transition"])
+    expect(singlesWithDims).toEqual(["transition", "character-fx"])
   })
 })

package/src/__tests__/video-reference-ref-id-tokens.test.ts

@@ -0,0 +1,301 @@
+/**
+ * `{ref:<id>}` / `{ref:<id>:<label>}` — id-addressed reference tokens.
+ *
+ * A client that names a reference by the `connectedReferences[].id` it sent
+ * (Studio's bound `@`-chips) gets the `@image_N` slot substituted by the
+ * platform AFTER the platform has numbered the references. That removes the
+ * client-side mirror of the numbering walk — the one duplicated rule that could
+ * silently misbind pictures for a client built against an older package.
+ *
+ * Contract pinned here:
+ *   - the slot comes from the SAME walk that numbers the directives (mention
+ *     URLs → canonical fallback → extras, offset by the leading flat refs);
+ *   - the token is resolved BEFORE the `referenceOrder` reorder, so the
+ *     renumber pass carries the binding to the ref's final seat — the opposite
+ *     of `{image:N}`, which is resolved AFTER it to keep the author's N;
+ *   - an unresolvable token never ships raw: label → the ref's display name
+ *     (when the id is known) → "";
+ *   - a prompt with no `{ref:` token is byte-identical to before.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  resolveVideoReferenceCore,
+  resolveRefIdTokens,
+  resolveReferenceTokens,
+} from "../video-reference-resolver.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const charRef = (over: Partial<ConnectedReference> = {}): ConnectedReference => ({
+  id: "char-kira", defaultName: "Kira", source: "wired-character", url: "https://r2/kira.png",
+  characterSlug: "kira", variantSlug: undefined, characterCanonicalDescription: null,
+  variantDescription: null, variantDisplayName: "canonical", ...over,
+})
+
+const A = "https://cdn/a.png"
+const B = "https://cdn/b.png"
+
+/** Every case: the token must be gone, whatever it resolved to. */
+function expectNoRawToken(prompt: string | undefined) {
+  expect(prompt ?? "").not.toMatch(/\{ref:/i)
+}
+
+describe("resolveVideoReferenceCore — {ref:<id>} id-addressed tokens", () => {
+  it("bare {ref:<id>} binds an image extra to its @image_N slot", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "drive {ref:car-1} fast",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/car.png"])
+    expect(out.prompt).toContain("- @image_1 (reference): a red car.")
+    expect(out.prompt).toContain("drive @image_1 fast")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("labeled {ref:<id>:<label>} binds through REF_BINDING.image (parity with {image:N:label})", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "drive {ref:car-1:car} fast",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.prompt).toContain("drive the car from @image_1 fast")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a canonical wired character binds to its canonical-fallback slot", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:char-kira} walks in",
+      wiredCharRefs: [charRef()],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png"])
+    expect(out.prompt).toContain("Use these characters:")
+    expect(out.prompt).toContain("@image_1 walks in")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a character VIEW (extra with characterSlug) binds to its pair-back slot after the canonical", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:view-1} turns to face {ref:char-kira}",
+      wiredCharRefs: [charRef()],
+      extraRefs: [{ id: "view-1", url: "https://r2/kira-side.png", characterSlug: "kira", description: "side profile" }],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png", "https://r2/kira-side.png"])
+    expect(out.prompt).toContain("- @image_2 is the same subject as @image_1, side profile.")
+    expect(out.prompt).toContain("@image_2 turns to face @image_1")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("leading flat refs offset the slot (D5 image-refs-first)", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "the {ref:obj} on the table",
+      wiredCharRefs: [],
+      leadingRefUrls: [A],
+      extraRefs: [{ id: "obj", url: B, description: "object" }],
+    })
+    expect(out.additionalUrls).toEqual([A, B])
+    expect(out.prompt).toContain("the @image_2 on the table")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("ids are opaque: `:` and `/` inside an id resolve, and a trailing label still parses", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:https://cdn/pic.png} beside {ref:kira:smile:smile}",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "https://cdn/pic.png", url: "https://cdn/pic.png", description: "pic" },
+        { id: "kira:smile", url: "https://r2/kira-smile.png", description: "smile" },
+      ],
+    })
+    expect(out.prompt).toContain("@image_1 beside the smile from @image_2")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("an unknown id degrades to its label, or to nothing — never the raw token", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a {ref:nope:ghost} b {ref:nope2} c",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "x", url: A, description: "d" }],
+    })
+    expect(out.prompt).toContain("a ghost b c")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a known ref the walk never seated degrades to its display name", () => {
+    // A wired character with no url is skipped by the canonical loop — the id
+    // is known (so the name is), but there is no slot to bind.
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:char-kira} waves at {ref:capped-1}",
+      wiredCharRefs: [charRef({ url: "" })],
+      extraRefs: [{ id: "x", url: A, description: "d" }],
+      // The caller's full id → name map (the route builds it from EVERY
+      // connectedReference, including the ones it capped out before the walk).
+      refNamesById: new Map([["capped-1", "Truck"]]),
+    })
+    expect(out.prompt).toContain("Kira waves at Truck")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a duplicate-URL extra never binds past the payload: its {ref:} degrades to its name", () => {
+    // The walk counts every extra with a url while `merged` dedups by URL, so
+    // the second extra's directive is numbered @image_2 although the payload
+    // carries ONE image (pre-existing walk-vs-merged drift). The token is
+    // range-gated against the image count, so it degrades instead of emitting
+    // a phantom binding.
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:x} then {ref:y}",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "x", url: A, description: "first" },
+        { id: "y", url: A, description: "second" },
+      ],
+      refNamesById: new Map([["y", "Second"]]),
+    })
+    expect(out.additionalUrls).toEqual([A])
+    expect(out.prompt).toContain("@image_1 then Second")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("resolves BEFORE the referenceOrder reorder, so the binding follows the ref to its final seat", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:y} leads, {ref:x} follows",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "x", url: A, description: "ax" },
+        { id: "y", url: B, description: "by" },
+      ],
+      // Extras' tile ids are `wired:<url>` (the reorder contract, unchanged).
+      referenceOrder: [`wired:${B}`, `wired:${A}`],
+    })
+    expect(out.additionalUrls).toEqual([B, A])
+    expect(out.prompt).toContain("@image_1 leads, @image_2 follows")
+    expect(out.prompt).toContain("- @image_1 (reference): by.")
+    expect(out.prompt).toContain("- @image_2 (reference): ax.")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("keeps {image:N} resolved AFTER the reorder (author's N kept) while {ref:} follows the ref", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:y} and {image:2:second}",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "x", url: A, description: "ax" },
+        { id: "y", url: B, description: "by" },
+      ],
+      referenceOrder: [`wired:${B}`, `wired:${A}`],
+    })
+    // y moved to seat 1 → {ref:y} rides along; {image:2} keeps the literal 2.
+    expect(out.prompt).toContain("@image_1 and the second from @image_2")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("an @-mentioned character's ref binds to the mention's slot", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1 waves, then {ref:char-kira} sits",
+      wiredCharRefs: [charRef()],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png"])
+    expect(out.prompt).toContain("Kira waves, then @image_1 sits")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("is independent of hybridRoles — same slot, no legend block", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "drive {ref:car-1} fast",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+      hybridRoles: true,
+    })
+    expect(out.prompt).not.toContain("Use these characters:")
+    expect(out.prompt).toContain("drive @image_1 fast")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a prompt with no {ref: token is untouched — `{ref}` and `ref:` are not tokens", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "circle {image:1:object} {ref} ref: x",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.prompt).toContain("circle the object from @image_1 {ref} ref: x")
+  })
+
+  it("an empty id drops to nothing and the keyword is case-insensitive", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "x {ref:} {REF:car-1} y",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.prompt).toContain("x @image_1 y")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("imageRefCount: 0 (no image tokens may bind) degrades a seated ref to its name", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:char-kira} walks",
+      wiredCharRefs: [charRef()],
+      imageRefCount: 0,
+    })
+    expect(out.prompt).toContain("Kira walks")
+    expect(out.prompt).not.toContain("@image_1 walks")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("early-return path (no wired chars, no extras): degrades to name / label / nothing", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:a} and {ref:b:the dog} and {ref:c}",
+      wiredCharRefs: [],
+      leadingRefUrls: [A],
+      refNamesById: new Map([["a", "Alpha"]]),
+    })
+    expect(out.additionalUrls).toEqual([A])
+    expect(out.prompt).toBe("Alpha and the dog and")
+    expectNoRawToken(out.prompt)
+  })
+})
+
+describe("resolveRefIdTokens — malformed and adversarial input", () => {
+  it("a malformed token (brace inside the id, no closing brace) never ships its `{ref:` prefix", () => {
+    const out = resolveRefIdTokens("x {ref:a{b} y {ref:unclosed z", {
+      slotById: new Map([["a", 1]]),
+      nameById: new Map(),
+      imageCount: 1,
+    })
+    expect(out).not.toMatch(/\{ref:/i)
+    // The net is bounded by whitespace/braces: the prose after each run survives.
+    expect(out).toContain(" y ")
+    expect(out).toContain(" z")
+  })
+
+  it("scans a prompt at the hard ceiling with an adversarial shape and still resolves (linear matcher)", () => {
+    // 30k chars of `{ref:` followed by label-class text with no closing brace —
+    // the shape that made a lazy-quantifier matcher quadratic.
+    const adversarial = "{ref:" + ":a".repeat(15000)
+    const out = resolveRefIdTokens(`${adversarial} end {ref:x}`, {
+      slotById: new Map([["x", 1]]),
+      nameById: new Map(),
+      imageCount: 1,
+    })
+    expect(out).not.toMatch(/\{ref:/i)
+    expect(out).toContain("end @image_1")
+  })
+})
+
+describe("resolveRefIdTokens (standalone — the route's no-image-ref early return)", () => {
+  it("binds in-range slots, and degrades label → name → nothing otherwise", () => {
+    const resolved = resolveRefIdTokens("{ref:x:car} {ref:x} {ref:y:dog} {ref:y} {ref:z}", {
+      slotById: new Map([["x", 2], ["y", 4]]),
+      nameById: new Map([["y", "Dog"]]),
+      imageCount: 3,
+    })
+    // y is seated at 4 but only 3 images ship → name; z is unknown → nothing.
+    expect(resolveReferenceTokens(resolved, { image: 3, video: 0, audio: 0 })).toBe(
+      "the car from @image_2 @image_2 dog Dog",
+    )
+  })
+
+  it("returns the prompt untouched when no {ref: token is present", () => {
+    const prompt = "plain {image:1} prose"
+    expect(resolveRefIdTokens(prompt, { slotById: new Map(), nameById: new Map(), imageCount: 0 })).toBe(prompt)
+    expect(resolveRefIdTokens(undefined, { slotById: new Map(), nameById: new Map(), imageCount: 0 })).toBeUndefined()
+  })
+})