@nodaro/prompts 1.8.1 → 1.10.0

package/src/transitions.ts

@@ -42,9 +42,23 @@ export interface Transition {
   readonly term?: string
 }
 
-export type TransitionPosition = "auto" | "start" | "middle" | "end" | "full"
-export type TransitionDuration = "auto" | "instant" | "short" | "medium" | "long"
-export type TransitionIntensity = "auto" | "subtle" | "natural" | "dynamic" | "crazy"
+/**
+ * The three timing scales, each derived from the catalog that defines it (see
+ * `TRANSITION_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 `transition-timing-catalogs.test.ts`.
+ */
+export type TransitionPosition = (typeof TRANSITION_POSITIONS)[number]["id"]
+export type TransitionDuration = (typeof TRANSITION_DURATIONS)[number]["id"]
+export type TransitionIntensity = (typeof TRANSITION_INTENSITIES)[number]["id"]
 
 export interface TransitionTiming {
   position?: TransitionPosition
@@ -303,27 +317,73 @@ export const TRANSITION_IDS: ReadonlyArray<string> = TRANSITIONS.map((t) => t.id
 // Graph-aware composer — start/end input handles + timing fields + multi-pick
 // ---------------------------------------------------------------------------
 
-const POSITION_CLAUSES: Record<Exclude<TransitionPosition, "auto">, string> = {
-  start:  "the transition occurs at the opening of the clip",
-  middle: "the transition occurs in the middle of the clip",
-  end:    "the transition occurs at the end of the clip",
-  full:   "the transition spans the entire clip",
+/**
+ * The transition node's three timing parameters, as catalogs.
+ *
+ * These are graded scales, not free numbers — the same shape as
+ * `exposure-settings`' aperture or `temporal`'s speed — so a consumer that can
+ * only send ids (Studio, the SDK, MCP) can offer them 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.
+ *
+ * `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 TransitionTimingOption {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+  readonly term?: string
 }
 
-const DURATION_CLAUSES: Record<Exclude<TransitionDuration, "auto">, string> = {
-  instant: "occurring instantaneously",
-  short:   "lasting approximately 1 second",
-  medium:  "lasting approximately 2 seconds",
-  long:    "lasting approximately 3 seconds",
-}
+export const TRANSITION_POSITIONS = [
+  { id: "auto",   label: "Auto",   description: "Let the model place it",        promptHint: "", term: "" },
+  { id: "start",  label: "Start",  description: "At the opening of the clip",    promptHint: "the transition occurs at the opening of the clip", term: "at the opening of the clip" },
+  { id: "middle", label: "Middle", description: "In the middle of the clip",     promptHint: "the transition occurs in the middle of the clip", term: "mid-clip" },
+  { id: "end",    label: "End",    description: "At the end of the clip",        promptHint: "the transition occurs at the end of the clip", term: "at the end of the clip" },
+  { id: "full",   label: "Full",   description: "Spans the entire clip",         promptHint: "the transition spans the entire clip", term: "across the whole clip" },
+] as const satisfies ReadonlyArray<TransitionTimingOption>
+
+export const TRANSITION_DURATIONS = [
+  { id: "auto",    label: "Auto",    description: "Let the model time it",       promptHint: "", term: "" },
+  { id: "instant", label: "Instant", description: "No perceptible duration",     promptHint: "occurring instantaneously", term: "instantaneous" },
+  { id: "short",   label: "Short (~1s)",   description: "Approximately 1 second",  promptHint: "lasting approximately 1 second", term: "about 1 second" },
+  { id: "medium",  label: "Medium (~2s)",  description: "Approximately 2 seconds", promptHint: "lasting approximately 2 seconds", term: "about 2 seconds" },
+  { id: "long",    label: "Long (~3s)",    description: "Approximately 3 seconds", promptHint: "lasting approximately 3 seconds", term: "about 3 seconds" },
+] as const satisfies ReadonlyArray<TransitionTimingOption>
+
+export const TRANSITION_INTENSITIES = [
+  { id: "auto",    label: "Auto",    description: "Let the model judge it",      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<TransitionTimingOption>
 
-const INTENSITY_CLAUSES: Record<Exclude<TransitionIntensity, "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",
+/**
+ * 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.
+ */
+function clausesOf<T extends TransitionTimingOption>(
+  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(TRANSITION_POSITIONS)
+const DURATION_CLAUSES = clausesOf(TRANSITION_DURATIONS)
+const INTENSITY_CLAUSES = clausesOf(TRANSITION_INTENSITIES)
+
 /**
  * Compose a structural prompt-hint sentence from a transition id (or array
  * of 1-2 ids for multi-pick) plus optional start-state/end-state hints

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],