@nodaro/shared 2.14.0 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

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

@@ -0,0 +1,303 @@
+import { describe, it, expect } from "vitest"
+import {
+  imageMentionSlug,
+  parseImageMentionToken,
+  findImageMentionTokens,
+  knownImageSlugsFromRefs,
+  imageMentionSlugForRef,
+} from "../image-mention-slug.js"
+import type { ConnectedReference } from "../types.js"
+
+/**
+ * Named-image mentions — `@<name-slug>:<index>[:<role>]`.
+ *
+ * Mirrors `location-mention-slug.test.ts`, minus everything locations have and
+ * media references don't (buckets, variants, usage modes). The load-bearing
+ * assertions here are the two that keep this parser from colliding with the
+ * other two grammars: a 4-part token is NEVER claimed, and the known-slug set
+ * drops grammar-invalid slugs.
+ */
+
+const media = (over: Partial<ConnectedReference> = {}): ConnectedReference => ({
+  id: "img-1",
+  defaultName: "Town",
+  source: "wired-image",
+  url: "https://cdn/town.png",
+  ...over,
+})
+
+describe("imageMentionSlug", () => {
+  it("lowercases and dash-joins", () => {
+    expect(imageMentionSlug("Town")).toBe("town")
+    expect(imageMentionSlug("Old Town Square")).toBe("old-town-square")
+  })
+
+  it("collapses punctuation runs and strips leading/trailing dashes", () => {
+    expect(imageMentionSlug("  Town -- Square!! ")).toBe("town-square")
+    expect(imageMentionSlug("--town--")).toBe("town")
+  })
+
+  it("keeps digits, including a leading one (emptiness is NOT the grammar gate)", () => {
+    // Non-empty yet UNPARSEABLE — the leading digit fails IMAGE_SLUG_PATTERN.
+    // `knownImageSlugsFromRefs` is what must drop it, not this function.
+    expect(imageMentionSlug("3D Render")).toBe("3d-render")
+  })
+
+  it("returns empty for a name with no latin alphanumerics", () => {
+    expect(imageMentionSlug("עיר")).toBe("")
+    expect(imageMentionSlug("🎬🎬")).toBe("")
+  })
+
+  it("is byte-identical to the character/location slug algorithm", () => {
+    for (const name of ["Kira", "Old Library", "A  B", "Ünï-cödé 12"]) {
+      expect(imageMentionSlug(name)).toBe(
+        name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, ""),
+      )
+    }
+  })
+})
+
+describe("parseImageMentionToken — rejects", () => {
+  it("rejects text that is not a token at all", () => {
+    expect(parseImageMentionToken("town:1")).toBeNull()   // no @
+    expect(parseImageMentionToken("@")).toBeNull()
+    expect(parseImageMentionToken("@town")).toBeNull()    // no index segment
+    expect(parseImageMentionToken("@town:")).toBeNull()   // empty index
+  })
+
+  it("rejects a non-positive or non-numeric index", () => {
+    expect(parseImageMentionToken("@town:0")).toBeNull()
+    expect(parseImageMentionToken("@town:x")).toBeNull()
+    expect(parseImageMentionToken("@town:1x")).toBeNull()
+  })
+
+  it("rejects out-of-grammar slugs", () => {
+    expect(parseImageMentionToken("@Town:1")).toBeNull()  // uppercase
+    expect(parseImageMentionToken("@3d:1")).toBeNull()    // leading digit
+    expect(parseImageMentionToken("@-town:1")).toBeNull() // leading dash
+  })
+
+  it("rejects a FOUR-part token — the collision guard against character mentions", () => {
+    expect(parseImageMentionToken("@town:1:a:b")).toBeNull()
+    expect(parseImageMentionToken("@kira:1:smile:face")).toBeNull()
+  })
+
+  it("rejects an empty or out-of-grammar role segment", () => {
+    expect(parseImageMentionToken("@town:1:")).toBeNull()
+    expect(parseImageMentionToken("@town:1:Bad")).toBeNull()
+    expect(parseImageMentionToken("@town:1:1st")).toBeNull()
+  })
+})
+
+describe("parseImageMentionToken — accepts", () => {
+  it("parses a bare 2-part token and emits NO role key", () => {
+    const parsed = parseImageMentionToken("@town:3")
+    expect(parsed).toEqual({ imageSlug: "town", imageIndex: 3 })
+    // Shape rule: a 2-part token must stay shape-identical to a role-less parser.
+    expect(parsed && "role" in parsed).toBe(false)
+    expect(parsed && "lock" in parsed).toBe(false)
+  })
+
+  it("parses a curated role in the 3rd segment", () => {
+    expect(parseImageMentionToken("@town:3:background")).toEqual({
+      imageSlug: "town",
+      imageIndex: 3,
+      role: "background",
+    })
+  })
+
+  it("passes a CUSTOM role through verbatim", () => {
+    expect(parseImageMentionToken("@town:3:my-custom-role")).toEqual({
+      imageSlug: "town",
+      imageIndex: 3,
+      role: "my-custom-role",
+    })
+  })
+
+  it("parses the ~lock / ~nolock sentinels as a tri-state", () => {
+    expect(parseImageMentionToken("@town:3~lock")).toEqual({
+      imageSlug: "town", imageIndex: 3, lock: true,
+    })
+    expect(parseImageMentionToken("@town:3~nolock")).toEqual({
+      imageSlug: "town", imageIndex: 3, lock: false,
+    })
+    expect(parseImageMentionToken("@town:3:background~nolock")).toEqual({
+      imageSlug: "town", imageIndex: 3, role: "background", lock: false,
+    })
+    // The role + force-ON pairing — the other half of the role×sentinel matrix.
+    expect(parseImageMentionToken("@town:3:background~lock")).toEqual({
+      imageSlug: "town", imageIndex: 3, role: "background", lock: true,
+    })
+  })
+
+  it("accepts a multi-segment slug and a large index", () => {
+    expect(parseImageMentionToken("@old-town-square:12")).toEqual({
+      imageSlug: "old-town-square",
+      imageIndex: 12,
+    })
+  })
+})
+
+describe("findImageMentionTokens", () => {
+  it("finds a known slug and reports its exact offset", () => {
+    const prompt = "a shot of @town:3 at dusk"
+    const [t] = findImageMentionTokens(prompt, ["town"])
+    expect(t.token).toBe("@town:3")
+    expect(t.imageSlug).toBe("town")
+    expect(t.imageIndex).toBe(3)
+    expect(prompt.slice(t.offset, t.offset + t.token.length)).toBe("@town:3")
+  })
+
+  it("matches a token at the very start of the prompt", () => {
+    const [t] = findImageMentionTokens("@town:1 at dusk", ["town"])
+    expect(t.offset).toBe(0)
+    expect(t.token).toBe("@town:1")
+  })
+
+  it("filters out slugs that are not known", () => {
+    expect(findImageMentionTokens("a shot of @town:3", [])).toEqual([])
+    expect(findImageMentionTokens("a shot of @town:3", ["village"])).toEqual([])
+  })
+
+  it("does not match an email-like `a@town:1` (preceding alphanumeric)", () => {
+    expect(findImageMentionTokens("mail a@town:1 now", ["town"])).toEqual([])
+  })
+
+  it("yields NO token for a 4-part CHARACTER token, even when the slug is a known image", () => {
+    // The `(?![:a-z0-9-])` lookahead: without it this would be captured as the
+    // 3-part `@kira:1:smile`, leaving `:face` dangling in the prompt.
+    expect(findImageMentionTokens("@kira:1:smile:face poses", ["kira"])).toEqual([])
+  })
+
+  it("does not swallow `~locked` as a sentinel (byte-identical to the location finder)", () => {
+    // The sentinel's own `(?![a-z0-9-])` rejects `~locked`, so the regex falls
+    // back to the bare `@town:1` and the `~locked` text stays literal — exactly
+    // what `findLocationMentionTokens` does for the same input.
+    const [t] = findImageMentionTokens("@town:1~locked", ["town"])
+    expect(t.token).toBe("@town:1")
+    expect("lock" in t).toBe(false)
+  })
+
+  it("does claim the sentinel when it is well-formed", () => {
+    const [t] = findImageMentionTokens("@town:1~lock", ["town"])
+    expect(t.token).toBe("@town:1~lock")
+    expect(t.lock).toBe(true)
+  })
+
+  it("claims a `~nolock` sentinel through the FINDER too (force-OFF, tri-state)", () => {
+    const [t] = findImageMentionTokens("a shot of @town:1~nolock at dusk", ["town"])
+    expect(t.token).toBe("@town:1~nolock")
+    expect(t.lock).toBe(false)
+    expect(findImageMentionTokens("@town:1~nolockx", ["town"])[0].token).toBe("@town:1")
+  })
+
+  it("yields NO token for a LOCATION bucket/variant token, even on a known slug", () => {
+    // The slash guard. Without it the finder claims the truncated 3-part prefix
+    // `@old-library:1:weather` and SPLICES it, leaving `/rain` dangling in the
+    // model-facing prompt — a corruption the character/location finders never
+    // commit (they leave an unresolvable token literal).
+    expect(findImageMentionTokens("a shot of @old-library:1:weather/rain", ["old-library"]))
+      .toEqual([])
+    // 4-part location token (variant + mode) — same rejection.
+    expect(findImageMentionTokens("@old-library:1:weather/rain:style", ["old-library"]))
+      .toEqual([])
+    // Sentinel + slash: the whole token stays literal rather than backtracking
+    // to `@town:1` and splicing that.
+    expect(findImageMentionTokens("@town:1~lock/rain", ["town"])).toEqual([])
+  })
+
+  it("still matches two mentions separated by a slash (`/` alone is not the signal)", () => {
+    const tokens = findImageMentionTokens("@town:1/@barn:2", ["town", "barn"])
+    expect(tokens.map((t) => t.token)).toEqual(["@town:1", "@barn:2"])
+  })
+
+  it("finds several mentions in prompt order", () => {
+    const tokens = findImageMentionTokens("@town:1 then @barn:2:background", ["town", "barn"])
+    expect(tokens.map((t) => t.token)).toEqual(["@town:1", "@barn:2:background"])
+    expect(tokens[1].role).toBe("background")
+  })
+})
+
+describe("knownImageSlugsFromRefs", () => {
+  it("includes wired-image and manual media refs", () => {
+    expect(
+      knownImageSlugsFromRefs([
+        media(),
+        media({ id: "m", defaultName: "My Upload", source: "manual", url: "https://cdn/u.png" }),
+      ]),
+    ).toEqual(["town", "my-upload"])
+  })
+
+  it("excludes every non-media source", () => {
+    expect(
+      knownImageSlugsFromRefs([
+        media({ source: "wired-character", defaultName: "Kira" }),
+        media({ source: "wired-location", defaultName: "Old Library" }),
+        media({ source: "wired-object", defaultName: "Chair" }),
+        media({ source: "wired-creature", defaultName: "Ember" }),
+      ]),
+    ).toEqual([])
+  })
+
+  it("excludes extra refs (they render through the extras path)", () => {
+    expect(knownImageSlugsFromRefs([media({ isExtraRef: true })])).toEqual([])
+  })
+
+  it("excludes url-less and name-less refs", () => {
+    expect(knownImageSlugsFromRefs([media({ url: "" })])).toEqual([])
+    expect(knownImageSlugsFromRefs([media({ defaultName: "" })])).toEqual([])
+  })
+
+  it("drops a grammar-invalid slug even though it is non-empty", () => {
+    // "3D Render" → "3d-render": truthy, but no token can ever match it.
+    expect(knownImageSlugsFromRefs([media({ defaultName: "3D Render" })])).toEqual([])
+    expect(knownImageSlugsFromRefs([media({ defaultName: "🎬" })])).toEqual([])
+  })
+
+  it("dedupes refs that slug to the same name", () => {
+    expect(
+      knownImageSlugsFromRefs([
+        media({ id: "a", defaultName: "Upload Image", url: "https://cdn/a.png" }),
+        media({ id: "b", defaultName: "Upload Image", url: "https://cdn/b.png" }),
+      ]),
+    ).toEqual(["upload-image"])
+  })
+
+  it("is the exact gate the finder uses (no slug in the set is unmatchable)", () => {
+    const refs = [media(), media({ id: "b", defaultName: "3D Render", url: "https://cdn/b.png" })]
+    const slugs = knownImageSlugsFromRefs(refs)
+    for (const slug of slugs) {
+      expect(findImageMentionTokens(`@${slug}:1`, slugs)).toHaveLength(1)
+    }
+  })
+})
+
+describe("imageMentionSlugForRef — the single mentionability gate", () => {
+  it("returns the slug for a mentionable media ref", () => {
+    expect(imageMentionSlugForRef(media())).toBe("town")
+    expect(imageMentionSlugForRef(media({ source: "manual", defaultName: "My Upload" })))
+      .toBe("my-upload")
+  })
+
+  it("returns null for every non-mentionable ref", () => {
+    expect(imageMentionSlugForRef(media({ source: "wired-character" }))).toBeNull()
+    expect(imageMentionSlugForRef(media({ isExtraRef: true }))).toBeNull()
+    expect(imageMentionSlugForRef(media({ url: "" }))).toBeNull()
+    expect(imageMentionSlugForRef(media({ defaultName: "" }))).toBeNull()
+    // Non-empty but grammar-invalid — emptiness is NOT the gate.
+    expect(imageMentionSlugForRef(media({ defaultName: "3D Render" }))).toBeNull()
+  })
+
+  it("is the SAME gate `knownImageSlugsFromRefs` applies (the two views cannot drift)", () => {
+    const refs = [
+      media(),
+      media({ id: "b", defaultName: "3D Render", url: "https://cdn/b.png" }),
+      media({ id: "c", defaultName: "Extra", isExtraRef: true, url: "https://cdn/c.png" }),
+      media({ id: "d", source: "wired-location", defaultName: "Old Library", url: "https://cdn/d.png" }),
+      media({ id: "e", source: "manual", defaultName: "My Upload", url: "https://cdn/e.png" }),
+    ]
+    expect(knownImageSlugsFromRefs(refs)).toEqual(
+      [...new Set(refs.map(imageMentionSlugForRef).filter((s): s is string => s !== null))],
+    )
+  })
+})

