@nodaro/prompts 1.9.0 → 1.11.0

package/src/prompt-builder.ts

@@ -12,6 +12,7 @@ import { usageModeDirective, DEFAULT_USAGE_MODE, type UsageMode } from "@nodaro/
 import { roleToPhrase, defaultRoleForSource, REFERENCE_ROLE_PRESETS, normalizeRoleSlug, resolveDefaultRole } from "@nodaro/shared"
 import { buildIdentityLockLine, withForcedIdentityLock } from "./identity-lock.js"
 import { findLocationMentionTokens, DEFAULT_LOCATION_USAGE_MODE, type LocationMentionTokenInfo, type LocationUsageMode } from "@nodaro/shared"
+import { findImageMentionTokens, imageMentionSlugForRef, knownImageSlugsFromRefs, type ImageMentionTokenInfo } from "@nodaro/shared"
 import type { CharacterDef, ConnectedReference, IdentityFidelity, IdentityMeta, ReferenceSource, SceneData } from "@nodaro/shared"
 import { locationReferencePhotoKindLabel, type LocationReferencePhotoKind } from "@nodaro/shared"
 
@@ -694,6 +695,131 @@ function resolveLocationMentionsHybrid(
   return { prompt: resolvedPrompt, additionalUrls, mentionedLocationSlugs, lockLines, elementDirectives }
 }
 
