@nodaro/prompts 1.11.0 → 1.13.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__/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)
+  })
+})