package/src/__tests__/prompt-length-limits.test.ts

@@ -92,8 +92,8 @@ describe("per-model prompt length limits", () => {
     it("returns verified per-model TTS caps", () => {
       expect(getMaxTtsChars("elevenlabs-turbo")).toBe(40000)
       expect(getMaxTtsChars("elevenlabs-multilingual")).toBe(10000)
-      expect(getMaxTtsChars("elevenlabs-v3")).toBe(3000) // conservative
-      expect(getMaxTtsChars("elevenlabs-dialogue")).toBe(2000)
+      expect(getMaxTtsChars("elevenlabs-v3")).toBe(5000) // official cap (probed 2026-08-30)
+      expect(getMaxTtsChars("elevenlabs-dialogue")).toBe(5000) // total across lines
     })
     it("defaults to TTS_TEXT_MAX for the legacy/unknown provider", () => {
       expect(getMaxTtsChars("elevenlabs")).toBe(TTS_TEXT_MAX)

package/src/__tests__/to-connected-references.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest"
 
 import { characterMentionSlug } from "../character-mention-slug.js"
 import { locationMentionSlug } from "../location-mention-slug.js"
+import { imageMentionSlug, knownImageSlugsFromRefs } from "../image-mention-slug.js"
 import {
   toConnectedReference,
   toConnectedReferences,
@@ -109,6 +110,50 @@ describe("toConnectedReference", () => {
     ).toBe(false)
   })
 
+  it("maps an image binding to a wired-image reference (no slug field — derived at prompt time)", () => {
+    expect(
+      toConnectedReference({
+        id: "img-1",
+        kind: "image",
+        name: "Town",
+        url: "https://r2.example/town.png",
+      }),
+    ).toEqual({
+      id: "img-1",
+      defaultName: "Town",
+      source: "wired-image",
+      url: "https://r2.example/town.png",
+    })
+  })
+
+  it("keeps the image name addressable by the derived mention slug", () => {
+    const ref = toConnectedReference({
+      id: "img-1",
+      kind: "image",
+      name: "Old Town Square",
+      url: "https://r2.example/town.png",
+    })
+    // There is no `imageSlug` on the wire — `knownImageSlugsFromRefs` derives it
+    // from `defaultName`, so this ref answers to `@old-town-square:N`.
+    expect(knownImageSlugsFromRefs([ref])).toEqual([imageMentionSlug("Old Town Square")])
+    expect(knownImageSlugsFromRefs([ref])).toEqual(["old-town-square"])
+  })
+
+  it("folds an image description into the reference; absent adds no key", () => {
+    expect(
+      toConnectedReference({
+        id: "img-1",
+        kind: "image",
+        name: "Town",
+        url: "https://r2.example/town.png",
+        description: "a quiet town square at dusk",
+      }).description,
+    ).toBe("a quiet town square at dusk")
+    expect(
+      "description" in toConnectedReference({ id: "img-2", kind: "image", name: "Barn" }),
+    ).toBe(false)
+  })
+
   it("falls back to a placeholder-safe empty url when the entity has no thumbnail", () => {
     expect(
       toConnectedReference({

package/src/__tests__/video-analysis.test.ts

@@ -287,6 +287,17 @@ describe("cinematography fields (angle / speed / onScreenText / look)", () => {
     expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene }] }).success).toBe(true)
   })
 
+  it("round 4: a scene carries a free-text `transition` beside the legacy enum", () => {
+    // F.8: the analyser describes the edit in its own words; the enum is legacy.
+    const ok = windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, transition: "fast blurred pan left" }] })
+    expect(ok.success).toBe(true)
+    expect(ok.success && ok.data.scenes[0]!.transition).toBe("fast blurred pan left")
+    expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, transition: "" }] }).success).toBe(false)
+    expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, transition: "x".repeat(121) }] }).success).toBe(false)
+    // legacy blueprints still parse
+    expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, transitionOut: "whip" }] }).success).toBe(true)
+  })
+
   it("marks the viewpoints where no face is visible — auto-cast reads this", () => {
     // A reference frame shot from behind cannot cast a face, however well framed.
     expect([...VIDEO_ANALYSIS_FACELESS_ANGLES].sort()).toEqual(["from-behind", "over-the-shoulder"])

package/src/character-voice.ts

@@ -40,9 +40,10 @@ export interface DialogueLine {
 }
 
 /**
- * A dialogue line resolved to a concrete voice, in the exact shape the
- * ElevenLabs Dialogue v3 primitive (`POST /v1/text-to-dialogue`) consumes:
- * `{ text, voice }` per line, in order. `voiceType` rides along so the TTS layer
+ * A dialogue line resolved to a concrete voice: `{ text, voice }` per line, in
+ * order. `voice` is OUR identifier (premade name or library/custom UUID) — the
+ * direct ElevenLabs Dialogue call resolves it per line to the `voice_id` the
+ * wire shape (`inputs[]`) wants. `voiceType` rides along so the TTS layer
  * resolves premade-by-name vs library/custom-by-id correctly.
  */
 export interface ResolvedDialogueVoiceLine {

package/src/image-mention-slug.ts

@@ -0,0 +1,236 @@
+/**
+ * Named-image `@-mention` parser — `@<name-slug>:<index>[:<role>]`.
+ *
+ * The media analog of `character-mention-slug.ts` / `location-mention-slug.ts`,
+ * for a wired image (`wired-image` / `manual` reference) addressed by the slug of
+ * its NAME: an upload node's label on the canvas, or the name a thin client puts
+ * on the reference. The grammar is the SIMPLEST of the three — 2 or 3 segments,
+ * no buckets, no variants, no usage-mode enum — because a media reference has no
+ * variant array to select from and no identity mode to override. Every valid 3rd
+ * segment is a ROLE.
+ *
+ *   @town:3                  — bare mention; renders the reference's binding
+ *                              ("reference image C") at the typed position
+ *   @town:3:background       — role phrase ("the background from reference image C")
+ *   @town:3:my-custom-role   — custom roles pass through verbatim
+ *   @town:3~lock             — additive identity-lock sentinel (also `~nolock`)
+ *   @town:1:a:b              — NULL. A 4-part token is never an image mention.
+ *
+ * NO WIRE FIELD. Unlike `characterSlug` / `locationSlug`, there is no `imageSlug`
+ * on `ConnectedReference`: the slug is DERIVED from `defaultName` at resolve time
+ * (`knownImageSlugsFromRefs`), so a client cannot drift from the grammar and the
+ * reference schema is untouched.
+ *
+ * NO LEGACY RESOLVER. Only the hybrid reference format resolves these tokens;
+ * under the legacy format an `@name:N` token stays literal text and the
+ * reference auto-attaches exactly as it does today.
+ */
+
+import type { ConnectedReference } from "./types.js"
+
+/**
+ * Grammar-valid slug shape — the exact shape `findImageMentionTokens`' regex can
+ * produce, and therefore the gate on BOTH sides of the match.
+ *
+ * Emptiness is NOT the gate: `imageMentionSlug("3D Render")` → `"3d-render"` is
+ * non-empty yet UNPARSEABLE (a leading digit), so a ref named "3D Render" must be
+ * dropped from the known-slug set even though its slug is truthy. This pattern is
+ * what drops it.
+ */
+const IMAGE_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/
+
+/**
+ * Slugify an image reference's display name for `@`-mention tokens. Byte-
+ * identical algorithm to `characterMentionSlug` / `locationMentionSlug`; kept as
+ * a separate export to make the call site's intent explicit and to allow future
+ * divergence.
+ */
+export function imageMentionSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+}
+
+export interface ImageMentionTokenInfo {
+  /** The matched token text, verbatim — spliced out of the prompt at resolve time. */
+  readonly token: string
+  readonly imageSlug: string
+  /**
+   * 1-based correlation index assigned at insertion by the autocomplete
+   * (`nextMentionIndex` = max(existing N) + 1, unified across characters,
+   * locations and images). The hybrid resolver binds by its own numbering walk,
+   * so the index is CORRELATION ONLY — it is never echoed into the prompt.
+   */
+  readonly imageIndex: number
+  /**
+   * Per-mention ROLE from the 3rd segment (`@town:3:background`) — curated
+   * (`REFERENCE_ROLE_PRESETS["wired-image"]`) or custom, stored VERBATIM. Media
+   * role presets are all single-word, so this never needs `normalizeRoleSlug`
+   * (the location-only remapping for multi-word presets). OMITTED (undefined,
+   * never null) for 2-part tokens, so those stay shape-identical to a parser
+   * with no role support.
+   */
+  readonly role?: string
+  /**
+   * Additive `~lock` / `~nolock` sentinel. Tri-state: `true` (force ON) |
+   * `false` (force OFF, suppressing a ref-level `identityLock.enabled`) |
+   * ABSENT/undefined (inherit the ref default). Honored only by the hybrid
+   * resolver — there is no legacy image resolver to make it inert on.
+   */
+  readonly lock?: boolean
+  /** Byte offset into the source prompt — used to splice the token out. */
+  readonly offset: number
+}
+
+/**
+ * Parse a single `@<name-slug>:<index>[:<role>]` token. Returns null when the
+ * token doesn't match a supported shape (the caller falls back to literal text).
+ *
+ * Segment count is 2 or 3 — NOT 2–4 like the character/location parsers. A media
+ * reference has no variant/bucket slot, so there is nothing for a 4th segment to
+ * mean, and claiming one would let this parser swallow a character token.
+ */
+export function parseImageMentionToken(text: string): {
+  imageSlug: string
+  imageIndex: number
+  /** Present ONLY for a 3-part token; omitted otherwise (shape rule). */
+  role?: string
+  /** Present ONLY when a sentinel was found; omitted otherwise (shape rule). */
+  lock?: boolean
+} | null {
+  if (!text.startsWith("@")) return null
+  let rest = text.slice(1)
+  if (rest.length === 0 || !/^[a-z]/.test(rest)) return null
+
+  // Strip a trailing `~nolock` (force OFF) or `~lock` (force ON) BEFORE splitting
+  // so the segment grammar is untouched (a `~` never appears inside a segment).
+  // Check `~nolock` FIRST — `~lock` is its suffix. A token with NEITHER sentinel
+  // gains NO `lock` key.
+  let lockField: { lock?: boolean } = {}
+  if (rest.endsWith("~nolock")) {
+    rest = rest.slice(0, -"~nolock".length)
+    lockField = { lock: false }
+  } else if (rest.endsWith("~lock")) {
+    rest = rest.slice(0, -"~lock".length)
+    lockField = { lock: true }
+  }
+
+  const parts = rest.split(":")
+  if (parts.length < 2 || parts.length > 3) return null
+
+  const [imageSlug, indexStr, third] = parts
+  if (!IMAGE_SLUG_PATTERN.test(imageSlug)) return null
+  if (!/^\d+$/.test(indexStr)) return null
+  const imageIndex = parseInt(indexStr, 10)
+  if (!Number.isInteger(imageIndex) || imageIndex < 1) return null
+
+  if (parts.length === 2) return { imageSlug, imageIndex, ...lockField }
+  if (!IMAGE_SLUG_PATTERN.test(third)) return null
+  return { imageSlug, imageIndex, role: third, ...lockField }
+}
+
+/**
+ * Find every image `@-mention` in a prompt whose slug is a known image slug.
+ *
+ * `knownImageSlugs` (from `knownImageSlugsFromRefs`) is what keeps this parser
+ * off the other two grammars' tokens — all three finders match the same
+ * `@slug:N…` surface and only the known-slug set separates them.
+ */
+export function findImageMentionTokens(
+  prompt: string,
+  knownImageSlugs: readonly string[],
+): ImageMentionTokenInfo[] {
+  const tokens: ImageMentionTokenInfo[] = []
+  // ONE optional segment (the role) — images have no variant/bucket slot.
+  //
+  // The trailing `(?![:a-z0-9-])` is the DELIBERATE divergence from the character
+  // and location finders. Without it, a 4-part CHARACTER token that the character
+  // pass failed to resolve (`@kira:1:smile:face`) would be captured here as the
+  // 3-part `@kira:1:smile`, leaving `:face` dangling in the prompt. The lookahead
+  // makes the regex backtrack and match nothing, so a 4-part token is NEVER an
+  // image mention. `~lock` still matches (`~` is outside the class), and its own
+  // `(?![a-z0-9-])` keeps `~locked` / `~nolockx` literal.
+  //
+  // Linear-scan shape (a fixed prefix then bounded optional groups, no nested
+  // quantifiers) — matching the sibling finders, and ReDoS-free.
+  const regex =
+    /(?:^|[^a-zA-Z0-9])(@[a-z][a-z0-9-]*:\d+(?::[a-z][a-z0-9-]*)?(?:~(?:no)?lock(?![a-z0-9-]))?)(?![:a-z0-9-])/g
+  const knownSet = new Set(knownImageSlugs)
+  for (const match of prompt.matchAll(regex)) {
+    const token = match[1]
+    const offset = (match.index ?? 0) + (match[0].length - token.length)
+    // SLASH GUARD — the second half of the collision guard, and the reason it
+    // is a post-match check instead of another lookahead in the regex. `/` is
+    // the LOCATION grammar's bucket/variant separator (`@lib:1:weather/rain`),
+    // so a token immediately followed by `/<segment>` is a sibling-grammar
+    // token, never an image mention. A lookahead cannot express this: the
+    // engine would just BACKTRACK to a shorter prefix (`@lib:1:weather` →
+    // `@lib:1`, or `@town:1~lock` → `@town:1`) and splice THAT, which is the
+    // very corruption being prevented. Rejecting the whole match here leaves
+    // the token literal, exactly as the character/location finders do.
+    //
+    // `/` alone is NOT the signal — `@town:1/@barn:2` (two mentions separated
+    // by a slash) must keep matching, and a location segment always starts
+    // `[a-z]`. So the guard is `/` + a segment start.
+    if (/^\/[a-z]/.test(prompt.slice(offset + token.length))) continue
+    const parsed = parseImageMentionToken(token)
+    if (parsed && knownSet.has(parsed.imageSlug)) {
+      tokens.push({ token, ...parsed, offset })
+    }
+  }
+  return tokens
+}
+
+/**
+ * The mention slug a single reference contributes, or `null` when the ref
+ * cannot carry a mention at all — the SINGLE gate, so every view of "which
+ * refs are mentionable" is the same view.
+ *
+ * Shared by `knownImageSlugsFromRefs` (the finder's known-slug set) and the
+ * prompt-builder's hybrid resolver (its slug → ref lookup map). Those two must
+ * admit exactly the same refs: a slug the finder accepts but the resolver drops
+ * would splice a token with nothing to bind, and a ref the resolver keys under
+ * a slug no token can match is dead weight. Emptiness is NOT the gate (see
+ * `IMAGE_SLUG_PATTERN`).
+ */
+export function imageMentionSlugForRef(r: ConnectedReference): string | null {
+  if (r.source !== "wired-image" && r.source !== "manual") return null
+  if (r.isExtraRef === true) return null
+  if (!r.url || !r.defaultName) return null
+  const slug = imageMentionSlug(r.defaultName)
+  return IMAGE_SLUG_PATTERN.test(slug) ? slug : null
+}
+
+/**
+ * The known-image-slug set for a reference list — the SINGLE source of truth for
+ * the derivation, shared by `buildImagePrompt`'s Phase 0 and the backend
+ * orchestrator's structured-branch gate so the two can never disagree about
+ * whether a prompt carries a resolvable image mention.
+ *
+ * Only MEDIA refs (`wired-image` / `manual`) with a URL participate — the other
+ * sources have their own mention grammars (characters, locations) or no mention
+ * path at all (objects, creatures).
+ *
+ * `isExtraRef` refs are EXCLUDED: an extra renders through the extras path with
+ * its own body line, so letting a mention also bind one would double-emit prose.
+ *
+ * Grammar-invalid slugs are DROPPED (see `IMAGE_SLUG_PATTERN`) — a ref named
+ * "3D Render" slugs to the non-empty but unparseable `"3d-render"`, and admitting
+ * it would put a slug in the set that no token can ever match.
+ *
+ * All four of those gates live in `imageMentionSlugForRef`, which the hybrid
+ * resolver's own lookup map uses too — one predicate, so the two views cannot
+ * drift apart.
+ */
+export function knownImageSlugsFromRefs(
+  refs: readonly ConnectedReference[],
+): string[] {
+  const out = new Set<string>()
+  for (const r of refs) {
+    const slug = imageMentionSlugForRef(r)
+    if (slug) out.add(slug)
+  }
+  return [...out]
+}

package/src/index.ts

@@ -809,6 +809,15 @@ export type {
   LocationMentionTokenInfo,
 } from "./location-mention-slug.js"
 
+export {
+  imageMentionSlug,
+  parseImageMentionToken,
+  findImageMentionTokens,
+  knownImageSlugsFromRefs,
+  imageMentionSlugForRef,
+} from "./image-mention-slug.js"
+export type { ImageMentionTokenInfo } from "./image-mention-slug.js"
+
 export {
   toConnectedReference,
   toConnectedReferences,