+interface ResolveImageMentionsHybridResult {
+  /** Body with each `@<image-name>` mention replaced INLINE by its role phrase
+   *  ("the {role} from reference image {LETTER}", or the bare binding when the
+   *  role resolves to the media default `""`). No directive block. */
+  prompt: string
+  /** Matched image URLs in mention order (deduped by the caller). */
+  additionalUrls: string[]
+  /** NO `mentionedImageSlugs` — the location result's analog exists to FILTER
+   *  mentioned refs out of `connectedReferences`, and this pass deliberately
+   *  does no such filtering (see the caller's NOTE). Carrying the set anyway
+   *  would advertise a filter that does not exist. */
+  /** Per-reference identity-lock lines (deduped per URL). Caller prepends them
+   *  as ONE block, merged with the character/location lock lines. */
+  lockLines: string[]
+  /** Non-empty `elementInjection` fragments (deduped per URL). Caller appends
+   *  them as trailing scene directives. */
+  elementDirectives: string[]
+}
+
+/**
+ * HYBRID named-image mention convergence (P3). The media analog of
+ * `resolveLocationMentionsHybrid`, for `wired-image` / `manual` references
+ * addressed by the slug of their `defaultName` (an upload node's label on the
+ * canvas, or the name a thin client puts on the reference).
+ *
+ * ASYMMETRY vs. characters and locations: a media ref AUTO-ATTACHES its URL
+ * through the New path whether or not it is mentioned, and carries NO canonical
+ * prose. So a mention here is BINDING + RE-SEATING, never attach-gating — which
+ * is why the caller does NOT filter mentioned refs out of `connectedReferences`
+ * the way the location pass does.
+ *
+ * NO LEGACY COUNTERPART. The Phase-0 arm that reaches this is hybrid-gated, so
+ * an `@name:N` token under the legacy reference format stays literal text and
+ * the ref attaches exactly as it does today (the `resolveLocationMentions`
+ * role-token precedent, where `if (t.role) continue` leaves the token alone).
+ *
+ * DUPLICATE SLUGS: FIRST WINS (`if (!bySlug.has(...))`), matching
+ * `buildTileIdForUrl`. Every unrenamed upload node shares its default label, so
+ * ties are the common case, not an edge.
+ *
+ * ROLE precedence: the per-mention 3rd segment (VERBATIM — media role presets
+ * are all single-word, so `normalizeRoleSlug` is location-only and must NOT be
+ * called here) → the node default via `resolveDefaultRole` → `""`, which
+ * `roleToPhrase` renders as the BARE binding ("reference image C"), i.e. today's
+ * ref-only default with a name attached to it.
+ *
+ * CAPPED REFS: `imageReferenceLimit(provider)` truncates `connectedReferences`
+ * BEFORE Phase 0, so a mention whose ref was capped out silently falls through
+ * as literal text — matching how a capped character mention behaves today.
+ */
+function resolveImageMentionsHybrid(
+  prompt: string,
+  tokens: readonly ImageMentionTokenInfo[],
+  refs: readonly ConnectedReference[],
+  existingUrls: readonly string[],
+): ResolveImageMentionsHybridResult {
+  const bySlug = new Map<string, ConnectedReference>()
+  for (const r of refs) {
+    // `imageMentionSlugForRef` is the SAME predicate `knownImageSlugsFromRefs`
+    // applies to build the finder's known-slug set — one gate, so this map and
+    // that set can never admit different refs. (It also drops extras, which
+    // render through `renderExtraRefsHybrid` with their own body lines, and
+    // grammar-invalid slugs, where emptiness is NOT the gate.)
+    const slug = imageMentionSlugForRef(r)
+    if (!slug) continue
+    if (!bySlug.has(slug)) bySlug.set(slug, r)
+  }
+
+  const additionalUrls: string[] = []
+  const refByUrl = new Map<string, ConnectedReference>()
+  // Per-mention `~lock` / `~nolock`: the tri-state lock OVERRIDE per attached
+  // URL, fed to `withForcedIdentityLock` below. Only sentinel-bearing mentions
+  // write here (last sentinel wins), mirroring the location resolver.
+  const lockOverrideByUrl = new Map<string, boolean>()
+  const matched: Array<{ token: string; offset: number; url: string; role: string }> = []
+
+  for (const t of tokens) {
+    const match = bySlug.get(t.imageSlug)
+    if (!match || !match.url) continue
+    additionalUrls.push(match.url)
+    refByUrl.set(match.url, match)
+    if (t.lock !== undefined) lockOverrideByUrl.set(match.url, t.lock)
+    const role = (t.role ?? "").trim()
+      || resolveDefaultRole(match.defaultRole, match.defaultUsageMode, match.source)
+    matched.push({ token: t.token, offset: t.offset, url: match.url, role })
+  }
+
+  // Slot letters from the deduped [existing, mention] URL list — the prefix of
+  // the caller's `finalIndexByUrl`, so the letters agree.
+  const slotByUrl = new Map<string, number>()
+  for (const u of [...existingUrls, ...additionalUrls]) {
+    if (!slotByUrl.has(u)) slotByUrl.set(u, slotByUrl.size + 1)
+  }
+  const bindingFor = (url: string): string => {
+    const slot = slotByUrl.get(url)
+    return slot ? `reference image ${slotToLetter(slot)}` : "the reference image"
+  }
+
+  // Replace mention tokens right-to-left so earlier offsets stay valid.
+  let resolvedPrompt = prompt
+  for (const m of [...matched].sort((a, b) => b.offset - a.offset)) {
+    const phrase = roleToPhrase(m.role, bindingFor(m.url))
+    resolvedPrompt =
+      resolvedPrompt.slice(0, m.offset) + phrase + resolvedPrompt.slice(m.offset + m.token.length)
+  }
+
+  // One lock + one element directive per UNIQUE attached URL.
+  const lockLines: string[] = []
+  const elementDirectives: string[] = []
+  const seenUrls = new Set<string>()
+  for (const m of matched) {
+    if (seenUrls.has(m.url)) continue
+    seenUrls.add(m.url)
+    const ref = refByUrl.get(m.url)
+    if (!ref) continue
+    const binding = bindingFor(m.url)
+    const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding)
+    if (lock) lockLines.push(lock)
+    const inject = ref.elementInjection?.trim()
+    if (inject) elementDirectives.push(inject)
+  }
+
+  return { prompt: resolvedPrompt, additionalUrls, lockLines, elementDirectives }
+}
+
 /**
  * Build the canonical-fallback directive lines + URLs for wired characters
  * that were NOT @-mentioned in the prompt. Matches the pre-mention behavior:
@@ -1495,6 +1621,12 @@ export interface BuildImagePromptConfig {
    * (`flux-lora-character`) — the trigger word + LoRA carries identity, so
    * the directive bullets are redundant and the wired-character refs
    * shouldn't be injected as `Image N`.
+   *
+   * The strip regex is grammar-agnostic — it eats LOCATION and named-IMAGE
+   * mentions (`@town:3:background`) as well as character ones. That is
+   * INTENDED, not an oversight: this path drops `connectedReferences` outright,
+   * so there is no reference left for any mention to bind to and a surviving
+   * token would reach the model as literal noise. Do not narrow it.
    */
   skipCharacterMentions?: boolean
 }
