@nodaro/prompts 1.9.0 → 1.10.0

package/src/character-fx.ts

@@ -37,9 +37,23 @@ export interface CharacterFx {
   readonly term?: string
 }
 
-export type CharacterFxPosition  = "auto" | "start" | "middle" | "end" | "full"
-export type CharacterFxDuration  = "auto" | "instant" | "short" | "medium" | "long"
-export type CharacterFxIntensity = "auto" | "subtle" | "natural" | "dynamic" | "crazy"
+/**
+ * The three timing scales, each derived from the catalog that defines it (see
+ * `CHARACTER_FX_POSITIONS` and friends below).
+ *
+ * The direction matters. These used to be hand-written unions with the clause
+ * tables written out separately beside them, so the two could disagree: add a
+ * step to the union, forget the clause, and the composer indexed a missing key
+ * — pushing `undefined` into the parts list, which `join(", ")` renders as a
+ * dangling separator on a prompt that then ships to a provider with the user's
+ * chosen parameter silently dropped. Deriving the union FROM the catalog makes
+ * that unrepresentable: one array is the source of the type, the option list
+ * the API serves, and the clause table, so a new step reaches all three or
+ * none. The exact id sets are pinned by `character-fx-timing-catalogs.test.ts`.
+ */
+export type CharacterFxPosition  = (typeof CHARACTER_FX_POSITIONS)[number]["id"]
+export type CharacterFxDuration  = (typeof CHARACTER_FX_DURATIONS)[number]["id"]
+export type CharacterFxIntensity = (typeof CHARACTER_FX_INTENSITIES)[number]["id"]
 
 export interface CharacterFxTiming {
   position?:  CharacterFxPosition
@@ -266,27 +280,96 @@ export const CHARACTER_FX_IDS: ReadonlyArray<string> = CHARACTER_FX.map((c) => c
 // Graph-aware composer — target input handle + timing fields + multi-pick
 // ---------------------------------------------------------------------------
 
-const POSITION_CLAUSES: Record<Exclude<CharacterFxPosition, "auto">, string> = {
-  start:  "the effect occurs at the opening of the clip",
-  middle: "the effect occurs in the middle of the clip",
-  end:    "the effect occurs at the end of the clip",
-  full:   "the effect persists for the entire clip",
+/**
+ * The character-fx node's three timing parameters, as catalogs.
+ *
+ * Graded scales in the standard option shape, so a consumer that can only send
+ * ids (Studio, the SDK, MCP) can offer Position / Duration / Intensity without
+ * composing prompt text of its own. `auto` is the no-op head of each scale: an
+ * empty `promptHint`, so an unset parameter contributes nothing and the model
+ * is left to decide, exactly as before these were enumerable.
+ *
+ * These are NOT the transition node's scales, even though the ids match. The
+ * wording is deliberately different — a transition OCCURS and SPANS the clip,
+ * an effect MANIFESTS and PERSISTS — and the three intensity clauses coincide
+ * by accident, not by shared definition. Keep the two catalogs separate; do
+ * not fold one into the other.
+ *
+ * `POSITION_CLAUSES` / `DURATION_CLAUSES` / `INTENSITY_CLAUSES` below are
+ * DERIVED from these arrays, so the clause the composer injects and the hint
+ * the catalog advertises are the same string by construction and cannot drift.
+ */
+export interface CharacterFxTimingOption {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+  readonly term?: string
 }
 
-const DURATION_CLAUSES: Record<Exclude<CharacterFxDuration, "auto">, string> = {
-  instant: "manifesting instantaneously",
-  short:   "manifesting over approximately 1 second",
-  medium:  "manifesting over approximately 2 seconds",
-  long:    "manifesting over approximately 3 seconds",
-}
+export const CHARACTER_FX_POSITIONS = [
+  { id: "auto",   label: "Auto",   description: "Let the model place the effect",    promptHint: "", term: "" },
+  { id: "start",  label: "Start",  description: "Occurs at the opening of the clip", promptHint: "the effect occurs at the opening of the clip", term: "at the opening of the clip" },
+  { id: "middle", label: "Middle", description: "Occurs in the middle of the clip",  promptHint: "the effect occurs in the middle of the clip", term: "mid-clip" },
+  { id: "end",    label: "End",    description: "Occurs at the end of the clip",     promptHint: "the effect occurs at the end of the clip", term: "at the end of the clip" },
+  { id: "full",   label: "Full",   description: "Persists for the entire clip",      promptHint: "the effect persists for the entire clip", term: "persisting for the whole clip" },
+] as const satisfies ReadonlyArray<CharacterFxTimingOption>
+
+export const CHARACTER_FX_DURATIONS = [
+  { id: "auto",    label: "Auto",         description: "Let the model time the effect",          promptHint: "", term: "" },
+  { id: "instant", label: "Instant",      description: "Manifests instantaneously",              promptHint: "manifesting instantaneously", term: "manifesting instantly" },
+  { id: "short",   label: "Short (~1s)",  description: "Manifests over approximately 1 second",  promptHint: "manifesting over approximately 1 second", term: "manifesting over about 1 second" },
+  { id: "medium",  label: "Medium (~2s)", description: "Manifests over approximately 2 seconds", promptHint: "manifesting over approximately 2 seconds", term: "manifesting over about 2 seconds" },
+  { id: "long",    label: "Long (~3s)",   description: "Manifests over approximately 3 seconds", promptHint: "manifesting over approximately 3 seconds", term: "manifesting over about 3 seconds" },
+] as const satisfies ReadonlyArray<CharacterFxTimingOption>
 
-const INTENSITY_CLAUSES: Record<Exclude<CharacterFxIntensity, "auto">, string> = {
-  subtle:  "with subtle restrained energy and minimal flourish",
-  natural: "with natural unhurried timing",
-  dynamic: "with dynamic energy and assertive flourish",
-  crazy:   "with extreme exaggerated energy, wild flourishes, and dramatic distortion",
+export const CHARACTER_FX_INTENSITIES = [
+  { id: "auto",    label: "Auto",    description: "Let the model judge the effect's energy", promptHint: "", term: "" },
+  { id: "subtle",  label: "Subtle",  description: "Restrained, minimal flourish",            promptHint: "with subtle restrained energy and minimal flourish", term: "subtly" },
+  { id: "natural", label: "Natural", description: "Unhurried, unforced timing",             promptHint: "with natural unhurried timing", term: "at a natural pace" },
+  { id: "dynamic", label: "Dynamic", description: "Assertive, energetic",                   promptHint: "with dynamic energy and assertive flourish", term: "energetically" },
+  { id: "crazy",   label: "Crazy",   description: "Extreme, wild, distorted",               promptHint: "with extreme exaggerated energy, wild flourishes, and dramatic distortion", term: "wildly exaggerated" },
+] as const satisfies ReadonlyArray<CharacterFxTimingOption>
+
+/**
+ * Index a timing catalog into the `Record<value, clause>` the composer reads.
+ *
+ * The key type is derived from the SAME array, so the record is total over the
+ * catalog by construction. That matters: the composer indexes these records
+ * without a fallback, and a missing key would push `undefined` into the parts
+ * list, which `join(", ")` renders as a dangling separator — a malformed prompt
+ * shipped to a provider with the user's chosen parameter silently dropped.
+ *
+ * Deliberately a private twin of the helper in `transitions.ts` rather than a
+ * shared import: the two nodes' timing catalogs must stay independent.
+ */
+function clausesOf<T extends CharacterFxTimingOption>(
+  options: ReadonlyArray<T>,
+): Record<Exclude<T["id"], "auto">, string> {
+  return Object.fromEntries(
+    options.filter((o) => o.id !== "auto").map((o) => [o.id, o.promptHint]),
+  ) as Record<Exclude<T["id"], "auto">, string>
 }
 
+const POSITION_CLAUSES  = clausesOf(CHARACTER_FX_POSITIONS)
+const DURATION_CLAUSES  = clausesOf(CHARACTER_FX_DURATIONS)
+const INTENSITY_CLAUSES = clausesOf(CHARACTER_FX_INTENSITIES)
+
+/**
+ * Widening guard. `as const` on the three arrays above is load-bearing: drop
+ * it and every id widens to `string`, the derived unions stop constraining
+ * anything, and the clause records degrade to `Record<string, string>` — the
+ * totality guarantee is gone with no runtime symptom. This assignment stops
+ * compiling the moment that happens (tsup's DTS build runs the type checker).
+ */
+type NarrowIds<T> = string extends T ? never : true
+const _timingIdsStayNarrow: [
+  NarrowIds<CharacterFxPosition>,
+  NarrowIds<CharacterFxDuration>,
+  NarrowIds<CharacterFxIntensity>,
+] = [true, true, true]
+void _timingIdsStayNarrow
+
 /**
  * Compose a character-fx prompt-hint sentence from an effect id (or array
  * of 1-2 ids for multi-pick) plus target-ref display names (from upstream

package/src/picker-catalogs.ts

@@ -59,7 +59,14 @@ import {
   TRANSITION_DURATIONS,
   TRANSITION_INTENSITIES,
 } from "./transitions.js"
-import { CHARACTER_FX, CHARACTER_FX_CATEGORY_LABELS, CHARACTER_FX_CATEGORY_ORDER } from "./character-fx.js"
+import {
+  CHARACTER_FX,
+  CHARACTER_FX_CATEGORY_LABELS,
+  CHARACTER_FX_CATEGORY_ORDER,
+  CHARACTER_FX_POSITIONS,
+  CHARACTER_FX_DURATIONS,
+  CHARACTER_FX_INTENSITIES,
+} from "./character-fx.js"
 import { POSES, POSE_CATEGORY_LABELS, POSE_CATEGORY_ORDER } from "./pose.js"
 import { MATERIALS, MATERIAL_CATEGORY_LABELS, MATERIAL_CATEGORY_ORDER } from "./materials.js"
 import { ANIMALS, ANIMAL_SUBCATEGORY_LABELS, ANIMAL_SUBCATEGORY_ORDER } from "@nodaro/shared"
@@ -557,6 +564,16 @@ const SINGLE_CATALOGS: readonly PickerCatalog[] = [
     categoryOrder: CHARACTER_FX_CATEGORY_ORDER,
     categoryLabels: CHARACTER_FX_CATEGORY_LABELS,
     options: toOptions(CHARACTER_FX, "category"),
+    // The node's three timing parameters, alongside the effect itself — the
+    // same shape `transition` carries above, but the character-fx scales, not
+    // the transition ones: the wording is deliberately different (an effect
+    // manifests and persists; a transition occurs and spans), so an id-only
+    // consumer must read these rows, never reuse the transition rows.
+    dimensions: perFieldDims([
+      ["position", CHARACTER_FX_POSITIONS],
+      ["duration", CHARACTER_FX_DURATIONS],
+      ["intensity", CHARACTER_FX_INTENSITIES],
+    ]),
   },
 
   // -------- "Subject / Object" family --------

package/src/provider-prompt-doctrine.ts

@@ -73,7 +73,7 @@ precise subject → action details → scene/environment → lighting & color to
 - Transitions and camera terms on 2.5: state a transition's trigger point AND method in one sentence — "At the 5-second mark, the camera quickly transitions leftward using a left wipe combined with a natural dissolve." Basic shot and camera terms are written directly (push in / pull out / pan / track / orbit / dolly zoom / whip pan / hard cut / dissolve / one-shot / speed ramp); only niche terms need [term + descriptive explanation] — which is exactly what the pickers' compact hint mode emits versus their long hints.
 
 **References (when reference media is attached)**
-- Refer to assets by ordinal in attachment order: "@Image 1", "Video 2", "Audio 1". Asset ORDER is priority — put the most identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding — \`{image:1:person}\` resolves to "the person from @image_1" — so a wired reference and its mention stay in sync.)
+- Refer to assets by ordinal in attachment order: "@Image 1", "Video 2", "Audio 1". Asset ORDER is priority — put the most identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding — \`{image:1:person}\` resolves to "the person from @image_1" — so a wired reference and its mention stay in sync. An API caller that passes \`connectedReferences\` can instead name a reference by its own id — \`{ref:<id>}\` / \`{ref:<id>:label}\` — and the platform substitutes the \`@image_N\` seat after it has numbered the references, so the client never computes N; a token whose reference was not attached drops to its label or name.)
 - Define each subject once, then reuse the label consistently: 'Define the woman in the red dress in Image 1 as the courier' … 'the courier opens the door'. In multi-character scenes bind every character to its image ("the man from Image 1 hands the box to the woman from Image 2") and append: "do not generate duplicate copies of the same character".
 - Character identity: ONE close-up headshot + ONE full-body image is ideal. On the 2.0 SKUs do NOT attach multi-view/three-view character sheets — the model reads the views as separate people, causing identity drift and twin duplicates; 2.5 accepts multi-view images (see "Generation differences").
 - 4-5 assets total works best (1-2 character images + 1 scene image + 1 camera-movement video + 1 audio clip). Maxing out the 9-image/3-video/3-audio limits degrades feature priority and adherence.
@@ -177,7 +177,7 @@ precise subject → action details → scene/environment → lighting & color to
 - Nothing visual connected → text-to-video. A concrete aspect ratio is required (21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 — no adaptive); Nodaro renders 16:9 unless one is picked.
 
 **References (when reference media is attached)**
-- Refer to assets by ordinal in attachment order: "@Image 1", "Video 1", "Audio 1". Put the identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding, so a wired reference and its mention stay in sync.)
+- Refer to assets by ordinal in attachment order: "@Image 1", "Video 1", "Audio 1". Put the identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding, so a wired reference and its mention stay in sync. An API caller that passes \`connectedReferences\` can instead write \`{ref:<id>}\` / \`{ref:<id>:label}\` with the reference's own id — the platform substitutes the \`@image_N\` seat after numbering.)
 - Caps: 9 reference images; 3 reference videos, each 2-15s and ≤15s combined; 3 reference audio clips, ≤15s combined. Reference audio cannot be used alone — it must accompany an image or video reference.
 - Define each subject once, then reuse the label consistently ("the woman from @Image 1 … the woman opens the door"). A focused set of 4-5 assets beats maxing every cap.
 - Billing note: generated seconds AND reference-video input seconds bill at the same per-second rate; the first 5 input images are free and each extra image adds a small surcharge; audio input is free.

package/src/ref-binding.ts

@@ -0,0 +1,45 @@
+/**
+ * The reference-binding surface string — `@image_N` / `@video_N` / `@audio_N`
+ * — and the one identity sentence built on it. Split out of
+ * `video-reference-resolver.ts` so the id-addressed token resolver
+ * (`ref-id-tokens.ts`) can bind through the same arrows without a module
+ * cycle; the resolver re-exports both, so importers are unaffected.
+ */
+
+/**
+ * The SINGLE swap-point for the reference-binding surface-string (design D1/D7).
+ *
+ * Every place that renders an `@image_N`-style binding into a video prompt — the
+ * per-image subject phrasing, the bare ordinal in a "Use these characters" /
+ * pair-back bullet, and the opening/closing frame directive — MUST go through
+ * these five arrows. The default form is `@image_N`; if the D7 probe shows a
+ * provider prefers the legacy `Image N` form, flipping is editing ONLY these five
+ * arrows (`@image_${n}` → `Image ${n}`), nothing downstream.
+ *
+ * This IS the live swap-point: `resolveVideoReferenceCore` routes the per-image
+ * subject phrasing, the "Use these characters" / pair-back bullet ordinals, and
+ * the frame directive through these arrows, and `resolveReferenceTokens` resolves
+ * the body `{image:N}` tokens through `REF_BINDING[kind]` — so the five arrows
+ * are the ONLY emission sites for the binding surface string.
+ */
+/**
+ * The identity-reference binding sentence shared by the flat-image-list
+ * resolvers (gemini-omni, veo i2v): names the ordinal span as identities and
+ * says the two things a multimodal model needs to hear — match exactly, and
+ * these are not frames. One spelling; both resolvers ride it.
+ */
+export function identityRefsSentence(firstOrdinal: number, lastOrdinal: number): string {
+  return firstOrdinal === lastOrdinal
+    ? `${REF_BINDING.ordinal(firstOrdinal)} is an identity reference for this shot's subjects — match its subject's exact appearance; it is not a frame.`
+    : `${REF_BINDING.ordinal(firstOrdinal)} through ${REF_BINDING.ordinal(lastOrdinal)} are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.`
+}
+
+export const REF_BINDING = {
+  image: (label: string, n: number) => `the ${label} from @image_${n}`,
+  video: (label: string, n: number) => `the ${label} from @video_${n}`,
+  audio: (label: string, n: number) => `the ${label} from @audio_${n}`,
+  /** ordinal as it appears in a "Use these characters" bullet / pair-back */
+  ordinal: (n: number) => `@image_${n}`,
+  frame: (n: number, role: "opening" | "closing") =>
+    `Use @image_${n} as the ${role} (${role === "opening" ? "first" : "last"}) frame of the video.`,
+} as const

package/src/ref-id-tokens.ts

@@ -0,0 +1,112 @@
+/**
+ * `{ref:<id>}` / `{ref:<id>:<label>}` — id-addressed reference tokens.
+ *
+ * The API/Studio form of the positional `{image:N}` token: the client names a
+ * reference by its OWN `connectedReferences[].id` and the platform substitutes
+ * the `@image_N` seat after IT has done the numbering. Without it a client that
+ * wanted the binding inline had to mirror the numbering walk client-side — a
+ * duplicated rule that misbinds pictures the moment the walk changes.
+ *
+ * `resolveVideoReferenceCore` builds the `RefIdTokenContext` DURING its walk
+ * and calls `resolveRefIdTokens` before the `referenceOrder` reorder (so the
+ * binding follows the reference to its final seat); the video routes call it
+ * standalone on their no-image-reference early return (nothing seated, so
+ * every token degrades).
+ */
+
+import { REF_BINDING } from "./ref-binding.js"
+
+/** The label class of `REFERENCE_TOKEN_RE` (`{image:N:label}`), shared. */
+const REF_TOKEN_LABEL_RE = /^[a-zA-Z0-9_ -]+$/
+/** Cheap gate for the whole pass — a prompt without it is untouched. */
+const HAS_REF_ID_TOKEN_RE = /\{ref:/i
+/**
+ * One well-formed `{ref:…}` token: everything between `{ref:` and the next
+ * `}` that contains no brace. Greedy over a brace-free class, so the scan is
+ * LINEAR in the prompt length whatever the content — `prompt` is up to
+ * `PROMPT_HARD_CEILING` (30k) chars of caller-controlled text, so a lazy
+ * quantifier with a nested optional label group here would be a quadratic-time
+ * ReDoS surface. The id / label split happens in code (`splitLabel`), not in
+ * the regex. `ref` is case-insensitive; ids are not.
+ */
+const REF_ID_TOKEN_RE = /\{[rR][eE][fF]:([^{}]*)\}/g
+/**
+ * Last-resort net for a MALFORMED `{ref:` (a brace inside the id, or no
+ * closing `}`): drop the `{ref:` run up to the next whitespace or brace, so
+ * the prefix can never reach a model, without eating prose past the token.
+ */
+const MALFORMED_REF_ID_TOKEN_RE = /\{[rR][eE][fF]:[^\s{}]*\}?/g
+
+/** What `resolveRefIdTokens` resolves against — the numbering walk's output. */
+export interface RefIdTokenContext {
+  /** Reference id → the 1-based `@image_N` seat the walk gave it. */
+  readonly slotById: ReadonlyMap<string, number>
+  /** Reference id → display name, the degrade target of a token that cannot bind. */
+  readonly nameById: ReadonlyMap<string, string>
+  /**
+   * How many image references actually ship — the same range gate `{image:N}`
+   * uses. A seat past it (a capped-out or duplicate-URL ref) must not bind.
+   */
+  readonly imageCount: number
+}
+
+/**
+ * Split a token's content into `<id>` and an optional `<label>` at the LAST
+ * colon — only when the tail is a well-formed label. Ids are opaque and may
+ * themselves contain `:` (`slug:variant`) or `/` (a URL), so nothing before
+ * the last colon is ever interpreted.
+ */
+function splitLabel(content: string): { id: string; label?: string } {
+  const at = content.lastIndexOf(":")
+  if (at === -1) return { id: content }
+  const tail = content.slice(at + 1)
+  if (!REF_TOKEN_LABEL_RE.test(tail)) return { id: content }
+  return { id: content.slice(0, at), label: tail }
+}
+
+/**
+ * Rewrite id-addressed reference tokens into the `@image_N` binding of the
+ * reference the caller sent under that id.
+ *
+ * Ids are matched by IDENTITY against the known ids (seated or named), never
+ * parsed by character class: the whole content is tried as an id first (the
+ * longest reading — an id may itself end in something label-shaped), then
+ * `<id>:<label>` split at the last colon, then the token is unknown. The label
+ * class is the one `REFERENCE_TOKEN_RE` uses. An id containing `{`, `}`, an
+ * `@name:N` mention or a `{image:N}` token is unsupported (the mention pass
+ * runs first and would rewrite it; a brace ends the token).
+ *
+ * Per token:
+ *   - id seated in range → `REF_BINDING.image(label, N)` when labeled, else the
+ *     bare `REF_BINDING.ordinal(N)` — exactly what `{image:N[:label]}` emits.
+ *   - otherwise (unknown id, ref skipped by the walk, capped out, or no image
+ *     references at all) → the label if given, else the ref's display name if
+ *     the id is known, else "". A token never ships raw — a malformed one is
+ *     dropped by the last-resort net.
+ *
+ * No whitespace tidy here: every caller runs `resolveReferenceTokens` after
+ * this (the core does at every return), and that collapses the gap a dropped
+ * token leaves. Returns the input untouched when it carries no `{ref:` at all.
+ */
+export function resolveRefIdTokens(
+  prompt: string | undefined,
+  ctx: RefIdTokenContext,
+): string | undefined {
+  if (!prompt || !HAS_REF_ID_TOKEN_RE.test(prompt)) return prompt
+  const known = (id: string): boolean => id.length > 0 && (ctx.slotById.has(id) || ctx.nameById.has(id))
+  const bind = (id: string, label: string | undefined): string => {
+    const slot = ctx.slotById.get(id)
+    if (slot !== undefined && slot >= 1 && slot <= ctx.imageCount) {
+      return label ? REF_BINDING.image(label, slot) : REF_BINDING.ordinal(slot)
+    }
+    return label ?? ctx.nameById.get(id) ?? ""
+  }
+  return prompt
+    .replace(REF_ID_TOKEN_RE, (_match, content: string) => {
+      if (known(content)) return bind(content, undefined)
+      const { id, label } = splitLabel(content)
+      if (known(id)) return bind(id, label)
+      return label ?? ""
+    })
+    .replace(MALFORMED_REF_ID_TOKEN_RE, "")
+}

package/src/video-reference-resolver.ts

@@ -33,44 +33,15 @@ import { resolveCharacterMentions, applyReferenceOrderToVideo } from "./prompt-b
 import { roleToPhrase, REFERENCE_ROLE_PRESETS, resolveDefaultRole } from "@nodaro/shared"
 import { buildIdentityLockLine, withForcedIdentityLock } from "./identity-lock.js"
 import type { ConnectedReference } from "@nodaro/shared"
+import { REF_BINDING } from "./ref-binding.js"
+import { resolveRefIdTokens } from "./ref-id-tokens.js"
 
-/**
- * The SINGLE swap-point for the reference-binding surface-string (design D1/D7).
- *
- * Every place that renders an `@image_N`-style binding into a video prompt — the
- * per-image subject phrasing, the bare ordinal in a "Use these characters" /
- * pair-back bullet, and the opening/closing frame directive — MUST go through
- * these five arrows. The default form is `@image_N`; if the D7 probe shows a
- * provider prefers the legacy `Image N` form, flipping is editing ONLY these five
- * arrows (`@image_${n}` → `Image ${n}`), nothing downstream.
- *
- * This IS the live swap-point: `resolveVideoReferenceCore` routes the per-image
- * subject phrasing, the "Use these characters" / pair-back bullet ordinals, and
- * the frame directive through these arrows, and `resolveReferenceTokens` resolves
- * the body `{image:N}` tokens through `REF_BINDING[kind]` — so the five arrows
- * are the ONLY emission sites for the binding surface string.
- */
-/**
- * The identity-reference binding sentence shared by the flat-image-list
- * resolvers (gemini-omni, veo i2v): names the ordinal span as identities and
- * says the two things a multimodal model needs to hear — match exactly, and
- * these are not frames. One spelling; both resolvers ride it.
- */
-export function identityRefsSentence(firstOrdinal: number, lastOrdinal: number): string {
-  return firstOrdinal === lastOrdinal
-    ? `${REF_BINDING.ordinal(firstOrdinal)} is an identity reference for this shot's subjects — match its subject's exact appearance; it is not a frame.`
-    : `${REF_BINDING.ordinal(firstOrdinal)} through ${REF_BINDING.ordinal(lastOrdinal)} are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.`
-}
+// The binding surface string and the id-addressed token resolver live in their
+// own modules (see them for the contracts); re-exported here so every existing
+// importer of this module — and the package index's `export *` — keeps working.
+export { REF_BINDING, identityRefsSentence } from "./ref-binding.js"
+export { resolveRefIdTokens, type RefIdTokenContext } from "./ref-id-tokens.js"
 
-export const REF_BINDING = {
-  image: (label: string, n: number) => `the ${label} from @image_${n}`,
-  video: (label: string, n: number) => `the ${label} from @video_${n}`,
-  audio: (label: string, n: number) => `the ${label} from @audio_${n}`,
-  /** ordinal as it appears in a "Use these characters" bullet / pair-back */
-  ordinal: (n: number) => `@image_${n}`,
-  frame: (n: number, role: "opening" | "closing") =>
-    `Use @image_${n} as the ${role} (${role === "opening" ? "first" : "last"}) frame of the video.`,
-} as const
 
 /**
  * Positional reference counts the editor tokens are resolved against — how many
@@ -135,11 +106,19 @@ export function resolveReferenceTokens(
   )
 }
 
+
 /**
  * A user-attached "extra reference image" row. Layer-agnostic shape of the
  * frontend `ExtraRef` / backend extras: only the fields this core reads.
  */
 export interface VideoExtraRef {
+  /**
+   * The caller's own id for this reference (`connectedReferences[].id` on the
+   * route, `extraRefs[].id` on the canvas) — what a `{ref:<id>}` token in the
+   * prompt names. Slot-map only: the reorder's tile id stays `wired:<url>`.
+   * Absent → the extra cannot be addressed by id (it still numbers normally).
+   */
+  id?: string
   url: string
   description?: string
   characterSlug?: string
@@ -241,6 +220,15 @@ export interface ResolveVideoReferenceCoreArgs {
    * Wired in Phase B Tasks 2-3.
    */
   hybridRoles?: boolean
+  /**
+   * Display names for EVERY reference the caller knows by id — including the
+   * ones it did NOT hand to this walk (the route caps `connectedReferences` to
+   * the provider's image budget before calling in). A `{ref:<id>}` token that
+   * cannot bind degrades to `label ?? refNamesById[id] ?? ""`, so a capped-out
+   * or skipped reference keeps its name in the prose instead of vanishing.
+   * The wired character refs' `defaultName`s are known without this.
+   */
+  refNamesById?: ReadonlyMap<string, string>
 }
 
 /** Result of the HYBRID mention pass — inline role phrases + surfaced opt-in
@@ -455,16 +443,39 @@ export function resolveVideoReferenceCore(
   // early-return below is gated on (no chars AND no extras) so we don't skip
   // extras-only setups.
   const hasExtras = (args.extraRefs?.length ?? 0) > 0
+  // `{ref:<id>}` degrade names — every id this call knows: the wired refs'
+  // display names, the extras' ids (name-less, so they match by identity rather
+  // than falling to the catch-all), then the caller's own map on top (it knows
+  // the refs it capped out before calling in).
+  const nameByRefId = new Map<string, string>()
+  for (const r of args.wiredCharRefs) {
+    if (r.id && !nameByRefId.has(r.id)) nameByRefId.set(r.id, r.defaultName || r.characterSlug || "")
+  }
+  for (const ex of args.extraRefs ?? []) {
+    if (ex.id && !nameByRefId.has(ex.id)) nameByRefId.set(ex.id, "")
+  }
+  for (const [id, name] of args.refNamesById ?? []) {
+    if (id) nameByRefId.set(id, name)
+  }
+  // id → seat, recorded by the walk below as `position` advances — never
+  // recovered from URLs afterwards (the walk counts a duplicate-URL extra that
+  // `merged` dedups, so URL → index is ambiguous; id → position is not).
+  const slotByRefId = new Map<string, number>()
   if (wiredCharRefs.length === 0 && !hasExtras) {
     // No wired chars / extras, but the node can still carry plain base reference
     // images (leadingRefUrls), so `{image:N}` body tokens MUST still resolve. The
     // count is the leading-ref count (or the legacy `imageRefCount` when no
     // leading refs were passed); the leading URLs are returned for the payload.
+    // Nothing was seated, so every `{ref:}` degrades (label → name → "").
+    const counts = tokenCounts(leadingRefUrls.length)
     return {
       // tokenCounts(leadingRefUrls.length) → image count == offset (no assets here):
       // leadingRefUrls mode counts the leading refs; ordinalOffset mode counts the
       // caller-owned leading refs the offset stands in for.
-      prompt: resolveReferenceTokens(args.prompt, tokenCounts(leadingRefUrls.length)),
+      prompt: resolveReferenceTokens(
+        resolveRefIdTokens(args.prompt, { slotById: slotByRefId, nameById: nameByRefId, imageCount: counts.image }),
+        counts,
+      ),
       additionalUrls: [...leadingRefUrls],
     }
   }
@@ -531,10 +542,17 @@ export function resolveVideoReferenceCore(
   let position = offset
   for (let i = 0; i < resolved.additionalUrls.length; i++) {
     position += 1
+    const url = resolved.additionalUrls[i]
     // Look up which ref this URL came from to learn its characterSlug.
-    const ref = wiredCharRefs.find((r) => r.url === resolved.additionalUrls[i])
+    const ref = wiredCharRefs.find((r) => r.url === url)
     const slug = ref?.characterSlug
     if (slug && !positionsByChar.has(slug)) positionsByChar.set(slug, position)
+    // `{ref:<id>}`: every wired ref sharing this URL sits in this seat (the
+    // merge dedups by URL). First sight wins — the legacy mention pass does
+    // not dedup, so a re-mentioned URL advances `position` but keeps its seat.
+    for (const r of wiredCharRefs) {
+      if (r.url === url && r.id && !slotByRefId.has(r.id)) slotByRefId.set(r.id, position)
+    }
   }
   for (const r of wiredCharRefs) {
     if (r.source !== "wired-character") continue
@@ -547,6 +565,7 @@ export function resolveVideoReferenceCore(
     fallbackUrls.push(r.url)
     position += 1
     if (!positionsByChar.has(r.characterSlug)) positionsByChar.set(r.characterSlug, position)
+    if (r.id && !slotByRefId.has(r.id)) slotByRefId.set(r.id, position)
     // Hybrid: emit the inline role phrase (`the person from @image_N`) + opt-in
     // lock + wired element injection instead of a "Use these characters:"
     // bullet. The selection above (canonical entry only, deduped, skip mentioned)
@@ -616,6 +635,7 @@ export function resolveVideoReferenceCore(
     for (const ex of args.extraRefs!) {
       if (!ex.url) continue
       position += 1
+      if (ex.id && !slotByRefId.has(ex.id)) slotByRefId.set(ex.id, position)
       const desc = (ex.description ?? "").trim()
       if (ex.characterSlug) {
         // First sight of this character via an extra. Resolution chain
@@ -797,6 +817,23 @@ export function resolveVideoReferenceCore(
     if (u && !seen.has(u)) { seen.add(u); merged.push(u) }
   }
 
+  // `{ref:<id>}` tokens resolve HERE — after the walk has seated every reference
+  // (the slot map is complete) and BEFORE the user reorder below, so the
+  // reorder's `@image_N` renumber pass carries the freshly emitted binding to
+  // the ref's final seat. That is the point of an id token: "this reference,
+  // wherever it lands". `{image:N}` is deliberately the opposite — resolved
+  // LAST, after the reorder, so the author's literal N is kept (see the note at
+  // the reorder return). Range-gated by the same image count `{image:N}` uses,
+  // so a seat the payload never ships (capped out, duplicate URL) degrades to
+  // the name instead of binding a phantom `@image_N`. A prompt with no `{ref:`
+  // is untouched — byte-identical to before this token existed.
+  finalPrompt =
+    resolveRefIdTokens(finalPrompt, {
+      slotById: slotByRefId,
+      nameById: nameByRefId,
+      imageCount: tokenCounts(merged.length).image,
+    }) ?? finalPrompt
+
   // Apply user-defined reorder + renumber `Image N` tokens — parity with the
   // backend `resolveVideoPromptMentions` and the shared image builder.
   const referenceOrder = args.referenceOrder
@@ -825,7 +862,9 @@ export function resolveVideoReferenceCore(
     // Resolve body tokens LAST — AFTER the reorder's `@image_N` renumber pass, so
     // it can't miscorrect a freshly-resolved binding (the curly `{image:N}` tokens
     // are invisible to the reorder's `(@image_|Image )` regex, so they ride through
-    // untouched and keep their author-typed N — documented v1 behavior).
+    // untouched and keep their author-typed N — documented v1 behavior). The
+    // id-addressed `{ref:<id>}` tokens are the deliberate opposite: resolved
+    // BEFORE the reorder (above), so their binding follows the reference.
     return {
       prompt: resolveReferenceTokens(reordered.prompt, tokenCounts(merged.length)),
       additionalUrls: [...leadingRefUrls, ...reordered.urls],