@nodaro/prompts 1.11.0 → 1.12.0

package/src/__tests__/mention-splice-spacing.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect } from "vitest"
+import { buildImagePrompt } from "../prompt-builder.js"
+import type { ConnectedReference } from "@nodaro/shared"
+
+/**
+ * Seam whitespace at a resolved mention (image path).
+ *
+ * A live prod payload assembled to
+ *
+ *   "the person from reference image A  and reference image C walking …"
+ *
+ * — TWO spaces after the character phrase. An editor serializes a mention chip
+ * as its token plus its own trailing space, and the prose that follows carries
+ * the space the author typed, so an ordinary sentence reaches the route as
+ * `@panda:1  and @panda2:2 …`. The VIDEO core never shows this: every return of
+ * `resolveVideoReferenceCore` runs `resolveReferenceTokens`, whose
+ * `[^\S\r\n]{2,}` collapse tidies the gap. The image path had no such tidy, so
+ * the doubled space landed in the model's prompt exactly where the reference is
+ * being described.
+ *
+ * `spliceMentionPhrase` now collapses the horizontal whitespace on either side
+ * of each splice seam — scoped to the seam, so prose the author double-spaced
+ * elsewhere is left alone and an already-single-spaced prompt is byte-identical.
+ */
+
+const panda: ConnectedReference = {
+  id: "c1", defaultName: "Panda", source: "wired-character",
+  url: "https://cdn/panda.png", characterSlug: "panda",
+}
+const panda2: ConnectedReference = {
+  id: "n2", defaultName: "Panda2", source: "wired-image", url: "https://cdn/panda2.png",
+}
+const beach: ConnectedReference = {
+  id: "l1", defaultName: "Beach", source: "wired-location",
+  url: "https://cdn/beach.png", locationSlug: "beach",
+}
+
+const REFS = [panda, panda2, beach]
+
+/** Mention URLs merge character → location → image, so the letters are
+ *  A = the character, B = the location, C = the named image. */
+const EXPECTED =
+  "the person from reference image A and reference image C walking in "
+  + "the location from reference image B at dusk"
+
+const build = (prompt: string) => buildImagePrompt({
+  prompt,
+  connectedReferences: REFS,
+  provider: "nano-banana-pro",
+  referenceFormat: "hybrid",
+}).prompt
+
+describe("mention splice — seam whitespace", () => {
+  it("Tal's shape: character + image + location in one sentence, single-spaced throughout", () => {
+    expect(build("@panda:1  and @panda2:2  walking in @beach:3  at dusk")).toBe(EXPECTED)
+  })
+
+  it("the already-single-spaced prompt is byte-identical (the collapse needs a 2+ run)", () => {
+    expect(build("@panda:1 and @panda2:2 walking in @beach:3 at dusk")).toBe(EXPECTED)
+  })
+
+  it("collapses on the LEADING side of a seam too", () => {
+    expect(build("@panda:1 and  @panda2:2 walking in  @beach:3 at dusk")).toBe(EXPECTED)
+  })
+
+  it("never emits a doubled space, whichever side of the chip carries it", () => {
+    for (const prompt of [
+      "@panda:1  and @panda2:2 walking in @beach:3 at dusk",
+      "@panda:1 and  @panda2:2 walking in @beach:3 at dusk",
+      "@panda:1   and   @panda2:2   walking in   @beach:3   at dusk",
+    ]) {
+      expect(build(prompt)).toBe(EXPECTED)
+    }
+  })
+
+  it("leaves a doubled space the author put in their own prose alone (seam-scoped, not a body tidy)", () => {
+    expect(build("@panda:1 walks  slowly past @beach:3")).toBe(
+      "the person from reference image A walks  slowly past the location from reference image B",
+    )
+  })
+
+  it("preserves newlines — the collapse class is horizontal-only", () => {
+    expect(build("@panda:1  runs\n\n@beach:3  at dusk")).toBe(
+      "the person from reference image A runs\n\nthe location from reference image B at dusk",
+    )
+  })
+})
+
+// The `{image:N:label}` positional pill is a mention chip like any other:
+// `buildRefPillNodes` appends its own trailing space to EVERY pill it builds,
+// the positional `imageRef` node included. Its hybrid expansion used a raw
+// `.replace`, so the same doubled space survived on this path after the three
+// `@`-mention resolvers were fixed.
+describe("mention splice — the {image:N:label} positional pill", () => {
+  const hat: ConnectedReference = {
+    id: "n1", defaultName: "Hat", source: "wired-image", url: "https://cdn/hat.png",
+  }
+  const coat: ConnectedReference = {
+    id: "n2", defaultName: "Coat", source: "wired-image", url: "https://cdn/coat.png",
+  }
+  const buildTokens = (prompt: string, refs: readonly ConnectedReference[]) => buildImagePrompt({
+    prompt,
+    connectedReferences: [...refs],
+    referenceImageUrls: refs.map((r) => r.url!),
+    provider: "nano-banana-pro",
+    referenceFormat: "hybrid",
+  }).prompt
+
+  it("collapses the trailing seam the pill's own space creates", () => {
+    expect(buildTokens("a man wearing {image:1:hat}  in the park", [hat])).toBe(
+      "A man wearing the hat from reference image A in the park",
+    )
+  })
+
+  it("the already-single-spaced prompt is byte-identical", () => {
+    expect(buildTokens("a man wearing {image:1:hat} in the park", [hat])).toBe(
+      "A man wearing the hat from reference image A in the park",
+    )
+  })
+
+  it("two pills in one sentence both splice cleanly (right-to-left offsets stay valid)", () => {
+    expect(buildTokens("a man wearing {image:1:hat}  and  {image:2:coat}  walks", [hat, coat])).toBe(
+      "A man wearing the hat from reference image A and the coat from reference image B walks",
+    )
+  })
+
+  it("leaves a doubled space the author put in their own prose alone", () => {
+    expect(buildTokens("{image:1:hat} worn  loosely", [hat])).toBe(
+      "The hat from reference image A worn  loosely",
+    )
+  })
+
+  it("an out-of-range token stays visible, and its whitespace with it", () => {
+    expect(buildTokens("a man wearing {image:7:hat}  in the park", [hat])).toContain(
+      "{image:7:hat}  in the park",
+    )
+  })
+})
+
+// Indentation is structure, not a seam. A run that OPENS a line is the author's
+// layout (a shot list, a numbered beat sheet), so the leading collapse is
+// anchored to prose on the same line via `(?<=\S)`. Without that anchor a
+// mention starting an indented line flattened the indent to a single space —
+// the same class of damage as merging paragraphs, and it would have made the
+// "an already-single-spaced prompt is byte-identical" claim false for every
+// multi-line prompt.
+describe("mention splice — line-initial indentation survives", () => {
+  /** One character ref only, so no unmentioned ref appends a canonical phrase
+   *  and the assertions can be byte-exact on the multi-line shape. */
+  const buildOne = (prompt: string) => buildImagePrompt({
+    prompt,
+    connectedReferences: [panda],
+    provider: "nano-banana-pro",
+    referenceFormat: "hybrid",
+  }).prompt
+
+  it("a mention that opens an indented line keeps the indent verbatim", () => {
+    expect(buildOne("Scene:\n    @panda:1 stands")).toBe(
+      "Scene:\n    the person from reference image A stands",
+    )
+  })
+
+  it("indent preserved AND the trailing seam still collapses on the same mention", () => {
+    expect(buildOne("Scene:\n  @panda:1  stands")).toBe(
+      "Scene:\n  the person from reference image A stands",
+    )
+  })
+
+  it("a leading run at the very start of the prompt is indentation too", () => {
+    expect(buildOne("   @panda:1  stands")).toBe(
+      "   the person from reference image A stands",
+    )
+  })
+
+  it("mid-line prose before the run still collapses (the anchor is `\\S`, not `^`)", () => {
+    expect(buildOne("Scene:\n    a man and  @panda:1 stands")).toBe(
+      "Scene:\n    a man and the person from reference image A stands",
+    )
+  })
+})
+
+// Wired CREATURE / OBJECT mentions (`@<name-slug>:<index>[:<role>]`) are chips
+// too — `buildRefPillNodes` gives them the same trailing space every other pill
+// gets — so their resolver splices through `spliceMentionPhrase` alongside the
+// character, location and named-image ones. Without that, the seam bug would
+// have been fixed for three mention kinds and reintroduced by the fourth.
+describe("mention splice — wired creature / object mentions", () => {
+  const nessie: ConnectedReference = {
+    id: "cr1", defaultName: "Nessie", source: "wired-creature", url: "https://cdn/nessie.png",
+  }
+  const chair: ConnectedReference = {
+    id: "ob1", defaultName: "Chair", source: "wired-object", url: "https://cdn/chair.png",
+  }
+
+  /** BOTH entities are mentioned in every case, so neither appends a trailing
+   *  canonical phrase and the assertions stay byte-exact on one line. */
+  const buildEntities = (prompt: string) => buildImagePrompt({
+    prompt,
+    connectedReferences: [nessie, chair],
+    provider: "nano-banana-pro",
+    referenceFormat: "hybrid",
+  }).prompt
+
+  const ENTITIES_EXPECTED =
+    "the creature from reference image A looms over "
+    + "the object from reference image B in the fog"
+
+  it("collapses the seam whitespace the chips' own trailing spaces create", () => {
+    expect(buildEntities("@nessie:1  looms over @chair:2  in the fog")).toBe(ENTITIES_EXPECTED)
+  })
+
+  it("the already-single-spaced prompt is byte-identical (the collapse needs a 2+ run)", () => {
+    expect(buildEntities("@nessie:1 looms over @chair:2 in the fog")).toBe(ENTITIES_EXPECTED)
+  })
+
+  it("collapses on the LEADING side of an entity seam too", () => {
+    expect(buildEntities("@nessie:1 looms over  @chair:2 in the fog")).toBe(ENTITIES_EXPECTED)
+  })
+
+  it("never emits a doubled space, whichever side of the chip carries it", () => {
+    for (const prompt of [
+      "@nessie:1  looms over @chair:2 in the fog",
+      "@nessie:1 looms over  @chair:2 in the fog",
+      "@nessie:1   looms over   @chair:2   in the fog",
+    ]) {
+      expect(buildEntities(prompt)).toBe(ENTITIES_EXPECTED)
+    }
+  })
+
+  it("a ROLE segment splices the same way", () => {
+    expect(buildEntities("@nessie:1:markings  over @chair:2:material  in the fog")).toBe(
+      "the markings from reference image A over "
+      + "the material from reference image B in the fog",
+    )
+  })
+
+  it("leaves a doubled space the author put in their own prose alone (seam-scoped)", () => {
+    expect(buildEntities("@nessie:1 looms  slowly over @chair:2 in the fog")).toBe(
+      "the creature from reference image A looms  slowly over "
+      + "the object from reference image B in the fog",
+    )
+  })
+
+  it("preserves newlines — the collapse class is horizontal-only", () => {
+    expect(buildEntities("@nessie:1  looms\n\n@chair:2  in the fog")).toBe(
+      "the creature from reference image A looms\n\n"
+      + "the object from reference image B in the fog",
+    )
+  })
+
+  it("an entity mention that opens an indented line keeps the indent verbatim", () => {
+    expect(buildEntities("Scene:\n    @nessie:1  looms over @chair:2 in the fog")).toBe(
+      "Scene:\n    the creature from reference image A looms over "
+      + "the object from reference image B in the fog",
+    )
+  })
+})