@@ -1714,7 +1846,22 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
           .filter((s): s is string => typeof s === "string" && s.length > 0)
       )
     )
-    if (knownCharacterSlugs.length > 0 || hasExtraRefs || knownLocationSlugs.length > 0) {
+    // Named-image mentions (P3). Slugs derive from each media ref's
+    // `defaultName` — there is no `imageSlug` wire field; the derivation is
+    // shared with the backend orchestrator's structured-branch gate via
+    // `knownImageSlugsFromRefs`, so the two can never disagree about whether a
+    // prompt carries a resolvable image mention.
+    const knownImageSlugs = knownImageSlugsFromRefs(connectedReferences)
+    // EXISTENCE-ONLY precheck, gating the Phase-0 arm below. Unlike characters
+    // (whose canonical fallback must run even with ZERO mentions), images have
+    // NO canonical fallback, so an image-only graph with no mention has no
+    // reason to enter Phase 0 — gating on TOKEN presence keeps today's control
+    // flow and byte output for every unmentioned graph BY CONSTRUCTION.
+    // HYBRID-only: under the legacy format an `@name:N` token stays literal text.
+    const hasImageMentionTokens = isHybrid
+      && knownImageSlugs.length > 0
+      && findImageMentionTokens(config.prompt, knownImageSlugs).length > 0
+    if (knownCharacterSlugs.length > 0 || hasExtraRefs || knownLocationSlugs.length > 0 || hasImageMentionTokens) {
       const mentionTokens = knownCharacterSlugs.length > 0
         ? findCharacterMentionTokens(config.prompt, knownCharacterSlugs)
         : []
@@ -1806,6 +1953,44 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
         if (r.locationVariantBucket) return false
         return !mentionedLocationSlugs.has(r.locationSlug)
       })
+      // Pass 3 (P3): named-image mentions, resolved on the POST-character,
+      // POST-location prompt. The finder MUST re-run here — the earlier passes
+      // spliced their own tokens out, so any offset computed before them is
+      // stale. PRECEDENCE character → location → image falls out of this pass
+      // order: a name shared by a character and an image resolves as the
+      // character, and the image token never fires.
+      //
+      // `existingUrls` is already location-inclusive because `additionalUrls`
+      // absorbed the location URLs just above, so the mention slot letters stay
+      // a prefix of the final `finalIndexByUrl`.
+      let hybridImageLockLines: string[] = []
+      let hybridImageElementDirectives: string[] = []
+      if (hasImageMentionTokens) {
+        const imageTokens = findImageMentionTokens(resolved.prompt, knownImageSlugs)
+        if (imageTokens.length > 0) {
+          const hi = resolveImageMentionsHybrid(
+            resolved.prompt,
+            imageTokens,
+            connectedReferences,
+            [...(referenceImageUrls || []), ...resolved.additionalUrls],
+          )
+          resolved.prompt = hi.prompt
+          resolved.additionalUrls = [...resolved.additionalUrls, ...hi.additionalUrls]
+          hybridImageLockLines = hi.lockLines
+          hybridImageElementDirectives = hi.elementDirectives
+          // Inline role phrases now live in the body → skip line-initial
+          // capitalization, which would otherwise corrupt a mid-sentence
+          // "the background from reference image C".
+          if (hi.additionalUrls.length > 0) hybridBodyConverged = true
+        }
+      }
+      // NOTE — deliberately NO `connectedReferences` filter for mentioned image
+      // refs (the location pass filters, just above). The New-path URL merge
+      // dedups by URL so the ref keeps its earlier Phase-0 slot; wired-image /
+      // manual refs have no canonical-fallback prose to double-emit (that loop
+      // is gated to wired-location/object/creature); and leaving the ref in
+      // place keeps `nonCharacterRefs[N-1]` positional indexing stable for
+      // `{image:N}` tokens.
       // Default-fallback canonical URLs + directives for any wired character
       // that has zero mentions in the prompt. Mirrors the legacy behavior the
       // mention feature replaced — wire a character with no typing required.
