@nodaro/shared 2.15.0 → 2.17.0

package/src/entity-mention-slug.ts

@@ -0,0 +1,203 @@
+/**
+ * Wired-entity `@-mention` parser — `@<name-slug>:<index>[:<role>][~lock|~nolock]`
+ * for `wired-creature` and `wired-object` references.
+ *
+ * THE BUG THIS KILLS. Before this leg, creatures and objects were the only wired
+ * sources with NO mention grammar. A user writing "Nessie rises from the lake"
+ * with a creature node wired in got the creature's NAME as plain prose while its
+ * binding dangled as a trailing "the creature from reference image D" line after
+ * the style hints — two disconnected halves of one intent, which is exactly the
+ * failure mode mentions exist to remove. With a mention, the binding renders
+ * INLINE at the typed position and the trailing canonical fallback for that ref
+ * is suppressed.
+ *
+ *   @nessie:4                — bare mention; the source-default role phrase
+ *                              ("the creature from reference image D")
+ *   @nessie:4:markings       — role phrase ("the markings from reference image D")
+ *   @chair:2:material        — objects use the `wired-object` presets
+ *   @nessie:4:my-custom-role — custom roles pass through verbatim
+ *   @nessie:4~lock           — additive identity-lock sentinel (also `~nolock`)
+ *   @nessie:4:a:b            — NULL. A 4-part token is never an entity mention.
+ *
+ * GRAMMAR CORE. Identical grammar to the named-image mention, so the slug shape,
+ * the parser and the finder (with BOTH collision guards — the 4-part trailing
+ * reject and the location slash guard) are the SHARED `mention-token-grammar.ts`,
+ * not a second hand-copied edition. This module is the ENTITY view of that core:
+ * the field names, and the part that genuinely differs — WHICH refs contribute a
+ * slug.
+ *
+ * PRECEDENCE, across all five kinds:
+ *
+ *     character → location → image → creature → object
+ *
+ * Enforced by RESOLUTION ORDER in `buildImagePrompt`'s Phase 0, not by anything
+ * in this file: each pass splices its matched tokens out of the prompt before the
+ * next pass runs its finder, so a slug claimed by an earlier kind never reaches a
+ * later pass. A name shared by a character and a creature resolves as the
+ * CHARACTER, and the creature token never fires. The creature-before-object half
+ * of the tail is enforced inside the single entity pass, whose slug → ref map is
+ * built creature-first (see `resolveEntityMentionsHybrid`).
+ *
+ * NO WIRE FIELD, matching the image grammar and unlike `characterSlug` /
+ * `locationSlug`: the slug is DERIVED from `defaultName` at resolve time
+ * (`knownEntitySlugsFromRefs`), so a client cannot drift from the grammar and the
+ * reference schema is untouched.
+ *
+ * NO LEGACY RESOLVER — the image-grammar precedent. Only the hybrid reference
+ * format resolves these tokens; under the legacy format an `@name:N` token stays
+ * literal text and the entity auto-attaches with its trailing canonical phrase
+ * exactly as it does today. Legacy assembly has no inline role-phrase machinery
+ * at all (its object/creature rendering is the numbered-directive block), so
+ * there is no clean seam to add one and no consumer asking for it.
+ */
+
+import type { ConnectedReference } from "./types.js"
+import {
+  MENTION_SLUG_PATTERN,
+  findMentionTokens,
+  mentionNameSlug,
+  parseMentionToken,
+} from "./mention-token-grammar.js"
+
+/**
+ * Slugify a wired entity's display name for `@`-mention tokens. Byte-identical
+ * algorithm to `characterMentionSlug` / `imageMentionSlug`; kept as a separate
+ * export to make the call site's intent explicit.
+ */
+export function entityMentionSlug(name: string): string {
+  return mentionNameSlug(name)
+}
+
+export interface EntityMentionTokenInfo {
+  /** The matched token text, verbatim — spliced out of the prompt at resolve time. */
+  readonly token: string
+  readonly entitySlug: string
+  /**
+   * 1-based correlation index assigned at insertion by the autocomplete
+   * (`nextMentionIndex` = max(existing N) + 1, unified across every mention
+   * kind). The hybrid resolver binds by its own numbering walk, so the index is
+   * CORRELATION ONLY — it is never echoed into the prompt.
+   */
+  readonly entityIndex: number
+  /**
+   * Per-mention ROLE from the 3rd segment (`@nessie:4:markings`) — curated
+   * (`REFERENCE_ROLE_PRESETS["wired-creature"]` / `["wired-object"]`) or custom,
+   * stored VERBATIM. Both preset lists are entirely single-word, so this never
+   * needs `normalizeRoleSlug` (the location-only remapping for multi-word
+   * presets). OMITTED (undefined, never null) for 2-part tokens.
+   */
+  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 entity 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 wired
+ * creature or object 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 parseEntityMentionToken(text: string): {
+  entitySlug: string
+  entityIndex: 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 {
+  const parsed = parseMentionToken(text)
+  if (!parsed) return null
+  return {
+    entitySlug: parsed.slug,
+    entityIndex: parsed.index,
+    ...(parsed.role !== undefined ? { role: parsed.role } : {}),
+    ...(parsed.lock !== undefined ? { lock: parsed.lock } : {}),
+  }
+}
+
+/**
+ * Find every entity `@-mention` in a prompt whose slug is a known entity slug.
+ *
+ * `knownEntitySlugs` (from `knownEntitySlugsFromRefs`) is what keeps this parser
+ * off the other grammars' tokens — every finder matches the same `@slug:N…`
+ * surface and only the known-slug set separates them. Cross-kind precedence is
+ * additionally enforced by pass ORDER at the resolver (see the module header).
+ */
+export function findEntityMentionTokens(
+  prompt: string,
+  knownEntitySlugs: readonly string[],
+): EntityMentionTokenInfo[] {
+  return findMentionTokens(prompt, knownEntitySlugs).map((t) => ({
+    token: t.token,
+    entitySlug: t.slug,
+    entityIndex: t.index,
+    ...(t.role !== undefined ? { role: t.role } : {}),
+    ...(t.lock !== undefined ? { lock: t.lock } : {}),
+    offset: t.offset,
+  }))
+}
+
+/**
+ * The mention slug a single reference contributes, or `null` when the ref cannot
+ * carry an entity mention at all — the SINGLE gate, so every view of "which refs
+ * are entity-mentionable" is the same view.
+ *
+ * Shared by `knownEntitySlugsFromRefs` (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
+ * `MENTION_SLUG_PATTERN`) — a creature named "3-Eyed Raven" slugs to the truthy
+ * but unparseable `"3-eyed-raven"`.
+ *
+ * `isExtraRef` refs are EXCLUDED, mirroring `imageMentionSlugForRef`: an extra
+ * renders through the extras path with its own body line, so letting a mention
+ * also bind one would double-emit prose.
+ */
+export function entityMentionSlugForRef(r: ConnectedReference): string | null {
+  if (r.source !== "wired-creature" && r.source !== "wired-object") return null
+  if (r.isExtraRef === true) return null
+  if (!r.url || !r.defaultName) return null
+  const slug = entityMentionSlug(r.defaultName)
+  return MENTION_SLUG_PATTERN.test(slug) ? slug : null
+}
+
+/**
+ * The known-entity-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 entity mention.
+ *
+ * UNFILTERED, exactly like `knownImageSlugsFromRefs` and the character/location
+ * slug sets: every mentionable creature/object contributes its slug regardless of
+ * what any OTHER kind may also claim. Cross-kind precedence is a property of the
+ * resolver's pass order (character → location → image → creature → object), NOT
+ * of this set — subtracting the earlier kinds' slugs here would put the
+ * precedence rule in two places and let them drift.
+ *
+ * Creature and object share ONE set (and one resolver pass): the grammar, the
+ * gate and the rendering are identical, and `defaultRoleForSource(r.source)`
+ * already tells the two apart at phrase time. Their relative precedence is
+ * settled where a tie can actually occur — the resolver's slug → ref map, built
+ * creature-first.
+ */
+export function knownEntitySlugsFromRefs(
+  refs: readonly ConnectedReference[],
+): string[] {
+  const out = new Set<string>()
+  for (const r of refs) {
+    const slug = entityMentionSlugForRef(r)
+    if (slug) out.add(slug)
+  }
+  return [...out]
+}

package/src/image-mention-slug.ts

@@ -0,0 +1,187 @@
+/**
+ * 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 SHORT one — 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.
+ * It is not unique to media: `entity-mention-slug.ts` (creatures/objects) speaks
+ * the identical grammar off the shared core noted below.
+ *
+ *   @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.
+ *
+ * GRAMMAR CORE. The slug shape, the parser and the finder (including BOTH
+ * collision guards) live in `mention-token-grammar.ts` and are shared verbatim
+ * with `entity-mention-slug.ts` (creatures/objects), which speaks the identical
+ * 2-or-3-segment grammar. This module is the MEDIA view of that core: the
+ * per-kind field names, and the part that genuinely differs — WHICH refs
+ * contribute a slug.
+ *
+ * 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"
+import {
+  MENTION_SLUG_PATTERN,
+  findMentionTokens,
+  mentionNameSlug,
+  parseMentionToken,
+} from "./mention-token-grammar.js"
+
+/**
+ * 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.
+ */
+export function imageMentionSlug(name: string): string {
+  return mentionNameSlug(name)
+}
+
+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.
+ *
+ * Delegates to the shared `parseMentionToken` and renames its kind-neutral
+ * `slug` / `index` to this module's `imageSlug` / `imageIndex`. The optional
+ * `role` / `lock` keys are re-emitted CONDITIONALLY so the documented shape rule
+ * survives the rename: a 2-part token has no `role` key at all.
+ */
+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 {
+  const parsed = parseMentionToken(text)
+  if (!parsed) return null
+  return {
+    imageSlug: parsed.slug,
+    imageIndex: parsed.index,
+    ...(parsed.role !== undefined ? { role: parsed.role } : {}),
+    ...(parsed.lock !== undefined ? { lock: parsed.lock } : {}),
+  }
+}
+
+/**
+ * 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 grammars' tokens — every finder matches the same `@slug:N…`
+ * surface and only the known-slug set separates them.
+ */
+export function findImageMentionTokens(
+  prompt: string,
+  knownImageSlugs: readonly string[],
+): ImageMentionTokenInfo[] {
+  return findMentionTokens(prompt, knownImageSlugs).map((t) => ({
+    token: t.token,
+    imageSlug: t.slug,
+    imageIndex: t.index,
+    ...(t.role !== undefined ? { role: t.role } : {}),
+    ...(t.lock !== undefined ? { lock: t.lock } : {}),
+    offset: t.offset,
+  }))
+}
+
+/**
+ * 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
+ * `MENTION_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 MENTION_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, and — since the
+ * creature/object leg — wired entities via `knownEntitySlugsFromRefs`.
+ *
+ * `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 `MENTION_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

@@ -637,6 +637,8 @@ export {
   ANIMAL_SUBCATEGORY_ORDER,
   getAnimal,
   getAnimalLabel,
+  getAnimalPromptHint,
+  getAnimalTerm,
 } from "./animals.js"
 export type { Animal, AnimalSubcategory } from "./animals.js"
 
@@ -768,6 +770,8 @@ export type {
   WorkflowMediaRef,
   WorkflowPortability,
   WorkflowImportReport,
+  WorkflowImportSkippedAsset,
+  WorkflowAssetKind,
 } from "./workflow-export.js"
 export { stripExportContent } from "./workflow-export.js"
 
@@ -809,6 +813,29 @@ 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"
+
+// Wired-creature / wired-object mentions — the SAME 2-or-3-segment grammar as
+// the named-image mention (both are views of `mention-token-grammar.ts`), with
+// their own ref gate. The grammar core itself stays internal to the package: it
+// has no standalone consumer, and a third public `@slug:N` surface would invite
+// call sites that bypass a kind's gate.
+export {
+  entityMentionSlug,
+  parseEntityMentionToken,
+  findEntityMentionTokens,
+  knownEntitySlugsFromRefs,
+  entityMentionSlugForRef,
+} from "./entity-mention-slug.js"
+export type { EntityMentionTokenInfo } from "./entity-mention-slug.js"
+
 export {
   toConnectedReference,
   toConnectedReferences,

package/src/mention-token-grammar.ts

@@ -0,0 +1,167 @@
+/**
+ * The SHORT `@-mention` grammar core — `@<name-slug>:<index>[:<role>][~lock|~nolock]`.
+ *
+ * ONE parser, ONE finder, ONE pair of collision guards, shared by every mention
+ * kind whose token has NO variant/bucket slot:
+ *
+ *   - `image-mention-slug.ts`  — wired media (`wired-image` / `manual`)
+ *   - `entity-mention-slug.ts` — wired entities (`wired-creature` / `wired-object`)
+ *
+ * WHY EXTRACTED (and why the 5-line slugify precedent does NOT apply here). The
+ * character/location/image modules each keep their own copy of the trivial
+ * `characterMentionSlug` algorithm — duplication that is cheap because the
+ * function is five obvious lines. What is shared HERE is the opposite: the
+ * two-part collision guard (`(?![:a-z0-9-])`, which stops a 4-part CHARACTER
+ * token being claimed as a 3-part one, and the post-match slash guard, which
+ * stops a LOCATION bucket token being spliced as its own truncated prefix).
+ * Those guards exist precisely to prevent prompt corruption, and a second
+ * hand-copied edition of them is a drift surface with a corruption payload. So
+ * the media and entity grammars converge on this module and the per-kind files
+ * keep only what genuinely differs: WHICH refs contribute a slug.
+ *
+ * The character and location grammars do NOT use this core — their tokens carry
+ * 2–4 segments with a variant/bucket/usage-mode slot, a materially different
+ * shape, and their finders deliberately have NO trailing-reject lookahead.
+ */
+
+/**
+ * Grammar-valid slug shape — the exact shape `findMentionTokens`' regex can
+ * produce, and therefore the gate on BOTH sides of the match.
+ *
+ * Emptiness is NOT the gate: `mentionNameSlug("3D Render")` → `"3d-render"` is
+ * non-empty yet UNPARSEABLE (a leading digit), so a ref named "3D Render" must
+ * be dropped from a known-slug set even though its slug is truthy. This pattern
+ * is what drops it.
+ */
+export const MENTION_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/
+
+/**
+ * Slugify a reference's display name for `@`-mention tokens. Byte-identical
+ * algorithm to `characterMentionSlug` / `locationMentionSlug`; the per-kind
+ * modules re-export it under their own name so each call site's intent stays
+ * explicit.
+ */
+export function mentionNameSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+}
+
+/** Kind-neutral parse result. The per-kind modules rename `slug` / `index`. */
+export interface ParsedMentionToken {
+  readonly slug: string
+  readonly index: number
+  /** Present ONLY for a 3-part token; omitted otherwise (shape rule). */
+  readonly role?: string
+  /** Present ONLY when a sentinel was found; omitted otherwise (shape rule). */
+  readonly lock?: boolean
+}
+
+/** Kind-neutral finder result — a `ParsedMentionToken` plus its splice site. */
+export interface FoundMentionToken extends ParsedMentionToken {
+  /** The matched token text, verbatim — spliced out of the prompt at resolve time. */
+  readonly token: string
+  /** 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. Neither
+ * a media reference nor a wired entity has a 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 parseMentionToken(text: string): ParsedMentionToken | 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 [slug, indexStr, third] = parts
+  if (!MENTION_SLUG_PATTERN.test(slug)) return null
+  if (!/^\d+$/.test(indexStr)) return null
+  const index = parseInt(indexStr, 10)
+  if (!Number.isInteger(index) || index < 1) return null
+
+  if (parts.length === 2) return { slug, index, ...lockField }
+  if (!MENTION_SLUG_PATTERN.test(third)) return null
+  return { slug, index, role: third, ...lockField }
+}
+
+// ONE optional segment (the role) — media refs and wired entities 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 a
+// short-grammar 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 MENTION_TOKEN_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
+
+/**
+ * Find every short-grammar `@-mention` in a prompt whose slug is in
+ * `knownSlugs`.
+ *
+ * `knownSlugs` is what keeps one kind's parser off another kind's tokens — every
+ * finder matches the same `@slug:N…` surface and only the known-slug set
+ * separates them.
+ */
+export function findMentionTokens(
+  prompt: string,
+  knownSlugs: readonly string[],
+): FoundMentionToken[] {
+  const tokens: FoundMentionToken[] = []
+  // A module-level `g` regex carries `lastIndex` state; `matchAll` requires the
+  // `g` flag but resets nothing, so re-create the scanner per call.
+  const regex = new RegExp(MENTION_TOKEN_REGEX.source, "g")
+  const knownSet = new Set(knownSlugs)
+  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 a short-grammar 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 = parseMentionToken(token)
+    if (parsed && knownSet.has(parsed.slug)) {
+      tokens.push({ token, ...parsed, offset })
+    }
+  }
+  return tokens
+}

package/src/model-catalog.ts

@@ -58,6 +58,10 @@ export type ModelMode =
   | "isolation"
   | "dubbing"
   | "forced-alignment"
+  // dialogue — deliberately its own mode, never "tts": the dialogue model
+  // takes a multi-speaker script shape (inputs[]), not the single-text
+  // generate_speech contract, so it must never appear in a TTS model list.
+  | "dialogue"
   // video analysis
   | "video-analysis"
   // video audit — deliberately its own mode, never "video-analysis": the
@@ -2143,18 +2147,17 @@ const AUDIO_MODELS: Record<string, ModelCatalogEntry> = {
   "elevenlabs-dialogue": {
     id: "elevenlabs-dialogue",
     kind: "audio",
-    modes: ["tts"] as const,
+    // Its own mode, never "tts": the script shape (inputs[]) doesn't fit the
+    // single-text generate_speech contract, so list_models must never offer
+    // it there. The dialogue-capable MCP verb is `generate_dialogue`.
+    modes: ["dialogue"] as const,
     family: "ElevenLabs",
     label: "ElevenLabs Dialogue v3",
     series: "ElevenLabs",
-    description: "Multi-speaker dialogue TTS — give it a script, it voices each role.",
+    description: "Multi-speaker dialogue via the direct ElevenLabs API — give it a script, it voices each role (any voice: premade, library, or cloned).",
     useCases: ["tts", "dialogue", "multi-speaker"],
+    features: ["audio-tags", "voice-cloning"],
     pricing: [{ identifier: "elevenlabs-dialogue", credits: 25, note: "per 1K chars" }],
-    // Driven only via the dialogue/character-voice path (multi-speaker script
-    // shape), NOT the single-text generate_speech verb. Hide from MCP
-    // list_models so generate_speech (TTS_PROVIDERS) can't advertise it and
-    // then 400. Re-expose if a dialogue-capable MCP verb is added.
-    mcpHidden: true,
   },
 
   // ── ElevenLabs voice utilities ──
@@ -2220,9 +2223,9 @@ const AUDIO_MODELS: Record<string, ModelCatalogEntry> = {
     family: "ElevenLabs",
     label: "ElevenLabs Dubbing",
     series: "ElevenLabs",
-    description: "Translate + dub a video into a new language. Async.",
+    description: "Translate + dub audio or a whole video into a new language — video in, dubbed video out. Async.",
     useCases: ["dubbing", "multilingual"],
-    pricing: [{ identifier: "elevenlabs-dubbing", credits: 80 }],
+    pricing: [{ identifier: "elevenlabs-dubbing", credits: 40, note: "per minute of the dubbed span (min 1)" }],
   },
   "elevenlabs-forced-alignment": {
     id: "elevenlabs-forced-alignment",