package/src/__tests__/read-node-subject.test.ts

@@ -0,0 +1,140 @@
+/**
+ * `readSubjectFields` is the CANVAS door into the subject fold — the twin of
+ * the route's `subjectSchema`. It reads untrusted persisted node JSONB (a
+ * workflow write is validated only as `z.record(z.string(), z.unknown())`), so
+ * every assertion here is on the three contracts it shares with
+ * `readDirectionFields`: drop-never-throw, `undefined` never `{}`, and bounds
+ * that MATCH the wire door by shared constant.
+ */
+import { describe, it, expect, beforeEach } from "vitest"
+import { readSubjectFields } from "../read-node-direction.js"
+import {
+  SUBJECT_ARRAY_CEILING,
+  SUBJECT_ID_MAX_CHARS,
+  SUBJECT_KEYS,
+  getRegisteredSubjectKeys,
+  renderSubjectHints,
+} from "../subject-registry.js"
+import { registerPersonPack, resetPersonPacks } from "../person-packs.js"
+import { resetCatalogPacks } from "../catalog-packs.js"
+import { getPersonPromptHint } from "../person.js"
+
+beforeEach(() => {
+  resetPersonPacks()
+  resetCatalogPacks()
+})
+
+const pack = {
+  id: "test/person-sector",
+  dimensions: [{ dimension: "sector-attire", field: "sectorAttire", label: "Sector Attire" }],
+  entries: [
+    {
+      id: "attire-modest-suit",
+      label: "Modest Suit",
+      group: "Attire",
+      dimension: "sector-attire",
+      description: "a modest tailored suit",
+      promptHint: "wearing a modest tailored suit",
+    },
+  ],
+}
+
+describe("readSubjectFields — shape", () => {
+  it("round-trips the ids a node actually stores", () => {
+    expect(
+      readSubjectFields({
+        type: "woman",
+        hairBase: "base-buzz",
+        jewelry: ["jewelry-gold", "jewelry-silver"],
+        animal: "dog-corgi",
+      }),
+    ).toEqual({
+      type: "woman",
+      hairBase: "base-buzz",
+      jewelry: ["jewelry-gold", "jewelry-silver"],
+      animal: "dog-corgi",
+    })
+  })
+
+  it("returns undefined — never {} — for a blob with nothing readable", () => {
+    expect(readSubjectFields(undefined)).toBeUndefined()
+    expect(readSubjectFields(null)).toBeUndefined()
+    expect(readSubjectFields("nope")).toBeUndefined()
+    expect(readSubjectFields([])).toBeUndefined()
+    expect(readSubjectFields({})).toBeUndefined()
+    expect(readSubjectFields({ notAField: "man" })).toBeUndefined()
+  })
+
+  it("drops junk instead of throwing on it", () => {
+    expect(
+      readSubjectFields({
+        type: { nested: true },
+        hairBase: 42,
+        jewelry: [null, { x: 1 }, "jewelry-gold"],
+        makeup: "",
+      }),
+    ).toEqual({ jewelry: ["jewelry-gold"] })
+  })
+
+  it("filters junk BEFORE the ceiling, so valid ids behind it survive", () => {
+    const v = [...Array.from({ length: SUBJECT_ARRAY_CEILING }, () => 1), "jewelry-gold"]
+    expect(readSubjectFields({ jewelry: v })).toEqual({ jewelry: ["jewelry-gold"] })
+  })
+})
+
+describe("readSubjectFields — bounds shared with the wire door", () => {
+  it("keeps the first SUBJECT_ARRAY_CEILING entries of an over-long array", () => {
+    const many = Array.from({ length: SUBJECT_ARRAY_CEILING + 5 }, (_, i) => `id-${i}`)
+    const out = readSubjectFields({ jewelry: many }) as Record<string, unknown>
+    expect(out.jewelry).toEqual(many.slice(0, SUBJECT_ARRAY_CEILING))
+  })
+
+  it("drops an id longer than SUBJECT_ID_MAX_CHARS, keeping one exactly at the bound", () => {
+    const ok = "x".repeat(SUBJECT_ID_MAX_CHARS)
+    const tooLong = "x".repeat(SUBJECT_ID_MAX_CHARS + 1)
+    expect(readSubjectFields({ type: tooLong })).toBeUndefined()
+    expect(readSubjectFields({ type: ok })).toEqual({ type: ok })
+    expect(readSubjectFields({ jewelry: [tooLong, ok] })).toEqual({ jewelry: [ok] })
+  })
+
+  it("does NOT apply the per-dimension cap — that stays the renderer's slice", () => {
+    const four = ["jewelry-subtle", "jewelry-statement", "jewelry-gold", "jewelry-silver"]
+    expect((readSubjectFields({ jewelry: four }) as Record<string, unknown>).jewelry).toEqual(four)
+  })
+})
+
+describe("readSubjectFields — customAge, the one number", () => {
+  it("passes a finite number through for the renderer to clamp", () => {
+    expect(readSubjectFields({ age: "age-custom", customAge: 34 })).toEqual({
+      age: "age-custom",
+      customAge: 34,
+    })
+    expect(readSubjectFields({ customAge: 9999 })).toEqual({ customAge: 9999 })
+    expect(renderSubjectHints(readSubjectFields({ age: "age-custom", customAge: 9999 }), {
+      surface: "image",
+    })).toEqual(["120 years old"])
+  })
+
+  it("drops a non-finite or non-number customAge", () => {
+    expect(readSubjectFields({ customAge: Number.NaN })).toBeUndefined()
+    expect(readSubjectFields({ customAge: "34" })).toBeUndefined()
+  })
+})
+
+describe("readSubjectFields — pack awareness", () => {
+  it("with no packs registered, the accepted key set IS SUBJECT_KEYS", () => {
+    expect(getRegisteredSubjectKeys()).toEqual([...SUBJECT_KEYS])
+  })
+
+  it("reads a deployment-registered pack dimension, and folds its hint", () => {
+    expect(readSubjectFields({ sectorAttire: "attire-modest-suit" })).toBeUndefined()
+    registerPersonPack(pack)
+    expect(getRegisteredSubjectKeys()).toContain("sectorAttire")
+    expect(readSubjectFields({ sectorAttire: "attire-modest-suit" })).toEqual({
+      sectorAttire: "attire-modest-suit",
+    })
+    expect(
+      renderSubjectHints({ type: "woman", sectorAttire: "attire-modest-suit" }, { surface: "image" }),
+    ).toEqual([`${getPersonPromptHint("woman")}, wearing a modest tailored suit`])
+  })
+})

