@nodaro/prompts 1.9.0 → 1.11.0

package/src/__tests__/video-reference-ref-id-tokens.test.ts

@@ -0,0 +1,301 @@
+/**
+ * `{ref:<id>}` / `{ref:<id>:<label>}` — id-addressed reference tokens.
+ *
+ * A client that names a reference by the `connectedReferences[].id` it sent
+ * (Studio's bound `@`-chips) gets the `@image_N` slot substituted by the
+ * platform AFTER the platform has numbered the references. That removes the
+ * client-side mirror of the numbering walk — the one duplicated rule that could
+ * silently misbind pictures for a client built against an older package.
+ *
+ * Contract pinned here:
+ *   - the slot comes from the SAME walk that numbers the directives (mention
+ *     URLs → canonical fallback → extras, offset by the leading flat refs);
+ *   - the token is resolved BEFORE the `referenceOrder` reorder, so the
+ *     renumber pass carries the binding to the ref's final seat — the opposite
+ *     of `{image:N}`, which is resolved AFTER it to keep the author's N;
+ *   - an unresolvable token never ships raw: label → the ref's display name
+ *     (when the id is known) → "";
+ *   - a prompt with no `{ref:` token is byte-identical to before.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  resolveVideoReferenceCore,
+  resolveRefIdTokens,
+  resolveReferenceTokens,
+} from "../video-reference-resolver.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const charRef = (over: Partial<ConnectedReference> = {}): ConnectedReference => ({
+  id: "char-kira", defaultName: "Kira", source: "wired-character", url: "https://r2/kira.png",
+  characterSlug: "kira", variantSlug: undefined, characterCanonicalDescription: null,
+  variantDescription: null, variantDisplayName: "canonical", ...over,
+})
+
+const A = "https://cdn/a.png"
+const B = "https://cdn/b.png"
+
+/** Every case: the token must be gone, whatever it resolved to. */
+function expectNoRawToken(prompt: string | undefined) {
+  expect(prompt ?? "").not.toMatch(/\{ref:/i)
+}
+
+describe("resolveVideoReferenceCore — {ref:<id>} id-addressed tokens", () => {
+  it("bare {ref:<id>} binds an image extra to its @image_N slot", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "drive {ref:car-1} fast",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/car.png"])
+    expect(out.prompt).toContain("- @image_1 (reference): a red car.")
+    expect(out.prompt).toContain("drive @image_1 fast")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("labeled {ref:<id>:<label>} binds through REF_BINDING.image (parity with {image:N:label})", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "drive {ref:car-1:car} fast",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.prompt).toContain("drive the car from @image_1 fast")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a canonical wired character binds to its canonical-fallback slot", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:char-kira} walks in",
+      wiredCharRefs: [charRef()],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png"])
+    expect(out.prompt).toContain("Use these characters:")
+    expect(out.prompt).toContain("@image_1 walks in")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a character VIEW (extra with characterSlug) binds to its pair-back slot after the canonical", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:view-1} turns to face {ref:char-kira}",
+      wiredCharRefs: [charRef()],
+      extraRefs: [{ id: "view-1", url: "https://r2/kira-side.png", characterSlug: "kira", description: "side profile" }],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png", "https://r2/kira-side.png"])
+    expect(out.prompt).toContain("- @image_2 is the same subject as @image_1, side profile.")
+    expect(out.prompt).toContain("@image_2 turns to face @image_1")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("leading flat refs offset the slot (D5 image-refs-first)", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "the {ref:obj} on the table",
+      wiredCharRefs: [],
+      leadingRefUrls: [A],
+      extraRefs: [{ id: "obj", url: B, description: "object" }],
+    })
+    expect(out.additionalUrls).toEqual([A, B])
+    expect(out.prompt).toContain("the @image_2 on the table")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("ids are opaque: `:` and `/` inside an id resolve, and a trailing label still parses", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:https://cdn/pic.png} beside {ref:kira:smile:smile}",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "https://cdn/pic.png", url: "https://cdn/pic.png", description: "pic" },
+        { id: "kira:smile", url: "https://r2/kira-smile.png", description: "smile" },
+      ],
+    })
+    expect(out.prompt).toContain("@image_1 beside the smile from @image_2")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("an unknown id degrades to its label, or to nothing — never the raw token", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "a {ref:nope:ghost} b {ref:nope2} c",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "x", url: A, description: "d" }],
+    })
+    expect(out.prompt).toContain("a ghost b c")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a known ref the walk never seated degrades to its display name", () => {
+    // A wired character with no url is skipped by the canonical loop — the id
+    // is known (so the name is), but there is no slot to bind.
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:char-kira} waves at {ref:capped-1}",
+      wiredCharRefs: [charRef({ url: "" })],
+      extraRefs: [{ id: "x", url: A, description: "d" }],
+      // The caller's full id → name map (the route builds it from EVERY
+      // connectedReference, including the ones it capped out before the walk).
+      refNamesById: new Map([["capped-1", "Truck"]]),
+    })
+    expect(out.prompt).toContain("Kira waves at Truck")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a duplicate-URL extra never binds past the payload: its {ref:} degrades to its name", () => {
+    // The walk counts every extra with a url while `merged` dedups by URL, so
+    // the second extra's directive is numbered @image_2 although the payload
+    // carries ONE image (pre-existing walk-vs-merged drift). The token is
+    // range-gated against the image count, so it degrades instead of emitting
+    // a phantom binding.
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:x} then {ref:y}",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "x", url: A, description: "first" },
+        { id: "y", url: A, description: "second" },
+      ],
+      refNamesById: new Map([["y", "Second"]]),
+    })
+    expect(out.additionalUrls).toEqual([A])
+    expect(out.prompt).toContain("@image_1 then Second")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("resolves BEFORE the referenceOrder reorder, so the binding follows the ref to its final seat", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:y} leads, {ref:x} follows",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "x", url: A, description: "ax" },
+        { id: "y", url: B, description: "by" },
+      ],
+      // Extras' tile ids are `wired:<url>` (the reorder contract, unchanged).
+      referenceOrder: [`wired:${B}`, `wired:${A}`],
+    })
+    expect(out.additionalUrls).toEqual([B, A])
+    expect(out.prompt).toContain("@image_1 leads, @image_2 follows")
+    expect(out.prompt).toContain("- @image_1 (reference): by.")
+    expect(out.prompt).toContain("- @image_2 (reference): ax.")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("keeps {image:N} resolved AFTER the reorder (author's N kept) while {ref:} follows the ref", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:y} and {image:2:second}",
+      wiredCharRefs: [],
+      extraRefs: [
+        { id: "x", url: A, description: "ax" },
+        { id: "y", url: B, description: "by" },
+      ],
+      referenceOrder: [`wired:${B}`, `wired:${A}`],
+    })
+    // y moved to seat 1 → {ref:y} rides along; {image:2} keeps the literal 2.
+    expect(out.prompt).toContain("@image_1 and the second from @image_2")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("an @-mentioned character's ref binds to the mention's slot", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "@kira:1 waves, then {ref:char-kira} sits",
+      wiredCharRefs: [charRef()],
+    })
+    expect(out.additionalUrls).toEqual(["https://r2/kira.png"])
+    expect(out.prompt).toContain("Kira waves, then @image_1 sits")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("is independent of hybridRoles — same slot, no legend block", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "drive {ref:car-1} fast",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+      hybridRoles: true,
+    })
+    expect(out.prompt).not.toContain("Use these characters:")
+    expect(out.prompt).toContain("drive @image_1 fast")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("a prompt with no {ref: token is untouched — `{ref}` and `ref:` are not tokens", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "circle {image:1:object} {ref} ref: x",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.prompt).toContain("circle the object from @image_1 {ref} ref: x")
+  })
+
+  it("an empty id drops to nothing and the keyword is case-insensitive", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "x {ref:} {REF:car-1} y",
+      wiredCharRefs: [],
+      extraRefs: [{ id: "car-1", url: "https://r2/car.png", description: "a red car" }],
+    })
+    expect(out.prompt).toContain("x @image_1 y")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("imageRefCount: 0 (no image tokens may bind) degrades a seated ref to its name", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:char-kira} walks",
+      wiredCharRefs: [charRef()],
+      imageRefCount: 0,
+    })
+    expect(out.prompt).toContain("Kira walks")
+    expect(out.prompt).not.toContain("@image_1 walks")
+    expectNoRawToken(out.prompt)
+  })
+
+  it("early-return path (no wired chars, no extras): degrades to name / label / nothing", () => {
+    const out = resolveVideoReferenceCore({
+      prompt: "{ref:a} and {ref:b:the dog} and {ref:c}",
+      wiredCharRefs: [],
+      leadingRefUrls: [A],
+      refNamesById: new Map([["a", "Alpha"]]),
+    })
+    expect(out.additionalUrls).toEqual([A])
+    expect(out.prompt).toBe("Alpha and the dog and")
+    expectNoRawToken(out.prompt)
+  })
+})
+
+describe("resolveRefIdTokens — malformed and adversarial input", () => {
+  it("a malformed token (brace inside the id, no closing brace) never ships its `{ref:` prefix", () => {
+    const out = resolveRefIdTokens("x {ref:a{b} y {ref:unclosed z", {
+      slotById: new Map([["a", 1]]),
+      nameById: new Map(),
+      imageCount: 1,
+    })
+    expect(out).not.toMatch(/\{ref:/i)
+    // The net is bounded by whitespace/braces: the prose after each run survives.
+    expect(out).toContain(" y ")
+    expect(out).toContain(" z")
+  })
+
+  it("scans a prompt at the hard ceiling with an adversarial shape and still resolves (linear matcher)", () => {
+    // 30k chars of `{ref:` followed by label-class text with no closing brace —
+    // the shape that made a lazy-quantifier matcher quadratic.
+    const adversarial = "{ref:" + ":a".repeat(15000)
+    const out = resolveRefIdTokens(`${adversarial} end {ref:x}`, {
+      slotById: new Map([["x", 1]]),
+      nameById: new Map(),
+      imageCount: 1,
+    })
+    expect(out).not.toMatch(/\{ref:/i)
+    expect(out).toContain("end @image_1")
+  })
+})
+
+describe("resolveRefIdTokens (standalone — the route's no-image-ref early return)", () => {
+  it("binds in-range slots, and degrades label → name → nothing otherwise", () => {
+    const resolved = resolveRefIdTokens("{ref:x:car} {ref:x} {ref:y:dog} {ref:y} {ref:z}", {
+      slotById: new Map([["x", 2], ["y", 4]]),
+      nameById: new Map([["y", "Dog"]]),
+      imageCount: 3,
+    })
+    // y is seated at 4 but only 3 images ship → name; z is unknown → nothing.
+    expect(resolveReferenceTokens(resolved, { image: 3, video: 0, audio: 0 })).toBe(
+      "the car from @image_2 @image_2 dog Dog",
+    )
+  })
+
+  it("returns the prompt untouched when no {ref: token is present", () => {
+    const prompt = "plain {image:1} prose"
+    expect(resolveRefIdTokens(prompt, { slotById: new Map(), nameById: new Map(), imageCount: 0 })).toBe(prompt)
+    expect(resolveRefIdTokens(undefined, { slotById: new Map(), nameById: new Map(), imageCount: 0 })).toBeUndefined()
+  })
+})

package/src/assemble-image-input.ts

@@ -16,13 +16,17 @@
  * This wrapper collapses them into one.
  *
  * THE NO-OP CONTRACT (load-bearing — the platform-caller parity relies on it):
- * the two platform callers (`execute-node` / `payload-builder`) compose their
- * prompt from the canvas graph themselves and pass NO cinematic `direction`
- * ids and NO `structured` fields. In that case `composePromptText` MUST return
- * the caller's `userPrompt` byte-for-byte unchanged, so the wrapper degenerates
- * to exactly the `buildImagePrompt(...)` call those sites make today. Studio
- * (and the MCP route) supply `direction` / `structured` and get the id-hint
- * composition on top.
+ * a node that carries NO stored `direction` / `structured` (every workflow
+ * authored before the canvas honored them) still reaches here with both absent,
+ * and `composePromptText` MUST return the caller's `userPrompt` byte-for-byte
+ * unchanged, so the wrapper degenerates to exactly the `buildImagePrompt(...)`
+ * call those sites made before. The platform callers (`execute-node` /
+ * `payload-builder`) compose their prompt from the canvas GRAPH themselves and
+ * ALSO forward a node's STORED `direction` / `structured` when it carries them
+ * (`readDirectionFields` / `readStructuredFields`); those nodes get the id-hint
+ * composition on top, ADDITIVE to the graph-wired cinematography hints the
+ * caller already folded into `userPrompt`. Studio and the MCP route supply the
+ * same two levers directly.
  *
  * THE EMPTY-CHECK FLAG (also load-bearing for parity): `execute-node` rejects a
  * truly-empty assembled prompt (its "type one, mention a character, or connect
@@ -35,31 +39,28 @@ import {
   buildImagePrompt,
   type BuildImagePromptResult,
 } from "./prompt-builder.js"
-import { getFramingPromptHint } from "./framing.js"
-import { getLightingPromptHint } from "./lighting.js"
-import { getLensPromptHint } from "./lens.js"
-import { getCameraFormatPromptHint } from "./camera-format.js"
 import {
   renderStructuredFields,
   type StructuredPromptFields,
 } from "./prompt-builder-structured-fields.js"
+import {
+  renderDirectionHints,
+  IMAGE_HINT_MODE_DEFAULT,
+  type DirectionFields,
+} from "./direction-registry.js"
+import { joinPromptHints } from "./prompt-hint-join.js"
 import type { CharacterDef, ConnectedReference, IdentityMeta } from "@nodaro/shared"
 
 /**
- * Flat cinematic-direction ids the Studio framing UI (and the MCP route)
- * expose — all optional. Promoted here from Studio's `assembly.ts` so the
- * id → hint composition lives in one place. The platform callers pass none of
- * these (they fold their hints from the graph into `userPrompt` themselves).
+ * Flat cinematic-direction ids the Studio framing UI, the MCP route and the
+ * canvas node data expose — all optional. The dimensions, their canonical fold
+ * ORDER and their per-catalog rendering live in `direction-registry.ts`; this
+ * re-export keeps the import path stable for existing consumers. The platform
+ * callers fold their GRAPH-WIRED hints into `userPrompt` themselves and pass
+ * these only when the node carries them as stored data (Studio-emitted graphs,
+ * spec D3).
  */
-export interface DirectionFields {
-  /** Shot Type — the FRAMINGS shot-size/coverage/composition/vantage dimensions. */
-  framingId?: string
-  /** Angle — the FRAMINGS angle dimension (separate pill, so it can coexist with Shot Type). */
-  framingAngleId?: string
-  lightingId?: string
-  lensId?: string
-  cameraFormatId?: string
-}
+export type { DirectionFields }
 
 /**
  * Input to `assembleImageInput`. A faithful SUPERSET of what the two platform
@@ -80,8 +81,9 @@ export interface AssembleImageInput {
   connectedReferences?: ConnectedReference[]
   /**
    * Flat cinematic-direction ids → folded into the prompt as hints. Studio /
-   * MCP-route use; the platform callers pass none (so `composePromptText` is a
-   * no-op for them and the result is byte-identical to today).
+   * MCP-route use, and the platform callers' narrow-read of a node's STORED
+   * `data.direction`; absent on a node that carries none (so `composePromptText`
+   * is a no-op for it and the result is byte-identical to today).
    */
   direction?: DirectionFields
   /** Path-1 structured fields → composed fragment appended to the prompt. */
@@ -142,17 +144,23 @@ export interface AssembleImageInput {
 
 /**
  * Compose the cinematic-direction hints + structured-field fragment with the
- * user's prompt. Each `get*PromptHint` returns "" on a miss, and
- * `renderStructuredFields` returns "" when nothing is populated.
+ * user's prompt. `renderDirectionHints` folds the `direction` ids in the
+ * registry's canonical table order (unknown keys and unknown ids contribute
+ * nothing), and `renderStructuredFields` returns "" when nothing is populated —
+ * so the structured fragment always lands LAST.
  *
  * EXACT NO-OP CONTRACT: when there are no cinematic/structured hint pieces (the
- * platform-caller case — execute-node / payload-builder never pass `direction`/
- * `structured`), the user's prompt is returned **verbatim, untrimmed**. This is
- * load-bearing for parity: 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. We only
- * trim the user prompt when joining it WITH hints, so it reads cleanly
- * ("prompt. hint", not "prompt . hint"). Never mutates inputs.
+ * platform-caller case for a node that carries no stored `direction`/
+ * `structured` — every workflow authored before the canvas honored them), the
+ * user's prompt is returned **verbatim, untrimmed** by `joinPromptHints`. This
+ * is load-bearing for parity: 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. Never
+ * mutates inputs.
+ *
+ * A node that DOES carry `direction`/`structured` takes the join branch and is
+ * therefore trimmed + `". "`-joined — intended, and asserted at the caller
+ * level by the payload-builder before/after test.
  */
 function composePromptText(
   userPrompt: string,
@@ -160,19 +168,10 @@ function composePromptText(
   structured: StructuredPromptFields | undefined,
 ): string {
   const hints = [
-    getFramingPromptHint(direction?.framingId),
-    getFramingPromptHint(direction?.framingAngleId),
-    getLightingPromptHint(direction?.lightingId),
-    getLensPromptHint(direction?.lensId),
-    getCameraFormatPromptHint(direction?.cameraFormatId),
+    ...renderDirectionHints(direction, { surface: "image", mode: IMAGE_HINT_MODE_DEFAULT }),
     structured ? renderStructuredFields(structured) : "",
   ].filter((p) => p.length > 0)
-  // No hints → verbatim (exact no-op = platform parity). With hints → trim the
-  // user prompt so the ". " join is clean. The trailing filter drops a blank
-  // user prompt so the join never starts with ". " (parity-critical — don't
-  // remove it as "redundant": `hints` is pre-filtered but `userPrompt` is not).
-  if (hints.length === 0) return userPrompt
-  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(". ")
+  return joinPromptHints(userPrompt, hints)
 }
 
 /**

package/src/assemble-video-input.ts

@@ -0,0 +1,89 @@
+/**
+ * `composeVideoPromptText` — the video twin of `assemble-image-input.ts`'s
+ * `composePromptText`: fold cinematic-direction picker IDS into the prompt BODY,
+ * server-side, at the model call.
+ *
+ * WHY THIS EXISTS: `/v1/generate-video` had no structured direction channel, so
+ * every client baked the hint TEXT itself. A copied scene then carried stale
+ * catalog wording forever, a re-generate double-baked it, and each client
+ * re-implemented the fold with its own separator and its own order. The wire
+ * now carries ids; the platform renders the clauses.
+ *
+ * WHERE IT RUNS (load-bearing): on the prompt BODY, BEFORE
+ * `resolveVideoReferenceCore`. That resolver FRAMES the body — legacy prepends
+ * its `Use these characters:` block, hybrid prepends the lock lines and APPENDS
+ * the canonical role phrases and extras. Folding afterwards would push the
+ * scene/look description PAST the identity directives, a worse version of the
+ * bug this channel exists to fix. The image side is structurally identical
+ * (`assembleImageInput` = `composePromptText` → `buildImagePrompt`).
+ *
+ * THE VERBOSITY POLICY LIVES HERE, NOT IN THE CLIENT: motion dimensions render
+ * their compact professional term, look dimensions their full clause
+ * (`VIDEO_HINT_MODE_DEFAULT`, resolved per row's `family` by the registry).
+ * It is a threaded PARAMETER with a pure default — never deployment state:
+ * `__tests__/content-free-contract.test.ts` hard-fails any environment read
+ * under `packages/prompts/src`, and this module has nothing to read anyway.
+ *
+ * EXACT NO-OP CONTRACT: with no direction and no structured fields the caller's
+ * `userPrompt` comes back VERBATIM AND UNTRIMMED — `undefined` included, since
+ * a video prompt is optional on the route. That is what keeps every existing
+ * caller byte-identical (the "backward-compatible: no connectedReferences →
+ * prompt + flat refs pass through unchanged" oracle in
+ * `backend/src/routes/__tests__/generate-video.test.ts`, restated locally in
+ * `__tests__/assemble-video-input.test.ts`).
+ *
+ * WHAT IS DELIBERATELY NOT HERE: the dimension table, the fold order, the
+ * dedupe and the surface filter all live in `direction-registry.ts` — ONE
+ * renderer serves both surfaces, so the image and video folds cannot drift.
+ * Clients render their "will inject into prompt" preview by importing
+ * `renderDirectionHints` + `joinPromptHints` directly.
+ */
+import {
+  renderDirectionHints,
+  VIDEO_HINT_MODE_DEFAULT,
+  type DirectionFields,
+  type DirectionHintMode,
+} from "./direction-registry.js"
+import { joinPromptHints } from "./prompt-hint-join.js"
+import {
+  renderStructuredFields,
+  type StructuredPromptFields,
+} from "./prompt-builder-structured-fields.js"
+
+/**
+ * Fold a video run's cinematic-direction ids (and optional structured fields)
+ * into its prompt body.
+ *
+ * The direction hints land first, in the registry's canonical table order
+ * (camera motion leads), and the structured fragment lands LAST — the same
+ * ordering `composePromptText` uses for stills.
+ *
+ * @param userPrompt The user's prompt. Optional: an image-to-video run may
+ *   legitimately have none, and it is returned as-is when nothing folds.
+ * @param direction Flat catalog ids. Unknown keys, off-surface keys (an
+ *   image-only dimension sent to a video run) and unknown ids all contribute
+ *   nothing — never a throw.
+ * @param structured Path-1 structured fields. Not a `/v1/generate-video` wire
+ *   field today; the canvas orchestrator passes it directly.
+ * @param opts.hintMode Override the verbosity policy (a whole-fold
+ *   `PickerHintMode`, or a `{ look, motion }` split).
+ */
+export function composeVideoPromptText(
+  userPrompt: string | undefined,
+  direction: DirectionFields | undefined,
+  structured?: StructuredPromptFields,
+  opts?: { readonly hintMode?: DirectionHintMode },
+): string | undefined {
+  const hints = [
+    ...renderDirectionHints(direction, {
+      surface: "video",
+      mode: opts?.hintMode ?? VIDEO_HINT_MODE_DEFAULT,
+    }),
+    structured ? renderStructuredFields(structured) : "",
+  ].filter((p) => p.length > 0)
+  // Nothing to fold → the caller's value straight back, `undefined` included.
+  // Do NOT collapse this into `joinPromptHints(userPrompt ?? "", hints)`: that
+  // would turn an absent prompt into `""` and break the no-op contract above.
+  if (hints.length === 0) return userPrompt
+  return joinPromptHints(userPrompt ?? "", hints)
+}