@nodaro/prompts 1.10.0 → 1.12.0

package/src/__tests__/assemble-video-input-cap.test.ts

@@ -0,0 +1,356 @@
+import { describe, it, expect } from "vitest"
+import { composeVideoPromptText } from "../assemble-video-input.js"
+import { resolveVideoReferenceCore } from "../video-reference-resolver.js"
+import { renderDirectionHints, VIDEO_HINT_MODE_DEFAULT } from "../direction-registry.js"
+import { renderSubjectHints, SUBJECT_VIDEO_HINT_MODE_DEFAULT } from "../subject-registry.js"
+import { renderStructuredFields } from "../prompt-builder-structured-fields.js"
+import { joinPromptHints } from "../prompt-hint-join.js"
+import { getMaxVideoPromptChars } from "@nodaro/shared"
+import type { ConnectedReference } from "@nodaro/shared"
+
+/**
+ * TRUNCATION ORDERING, VIDEO HALF — `composeVideoPromptText` sheds its own hint
+ * clauses before the provider clamp's ORDER-BLIND tail cut can reach a
+ * reference binding or the user's prose. The image twin is
+ * `assemble-image-input-cap.test.ts`; this suite mirrors its shape.
+ *
+ * THE ORDERING PROBLEM THIS SIDE HAS AND THE IMAGE SIDE DID NOT: the fold runs
+ * BEFORE `resolveVideoReferenceCore`, and the resolver then ADDS the binding
+ * text — hybrid's role phrases are APPENDED, so they sit behind every folded
+ * hint and are the first thing a tail cut destroys. So the shed is decided on
+ * the FRAMED length (`opts.frame`), not on the folded body: the resolver's
+ * additions are inside the budget, while the only thing the composer can drop
+ * is a clause it rendered itself. The frame below is the real resolver.
+ *
+ * Video caps are far tighter than the image side's (kling = 1000 vs seedream =
+ * 3000), so an ordinary direction overflows without any contrived prose.
+ */
+
+// A broad but ordinary video direction — the kind a "set every picker" UI emits.
+// Ids that don't resolve contribute nothing (registry tolerance); what matters
+// is that the fold is large enough to overflow kling.
+const DIRECTION = {
+  cameraMotion: "handheld",
+  shotSize: "wide-shot",
+  angle: "low-angle",
+  timeOfDay: "golden-hour",
+  lightingStyle: "rembrandt",
+  colorLook: "teal-orange",
+  atmosphere: ["fog"],
+  style: "cinematic",
+  mood: ["happy", "joyful"],
+  setting: "forest",
+} as const
+
+const VIDEO_HINTS = renderDirectionHints(DIRECTION, {
+  surface: "video",
+  mode: VIDEO_HINT_MODE_DEFAULT,
+})
+
+/** The mentioned character — hybrid replaces the mention INLINE, mid-prose. */
+const KIRA: ConnectedReference = {
+  id: "kira-id",
+  defaultName: "Kira",
+  source: "wired-character",
+  url: "https://r2.example/kira.png",
+  characterSlug: "kira",
+  variantSlug: undefined,
+  characterCanonicalDescription: "a young woman with copper hair",
+  variantDescription: null,
+  variantDisplayName: "canonical",
+}
+
+/** An UNMENTIONED wired character — hybrid renders its canonical-fallback role
+ *  phrase at the very END, behind every folded hint. The order-blind casualty. */
+const RAY: ConnectedReference = {
+  id: "ray-id",
+  defaultName: "Ray",
+  source: "wired-character",
+  url: "https://r2.example/ray.png",
+  characterSlug: "ray",
+  variantSlug: undefined,
+  characterCanonicalDescription: "a grizzled dockworker",
+  variantDescription: null,
+  variantDisplayName: "canonical",
+}
+
+const KLING_CAP = getMaxVideoPromptChars("kling")
+
+/** Prose long enough that prose + bindings + the full fold clears 1000. */
+const PROSE = "@kira:1 walks the seawall at dusk. " + "The waves are loud. ".repeat(14)
+
+/**
+ * The FRAME under test: the production reference resolver in the hybrid format,
+ * exactly the shape the routes' `assembleVideoConnectedReferences` drives it in.
+ * Pure, so the composer may call it once per shed iteration.
+ */
+const frame = (body: string | undefined): string | undefined =>
+  resolveVideoReferenceCore({
+    prompt: body,
+    wiredCharRefs: [KIRA, RAY],
+    hybridRoles: true,
+  }).prompt
+
+/** The binding that lands inline, inside the prose. */
+const MENTION_BINDING = "@image_1"
+/** Ray is unmentioned → his canonical-fallback phrase is APPENDED, last. */
+const TRAILING_BINDING = "@image_2"
+
+describe("composeVideoPromptText — cap-aware hint shedding", () => {
+  it("the unshed fold really does overflow kling through the frame (non-vacuity guard)", () => {
+    // The oracle for "what the composer produced before": fold every hint, hand
+    // the body to the resolver, let the provider clamp decide. If catalog
+    // wording ever shrinks enough that this stops overflowing, every scenario
+    // below is vacuous and this assertion says so loudly.
+    const naive = frame(composeVideoPromptText(PROSE, DIRECTION))!
+    expect(naive.length).toBeGreaterThan(KLING_CAP)
+    // …and what a tail cut at the cap would destroy is the trailing BINDING,
+    // not the decorative tail: the role phrase sits past the cap.
+    expect(naive.slice(0, KLING_CAP)).not.toContain(TRAILING_BINDING)
+  })
+
+  it("keeps every binding and the full prose, dropping trailing hints", () => {
+    const body = composeVideoPromptText(PROSE, DIRECTION, undefined, {
+      cap: KLING_CAP,
+      frame,
+    })!
+    const framed = frame(body)!
+
+    // Fits — the shed resolved the whole overflow, so the provider clamp is
+    // never reached and nothing is cut mid-word.
+    expect(framed.length).toBeLessThanOrEqual(KLING_CAP)
+
+    // Both bindings survive: the mention resolved inline AND the trailing
+    // canonical-fallback role phrase the resolver appends last.
+    expect(framed).toContain(MENTION_BINDING)
+    expect(framed).toContain(TRAILING_BINDING)
+
+    // The user's prose survives IN FULL and still leads the body (the hint join
+    // trims its trailing space), and it survives the framing too — the mention
+    // resolving inline to its role phrase is the only edit it takes.
+    expect(body.startsWith(PROSE.trim())).toBe(true)
+    expect(framed).toContain(PROSE.replace("@kira:1", `the person from ${MENTION_BINDING}`).trim())
+
+    // The LAST-folded hint clause is gone; the FIRST-folded one stayed. Shedding
+    // walks the fold order from the tail, so the dimensions the registry folds
+    // first outlive the ones it folds last.
+    expect(body).not.toContain(VIDEO_HINTS[VIDEO_HINTS.length - 1])
+    expect(body).toContain(VIDEO_HINTS[0])
+  })
+
+  it("sheds more as the cap tightens, and everything at a cap prose alone can't meet", () => {
+    const roomy = composeVideoPromptText(PROSE, DIRECTION, undefined, { cap: KLING_CAP, frame })!
+    const tight = composeVideoPromptText(PROSE, DIRECTION, undefined, { cap: 700, frame })!
+    expect(tight.length).toBeLessThan(roomy.length)
+
+    // A cap the framed prose alone cannot meet sheds every hint and then stops —
+    // prose is never touched, and the provider clamp stays the last resort.
+    const starved = composeVideoPromptText(PROSE, DIRECTION, undefined, { cap: 10, frame })
+    expect(starved).toBe(PROSE)
+    for (const hint of VIDEO_HINTS) expect(starved).not.toContain(hint)
+  })
+
+  it("reserves the caller's budget rather than re-deriving a provider cap", () => {
+    // The routes pass `effectiveVideoPromptCeiling`, which for a NON-native
+    // negative provider is `cap - "\nAvoid: …".length`. The composer must honor
+    // that reduced number verbatim — a composer that read `getMaxVideoPromptChars`
+    // itself would shed too little and let the clamp sever the Avoid suffix's
+    // room. `minimax` is outside NATIVE_NEGATIVE_VIDEO_PROVIDERS, so its ceiling
+    // really does shrink.
+    const rawCap = getMaxVideoPromptChars("minimax")
+    const reserved = rawCap - "\nAvoid: blurry, low quality".length
+    const atRaw = composeVideoPromptText(PROSE, DIRECTION, undefined, { cap: rawCap, frame })!
+    const atReserved = composeVideoPromptText(PROSE, DIRECTION, undefined, { cap: reserved, frame })!
+    expect(frame(atReserved)!.length).toBeLessThanOrEqual(reserved)
+    expect(atReserved.length).toBeLessThanOrEqual(atRaw.length)
+  })
+
+  it("never sheds the structured fragment — it is user content, not a garnish", () => {
+    const structured = { subject: "a lighthouse keeper", action: "hauls a rope hand over hand" }
+    const fragment = renderStructuredFields(structured)
+    const body = composeVideoPromptText(PROSE, DIRECTION, structured, { cap: 700, frame })!
+    expect(body).toContain(fragment)
+    // …and it still lands LAST, behind the surviving hints.
+    expect(body.endsWith(fragment)).toBe(true)
+  })
+})
+
+describe("composeVideoPromptText — under-cap byte parity", () => {
+  // The oracle is literally the capless call. A framed prompt that FITS must be
+  // byte-identical to it, so the whole leg lands dark for every under-cap run.
+  const parityCases: ReadonlyArray<{ name: string; provider: string; prompt: string }> = [
+    { name: "high-cap provider with the same fold", provider: "seedance-2", prompt: PROSE },
+    { name: "low-cap provider, short prose", provider: "kling", prompt: "a knight on a hill" },
+  ]
+
+  for (const { name, provider, prompt } of parityCases) {
+    it(`is byte-identical to the capless fold — ${name}`, () => {
+      const cap = getMaxVideoPromptChars(provider)
+      const expected = composeVideoPromptText(prompt, DIRECTION)
+      const actual = composeVideoPromptText(prompt, DIRECTION, undefined, { cap, frame })
+      expect(actual).toBe(expected)
+      // Guard the guard: a case that overflowed would prove nothing.
+      expect(frame(expected)!.length).toBeLessThanOrEqual(cap)
+    })
+  }
+
+  it("leaves the no-direction platform-caller path an exact no-op under a cap", () => {
+    // No hints → nothing droppable → the prompt comes back verbatim and
+    // UNTRIMMED, `undefined` included, exactly as before, even on a tiny cap.
+    expect(composeVideoPromptText("  \n", undefined, undefined, { cap: 1, frame })).toBe("  \n")
+    expect(composeVideoPromptText(undefined, undefined, undefined, { cap: 1, frame })).toBeUndefined()
+    expect(composeVideoPromptText("a knight", {}, undefined, { cap: 1, frame })).toBe("a knight")
+  })
+
+  it("treats an absent frame as identity, and an absent cap as no shedding at all", () => {
+    // A caller with a cap but no references measures the body itself…
+    const framedless = composeVideoPromptText(PROSE, DIRECTION, undefined, { cap: 400 })!
+    expect(framedless.length).toBeLessThanOrEqual(400)
+    // …and a caller with no cap gets the full fold no matter how long it is.
+    expect(composeVideoPromptText(PROSE, DIRECTION, undefined, { frame })).toBe(
+      composeVideoPromptText(PROSE, DIRECTION),
+    )
+  })
+})
+
+/**
+ * THE SUBJECT CHANNEL UNDER THE SAME CAP. The decision this pins: subject
+ * clauses ARE shed candidates, exactly like direction clauses — both are
+ * catalog decoration the platform rendered from ids — and they shed AFTER the
+ * direction fold, because both channels ride ONE list (`[...subject,
+ * ...direction]`) that the shared `hint-shedding.ts` arithmetic walks TAIL
+ * FIRST. Exempting the subject fold would not save it: a fully specified person
+ * is the largest single fold on the surface, so the overflow would simply land
+ * in the provider's order-blind clamp and sever a binding or the prose instead.
+ *
+ * The image twin of this ordering is pinned in `subject-fold.test.ts`; what is
+ * new HERE is the composition the video surface only gained once the cap and
+ * the subject channel met — including the SUBJECT-ONLY fold, which neither
+ * channel's own suite exercises under a cap.
+ *
+ * Caps are derived from the framed body rather than hardcoded, so the cases
+ * keep testing the claim when catalog wording changes.
+ */
+describe("composeVideoPromptText — the subject fold under the cap", () => {
+  const SUBJECT = {
+    type: "woman",
+    ethnicity: "east-asian",
+    hairBase: "base-short-straight",
+    makeup: "makeup-smoky",
+    animal: "dog-corgi",
+  } as const
+
+  const SUBJECT_HINTS = renderSubjectHints(SUBJECT, {
+    surface: "video",
+    mode: SUBJECT_VIDEO_HINT_MODE_DEFAULT,
+  })
+
+  /**
+   * Framed length of the body that folds exactly the first `n` subject clauses
+   * and no direction at all — i.e. the tightest budget under which the shed
+   * should settle on `n` kept clauses. Built the same way the composer builds
+   * it, so the derived caps track catalog wording instead of pinning it.
+   */
+  const framedWithSubjectClauses = (n: number): number =>
+    frame(n === 0 ? PROSE : joinPromptHints(PROSE, SUBJECT_HINTS.slice(0, n)))!.length
+
+  it("sheds the whole direction fold before a single subject clause", () => {
+    // Non-vacuity: subject + direction together really do overflow the frame.
+    const unshed = frame(
+      composeVideoPromptText(PROSE, DIRECTION, undefined, { subject: SUBJECT }),
+    )!
+    expect(unshed.length).toBeGreaterThan(KLING_CAP)
+    expect(SUBJECT_HINTS.length).toBeGreaterThan(1)
+
+    // A budget that fits the prose plus the FULL subject fold and nothing else.
+    const cap = framedWithSubjectClauses(SUBJECT_HINTS.length)
+    const body = composeVideoPromptText(PROSE, DIRECTION, undefined, {
+      subject: SUBJECT,
+      cap,
+      frame,
+    })!
+    expect(frame(body)!.length).toBeLessThanOrEqual(cap)
+    // Every subject clause survived; the direction fold paid the whole bill.
+    for (const hint of SUBJECT_HINTS) expect(body).toContain(hint)
+    for (const hint of VIDEO_HINTS) expect(body).not.toContain(hint)
+    // …and the prose and both bindings are untouched, as always.
+    expect(body.startsWith(PROSE.trim())).toBe(true)
+    expect(frame(body)!).toContain(MENTION_BINDING)
+    expect(frame(body)!).toContain(TRAILING_BINDING)
+  })
+
+  it("then sheds subject clauses too, last-folded first, once direction is gone", () => {
+    // Tighter than the prose plus the full subject fold → the tail of the
+    // SUBJECT list has to go as well. This is the decision: subject clauses are
+    // shed candidates, not a protected channel.
+    const cap = framedWithSubjectClauses(SUBJECT_HINTS.length - 1)
+    const body = composeVideoPromptText(PROSE, DIRECTION, undefined, {
+      subject: SUBJECT,
+      cap,
+      frame,
+    })!
+    expect(frame(body)!.length).toBeLessThanOrEqual(cap)
+    expect(body).not.toContain(SUBJECT_HINTS[SUBJECT_HINTS.length - 1])
+    expect(body).toContain(SUBJECT_HINTS[0])
+  })
+
+  it("sheds a SUBJECT-ONLY fold, and still never the prose or the bindings", () => {
+    // The composition neither parent shipped: `subject` with a cap and no
+    // `direction` at all — the shape a subject-only route request takes.
+    const cap = framedWithSubjectClauses(0)
+    const body = composeVideoPromptText(PROSE, undefined, undefined, {
+      subject: SUBJECT,
+      cap,
+      frame,
+    })!
+    // Everything droppable is gone, so the body is the prose VERBATIM (the
+    // `kept === 0` no-op branch), which is what leaves the route's
+    // `composed !== prompt` guard correctly unpinned.
+    expect(body).toBe(PROSE)
+    for (const hint of SUBJECT_HINTS) expect(body).not.toContain(hint)
+    const framed = frame(body)!
+    expect(framed).toContain(MENTION_BINDING)
+    expect(framed).toContain(TRAILING_BINDING)
+  })
+
+  it("never sheds the structured fragment to save a subject clause", () => {
+    // Ordering across ALL THREE pieces at once: user content outranks both
+    // catalog channels and still lands last.
+    const structured = { subject: "a lighthouse keeper", action: "hauls a rope" }
+    const fragment = renderStructuredFields(structured)
+    const body = composeVideoPromptText(PROSE, DIRECTION, structured, {
+      subject: SUBJECT,
+      cap: framedWithSubjectClauses(0),
+      frame,
+    })!
+    expect(body.endsWith(fragment)).toBe(true)
+    for (const hint of [...SUBJECT_HINTS, ...VIDEO_HINTS]) {
+      expect(body).not.toContain(hint)
+    }
+  })
+
+  it("is byte-identical to the capless subject fold when it fits", () => {
+    // The under-cap parity oracle, extended to the subject channel: a fold that
+    // fits must not be able to tell it was budgeted.
+    const short = "a knight on a hill"
+    const cap = getMaxVideoPromptChars("seedance-2")
+    const expected = composeVideoPromptText(short, DIRECTION, undefined, { subject: SUBJECT })
+    const actual = composeVideoPromptText(short, DIRECTION, undefined, {
+      subject: SUBJECT,
+      cap,
+      frame,
+    })
+    expect(actual).toBe(expected)
+    expect(frame(expected)!.length).toBeLessThanOrEqual(cap)
+  })
+
+  it("leaves a subject-less request byte-identical under a cap (the parity oracle)", () => {
+    // The channel must stay dark: no `subject` → exactly what the direction-only
+    // cap path produced before the two met.
+    for (const cap of [KLING_CAP, 700, 10]) {
+      expect(composeVideoPromptText(PROSE, DIRECTION, undefined, { cap, frame })).toBe(
+        composeVideoPromptText(PROSE, DIRECTION, undefined, { subject: {}, cap, frame }),
+      )
+    }
+  })
+})