package/src/__tests__/subject-fold.test.ts

@@ -0,0 +1,232 @@
+/**
+ * The `subject` fold where it actually lands: `assembleImageInput` (stills) and
+ * `composeVideoPromptText` (clips).
+ *
+ * THE LOAD-BEARING TEST IN THIS FILE is the NO-SUBJECT ORACLE: with no
+ * `subject` — which is every caller in the world on the day this ships — the
+ * assembled prompt must be byte-for-byte what it was before the channel
+ * existed. That is what makes the rollout dark. The oracle is written as an
+ * independent recomputation (`joinPromptHints` over `renderDirectionHints`),
+ * not as a snapshot, so it keeps testing the claim if the catalogs change.
+ */
+import { describe, it, expect } from "vitest"
+import { assembleImageInput } from "../assemble-image-input.js"
+import { composeVideoPromptText } from "../assemble-video-input.js"
+import { buildImagePrompt } from "../prompt-builder.js"
+import { joinPromptHints, PROMPT_HINT_SEPARATOR } from "../prompt-hint-join.js"
+import { renderDirectionHints, IMAGE_HINT_MODE_DEFAULT, VIDEO_HINT_MODE_DEFAULT } from "../direction-registry.js"
+import {
+  renderSubjectHints,
+  SUBJECT_IMAGE_HINT_MODE_DEFAULT,
+  SUBJECT_VIDEO_HINT_MODE_DEFAULT,
+} from "../subject-registry.js"
+import { getMaxImagePromptChars } from "@nodaro/shared"
+import type { ConnectedReference } from "@nodaro/shared"
+
+const DIRECTION = {
+  shotSize: "wide-shot",
+  timeOfDay: "golden-hour",
+  lens: "wide-24mm",
+  style: "anime",
+} as const
+
+const SUBJECT = {
+  type: "woman",
+  ethnicity: "east-asian",
+  hairBase: "base-short-straight",
+  makeup: "makeup-smoky",
+  animal: "dog-corgi",
+} as const
+
+const STRUCTURED = { person: { age: 34, hair: "auburn" } } as const
+
+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",
+}
+
+describe("the no-subject oracle — the fold is dark until a caller opts in", () => {
+  const cases: ReadonlyArray<{ name: string; input: Parameters<typeof assembleImageInput>[0] }> = [
+    {
+      name: "bare prompt (the exact no-op contract, untrimmed)",
+      input: { userPrompt: "  a knight on a hill  ", provider: "nano-banana" },
+    },
+    {
+      name: "direction only",
+      input: { userPrompt: "a knight on a hill", provider: "nano-banana", direction: DIRECTION },
+    },
+    {
+      name: "structured only",
+      input: { userPrompt: "a knight on a hill", provider: "nano-banana", structured: STRUCTURED },
+    },
+    {
+      name: "direction + structured + a bound reference",
+      input: {
+        userPrompt: "@kira:1 on a hill",
+        provider: "nano-banana",
+        connectedReferences: [KIRA],
+        direction: DIRECTION,
+        structured: STRUCTURED,
+      },
+    },
+  ]
+
+  for (const { name, input } of cases) {
+    it(`is unchanged by the channel's existence — ${name}`, () => {
+      const withNothing = assembleImageInput(input)
+      // An explicitly-undefined subject, an empty bag, and a bag of keys the
+      // platform does not know are all the same as not passing one.
+      expect(assembleImageInput({ ...input, subject: undefined })).toEqual(withNothing)
+      expect(assembleImageInput({ ...input, subject: {} })).toEqual(withNothing)
+      expect(assembleImageInput({ ...input, subject: { notAField: "x" } })).toEqual(withNothing)
+    })
+  }
+
+  it("returns the user's prompt VERBATIM AND UNTRIMMED with no lever at all", () => {
+    const userPrompt = "  a knight on a hill  "
+    expect(assembleImageInput({ userPrompt, provider: "nano-banana" }).prompt).toBe(userPrompt)
+  })
+
+  it("matches an independent recomputation of the direction-only fold", () => {
+    const userPrompt = "a knight on a hill"
+    const expected = buildImagePrompt({
+      prompt: joinPromptHints(
+        userPrompt,
+        renderDirectionHints(DIRECTION, { surface: "image", mode: IMAGE_HINT_MODE_DEFAULT }),
+      ),
+      provider: "nano-banana",
+    })
+    expect(assembleImageInput({ userPrompt, provider: "nano-banana", direction: DIRECTION })).toEqual(
+      expected,
+    )
+  })
+
+  it("leaves the video composer's no-op contract intact (undefined stays undefined)", () => {
+    expect(composeVideoPromptText(undefined, undefined)).toBeUndefined()
+    expect(composeVideoPromptText(undefined, undefined, undefined, { subject: {} })).toBeUndefined()
+    expect(
+      composeVideoPromptText(undefined, undefined, undefined, { subject: { notAField: "x" } }),
+    ).toBeUndefined()
+    expect(composeVideoPromptText("  a clip  ", undefined, undefined, { subject: {} })).toBe(
+      "  a clip  ",
+    )
+  })
+})
+
+describe("the subject fold — position and content", () => {
+  it("lands the subject clauses AHEAD of the direction clauses", () => {
+    const userPrompt = "on the seawall"
+    const subjectHints = renderSubjectHints(SUBJECT, {
+      surface: "image",
+      mode: SUBJECT_IMAGE_HINT_MODE_DEFAULT,
+    })
+    const directionHints = renderDirectionHints(DIRECTION, {
+      surface: "image",
+      mode: IMAGE_HINT_MODE_DEFAULT,
+    })
+    const result = assembleImageInput({
+      userPrompt,
+      provider: "nano-banana",
+      subject: SUBJECT,
+      direction: DIRECTION,
+    })
+    expect(result.prompt).toBe(
+      buildImagePrompt({
+        prompt: joinPromptHints(userPrompt, [...subjectHints, ...directionHints]),
+        provider: "nano-banana",
+      }).prompt,
+    )
+    expect(result.prompt.indexOf(subjectHints[0]!)).toBeLessThan(
+      result.prompt.indexOf(directionHints[0]!),
+    )
+  })
+
+  it("joins person and styling as ONE clause each, not N sentence fragments", () => {
+    const result = assembleImageInput({
+      userPrompt: "on the seawall",
+      provider: "nano-banana",
+      subject: { type: "woman", ethnicity: "east-asian", makeup: "makeup-smoky" },
+    })
+    // Three catalog fragments, but only ONE sentence separator from the person
+    // clause: the person row comma-joins its own fragments.
+    const sentences = result.prompt.split(PROMPT_HINT_SEPARATOR)
+    expect(sentences).toHaveLength(3) // prose. person clause. styling clause.
+    expect(sentences[1]).toContain(", ")
+  })
+
+  it("folds the subject on the video surface, compact, ahead of direction", () => {
+    const composed = composeVideoPromptText("she walks", DIRECTION, undefined, { subject: SUBJECT })
+    expect(composed).toBe(
+      joinPromptHints("she walks", [
+        ...renderSubjectHints(SUBJECT, {
+          surface: "video",
+          mode: SUBJECT_VIDEO_HINT_MODE_DEFAULT,
+        }),
+        ...renderDirectionHints(DIRECTION, { surface: "video", mode: VIDEO_HINT_MODE_DEFAULT }),
+      ]),
+    )
+  })
+
+  it("honors an explicit subject verbosity override", () => {
+    const full = composeVideoPromptText("she walks", undefined, undefined, {
+      subject: SUBJECT,
+      subjectHintMode: "full",
+    })
+    const compact = composeVideoPromptText("she walks", undefined, undefined, { subject: SUBJECT })
+    expect(full).not.toBe(compact)
+    expect(full!.length).toBeGreaterThan(compact!.length)
+  })
+})
+
+describe("the subject fold — under the provider cap", () => {
+  const SEEDREAM_CAP = getMaxImagePromptChars("seedream")
+  // A broad direction fold plus a broad subject fold, on prose long enough that
+  // the three together clear the lowest cap in the catalog.
+  const BIG_DIRECTION = {
+    ...DIRECTION,
+    angle: "low-angle",
+    cameraFormat: "16mm-film",
+    isoValue: "iso-100",
+    lightingStyle: "rembrandt",
+    colorLook: "teal-orange",
+    atmosphere: ["fog"],
+    mood: ["happy", "joyful"],
+    photographer: ["annie-leibovitz"],
+    setting: "forest",
+  } as const
+  const PROSE = "She walks the seawall at dusk. " + "The waves are loud. ".repeat(90)
+
+  it("sheds the direction fold BEFORE the subject fold", () => {
+    const subjectHints = renderSubjectHints(SUBJECT, {
+      surface: "image",
+      mode: SUBJECT_IMAGE_HINT_MODE_DEFAULT,
+    })
+    const directionHints = renderDirectionHints(BIG_DIRECTION, {
+      surface: "image",
+      mode: IMAGE_HINT_MODE_DEFAULT,
+    })
+    // Non-vacuity: the un-shed fold really does overflow.
+    expect(
+      joinPromptHints(PROSE, [...subjectHints, ...directionHints]).length,
+    ).toBeGreaterThan(SEEDREAM_CAP)
+
+    const result = assembleImageInput({
+      userPrompt: PROSE,
+      provider: "seedream",
+      subject: SUBJECT,
+      direction: BIG_DIRECTION,
+    })
+    expect(result.prompt.length).toBeLessThanOrEqual(SEEDREAM_CAP)
+    expect(result.prompt.endsWith("...")).toBe(false)
+    // Who is in the shot outlived how it was lit.
+    expect(result.prompt).toContain(subjectHints[0])
+    expect(result.prompt).not.toContain(directionHints[directionHints.length - 1])
+  })
+})