@nodaro/shared 2.15.0 → 2.17.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__/producer-types.test.ts

@@ -42,6 +42,28 @@ describe("producer-types", () => {
     expect(DYNAMIC_PRODUCER_TYPES.has("voice-changer-pro")).toBe(true)
   })
 
+  // Dubbing joined the dual-mode family with the full-surface upgrade
+  // (audio in → dubbed audio; video in / video sourceUrl → dubbed video +
+  // audio sidecar). EXPLICIT assertions — the suite does not fail on
+  // omission, so without these a refactor could drop dubbing from a set
+  // and resurrect the "cannot connect the outputs" bug for it alone.
+  it("registers dubbing as an audio producer (its default output)", () => {
+    expect(AUDIO_PRODUCER_TYPES.has("dubbing")).toBe(true)
+  })
+
+  it("registers dubbing as a dynamic producer (dual-mode → accepted on BOTH audio and video input handles)", () => {
+    expect(DYNAMIC_PRODUCER_TYPES.has("dubbing")).toBe(true)
+  })
+
+  it("keeps dubbing's producer membership identical to voice-changer (same dual-mode contract)", () => {
+    for (const [name, set] of Object.entries(ALL_SETS)) {
+      expect(
+        set.has("dubbing"),
+        `dubbing must match voice-changer in ${name}`,
+      ).toBe(set.has("voice-changer"))
+    }
+  })
+
   // voice-changer-pro is a behavioral twin of voice-changer (identical
   // dual-mode output: audio in → audio out; video in → video out). Their
   // producer-set membership must never drift apart — if voice-changer is

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/animals.ts

@@ -208,6 +208,63 @@ export function getAnimalLabel(id: string | undefined | null, fallback?: string)
   return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
 }
 
+/**
+ * The ONE authored phrasing for an animal selection — "featuring a golden
+ * retriever, Medium-large dog with …".
+ *
+ * WHY IT LIVES HERE: the phrase had two independent copies (the picker-catalog
+ * funnel's synthesized `promptHint` and `getParameterPromptHint`'s `animal`
+ * case), and the `subject` prompt channel needs a third caller. A third copy
+ * would be new drift, and the channel's registry cannot read `ANIMALS`
+ * directly — `catalog-funnel-ratchet.test.ts` derives its watch set from
+ * `picker-catalogs.ts`'s own uppercase value imports and can only SHRINK, so a
+ * new raw-array reader under `packages/prompts/src` fails CI. A FUNCTION in
+ * `@nodaro/shared` (where the catalog itself lives) is invisible to that scan
+ * and is the same "functions only" discipline `direction-registry.ts` follows.
+ *
+ * Empty string on a miss, matching every `get*PromptHint` in `@nodaro/prompts`:
+ * a retired or unknown id contributes no clause rather than throwing.
+ */
+export function getAnimalPromptHint(id: string | undefined | null): string {
+  const a = getAnimal(id)
+  return a ? `featuring a ${a.label.toLowerCase()}, ${a.description}` : ""
+}
+
+/** Parenthetical segments — "Rifle (bolt-action)", "ISO 1600 (visible grain)". */
+const PARENTHETICAL = /\([^)]*\)/g
+
+/**
+ * Mechanical label → term derivation, a deliberate LOCAL COPY of
+ * `@nodaro/prompts`' `deriveTerm`: `@nodaro/prompts` depends on this package,
+ * never the other way round, so the function cannot be imported here. The copy
+ * is pinned byte-for-byte against the original by
+ * `packages/prompts/src/__tests__/animal-getters-parity.test.ts` (which can
+ * import both sides) — the repo's "an invariant + guard test" idiom rather than
+ * "remember to update the other one".
+ */
+function deriveAnimalTerm(label: string): string {
+  return label
+    .replace(PARENTHETICAL, " ")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim()
+}
+
+/**
+ * The COMPACT counterpart of `getAnimalPromptHint`: the same lookup, the same
+ * empty-string-on-miss, returning the short professional term a prompt would
+ * actually carry ("golden retriever", "t-rex") instead of the full clause.
+ *
+ * An authored `term` wins; otherwise the label IS the professional term for a
+ * concrete object, resolved through the mechanical derivation — NOT a bare
+ * `toLowerCase()` — so a parenthetical label is stripped exactly the way every
+ * other catalog strips it.
+ */
+export function getAnimalTerm(id: string | undefined | null): string {
+  const a = getAnimal(id)
+  return a ? (a.term ?? deriveAnimalTerm(a.label)) : ""
+}
+
 export const ANIMAL_IDS: ReadonlyArray<string> = ANIMALS.map((a) => a.id)
 
 export const ANIMAL_SUBCATEGORY_LABELS: Readonly<Record<AnimalSubcategory, string>> = {

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 {