@nodaro/prompts 1.12.0 → 1.13.0

package/src/__tests__/prompt-style-section.test.ts

@@ -0,0 +1,345 @@
+import { describe, it, expect } from "vitest"
+import {
+  STYLE_SECTION_HEADER,
+  asBodyClauses,
+  composeSectionedPrompt,
+  endsInsideStyleSection,
+  insertBeforeStyleSection,
+  partitionStyleClauses,
+  renderStyleSection,
+  sectionedClauseCosts,
+  splitStyleSection,
+  styleSectionFromClauses,
+} from "../prompt-style-section.js"
+import {
+  DIRECTION_FIELDS,
+  FILM_STYLE_KEYS,
+  IMAGE_HINT_MODE_DEFAULT,
+  VIDEO_HINT_MODE_DEFAULT,
+  directionFieldsForSurface,
+  renderDirectionHints,
+} from "../direction-registry.js"
+import { joinPromptHints } from "../prompt-hint-join.js"
+import { getStylePromptHint } from "../style.js"
+import { getColorLookPromptHint } from "../color-look.js"
+import { getEraPromptHint } from "../era.js"
+import { getCameraFormatPromptHint } from "../camera-format.js"
+import { getFramingPromptHint } from "../framing.js"
+import { getLightingPromptHint } from "../lighting.js"
+import { getCameraMotionTerm } from "../camera-motions.js"
+import { getTransitionTerm } from "../transitions.js"
+
+/**
+ * THE `[style]` SECTION CONTRACT, at the level it is defined: clauses in, one
+ * string out. The composers (`assembleImageInput`, `composeVideoPromptText`)
+ * are pinned against the same shape in their own suites; what lives here is the
+ * grammar itself — which clause lands on which line, and the exact bytes.
+ *
+ * The header is asserted as a LITERAL everywhere below, never through
+ * `STYLE_SECTION_HEADER`, so a typo in the constant fails here instead of
+ * silently redefining the contract.
+ */
+
+// Real catalog ids: every `get*PromptHint` returns "" on a miss, so a made-up
+// id would make most of these assertions vacuously pass.
+const STYLE = "anime" // look • film
+const COLOR_LOOK = "teal-orange" // look • film
+const ERA = "1920s-flapper" // look • film
+const CAMERA_FORMAT = "16mm-film" // look • film
+const SHOT_SIZE = "wide-shot" // look • scene
+const TIME_OF_DAY = "golden-hour" // look • scene
+const CAMERA_MOTION = "handheld" // motion • body
+const TRANSITION = "cross-dissolve" // motion • body
+
+const IMAGE = { surface: "image", mode: IMAGE_HINT_MODE_DEFAULT } as const
+const VIDEO = { surface: "video", mode: VIDEO_HINT_MODE_DEFAULT } as const
+
+describe("the section header", () => {
+  it("is exactly `[style]:`, lowercase", () => {
+    expect(STYLE_SECTION_HEADER).toBe("[style]:")
+  })
+})
+
+describe("FILM_STYLE_KEYS — the film/scene split lives in the registry", () => {
+  it("names the five film rows, in table order", () => {
+    expect(FILM_STYLE_KEYS).toEqual([
+      "cameraFormat",
+      "colorLook",
+      "style",
+      "era",
+      "cameraFormatId",
+    ])
+  })
+
+  it("derives from the table's own `styleGroup` column (no second list)", () => {
+    expect(FILM_STYLE_KEYS).toEqual(
+      DIRECTION_FIELDS.filter((f) => "styleGroup" in f && f.styleGroup === "film").map(
+        (f) => f.key,
+      ),
+    )
+  })
+
+  it("marks only LOOK rows as film (a motion row could never reach the section)", () => {
+    for (const spec of DIRECTION_FIELDS) {
+      if ("styleGroup" in spec && spec.styleGroup === "film") {
+        expect(spec.family, spec.key).toBe("look")
+      }
+    }
+  })
+})
+
+describe("partitionStyleClauses — which slot a clause lands in", () => {
+  it("sends the MOTION family to the body and the LOOK family to the section", () => {
+    const slots = new Map(
+      partitionStyleClauses(
+        { cameraMotion: CAMERA_MOTION, transition: TRANSITION, style: STYLE, shotSize: SHOT_SIZE },
+        VIDEO,
+      ).map((c) => [c.text, c.slot]),
+    )
+    expect(slots.get(getCameraMotionTerm(CAMERA_MOTION))).toBe("body")
+    expect(slots.get(getTransitionTerm(TRANSITION))).toBe("body")
+    expect(slots.get(getStylePromptHint(STYLE))).toBe("film")
+    expect(slots.get(getFramingPromptHint(SHOT_SIZE))).toBe("scene")
+  })
+
+  it("leaves the image surface with no body clause at all (no motion row folds there)", () => {
+    // The surface filter and the family split are deliberately aligned: every
+    // image-surface direction row is `look`, so an image `[style]` section
+    // carries the WHOLE direction fold and the body carries none of it.
+    expect(directionFieldsForSurface("image").every((f) => f.family === "look")).toBe(true)
+    const everyImageKey = Object.fromEntries(
+      directionFieldsForSurface("image").map((f) => [f.key, ""]),
+    )
+    expect(
+      partitionStyleClauses({ ...everyImageKey, style: STYLE, shotSize: SHOT_SIZE }, IMAGE).every(
+        (c) => c.slot !== "body",
+      ),
+    ).toBe(true)
+  })
+
+  it("keeps registry table order inside each slot", () => {
+    const direction = { style: STYLE, colorLook: COLOR_LOOK, shotSize: SHOT_SIZE, timeOfDay: TIME_OF_DAY }
+    expect(partitionStyleClauses(direction, IMAGE).map((c) => c.text)).toEqual(
+      renderDirectionHints(direction, IMAGE),
+    )
+  })
+
+  it("returns nothing for an absent, empty or unresolvable direction", () => {
+    expect(partitionStyleClauses(undefined, IMAGE)).toEqual([])
+    expect(partitionStyleClauses({}, IMAGE)).toEqual([])
+    expect(partitionStyleClauses({ style: "__no_such_id__" }, IMAGE)).toEqual([])
+  })
+})
+
+describe("renderStyleSection — the two lines", () => {
+  it("puts the film line first and the scene line second, each `. `-joined", () => {
+    expect(
+      renderStyleSection(
+        {
+          cameraFormat: CAMERA_FORMAT,
+          colorLook: COLOR_LOOK,
+          style: STYLE,
+          era: ERA,
+          shotSize: SHOT_SIZE,
+          timeOfDay: TIME_OF_DAY,
+        },
+        IMAGE,
+      ),
+    ).toBe(
+      "[style]:\n" +
+        [
+          getCameraFormatPromptHint(CAMERA_FORMAT),
+          getColorLookPromptHint(COLOR_LOOK),
+          getStylePromptHint(STYLE),
+          getEraPromptHint(ERA),
+        ].join(". ") +
+        "\n" +
+        [getFramingPromptHint(SHOT_SIZE), getLightingPromptHint(TIME_OF_DAY)].join(". "),
+    )
+  })
+
+  it("omits the film line entirely when no film dimension is selected", () => {
+    expect(renderStyleSection({ shotSize: SHOT_SIZE }, IMAGE)).toBe(
+      `[style]:\n${getFramingPromptHint(SHOT_SIZE)}`,
+    )
+  })
+
+  it("omits the scene line entirely when no other look dimension is selected", () => {
+    expect(renderStyleSection({ style: STYLE }, IMAGE)).toBe(
+      `[style]:\n${getStylePromptHint(STYLE)}`,
+    )
+  })
+
+  it("renders NOTHING when the fold carries no look clause", () => {
+    expect(renderStyleSection(undefined, VIDEO)).toBe("")
+    expect(renderStyleSection({}, VIDEO)).toBe("")
+    expect(renderStyleSection({ cameraMotion: CAMERA_MOTION, transition: TRANSITION }, VIDEO)).toBe("")
+  })
+
+  it("never indents a line and never ends with a newline", () => {
+    // The video reference resolver collapses 2+ HORIZONTAL spaces unanchored,
+    // so an indented section line would come back flattened — the section is
+    // written flush-left instead of relying on the collapse leaving it alone.
+    const section = renderStyleSection(
+      { style: STYLE, colorLook: COLOR_LOOK, shotSize: SHOT_SIZE },
+      IMAGE,
+    )
+    for (const line of section.split("\n")) expect(line).toBe(line.trimStart())
+    expect(section.endsWith("\n")).toBe(false)
+    expect(section).not.toMatch(/[^\S\r\n]{2,}/)
+  })
+
+  it("agrees with the clause-level renderer the composers use", () => {
+    const direction = { style: STYLE, shotSize: SHOT_SIZE }
+    expect(renderStyleSection(direction, VIDEO)).toBe(
+      styleSectionFromClauses(partitionStyleClauses(direction, VIDEO)),
+    )
+  })
+})
+
+describe("composeSectionedPrompt — body, gap, section", () => {
+  const FILM = getStylePromptHint(STYLE)
+  const SCENE = getFramingPromptHint(SHOT_SIZE)
+  const clauses = [
+    { text: "a knight rides", slot: "body" },
+    { text: FILM, slot: "film" },
+    { text: SCENE, slot: "scene" },
+  ] as const
+
+  it("joins body clauses with `. ` and hangs the section off a blank line", () => {
+    expect(composeSectionedPrompt("at dusk", clauses, "")).toBe(
+      `at dusk. a knight rides\n\n[style]:\n${FILM}\n${SCENE}`,
+    )
+  })
+
+  it("keeps the structured fragment last IN THE BODY, ahead of the section", () => {
+    expect(composeSectionedPrompt("at dusk", clauses, "Subject: a knight.")).toBe(
+      `at dusk. a knight rides. Subject: a knight.\n\n[style]:\n${FILM}\n${SCENE}`,
+    )
+  })
+
+  it("emits NO header and no extra newline when nothing reaches the section", () => {
+    // Byte-identical to the plain hint join — this is what keeps every
+    // look-free caller (and every fully-shed one) exactly where it was.
+    const bodyOnly = [{ text: "a knight rides", slot: "body" }] as const
+    expect(composeSectionedPrompt("at dusk", bodyOnly, "")).toBe(
+      joinPromptHints("at dusk", ["a knight rides"]),
+    )
+    expect(composeSectionedPrompt("at dusk", bodyOnly, "")).not.toContain("[style]")
+  })
+
+  it("returns the prompt VERBATIM AND UNTRIMMED with no clause and no fragment", () => {
+    expect(composeSectionedPrompt("  a knight \n", [], "")).toBe("  a knight \n")
+    expect(composeSectionedPrompt(undefined, [], "")).toBeUndefined()
+  })
+
+  it("TRIMS the prompt when the section is the only thing folded", () => {
+    // The section counts as "something folded", so the body is trimmed exactly
+    // as the hint-join branch trims it — otherwise the blank line would inherit
+    // the prompt's trailing whitespace.
+    expect(composeSectionedPrompt("  a knight \n", [{ text: FILM, slot: "film" }], "")).toBe(
+      `a knight\n\n[style]:\n${FILM}`,
+    )
+  })
+
+  it("drops the gap for a blank or absent prompt (never a leading newline)", () => {
+    const only = [{ text: FILM, slot: "film" }] as const
+    expect(composeSectionedPrompt("", only, "")).toBe(`[style]:\n${FILM}`)
+    expect(composeSectionedPrompt("   ", only, "")).toBe(`[style]:\n${FILM}`)
+    expect(composeSectionedPrompt(undefined, only, "")).toBe(`[style]:\n${FILM}`)
+  })
+
+  it("never ends the composed prompt with a newline", () => {
+    for (const prompt of ["a knight", "", undefined]) {
+      expect(composeSectionedPrompt(prompt, clauses, "Subject: a knight.")!.endsWith("\n")).toBe(
+        false,
+      )
+    }
+  })
+
+  it("marks every subject clause as body", () => {
+    expect(asBodyClauses(["a woman in her 30s", "wearing a red coat"])).toEqual([
+      { text: "a woman in her 30s", slot: "body" },
+      { text: "wearing a red coat", slot: "body" },
+    ])
+  })
+})
+
+describe("sectionedClauseCosts — what each clause really costs", () => {
+  const clauses = [
+    { text: "a knight rides", slot: "body" },
+    { text: getStylePromptHint(STYLE), slot: "film" },
+    { text: getFramingPromptHint(SHOT_SIZE), slot: "scene" },
+  ] as const
+
+  it("is the exact composed-length delta of each clause, tail-first", () => {
+    const costs = sectionedClauseCosts("at dusk", clauses, "")
+    expect(costs).toHaveLength(clauses.length)
+    for (let kept = 0; kept < clauses.length; kept++) {
+      const below = composeSectionedPrompt("at dusk", clauses.slice(0, kept), "")?.length ?? 0
+      const at = composeSectionedPrompt("at dusk", clauses.slice(0, kept + 1), "")?.length ?? 0
+      expect(costs[kept]).toBe(at - below)
+    }
+  })
+
+  it("charges the LAST surviving look clause for the header it keeps alive", () => {
+    // "\n\n[style]:\n" is 11 characters that only come back when the section
+    // disappears entirely — so the first look clause carries them, and a shed
+    // that drops it reclaims more than the clause's own text.
+    const costs = sectionedClauseCosts("at dusk", clauses, "")
+    expect(costs[1]).toBe(getStylePromptHint(STYLE).length + "\n\n[style]:\n".length)
+    // The second look clause only brings its own line separator.
+    expect(costs[2]).toBe(getFramingPromptHint(SHOT_SIZE).length + "\n".length)
+    // A body clause brings the ". " it was joined with.
+    expect(costs[0]).toBe("a knight rides".length + ". ".length)
+  })
+})
+
+describe("the section boundary — what a later assembler may append", () => {
+  const FILM = getStylePromptHint(STYLE)
+  const clauses = [{ text: FILM, slot: "film" }] as const
+  const composed = composeSectionedPrompt("a knight", clauses, "")!
+  const bodyless = composeSectionedPrompt("", clauses, "")!
+
+  it("splits a composed prompt into its body and its section", () => {
+    expect(splitStyleSection(composed)).toEqual({ body: "a knight", section: `[style]:\n${FILM}` })
+  })
+
+  it("splits the body-less form, where the section IS the prompt", () => {
+    expect(splitStyleSection(bodyless)).toEqual({ body: "", section: `[style]:\n${FILM}` })
+  })
+
+  it("reports no section for a prompt that carries none", () => {
+    expect(splitStyleSection("a knight")).toEqual({ body: "a knight", section: "" })
+  })
+
+  it("inserts body lines AHEAD of the section, keeping the look clauses last", () => {
+    expect(insertBeforeStyleSection(composed, ["the person from reference image A"])).toBe(
+      `a knight\nthe person from reference image A\n\n[style]:\n${FILM}`,
+    )
+    expect(insertBeforeStyleSection(bodyless, ["the person from reference image A"])).toBe(
+      `the person from reference image A\n\n[style]:\n${FILM}`,
+    )
+  })
+
+  it("is the plain `\\n` join with no section — the byte-parity path", () => {
+    // What every appender emitted before the section existed, including the
+    // leading newline an empty prompt produces. Anything else would move bytes
+    // on the look-free runs, which are most of them.
+    expect(insertBeforeStyleSection("a knight", ["a", "b"])).toBe("a knight\na\nb")
+    expect(insertBeforeStyleSection("", ["a"])).toBe("\na")
+  })
+
+  it("is a no-op with no lines to add", () => {
+    expect(insertBeforeStyleSection(composed, [])).toBe(composed)
+  })
+
+  it("knows when a prompt ends INSIDE the section", () => {
+    expect(endsInsideStyleSection(composed)).toBe(true)
+    expect(endsInsideStyleSection(bodyless)).toBe(true)
+    // A blank line closes the header's scope, and the next appender sees it.
+    expect(endsInsideStyleSection(`${composed}\n\nStyle: cinematic`)).toBe(false)
+    expect(endsInsideStyleSection("a knight")).toBe(false)
+    expect(endsInsideStyleSection("")).toBe(false)
+  })
+})

