@nodaro/prompts 1.12.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -20,7 +20,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nodaro/shared": "^2.17.0"
+    "@nodaro/shared": "^2.19.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

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

@@ -2,7 +2,7 @@ import { describe, it, expect } from "vitest"
 import { assembleImageInput } from "../assemble-image-input.js"
 import { buildImagePrompt, buildImagePromptWithOverflow } from "../prompt-builder.js"
 import { renderDirectionHints, IMAGE_HINT_MODE_DEFAULT } from "../direction-registry.js"
-import { joinPromptHints } from "../prompt-hint-join.js"
+import { renderStyleSection } from "../prompt-style-section.js"
 import { getMaxImagePromptChars } from "@nodaro/shared"
 import type { ConnectedReference } from "@nodaro/shared"
 
@@ -14,11 +14,15 @@ import type { ConnectedReference } from "@nodaro/shared"
  * TRULY maximal image-surface `direction` renders ~3.3K characters of clauses —
  * the broad-but-not-maximal fold below renders ~1.2K, which is already enough
  * to push the assembled prompt past a low-cap provider (seedream = 3000).
- * `buildImagePrompt` then cuts the TAIL — and in the hybrid reference
- * format the trailing canonical role phrase ("the location from reference image
- * B") sits AFTER the folded hints, so the cut severs a REFERENCE BINDING while
- * decorative hint clauses survive. The assembler knows which clauses are hints
- * (it just rendered them), so it drops them last-folded-first and re-assembles.
+ * `buildImagePrompt` then cuts the TAIL, order-blind and mid-word.
+ *
+ * WHAT THE CUT REACHES FIRST is the `[style]` section: the hybrid role phrases
+ * splice into the BODY ahead of it (`insertBeforeStyleSection`), so the
+ * casualty is a look clause the user picked, severed halfway through, rather
+ * than a whole clause dropped cleanly. The assembler knows which clauses are
+ * hints (it just rendered them), so it drops them last-folded-first and
+ * re-assembles. A larger fold walks the same cut back into the bindings and the
+ * prose, which is what the shed keeps out of reach entirely.
  */
 
 // A broad but ordinary image direction — the kind a "set every picker" UI
@@ -45,6 +49,18 @@ const IMAGE_HINTS = renderDirectionHints(DIRECTION, {
   mode: IMAGE_HINT_MODE_DEFAULT,
 })
 
+/**
+ * The UNSHED body for a prompt — the oracle for "what the assembler composes
+ * before any cap thinking". Every image-surface direction row is `look`, so the
+ * whole fold lands in the `[style]` section and the body is the prose alone,
+ * trimmed (something folded).
+ */
+const unshedBody = (prompt: string): string =>
+  `${prompt.trim()}\n\n${renderStyleSection(DIRECTION, {
+    surface: "image",
+    mode: IMAGE_HINT_MODE_DEFAULT,
+  })}`
+
 /** The mentioned character — its directive is the FIRST binding in the prompt. */
 const KIRA: ConnectedReference = {
   id: "kira-id",
@@ -58,8 +74,8 @@ const KIRA: ConnectedReference = {
   variantDisplayName: "canonical",
 }
 
-/** An UNMENTIONED wired location — hybrid renders its role phrase at the very
- *  END of the prompt, behind every folded hint. The order-blind casualty. */
+/** An UNMENTIONED wired location — hybrid renders its role phrase as the last
+ *  line of the BODY, just ahead of the `[style]` section. */
 const PIER: ConnectedReference = {
   id: "pier-id",
   defaultName: "Pier",
@@ -70,9 +86,15 @@ const PIER: ConnectedReference = {
 
 /** The mention-resolved character binding, in the middle of the prose. */
 const CHARACTER_BINDING = "the person from reference image A"
-/** The binding the tail cut destroys when nothing sheds the hints first. */
+/** The binding the tail cut used to destroy when nothing shed the hints first. */
 const LOCATION_BINDING = "the location from reference image B"
 
+/** The whole look section, unshed — what an order-blind cut severs first. */
+const FULL_SECTION = renderStyleSection(DIRECTION, {
+  surface: "image",
+  mode: IMAGE_HINT_MODE_DEFAULT,
+})
+
 /** Prose long enough that prose + directives + the full fold clears 3000. */
 const PROSE = "@kira:1 walks the seawall at dusk. " + "The waves are loud. ".repeat(90)
 
@@ -93,14 +115,16 @@ describe("assembleImageInput — cap-aware hint shedding", () => {
     // ever shrinks enough that this no longer truncates, the scenario below is
     // vacuous and this assertion says so loudly.
     const naive = buildImagePrompt({
-      prompt: joinPromptHints(PROSE, IMAGE_HINTS),
+      prompt: unshedBody(PROSE),
       provider: "seedream",
       connectedReferences: [KIRA, PIER],
       referenceFormat: "hybrid",
     })
     expect(naive.prompt.endsWith("...")).toBe(true)
-    // …and what it cut was the reference binding, not the decorative tail.
-    expect(naive.prompt).not.toContain(LOCATION_BINDING)
+    // …and what it cut was the look section, mid-clause — the binding spliced
+    // into the body ahead of it and survives the cut it used to die to.
+    expect(naive.prompt).toContain(LOCATION_BINDING)
+    expect(naive.prompt).not.toContain(FULL_SECTION)
   })
 
   it("keeps every reference binding and the full prose, dropping trailing hints", () => {
@@ -154,7 +178,7 @@ describe("assembleImageInput — under-cap byte parity", () => {
   for (const { name, provider, prompt } of parityCases) {
     it(`is byte-identical to the unordered fold — ${name}`, () => {
       const expected = buildImagePrompt({
-        prompt: joinPromptHints(prompt, IMAGE_HINTS),
+        prompt: unshedBody(prompt),
         provider,
         connectedReferences: [KIRA, PIER],
         referenceFormat: "hybrid",

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

@@ -49,7 +49,9 @@ describe("assembleImageInput — id-based composition (Studio oracle)", () => {
       connectedReferences: [ref],
       direction: { framingId: "medium-shot" },
     })
-    expect(result.prompt).toBe(`a knight. ${getFramingPromptHint("medium-shot")}`)
+    expect(result.prompt).toBe(
+      `a knight\n\n[style]:\n${getFramingPromptHint("medium-shot")}`,
+    )
     expect(result.referenceImageUrls).toEqual(["https://r2.example/hero.png"])
   })
 
@@ -59,8 +61,10 @@ describe("assembleImageInput — id-based composition (Studio oracle)", () => {
       provider: REF_PROVIDER,
       direction: { framingId: "medium-shot", framingAngleId: "low-angle" },
     })
+    // Two scene-line clauses share one line, `. `-joined.
     expect(result.prompt).toBe(
-      `a knight. ${getFramingPromptHint("medium-shot")}. ${getFramingPromptHint("low-angle")}`,
+      `a knight\n\n[style]:\n` +
+        `${getFramingPromptHint("medium-shot")}. ${getFramingPromptHint("low-angle")}`,
     )
   })
 
@@ -120,7 +124,7 @@ describe("assembleImageInput — id-based composition (Studio oracle)", () => {
       provider: REF_PROVIDER,
       direction: { style: "anime" },
     })
-    expect(result.prompt).toBe(`a knight. ${getStylePromptHint("anime")}`)
+    expect(result.prompt).toBe(`a knight\n\n[style]:\n${getStylePromptHint("anime")}`)
   })
 
   it("blends a multi-pick dimension into ONE clause", () => {
@@ -131,21 +135,37 @@ describe("assembleImageInput — id-based composition (Studio oracle)", () => {
       provider: REF_PROVIDER,
       direction: { mood: ["happy", "joyful"] },
     })
-    expect(result.prompt).toBe(`a knight. ${blended[0]}`)
+    expect(result.prompt).toBe(`a knight\n\n[style]:\n${blended[0]}`)
   })
 
-  it("folds in TABLE order, not the caller's object-literal order", () => {
+  it("groups before it orders: the film line leads the scene line", () => {
+    // `shotSize` folds at row 2 and `style` at row 22, so table order alone
+    // would read the framing clause first; the section's two lines outrank it.
     const result = assembleImageInput({
       userPrompt: "a knight",
       provider: REF_PROVIDER,
       direction: { style: "anime", shotSize: "wide-shot" },
     })
     expect(result.prompt).toBe(
-      `a knight. ${getFramingPromptHint("wide-shot")}. ${getStylePromptHint("anime")}`,
+      `a knight\n\n[style]:\n` +
+        `${getStylePromptHint("anime")}\n${getFramingPromptHint("wide-shot")}`,
     )
   })
 
-  it("keeps the five pre-registry keys byte-identical to the old inlined fold", () => {
+  it("folds in TABLE order within a line, not the caller's object-literal order", () => {
+    // `shotSize` (row 2) precedes `timeOfDay` (row 14) on the scene line.
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      direction: { timeOfDay: "golden-hour", shotSize: "wide-shot" },
+    })
+    expect(result.prompt).toBe(
+      `a knight\n\n[style]:\n` +
+        `${getFramingPromptHint("wide-shot")}. ${getLightingPromptHint("golden-hour")}`,
+    )
+  })
+
+  it("splits the five pre-registry keys across the section's two lines", () => {
     const direction = {
       framingId: "wide-shot",
       framingAngleId: "low-angle",
@@ -158,21 +178,21 @@ describe("assembleImageInput — id-based composition (Studio oracle)", () => {
       provider: REF_PROVIDER,
       direction,
     })
-    // The exact string the pre-registry `composePromptText` produced: the same
-    // five clauses, in the same order, joined with the same ". ".
+    // `cameraFormatId` is the one film row in the legacy block; the other four
+    // fall to the scene line, in the same relative order they always folded in.
     expect(result.prompt).toBe(
-      [
-        "a knight",
-        getFramingPromptHint("wide-shot"),
-        getFramingPromptHint("low-angle"),
-        getLightingPromptHint("golden-hour"),
-        getLensPromptHint("wide-24mm"),
-        getCameraFormatPromptHint("16mm-film"),
-      ].join(". "),
+      "a knight\n\n[style]:\n" +
+        `${getCameraFormatPromptHint("16mm-film")}\n` +
+        [
+          getFramingPromptHint("wide-shot"),
+          getFramingPromptHint("low-angle"),
+          getLightingPromptHint("golden-hour"),
+          getLensPromptHint("wide-24mm"),
+        ].join(". "),
     )
   })
 
-  it("keeps the structured fragment LAST, after every direction clause", () => {
+  it("keeps the structured fragment LAST IN THE BODY, ahead of the section", () => {
     const result = assembleImageInput({
       userPrompt: "a portrait",
       provider: REF_PROVIDER,
@@ -180,8 +200,69 @@ describe("assembleImageInput — id-based composition (Studio oracle)", () => {
       structured: { person: { age: 30, gender: "woman", expression: "calm" } },
     })
     expect(result.prompt).toBe(
-      `a portrait. ${getStylePromptHint("anime")}. Subject: 30 years old, woman, calm expression.`,
+      "a portrait. Subject: 30 years old, woman, calm expression." +
+        `\n\n[style]:\n${getStylePromptHint("anime")}`,
+    )
+  })
+
+  it("emits no section on the image surface only when nothing look-family folds", () => {
+    // Every image-surface direction row is `look` (the registry has no
+    // image-surface motion row), so a direction that renders ANY clause always
+    // opens a section — and a structured-only fold never does.
+    expect(
+      assembleImageInput({
+        userPrompt: "a portrait",
+        provider: REF_PROVIDER,
+        structured: { person: { age: 30 } },
+      }).prompt,
+    ).not.toContain("[style]")
+    expect(
+      assembleImageInput({
+        userPrompt: "a portrait",
+        provider: REF_PROVIDER,
+        direction: { isoValue: "iso-100" },
+      }).prompt,
+    ).toContain("[style]:\n")
+  })
+})
+
+/**
+ * THE HYBRID LINE-CAPITALIZER. On the hybrid reference format with connected
+ * references and NO converged `@`-mention, `buildHybridScene` capitalizes the
+ * first alphabetic character of EVERY line of the body. Run over the section
+ * that would rewrite the header to `[Style]:` and give every catalog clause a
+ * capital it was not written with — so the capitalizer stops at the header.
+ */
+describe("assembleImageInput — the hybrid capitalizer stops at the section", () => {
+  // A plain wired image: no mention to converge and no canonical role phrase to
+  // render, which is what leaves the body UNCONVERGED — the only path where the
+  // capitalizer runs at all. (A wired CHARACTER converges via its canonical
+  // phrase and skips the capitalizer entirely.)
+  const plate: ConnectedReference = {
+    id: "plate-id",
+    defaultName: "Plate",
+    source: "wired-image",
+    url: "https://r2.example/plate.png",
+  }
+
+  const hybridInput = {
+    userPrompt: "a knight on a hill",
+    provider: REF_PROVIDER,
+    connectedReferences: [plate],
+    referenceFormat: "hybrid" as const,
+    direction: { style: "anime", shotSize: "wide-shot" },
+  }
+
+  it("capitalizes the body line (non-vacuity: the capitalizer really runs here)", () => {
+    expect(assembleImageInput(hybridInput).prompt).toContain("A knight on a hill")
+  })
+
+  it("leaves the header and every clause line byte-intact", () => {
+    const result = assembleImageInput(hybridInput)
+    expect(result.prompt).toContain(
+      `[style]:\n${getStylePromptHint("anime")}\n${getFramingPromptHint("wide-shot")}`,
     )
+    expect(result.prompt).not.toContain("[Style]")
   })
 })
 

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

@@ -4,6 +4,11 @@ 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 {
+  composeSectionedPrompt,
+  partitionStyleClauses,
+  renderStyleSection,
+} from "../prompt-style-section.js"
 import { joinPromptHints } from "../prompt-hint-join.js"
 import { getMaxVideoPromptChars } from "@nodaro/shared"
 import type { ConnectedReference } from "@nodaro/shared"
@@ -15,12 +20,13 @@ import type { ConnectedReference } from "@nodaro/shared"
  * `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.
+ * BEFORE `resolveVideoReferenceCore`, and the resolver then ADDS binding text —
+ * lock lines ahead of the body, role phrases spliced in at the end of it, just
+ * before the `[style]` section. None of it is sheddable and all of it counts
+ * against the ceiling, 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.
@@ -47,6 +53,15 @@ const VIDEO_HINTS = renderDirectionHints(DIRECTION, {
   mode: VIDEO_HINT_MODE_DEFAULT,
 })
 
+/** The same clauses, slotted — the shed keeps a PREFIX of exactly this list. */
+const DIRECTION_CLAUSES = partitionStyleClauses(DIRECTION, {
+  surface: "video",
+  mode: VIDEO_HINT_MODE_DEFAULT,
+})
+
+/** Everything before the `[style]` section — the half the shed budget grows. */
+const bodyOf = (composed: string): string => composed.split("\n\n[style]:\n")[0]!
+
 /** The mentioned character — hybrid replaces the mention INLINE, mid-prose. */
 const KIRA: ConnectedReference = {
   id: "kira-id",
@@ -93,9 +108,16 @@ const frame = (body: string | undefined): string | undefined =>
 
 /** The binding that lands inline, inside the prose. */
 const MENTION_BINDING = "@image_1"
-/** Ray is unmentioned → his canonical-fallback phrase is APPENDED, last. */
+/** Ray is unmentioned → his canonical-fallback phrase ends the BODY, spliced in
+ *  ahead of the `[style]` section. */
 const TRAILING_BINDING = "@image_2"
 
+/** The whole look section, unshed — what an order-blind cut severs first. */
+const FULL_SECTION = renderStyleSection(DIRECTION, {
+  surface: "video",
+  mode: VIDEO_HINT_MODE_DEFAULT,
+})
+
 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
@@ -104,9 +126,11 @@ describe("composeVideoPromptText — cap-aware hint shedding", () => {
     // 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)
+    // …and what a tail cut at the cap would destroy is the look section,
+    // mid-clause: the role phrase splices into the body ahead of it and clears
+    // the cut, so the shed's job is to drop whole clauses instead.
+    expect(naive.slice(0, KLING_CAP)).toContain(TRAILING_BINDING)
+    expect(naive.slice(0, KLING_CAP)).not.toContain(FULL_SECTION)
   })
 
   it("keeps every binding and the full prose, dropping trailing hints", () => {
@@ -148,6 +172,53 @@ describe("composeVideoPromptText — cap-aware hint shedding", () => {
     const starved = composeVideoPromptText(PROSE, DIRECTION, undefined, { cap: 10, frame })
     expect(starved).toBe(PROSE)
     for (const hint of VIDEO_HINTS) expect(starved).not.toContain(hint)
+    // A FULL shed takes the header with it — byte-identical to the prompt, not
+    // an empty section hanging off it. This is what keeps the routes'
+    // `composed !== prompt` guard reading false when nothing survived.
+    expect(starved).not.toContain("[style]")
+  })
+
+  it("survives the reference resolver byte-intact", () => {
+    // The resolver is why the section is written flush-left: it collapses 2+
+    // HORIZONTAL spaces unanchored, and it rewrites mentions and appends role
+    // phrases around the body. None of that may touch the section's bytes.
+    const body = composeVideoPromptText(PROSE, DIRECTION)!
+    const section = body.slice(body.indexOf("\n\n[style]:\n"))
+    expect(section).toContain("[style]:\n")
+    // ENDS with it, not merely contains it: the resolver's role phrases splice
+    // into the body ahead of the section, so nothing of the resolver's may
+    // extend the clause block the header opens.
+    expect(frame(body)!.endsWith(section)).toBe(true)
+  })
+
+  it("reclaims the header only when the LAST look clause sheds", () => {
+    // Budgets derived from what the composer actually builds, so they track
+    // catalog wording instead of pinning it.
+    const capForKept = (n: number): number =>
+      frame(composeSectionedPrompt(PROSE, DIRECTION_CLAUSES.slice(0, n), ""))!.length
+    // The first clause is `cameraMotion` (motion → body), the second the first
+    // LOOK clause — so `kept = 2` is "body plus exactly one section clause".
+    expect(DIRECTION_CLAUSES[0]!.slot).toBe("body")
+    expect(DIRECTION_CLAUSES[1]!.slot).not.toBe("body")
+
+    const atTwo = composeVideoPromptText(PROSE, DIRECTION, undefined, {
+      cap: capForKept(2),
+      frame,
+    })!
+    expect(atTwo).toBe(composeSectionedPrompt(PROSE, DIRECTION_CLAUSES.slice(0, 2), ""))
+    expect(atTwo).toContain("[style]:")
+
+    // ONE byte tighter, and the section's last clause goes — taking the whole
+    // 11-byte `"\n\n[style]:\n"` with it, so the body drops all the way back to
+    // the prose. (The cost of under-pricing that header instead shows up as an
+    // over-shed in "sheds the whole direction fold before a single subject
+    // clause" below, which is where a flat per-clause charge fails.)
+    const justUnder = composeVideoPromptText(PROSE, DIRECTION, undefined, {
+      cap: capForKept(2) - 1,
+      frame,
+    })!
+    expect(justUnder).toBe(composeSectionedPrompt(PROSE, DIRECTION_CLAUSES.slice(0, 1), ""))
+    expect(justUnder).not.toContain("[style]")
   })
 
   it("reserves the caller's budget rather than re-deriving a provider cap", () => {
@@ -166,12 +237,25 @@ describe("composeVideoPromptText — cap-aware hint shedding", () => {
   })
 
   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 structured = { person: { profession: "a lighthouse keeper", expression: "focused" } }
     const fragment = renderStructuredFields(structured)
+    expect(fragment.length, "an empty fragment makes every claim below vacuous").toBeGreaterThan(0)
     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)
+    // …and it still ends the BODY, behind every surviving body hint.
+    expect(bodyOf(body).endsWith(fragment)).toBe(true)
+  })
+
+  it("ends the BODY with the fragment even when the section survives above it", () => {
+    // The capless fold, where every clause lives: the fragment is the last
+    // thing in the body and the section reads after it, so the composed prompt
+    // does NOT end with the fragment any more.
+    const structured = { person: { profession: "a lighthouse keeper", expression: "focused" } }
+    const fragment = renderStructuredFields(structured)
+    const body = composeVideoPromptText(PROSE, DIRECTION, structured)!
+    expect(body).toContain("\n\n[style]:\n")
+    expect(bodyOf(body).endsWith(fragment)).toBe(true)
+    expect(body.endsWith(fragment)).toBe(false)
   })
 })
 
@@ -316,17 +400,19 @@ describe("composeVideoPromptText — the subject fold under the cap", () => {
   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 structured = { person: { profession: "a lighthouse keeper", expression: "focused" } }
     const fragment = renderStructuredFields(structured)
     const body = composeVideoPromptText(PROSE, DIRECTION, structured, {
       subject: SUBJECT,
       cap: framedWithSubjectClauses(0),
       frame,
     })!
-    expect(body.endsWith(fragment)).toBe(true)
+    expect(bodyOf(body).endsWith(fragment)).toBe(true)
     for (const hint of [...SUBJECT_HINTS, ...VIDEO_HINTS]) {
       expect(body).not.toContain(hint)
     }
+    // Everything droppable went, so there is no section left to end with.
+    expect(body).not.toContain("[style]")
   })
 
   it("is byte-identical to the capless subject fold when it fits", () => {