@nodaro/prompts 1.11.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.11.0",
+  "version": "1.13.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.16.0"
+    "@nodaro/shared": "^2.18.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/__snapshots__/entity-convergence-image.test.ts.snap

@@ -0,0 +1,19 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`byte-identity guarantees > mention-free prompt with a wired creature AND object is unchanged 1`] = `
+"A still life in a dim room
+the creature from reference image A
+the object from reference image B"
+`;
+
+exports[`byte-identity guarantees > mention-free prompt with a wired creature is unchanged 1`] = `
+"A wide shot of a lake monster at dusk
+the creature from reference image A"
+`;
+
+exports[`byte-identity guarantees > no connectedReferences at all is unchanged 1`] = `"a wide shot of a lake at dusk"`;
+
+exports[`byte-identity guarantees > prompt with an @-token that matches no entity is unchanged 1`] = `
+"A shot of @dragon:1 over the lake
+the creature from reference image A"
+`;

package/src/__tests__/animal-getters-parity.test.ts

@@ -0,0 +1,82 @@
+/**
+ * The animal hint/term getters live in `@nodaro/shared` (`animals.ts`) rather
+ * than here, for one hard reason: `catalog-funnel-ratchet.test.ts` derives its
+ * watch set from `picker-catalogs.ts`'s uppercase value imports — `ANIMALS`
+ * included — scans all of `packages/prompts/src`, and its allowlist can only
+ * SHRINK. A getter under `prompts/src` that read `ANIMALS` would be a new
+ * offender. Putting them where the catalog lives keeps the funnel honest.
+ *
+ * That placement costs one thing: `@nodaro/prompts` depends on
+ * `@nodaro/shared`, never the reverse, so `getAnimalTerm` cannot call this
+ * package's `deriveTerm` and carries a local copy of the four-line derivation.
+ * THIS FILE IS THE PIN on that copy — it is the only place that can import both
+ * sides. If it fails, the copy in `shared/animals.ts` has drifted from
+ * `term.ts`'s `deriveTerm` and must be brought back, not "fixed" by editing the
+ * expectation.
+ *
+ * It also pins the two repointed call sites (the picker-catalog funnel's
+ * synthesized `promptHint` and `getParameterPromptHint`'s `animal` case)
+ * against the getters, so the phrasing keeps ONE owner.
+ */
+import { describe, it, expect } from "vitest"
+import { ANIMALS, getAnimalPromptHint, getAnimalTerm } from "@nodaro/shared"
+import { deriveTerm } from "../term.js"
+import { PICKER_CATALOGS } from "../picker-catalogs.js"
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+
+const animalCatalog = PICKER_CATALOGS.find((c) => c.nodeType === "animal")
+
+describe("animal getters", () => {
+  it("phrases the full hint as 'featuring a {label}, {description}'", () => {
+    const a = ANIMALS[0]!
+    expect(getAnimalPromptHint(a.id)).toBe(
+      `featuring a ${a.label.toLowerCase()}, ${a.description}`,
+    )
+  })
+
+  it("returns '' for an unknown, empty, undefined or null id (never throws)", () => {
+    for (const id of ["__no_such_animal__", "", undefined, null]) {
+      expect(getAnimalPromptHint(id)).toBe("")
+      expect(getAnimalTerm(id)).toBe("")
+    }
+  })
+
+  it("derives every term exactly as `deriveTerm` would (the cross-package copy pin)", () => {
+    for (const a of ANIMALS) {
+      expect(getAnimalTerm(a.id), a.id).toBe(a.term ?? deriveTerm(a.label))
+    }
+  })
+
+  it("gives every catalog entry a non-empty hint and term", () => {
+    for (const a of ANIMALS) {
+      expect(getAnimalPromptHint(a.id).length, a.id).toBeGreaterThan(0)
+      expect(getAnimalTerm(a.id).length, a.id).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe("both repointed call sites read the getters", () => {
+  it("the picker-catalog funnel synthesizes every animal option from `getAnimalPromptHint`", () => {
+    expect(animalCatalog?.options?.length).toBe(ANIMALS.length)
+    for (const opt of animalCatalog!.options!) {
+      expect(opt.promptHint, opt.id).toBe(getAnimalPromptHint(opt.id))
+      expect(opt.term, opt.id).toBe(getAnimalTerm(opt.id))
+    }
+  })
+
+  it("`getParameterPromptHint` renders an animal node through the getters, per mode", () => {
+    const a = ANIMALS[0]!
+    expect(getParameterPromptHint({ id: "n1", type: "animal", data: { animal: a.id } })).toBe(
+      getAnimalPromptHint(a.id),
+    )
+    expect(
+      getParameterPromptHint({ id: "n1", type: "animal", data: { animal: a.id, hintMode: "compact" } }),
+    ).toBe(getAnimalTerm(a.id))
+  })
+
+  it("an animal node with an unknown id contributes nothing", () => {
+    expect(
+      getParameterPromptHint({ id: "n1", type: "animal", data: { animal: "__no_such_animal__" } }),
+    ).toBe("")
+  })
+})

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

@@ -0,0 +1,236 @@
+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 { renderStyleSection } from "../prompt-style-section.js"
+import { getMaxImagePromptChars } from "@nodaro/shared"
+import type { ConnectedReference } from "@nodaro/shared"
+
+/**
+ * TRUNCATION ORDERING — `assembleImageInput` sheds its own hint clauses before
+ * the provider cap's ORDER-BLIND tail cut can reach anything that matters.
+ *
+ * The failure this pins (filed as a follow-up on the direction-registry PR): a
+ * 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, 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
+// emits. Ids that don't resolve contribute nothing (registry tolerance), which
+// is fine: what matters is that the fold is large enough to overflow seedream.
+const DIRECTION = {
+  shotSize: "wide-shot",
+  angle: "low-angle",
+  cameraFormat: "16mm-film",
+  lens: "wide-24mm",
+  isoValue: "iso-100",
+  timeOfDay: "golden-hour",
+  lightingStyle: "rembrandt",
+  colorLook: "teal-orange",
+  atmosphere: ["fog"],
+  style: "anime",
+  mood: ["happy", "joyful"],
+  photographer: ["annie-leibovitz"],
+  setting: "forest",
+} as const
+
+const IMAGE_HINTS = renderDirectionHints(DIRECTION, {
+  surface: "image",
+  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",
+  defaultName: "Kira",
+  source: "wired-character",
+  url: "https://r2.example/kira.png",
+  characterSlug: "kira",
+  variantSlug: undefined,
+  characterCanonicalDescription: "a young woman with copper hair",
+  variantDescription: null,
+  variantDisplayName: "canonical",
+}
+
+/** An UNMENTIONED wired 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",
+  source: "wired-location",
+  url: "https://r2.example/pier.png",
+  locationSlug: "pier",
+}
+
+/** 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 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)
+
+const SEEDREAM_CAP = getMaxImagePromptChars("seedream")
+
+const overCapInput = {
+  userPrompt: PROSE,
+  provider: "seedream",
+  connectedReferences: [KIRA, PIER],
+  direction: DIRECTION,
+  referenceFormat: "hybrid" as const,
+}
+
+describe("assembleImageInput — cap-aware hint shedding", () => {
+  it("the unordered fold really does overflow seedream (non-vacuity guard)", () => {
+    // The oracle for "what the assembler would have produced before": fold every
+    // hint, hand it to the builder, let the tail cut decide. If catalog wording
+    // ever shrinks enough that this no longer truncates, the scenario below is
+    // vacuous and this assertion says so loudly.
+    const naive = buildImagePrompt({
+      prompt: unshedBody(PROSE),
+      provider: "seedream",
+      connectedReferences: [KIRA, PIER],
+      referenceFormat: "hybrid",
+    })
+    expect(naive.prompt.endsWith("...")).toBe(true)
+    // …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", () => {
+    const result = assembleImageInput(overCapInput)
+
+    // Fits WITHOUT a tail cut — the shed resolved the whole overflow.
+    expect(result.prompt.length).toBeLessThanOrEqual(SEEDREAM_CAP)
+    expect(result.prompt.endsWith("...")).toBe(false)
+
+    // Both bindings survive: the mention-resolved character phrase inside the
+    // prose and the unmentioned location's TRAILING role phrase.
+    expect(result.prompt).toContain(CHARACTER_BINDING)
+    expect(result.prompt).toContain(LOCATION_BINDING)
+    expect(result.referenceImageUrls).toEqual([
+      "https://r2.example/kira.png",
+      "https://r2.example/pier.png",
+    ])
+
+    // The user's prose survives in full (the mention resolves to its binding;
+    // the hint join trims the body's trailing space).
+    expect(result.prompt).toContain(PROSE.replace("@kira:1", CHARACTER_BINDING).trim())
+
+    // The LAST-folded hint clause is gone; the FIRST-folded one stayed. Shedding
+    // walks the fold order from the tail, so the dimensions the registry ranks
+    // first outlive the ones it ranks last.
+    expect(result.prompt).not.toContain(IMAGE_HINTS[IMAGE_HINTS.length - 1])
+    expect(result.prompt).toContain(IMAGE_HINTS[0])
+  })
+
+  it("falls back to the builder's clamp when the body overflows on prose alone", () => {
+    // Nothing droppable can save a body that blows the cap by itself — the
+    // order-blind clamp is still the last resort, unchanged.
+    const result = assembleImageInput({
+      userPrompt: "x".repeat(SEEDREAM_CAP + 500),
+      provider: "seedream",
+      direction: DIRECTION,
+    })
+    expect(result.prompt.length).toBe(SEEDREAM_CAP)
+    expect(result.prompt.endsWith("...")).toBe(true)
+  })
+})
+
+describe("assembleImageInput — under-cap byte parity", () => {
+  // The oracle is literally the pre-change implementation: compose every hint,
+  // call buildImagePrompt. A prompt that FITS must be byte-identical to it.
+  const parityCases: ReadonlyArray<{ name: string; provider: string; prompt: string }> = [
+    { name: "high-cap provider with the same maximal fold", provider: "nano-banana-pro", prompt: PROSE },
+    { name: "low-cap provider, short prose", provider: "seedream", prompt: "a knight on a hill" },
+  ]
+
+  for (const { name, provider, prompt } of parityCases) {
+    it(`is byte-identical to the unordered fold — ${name}`, () => {
+      const expected = buildImagePrompt({
+        prompt: unshedBody(prompt),
+        provider,
+        connectedReferences: [KIRA, PIER],
+        referenceFormat: "hybrid",
+      })
+      const actual = assembleImageInput({
+        userPrompt: prompt,
+        provider,
+        connectedReferences: [KIRA, PIER],
+        direction: DIRECTION,
+        referenceFormat: "hybrid",
+      })
+      expect(actual).toEqual(expected)
+      // Guard the guard: a case that truncated would prove nothing.
+      expect(expected.prompt.endsWith("...")).toBe(false)
+    })
+  }
+
+  it("leaves the no-direction platform-caller path an exact no-op", () => {
+    // No hints → nothing droppable → the prompt reaches the builder verbatim
+    // and untrimmed, exactly as before, even on the low-cap provider.
+    const result = assembleImageInput({ userPrompt: "  a knight  ", provider: "seedream" })
+    expect(result.prompt).toBe("  a knight  ")
+  })
+})
+
+describe("buildImagePromptWithOverflow", () => {
+  it("reports 0 and the identical prompt when the assembly fits", () => {
+    const config = { prompt: "a knight on a hill", provider: "seedream" }
+    const fitted = buildImagePromptWithOverflow(config)
+    expect(fitted.overflowChars).toBe(0)
+    const { overflowChars, ...result } = fitted
+    expect(result).toEqual(buildImagePrompt(config))
+  })
+
+  it("reports how many characters the cap forced off the tail", () => {
+    const config = { prompt: "x".repeat(SEEDREAM_CAP + 250), provider: "seedream" }
+    const fitted = buildImagePromptWithOverflow(config)
+    expect(fitted.overflowChars).toBe(250)
+    const { overflowChars, ...result } = fitted
+    expect(result).toEqual(buildImagePrompt(config))
+  })
+
+  it("counts the reserved Style/Avoid suffixes in the overflow", () => {
+    // The suffixes are reserved BEFORE the body is cut, so they are part of what
+    // must be reclaimed — a caller shedding only `overflowChars` of body still fits.
+    const config = {
+      prompt: "x".repeat(SEEDREAM_CAP),
+      provider: "seedream",
+      negativePrompt: "blurry",
+    }
+    const fitted = buildImagePromptWithOverflow(config)
+    expect(fitted.overflowChars).toBe("\nAvoid: blurry".length)
+    expect(fitted.prompt.length).toBeLessThanOrEqual(SEEDREAM_CAP)
+  })
+})

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]")
   })
 })