package/src/__tests__/style-section-boundary.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect } from "vitest"
+import { applyVideoNegativePrompt, getMaxImagePromptChars } from "@nodaro/shared"
+import type { CharacterDef, ConnectedReference } from "@nodaro/shared"
+import { buildImagePrompt } from "../prompt-builder.js"
+import { assembleImageInput } from "../assemble-image-input.js"
+import { composeVideoPromptText } from "../assemble-video-input.js"
+import { resolveVideoReferenceCore } from "../video-reference-resolver.js"
+import { getStylePromptHint } from "../style.js"
+
+/**
+ * WHERE THE `[style]` SECTION ENDS. The section has no terminator and every
+ * assembler downstream of the composer appends to the string it returns — the
+ * reference resolvers' role phrases and element directives, the legacy
+ * character descriptions, `Style:` and `Avoid:`. Line-joined onto a prompt that
+ * ENDS with the section, each of them reads as one more look clause under the
+ * header, which is exactly the confusion the section exists to remove.
+ *
+ * Two shapes keep them out, one per kind of text:
+ *  - BODY content — a reference binding, an element directive, a character
+ *    description — is SPLICED in ahead of the section, where the prose it
+ *    belongs with already is. The look tail stays last, which is where it was
+ *    measured to be free.
+ *  - The self-labeling control lines (`Style:` / `Avoid:`) stay at the end and
+ *    close the header's scope with a blank line instead.
+ *
+ * Assertions read the header as a LITERAL and the clause wording through the
+ * catalogs, so this suite pins the BOUNDARY, not the catalog copy.
+ */
+
+/** The `\n\n`-delimited block the `[style]:` header opens — every line the
+ *  model reads as a look clause. `""` when the prompt carries no section. */
+const styleBlockOf = (prompt: string): string =>
+  prompt.split("\n\n").find((b) => b.startsWith("[style]:")) ?? ""
+
+const LIBRARY: ConnectedReference = {
+  id: "l", defaultName: "Old Library", source: "wired-location",
+  url: "https://cdn/library.png", locationSlug: "old-library",
+}
+
+const KIRA: ConnectedReference = {
+  id: "kira", defaultName: "Kira", source: "wired-character",
+  url: "https://cdn/kira.png", characterSlug: "kira",
+  characterCanonicalDescription: "a young woman with copper hair",
+  variantSlug: undefined, variantDescription: null, variantDisplayName: "canonical",
+}
+
+const KIRA_DEF: CharacterDef = {
+  id: "kira", name: "Kira", type: "description", category: "character",
+  description: "auburn hair, hazel eyes",
+}
+
+/** Look on both lines: `style` is a film clause, `shotSize` a scene clause. */
+const DIRECTION = { style: "anime", shotSize: "wide-shot" } as const
+
+/** What the inline `style` text renders as in the `Style:` control line. */
+const CINEMATIC = getStylePromptHint("cinematic")
+
+/** The trailing role phrase a canonical (unmentioned) wired location renders. */
+const LOCATION_PHRASE = "the location from reference image A"
+/** The video twin, bound to the resolver's `@image_N` shape. */
+const CHARACTER_PHRASE = "the person from @image_1"
+
+describe("image assembly — nothing lands under the `[style]` header", () => {
+  const hybrid = assembleImageInput({
+    userPrompt: "a man walks",
+    provider: "nano-banana",
+    direction: DIRECTION,
+    connectedReferences: [LIBRARY],
+    referenceFormat: "hybrid",
+    style: "cinematic",
+    negativePrompt: "blurry",
+  }).prompt
+
+  it("splices the reference binding into the body, ahead of the section", () => {
+    // Non-vacuity: the section really is there, carrying both look lines.
+    expect(styleBlockOf(hybrid)).toContain("[style]:\n")
+    expect(styleBlockOf(hybrid)).toContain("wide shot")
+
+    expect(styleBlockOf(hybrid)).not.toContain(LOCATION_PHRASE)
+    expect(hybrid.indexOf(LOCATION_PHRASE)).toBeGreaterThan(-1)
+    expect(hybrid.indexOf(LOCATION_PHRASE)).toBeLessThan(hybrid.indexOf("[style]:"))
+  })
+
+  it("closes the section with a blank line before `Style:` / `Avoid:`", () => {
+    expect(styleBlockOf(hybrid)).not.toContain("Style:")
+    expect(styleBlockOf(hybrid)).not.toContain("Avoid:")
+    // The control lines stay together at the very end, one block of their own:
+    // the blank line is `Style:`'s to add, and `Avoid:` sees a closed section.
+    expect(hybrid.endsWith(`\n\nStyle: ${CINEMATIC}\nAvoid: blurry`)).toBe(true)
+  })
+
+  it("splices the LEGACY character description into the body too", () => {
+    const legacy = assembleImageInput({
+      userPrompt: "a man walks",
+      provider: "nano-banana",
+      direction: DIRECTION,
+      characterDefs: [KIRA_DEF],
+    }).prompt
+    const desc = "Include character 'Kira': auburn hair, hazel eyes."
+    expect(legacy).toContain(desc)
+    expect(styleBlockOf(legacy)).not.toContain(desc)
+    expect(legacy.indexOf(desc)).toBeLessThan(legacy.indexOf("[style]:"))
+  })
+
+  it("honors a user-overridden wrapper template while keeping the section last", () => {
+    const legacy = assembleImageInput({
+      userPrompt: "a man walks",
+      provider: "nano-banana",
+      direction: DIRECTION,
+      characterDefs: [KIRA_DEF],
+      userTemplates: { "generate-image-wrapper": "{assetDescriptions} // {userPrompt}" },
+    }).prompt
+    expect(legacy.startsWith("Include character 'Kira': auburn hair, hazel eyes. // a man walks")).toBe(true)
+    expect(styleBlockOf(legacy)).not.toContain("Kira")
+  })
+
+  it("re-derives the separator after the cap's tail cut, within the reservation", () => {
+    // The control lines are reserved BEFORE the cut and rendered AFTER it, and
+    // the cut moves the boundary they read. Both directions, one cap:
+    const cap = getMaxImagePromptChars("seedream")
+    const cut = (prompt: string) =>
+      buildImagePrompt({ prompt, provider: "seedream", style: "cinematic", negativePrompt: "blurry" }).prompt
+    const tail = `\nStyle: ${CINEMATIC}\nAvoid: blurry`
+
+    // (a) a short section, cut away entirely → the separator narrows to `\n`.
+    const shortSection = cut(`${"a man walks. ".repeat(400)}\n\n[style]:\nanime style`)
+    expect(shortSection.length).toBeLessThanOrEqual(cap)
+    expect(shortSection.endsWith(`...${tail}`)).toBe(true)
+
+    // (b) a section longer than the reservation, so the cut lands INSIDE it →
+    // the separator stays a blank line, exactly what was reserved.
+    const look = "anime style, ".repeat(24)
+    const longSection = cut(`${"x".repeat(cap - look.length - 60)}\n\n[style]:\n${look}`)
+    expect(longSection.length).toBeLessThanOrEqual(cap)
+    expect(longSection.endsWith(`...\n${tail}`)).toBe(true)
+  })
+
+  it("keeps the no-section shapes byte-identical (the append fallback)", () => {
+    const noSection = assembleImageInput({
+      userPrompt: "a man walks",
+      provider: "nano-banana",
+      connectedReferences: [LIBRARY],
+      referenceFormat: "hybrid",
+      style: "cinematic",
+      negativePrompt: "blurry",
+    }).prompt
+    expect(noSection).toBe(
+      `A man walks\n${LOCATION_PHRASE}\nStyle: ${CINEMATIC}\nAvoid: blurry`,
+    )
+  })
+})
+
+describe("video assembly — nothing lands under the `[style]` header", () => {
+  const body = composeVideoPromptText("a knight rides", DIRECTION)
+  const framed = resolveVideoReferenceCore({
+    prompt: body,
+    wiredCharRefs: [KIRA],
+    hybridRoles: true,
+  }).prompt!
+
+  it("splices the resolver's role phrase ahead of the section, which ends the prompt", () => {
+    expect(styleBlockOf(framed)).toContain("[style]:\n")
+    expect(styleBlockOf(framed)).not.toContain(CHARACTER_PHRASE)
+    expect(framed.indexOf(CHARACTER_PHRASE)).toBeLessThan(framed.indexOf("[style]:"))
+    // The look tail really is the tail: nothing follows the section.
+    expect(framed.endsWith(styleBlockOf(framed))).toBe(true)
+  })
+
+  it("closes the section with a blank line before the folded `Avoid:`", () => {
+    const withNeg = applyVideoNegativePrompt(framed, "blurry, watermark", "seedance-2").prompt!
+    expect(styleBlockOf(withNeg)).not.toContain("Avoid:")
+    expect(withNeg.endsWith("\n\nAvoid: blurry, watermark")).toBe(true)
+  })
+
+  it("keeps the sectionless `Avoid:` join byte-identical", () => {
+    const plain = applyVideoNegativePrompt("a knight rides", "blurry", "seedance-2").prompt
+    expect(plain).toBe("a knight rides\nAvoid: blurry")
+  })
+})

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