@@ -1944,12 +2129,14 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
         const allLockLines = [...new Set([
           ...hybridLockLines,
           ...hybridLocationLockLines,
+          ...hybridImageLockLines,
           ...canonical.lockLines,
           ...extrasRendered.lockLines,
         ])]
         const trailingLines = [
           ...hybridElementDirectives,
           ...hybridLocationElementDirectives,
+          ...hybridImageElementDirectives,
           ...canonical.phrases,
           ...canonical.elementDirectives,
           ...extrasRendered.bodyLines,

package/src/prompt-hint-join.ts

@@ -0,0 +1,30 @@
+/**
+ * The measured hint join, shared by the image (`composePromptText`) and video
+ * (`composeVideoPromptText`) composers so the two can never drift.
+ *
+ * EXACT NO-OP: zero hints → the user's prompt back VERBATIM AND UNTRIMMED (the
+ * platform-caller byte-parity contract — the old platform path passed the
+ * prompt straight to `buildImagePrompt`, which never trims, so trimming here
+ * would change the assembled prompt and the recorded `jobs.input_data`
+ * byte-for-byte). With hints → trim the body so the join reads cleanly
+ * ("prompt. hint", not "prompt . hint"), and drop a blank body so the result
+ * never starts with ". ".
+ *
+ * Never mutates its inputs.
+ */
+
+/** The measured separator between the user's prompt and each folded hint. */
+export const PROMPT_HINT_SEPARATOR = ". "
+
+/**
+ * Join a user prompt with its folded hint clauses.
+ *
+ * The trailing `.filter((p) => p.length > 0)` on the join array is
+ * parity-critical — do NOT remove it as "redundant": `hints` arrives
+ * pre-filtered but `userPrompt` does not, so a blank user prompt would
+ * otherwise make the result start with ". ".
+ */
+export function joinPromptHints(userPrompt: string, hints: readonly string[]): string {
+  if (hints.length === 0) return userPrompt
+  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(PROMPT_HINT_SEPARATOR)
+}

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/read-node-direction.ts

@@ -0,0 +1,174 @@
+/**
+ * Narrow readers turning UNTRUSTED persisted node data (`workflows.nodes`
+ * JSONB — import, MCP write, node preset, a Studio-emitted graph) into the
+ * typed `direction` / `structured` levers `assembleImageInput` accepts.
+ * `buildPayload` has no zod and workflow writes are
+ * `z.record(z.string(), z.unknown())`, so this blob may have been written years
+ * ago by any client.
+ *
+ * Used by ALL THREE image-assembly sites so what the canvas accepts cannot
+ * drift between them: the frontend single-node executor (`execute-node.ts`),
+ * the orchestrator (`payload-builder.ts`), and the config-panel final-prompt
+ * preview (`build-image-assemble-input.ts`).
+ *
+ * `readDirectionFields` is DERIVED FROM `DIRECTION_FIELDS`, never a hand list:
+ * a dimension added to the registry is honored here by construction, so the
+ * reader can never silently drop a key the wire schema and the renderer both
+ * know about. Anything unrecognised is DROPPED, never thrown on — a malformed
+ * blob must not fail a canvas run, and an unknown catalog ID already degrades
+ * to `""` inside each `get*PromptHint`, so this validates SHAPE only.
+ *
+ * BOUNDS MATCH THE WIRE SCHEMA where both exist, by SHARED CONSTANT:
+ * `DIRECTION_ID_MAX_CHARS` and `DIRECTION_ARRAY_CEILING` are the same two
+ * literals the `generate-image` route's `directionSchema` enforces, imported
+ * from the registry rather than re-typed here — a body the route accepts and a
+ * node the canvas re-runs must not disagree about which strings are ids.
+ *
+ * DELIBERATELY STRICTER THAN THE WIRE SCHEMA on `structured` values: the
+ * route's `structuredPromptFieldsSchema` declares every field as a bare
+ * `z.string().optional()` (unbounded), while `MAX_STRUCTURED_VALUE_CHARS` below
+ * bounds them at 200. Do not "fix" that asymmetry by loosening HERE — this
+ * reads a blob any client may have written years ago, and the values land
+ * verbatim in `jobs.input_data.prompt`. Tightening the ROUTE instead would be a
+ * new 400 on currently-accepted input, so a >200-char structured value stored
+ * on a node is dropped on a canvas run while `POST /v1/generate-image` still
+ * renders it. That is the one known divergence; it is bounded to a field the
+ * canvas UI never writes that long.
+ *
+ * RETURNS `undefined`, NEVER `{}`: an empty object would still be a *defined*
+ * `direction`, and the call sites' `...(x !== undefined ? { x } : {})` spread
+ * would then hand `assembleImageInput` a defined-but-empty lever. Returning
+ * `undefined` keeps that spread honest and the exact no-op branch taken.
+ */
+import {
+  DIRECTION_ARRAY_CEILING,
+  DIRECTION_FIELDS,
+  DIRECTION_ID_MAX_CHARS,
+  type DirectionFields,
+} from "./direction-registry.js"
+import type { StructuredPromptFields } from "./prompt-builder-structured-fields.js"
+
+/**
+ * Read a node's stored cinematic-direction ids. Accepts a single id OR an array
+ * on every key (multi-pick dimensions carry arrays; a single-pick key may
+ * legitimately carry one).
+ *
+ * The SEMANTIC per-dimension cap stays the renderer's slice (`maxPicks`) — this
+ * reader does not know a row's pick budget and must not guess it. But it DOES
+ * bound cardinality at `DIRECTION_ARRAY_CEILING`, the same ceiling the wire
+ * schema enforces: the value is untrusted persisted JSONB (a node blob is
+ * validated only as `z.record(z.string(), z.unknown())` on write), and handing
+ * an unbounded array to `renderDirectionHints` would put an `includes`-dedupe
+ * scan in front of that slice. Keeping the FIRST `DIRECTION_ARRAY_CEILING`
+ * survivors is what the wire door already does to the same input.
+ *
+ * Junk is filtered BEFORE the cap, so valid ids sitting behind malformed
+ * entries survive rather than being crowded out by them.
+ */
+export function readDirectionFields(value: unknown): DirectionFields | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined
+  const src = value as Record<string, unknown>
+  const out: Record<string, string | string[]> = {}
+  for (const spec of DIRECTION_FIELDS) {
+    const v = src[spec.key]
+    if (typeof v === "string") {
+      if (v.length > 0 && v.length <= DIRECTION_ID_MAX_CHARS) out[spec.key] = v
+    } else if (Array.isArray(v)) {
+      const kept: string[] = []
+      for (const x of v) {
+        if (kept.length >= DIRECTION_ARRAY_CEILING) break
+        if (typeof x === "string" && x.length > 0 && x.length <= DIRECTION_ID_MAX_CHARS) {
+          kept.push(x)
+        }
+      }
+      if (kept.length > 0) out[spec.key] = kept
+    }
+  }
+  return Object.keys(out).length > 0 ? (out as DirectionFields) : undefined
+}
+
+// ── structured ───────────────────────────────────────────────────────────────
+
+type FieldKind = "string" | "number" | "gender"
+const GENDERS = ["man", "woman", "child", "non-binary"] as const
+const MAX_STRUCTURED_VALUE_CHARS = 200
+
+type Group = Exclude<keyof StructuredPromptFields, "mood">
+type GroupFields<K extends Group> = Record<keyof NonNullable<StructuredPromptFields[K]>, FieldKind>
+
+/**
+ * A FIELD-BY-FIELD table (not a registry walk) on purpose:
+ * `StructuredPromptFields` is a small HAND-AUTHORED type, not catalog-derived,
+ * and the table is what blocks `person: { age: "drop table" }` from rendering
+ * verbatim into `jobs.input_data.prompt` — `renderStructuredFields` never
+ * throws on junk, but it does render it. Totality is enforced by the
+ * `GroupFields<K>` / `{ [K in Group]: … }` mapped types: a new field or group
+ * on the published type fails to typecheck here.
+ */
+const PERSON_FIELDS: GroupFields<"person"> = {
+  age: "number",
+  gender: "gender",
+  hair: "string",
+  eyes: "string",
+  expression: "string",
+  profession: "string",
+  warriorType: "string",
+}
+const STYLING_FIELDS: GroupFields<"styling"> = {
+  mood: "string",
+  lighting: "string",
+  aesthetic: "string",
+  colorLook: "string",
+}
+const SETTING_FIELDS: GroupFields<"setting"> = {
+  era: "string",
+  atmosphere: "string",
+  backdrop: "string",
+}
+const CAMERA_FIELDS: GroupFields<"camera"> = {
+  framing: "string",
+  motion: "string",
+  format: "string",
+}
+const LENS_FIELDS: GroupFields<"lens"> = { focalLength: "string", aperture: "string" }
+
+const STRUCTURED_GROUPS: { [K in Group]: GroupFields<K> } = {
+  person: PERSON_FIELDS,
+  styling: STYLING_FIELDS,
+  setting: SETTING_FIELDS,
+  camera: CAMERA_FIELDS,
+  lens: LENS_FIELDS,
+}
+
+function readField(v: unknown, kind: FieldKind): string | number | undefined {
+  if (kind === "number") return typeof v === "number" && Number.isFinite(v) ? v : undefined
+  if (typeof v !== "string" || v.length === 0 || v.length > MAX_STRUCTURED_VALUE_CHARS) {
+    return undefined
+  }
+  if (kind === "gender") return (GENDERS as readonly string[]).includes(v) ? v : undefined
+  return v
+}
+
+/** Read a node's stored Path-1 structured prompt fields. Same drop-never-throw
+ *  and `undefined`-never-`{}` contract as `readDirectionFields`. */
+export function readStructuredFields(value: unknown): StructuredPromptFields | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined
+  const src = value as Record<string, unknown>
+  const out: Record<string, unknown> = {}
+  for (const group of Object.keys(STRUCTURED_GROUPS) as Group[]) {
+    const raw = src[group]
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue
+    const rawRec = raw as Record<string, unknown>
+    const kept: Record<string, unknown> = {}
+    for (const [field, kind] of Object.entries(
+      STRUCTURED_GROUPS[group] as Record<string, FieldKind>,
+    )) {
+      const v = readField(rawRec[field], kind)
+      if (v !== undefined) kept[field] = v
+    }
+    if (Object.keys(kept).length > 0) out[group] = kept
+  }
+  const mood = readField(src.mood, "string")
+  if (mood !== undefined) out.mood = mood
+  return Object.keys(out).length > 0 ? (out as StructuredPromptFields) : undefined
+}

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, "")
+}