package/src/__tests__/assemble-video-input.test.ts

@@ -0,0 +1,301 @@
+import { describe, it, expect } from "vitest"
+import { composeVideoPromptText } from "../assemble-video-input.js"
+import { directionFieldsForSurface } from "../direction-registry.js"
+import { getStylePromptHint, getStyleTerm } from "../style.js"
+import { getTransitionPromptHint, getTransitionTerm } from "../transitions.js"
+import { getCameraMotionPromptHint, getCameraMotionTerm } from "../camera-motions.js"
+import { getFramingPromptHint } from "../framing.js"
+import { getLightingPromptHint } from "../lighting.js"
+import { buildMoodHints } from "../mood.js"
+import { buildAestheticHints } from "../aesthetic.js"
+import { buildAtmosphereHints } from "../atmosphere.js"
+import { buildPhotographerHints } from "../photographer.js"
+import { renderStructuredFields } from "../prompt-builder-structured-fields.js"
+
+/**
+ * `composeVideoPromptText` is the video route's ONLY prompt-composition step,
+ * so two contracts matter here above everything else:
+ *
+ *  1. THE NO-OP CONTRACT — with no direction the caller's prompt comes back
+ *     verbatim and untrimmed, `undefined` included. This is the local
+ *     restatement of the route-level byte-parity oracle ("backward-compatible:
+ *     no connectedReferences → prompt + flat refs pass through unchanged" in
+ *     `backend/src/routes/__tests__/generate-video.test.ts`), and it is what
+ *     makes this whole leg land dark.
+ *  2. THE VERBOSITY POLICY — look dimensions render their full clause, motion
+ *     dimensions their compact professional term. That split moved from the
+ *     client to the platform, so it is pinned in both directions.
+ *
+ * Real catalog ids throughout: every `get*PromptHint` returns `""` on a miss,
+ * so a made-up id would make most assertions vacuously pass.
+ */
+
+// ── Real ids, one per dimension used below ──────────────────────────────────
+const STYLE = "cinematic" // look
+const TRANSITION = "cross-dissolve" // motion
+const CAMERA_MOTION = "handheld" // motion
+const SHOT_SIZE = "wide-shot" // look, framing catalog
+const TIME_OF_DAY = "dawn" // look, lighting catalog (time-of-day category)
+const LIGHTING_STYLE = "three-point" // look, lighting catalog (style category)
+const PHOTOGRAPHER = "tim-walker" // IMAGE-ONLY dimension
+const NO_SUCH_ID = "__no_such_id__"
+
+describe("composeVideoPromptText — the no-op contract", () => {
+  it("returns a prompt verbatim when no direction is passed", () => {
+    expect(composeVideoPromptText("a knight rides at dusk", undefined)).toBe(
+      "a knight rides at dusk",
+    )
+  })
+
+  it("returns a whitespace-only prompt verbatim and UNTRIMMED", () => {
+    expect(composeVideoPromptText("  \n", undefined)).toBe("  \n")
+  })
+
+  it("preserves `undefined` (the video prompt is optional)", () => {
+    expect(composeVideoPromptText(undefined, undefined)).toBeUndefined()
+  })
+
+  it("treats an empty direction object as no direction", () => {
+    expect(composeVideoPromptText("a knight", {})).toBe("a knight")
+    expect(composeVideoPromptText(undefined, {})).toBeUndefined()
+  })
+})
+
+describe("composeVideoPromptText — the verbosity policy", () => {
+  it("renders a LOOK dimension as its full clause", () => {
+    expect(composeVideoPromptText("a knight", { style: STYLE })).toBe(
+      `a knight. ${getStylePromptHint(STYLE)}`,
+    )
+  })
+
+  it("renders a MOTION dimension as its compact term, not its full hint", () => {
+    const out = composeVideoPromptText("a knight", { transition: TRANSITION })
+    expect(out).toBe(`a knight. ${getTransitionTerm(TRANSITION)}`)
+    expect(out).not.toContain(getTransitionPromptHint(TRANSITION))
+  })
+
+  it("applies both halves of the split policy in ONE fold", () => {
+    const out = composeVideoPromptText("a knight", {
+      style: STYLE,
+      transition: TRANSITION,
+    })
+    expect(out).toContain(getStylePromptHint(STYLE))
+    expect(out).toContain(getTransitionTerm(TRANSITION))
+    expect(out).not.toContain(getTransitionPromptHint(TRANSITION))
+  })
+
+  it("honors a whole-fold `hintMode` override in both directions", () => {
+    // "full" promotes the motion family to its full clause…
+    expect(
+      composeVideoPromptText("a knight", { transition: TRANSITION }, undefined, {
+        hintMode: "full",
+      }),
+    ).toBe(`a knight. ${getTransitionPromptHint(TRANSITION)}`)
+    // …and "compact" demotes the look family to its term.
+    expect(
+      composeVideoPromptText("a knight", { style: STYLE }, undefined, {
+        hintMode: "compact",
+      }),
+    ).toBe(`a knight. ${getStyleTerm(STYLE)}`)
+  })
+})
+
+describe("composeVideoPromptText — ordering", () => {
+  it("puts camera motion first (the order Studio and the orchestrator both emit)", () => {
+    const out = composeVideoPromptText("a knight", {
+      style: STYLE,
+      cameraMotion: CAMERA_MOTION,
+    })!
+    expect(out.indexOf(getCameraMotionTerm(CAMERA_MOTION))).toBeLessThan(
+      out.indexOf(getStylePromptHint(STYLE)),
+    )
+    // Compact motion again — the camera-motion row is `family: "motion"`.
+    expect(out).not.toContain(getCameraMotionPromptHint(CAMERA_MOTION))
+  })
+
+  it("folds in TABLE order, not the caller's object order", () => {
+    // `shotSize` (row 2) precedes `style` (row 22) however the object is written.
+    const out = composeVideoPromptText("a knight", {
+      style: STYLE,
+      shotSize: SHOT_SIZE,
+    })!
+    expect(out.indexOf(getFramingPromptHint(SHOT_SIZE))).toBeLessThan(
+      out.indexOf(getStylePromptHint(STYLE)),
+    )
+  })
+
+  it("appends the structured fragment AFTER every direction hint", () => {
+    const structured = { mood: "wistful" }
+    const fragment = renderStructuredFields(structured)
+    expect(fragment.length).toBeGreaterThan(0)
+    const out = composeVideoPromptText("a knight", { style: STYLE }, structured)!
+    expect(out).toBe(`a knight. ${getStylePromptHint(STYLE)}. ${fragment}`)
+  })
+})
+
+describe("composeVideoPromptText — multi-pick doctrine", () => {
+  it("BLENDS two moods into ONE clause (not a per-id loop)", () => {
+    const blended = buildMoodHints({ mood: ["happy", "serene"] }, "full")
+    expect(blended).toHaveLength(1)
+    expect(composeVideoPromptText("a knight", { mood: ["happy", "serene"] })).toBe(
+      `a knight. ${blended[0]}`,
+    )
+  })
+
+  it("BLENDS two aesthetics into ONE clause", () => {
+    const blended = buildAestheticHints(["y2k", "cottagecore"], "full")
+    expect(blended.length).toBeGreaterThan(0)
+    expect(
+      composeVideoPromptText("a knight", { aesthetic: ["y2k", "cottagecore"] }),
+    ).toBe(`a knight. ${blended}`)
+  })
+
+  it("slices an over-cap array to the dimension's maxPicks (atmosphere = 2)", () => {
+    const out = composeVideoPromptText("a knight", {
+      atmosphere: ["clear", "cloudy", "overcast"],
+    })!
+    const kept = buildAtmosphereHints(["clear", "cloudy"], "full")
+    expect(kept).toHaveLength(2)
+    expect(out).toBe(`a knight. ${kept.join(". ")}`)
+    expect(out).not.toContain(buildAtmosphereHints("overcast", "full")[0])
+  })
+
+  it("accepts an ARRAY on a single-pick key and keeps the first id", () => {
+    // The legacy `V2LookPicker` shape: a single-pick dimension that stored an
+    // array. Must degrade to one hint, never throw and never drop the key.
+    const out = composeVideoPromptText("a knight", { style: [STYLE, "anime"] })
+    expect(out).toBe(`a knight. ${getStylePromptHint(STYLE)}`)
+  })
+})
+
+describe("composeVideoPromptText — tolerance", () => {
+  it("skips an unknown id and leaves the prompt verbatim (no dangling '. ')", () => {
+    expect(composeVideoPromptText("a knight", { style: NO_SUCH_ID })).toBe("a knight")
+  })
+
+  it("skips an IMAGE-ONLY dimension sent to a video run", () => {
+    // `photographer` is accepted on the wire (surface is a render concern, not
+    // a wire concern) and simply contributes nothing here.
+    expect(buildPhotographerHints(PHOTOGRAPHER, "full").length).toBeGreaterThan(0)
+    expect(composeVideoPromptText("a knight", { photographer: PHOTOGRAPHER })).toBe(
+      "a knight",
+    )
+  })
+
+  it("skips an unknown wire key entirely", () => {
+    expect(
+      composeVideoPromptText("a knight", { __not_a_dimension__: "x" } as never),
+    ).toBe("a knight")
+  })
+})
+
+describe("composeVideoPromptText — an empty or absent body", () => {
+  it("returns the hints alone for an empty prompt (never a leading '. ')", () => {
+    expect(composeVideoPromptText("", { style: STYLE })).toBe(getStylePromptHint(STYLE))
+  })
+
+  it("returns the hints alone for an ABSENT prompt", () => {
+    expect(composeVideoPromptText(undefined, { style: STYLE })).toBe(
+      getStylePromptHint(STYLE),
+    )
+  })
+})
+
+describe("composeVideoPromptText — the dedupe invariant", () => {
+  // The five legacy keys address a WHOLE catalog, so they are not aliases of
+  // their canonical counterparts. Overlap is resolved by exact-clause dedupe,
+  // which suppresses a repeated clause without suppressing a different id.
+  it("emits ONE clause when a legacy and a canonical key carry the SAME id", () => {
+    expect(
+      composeVideoPromptText("a knight", { framingId: SHOT_SIZE, shotSize: SHOT_SIZE }),
+    ).toBe(`a knight. ${getFramingPromptHint(SHOT_SIZE)}`)
+  })
+
+  it("emits BOTH clauses for two DIFFERENT ids of one catalog", () => {
+    // The case an alias table would have wrongly collapsed: `lightingId` is
+    // whole-catalog, so a time-of-day pick beside a lighting-style pick is two
+    // legitimate selections.
+    const out = composeVideoPromptText("a knight", {
+      lightingStyle: LIGHTING_STYLE,
+      lightingId: TIME_OF_DAY,
+    })
+    expect(out).toBe(
+      `a knight. ${getLightingPromptHint(LIGHTING_STYLE)}. ${getLightingPromptHint(TIME_OF_DAY)}`,
+    )
+  })
+})
+
+/**
+ * ORDER TOTALITY — every video-surface dimension, folded in one call.
+ *
+ * The fixture is keyed in `directionFieldsForSurface("video")` order and pinned
+ * against it, so adding, removing or reordering a video row fails HERE as well
+ * as in the registry test. Each id was chosen to render a clause distinct from
+ * every other row's, so the dedupe pass cannot mask a mis-ordering.
+ */
+const EVERY_VIDEO_DIMENSION: Record<string, string> = {
+  cameraMotion: "static",
+  shotSize: "extreme-wide-shot",
+  angle: "eye-level",
+  coverage: "single",
+  composition: "rule-of-thirds",
+  vantage: "front-on",
+  pose: "standing-upright",
+  compositionEffect: "bursting-through-frame",
+  cameraFormat: "35mm-film",
+  lens: "ultra-wide-14mm",
+  timeOfDay: "dawn",
+  lightingStyle: "three-point",
+  lightingDirection: "front",
+  lightingRatio: "ratio-1-1",
+  colorTemperature: "temp-2700k",
+  colorLook: "warm",
+  atmosphere: "clear",
+  style: "3d-render",
+  mood: "happy",
+  aesthetic: "y2k",
+  setting: "coffee-shop",
+  era: "1920s-flapper",
+  backdrop: "white-seamless",
+  actionFx: "earthquake-tremor",
+  temporalSpeed: "real-time",
+  temporalFreeze: "full-freeze",
+  temporalDirection: "forward",
+  temporalShutter: "long-exposure",
+  transition: "none",
+  loopSubject: "aurora",
+  framingId: "wide-shot",
+  framingAngleId: "medium-wide-shot",
+  lightingId: "sunrise",
+  lensId: "wide-24mm",
+  cameraFormatId: "16mm-film",
+}
+
+describe("composeVideoPromptText — order totality over every video dimension", () => {
+  it("covers exactly the video surface, in table order", () => {
+    expect(Object.keys(EVERY_VIDEO_DIMENSION)).toEqual(
+      directionFieldsForSurface("video").map((f) => f.key),
+    )
+  })
+
+  it("resolves every fixture id to a real clause", () => {
+    for (const [key, id] of Object.entries(EVERY_VIDEO_DIMENSION)) {
+      expect(composeVideoPromptText("", { [key]: id }), `${key}=${id}`).not.toBe("")
+    }
+  })
+
+  it("folds all 35 dimensions in registry order, one clause each", () => {
+    // Per-dimension renders, composed in isolation through the same public
+    // entry point, then concatenated in table order: the whole fold must equal
+    // exactly that. Any reorder, drop or duplicate shows up as a diff.
+    const expected = Object.entries(EVERY_VIDEO_DIMENSION).map(
+      ([key, id]) => composeVideoPromptText("", { [key]: id })!,
+    )
+    expect(new Set(expected).size, "fixture ids must render distinct clauses").toBe(
+      expected.length,
+    )
+    expect(composeVideoPromptText("a knight", EVERY_VIDEO_DIMENSION)).toBe(
+      ["a knight", ...expected].join(". "),
+    )
+  })
+})