@@ -15,6 +15,7 @@ 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 { renderStyleSection } from "../prompt-style-section.js"
 import {
   renderSubjectHints,
   SUBJECT_IMAGE_HINT_MODE_DEFAULT,
@@ -95,12 +96,15 @@ describe("the no-subject oracle — the fold is dark until a caller opts in", ()
   })
 
   it("matches an independent recomputation of the direction-only fold", () => {
+    // Every image-surface direction row is `look`, so a direction-only fold
+    // adds NOTHING to the body: the prompt is trimmed (something folded) and
+    // the whole fold reads in the section.
     const userPrompt = "a knight on a hill"
     const expected = buildImagePrompt({
-      prompt: joinPromptHints(
-        userPrompt,
-        renderDirectionHints(DIRECTION, { surface: "image", mode: IMAGE_HINT_MODE_DEFAULT }),
-      ),
+      prompt: `${userPrompt}\n\n${renderStyleSection(DIRECTION, {
+        surface: "image",
+        mode: IMAGE_HINT_MODE_DEFAULT,
+      })}`,
       provider: "nano-banana",
     })
     expect(assembleImageInput({ userPrompt, provider: "nano-banana", direction: DIRECTION })).toEqual(
@@ -121,7 +125,7 @@ describe("the no-subject oracle — the fold is dark until a caller opts in", ()
 })
 
 describe("the subject fold — position and content", () => {
-  it("lands the subject clauses AHEAD of the direction clauses", () => {
+  it("lands the subject clauses in the BODY, ahead of the direction section", () => {
     const userPrompt = "on the seawall"
     const subjectHints = renderSubjectHints(SUBJECT, {
       surface: "image",
@@ -137,9 +141,14 @@ describe("the subject fold — position and content", () => {
       subject: SUBJECT,
       direction: DIRECTION,
     })
+    // The subject is the noun phrase the look modifies, so it stays inline with
+    // the prose; the direction fold lifts out behind it.
     expect(result.prompt).toBe(
       buildImagePrompt({
-        prompt: joinPromptHints(userPrompt, [...subjectHints, ...directionHints]),
+        prompt: `${joinPromptHints(userPrompt, subjectHints)}\n\n${renderStyleSection(DIRECTION, {
+          surface: "image",
+          mode: IMAGE_HINT_MODE_DEFAULT,
+        })}`,
         provider: "nano-banana",
       }).prompt,
     )
@@ -161,16 +170,19 @@ describe("the subject fold — position and content", () => {
     expect(sentences[1]).toContain(", ")
   })
 
-  it("folds the subject on the video surface, compact, ahead of direction", () => {
+  it("folds the subject on the video surface, compact, in the body", () => {
     const composed = composeVideoPromptText("she walks", DIRECTION, undefined, { subject: SUBJECT })
     expect(composed).toBe(
-      joinPromptHints("she walks", [
-        ...renderSubjectHints(SUBJECT, {
+      `${joinPromptHints(
+        "she walks",
+        renderSubjectHints(SUBJECT, {
           surface: "video",
           mode: SUBJECT_VIDEO_HINT_MODE_DEFAULT,
         }),
-        ...renderDirectionHints(DIRECTION, { surface: "video", mode: VIDEO_HINT_MODE_DEFAULT }),
-      ]),
+      )}\n\n${renderStyleSection(DIRECTION, {
+        surface: "video",
+        mode: VIDEO_HINT_MODE_DEFAULT,
+      })}`,
     )
   })
 
@@ -212,9 +224,16 @@ describe("the subject fold — under the provider cap", () => {
       surface: "image",
       mode: IMAGE_HINT_MODE_DEFAULT,
     })
-    // Non-vacuity: the un-shed fold really does overflow.
+    // Non-vacuity: the un-shed fold really does overflow. Measured through a
+    // high-cap provider so the oracle is the assembler's own composition, not a
+    // hand-rebuilt approximation of it.
     expect(
-      joinPromptHints(PROSE, [...subjectHints, ...directionHints]).length,
+      assembleImageInput({
+        userPrompt: PROSE,
+        provider: "nano-banana-pro",
+        subject: SUBJECT,
+        direction: BIG_DIRECTION,
+      }).prompt.length,
     ).toBeGreaterThan(SEEDREAM_CAP)
 
     const result = assembleImageInput({