@nodaro/prompts 1.10.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.10.0",
+  "version": "1.12.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.14.0"
+    "@nodaro/shared": "^2.17.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,212 @@
+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 { 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 — 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.
+ */
+
+// 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 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 at the very
+ *  END of the prompt, behind every folded hint. The order-blind casualty. */
+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 destroys when nothing sheds the hints first. */
+const LOCATION_BINDING = "the location from reference image B"
+
+/** 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: joinPromptHints(PROSE, IMAGE_HINTS),
+      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)
+  })
+
+  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: joinPromptHints(prompt, IMAGE_HINTS),
+        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

@@ -3,6 +3,10 @@ import { assembleImageInput } from "../assemble-image-input.js"
 import { buildImagePrompt } from "../prompt-builder.js"
 import { getFramingPromptHint } from "../framing.js"
 import { getLightingPromptHint } from "../lighting.js"
+import { getLensPromptHint } from "../lens.js"
+import { getCameraFormatPromptHint } from "../camera-format.js"
+import { getStylePromptHint } from "../style.js"
+import { buildMoodHints } from "../mood.js"
 import type { ConnectedReference } from "@nodaro/shared"
 
 /**
@@ -11,9 +15,9 @@ import type { ConnectedReference } from "@nodaro/shared"
  * `generate-image` assembly through it. These tests pin BOTH layers:
  *   (a) the id-based composition (direction / structured) — ported from
  *       Studio's `assembly.test.ts` as the oracle, and
- *   (b) the BY-CONSTRUCTION PARITY the caller refactor relies on: with no
- *       direction/structured, the wrapper === the old inline `buildImagePrompt`
- *       call + empty-check, byte-for-byte.
+ *   (b) the BY-CONSTRUCTION PARITY the caller refactor relies on: for a node
+ *       that carries no direction/structured, the wrapper === the old inline
+ *       `buildImagePrompt` call + empty-check, byte-for-byte.
  */
 
 // flux-2-max supports reference images (used to assert refs survive the gate).
@@ -93,6 +97,92 @@ describe("assembleImageInput — id-based composition (Studio oracle)", () => {
     })
     expect(result.prompt).toBe("a portrait. Subject: 30 years old, woman, calm expression.")
   })
+
+  // ── The direction registry (the fold moved into `direction-registry.ts`) ──
+
+  it("returns the prompt VERBATIM and UNTRIMMED for a direction that renders nothing", () => {
+    // The no-op branch is what the platform-caller parity contract rests on: an
+    // empty (or all-empty-valued) `direction` must not trip the join, or the
+    // prompt would silently get trimmed.
+    for (const direction of [{}, { style: "" }, { mood: [] }, { style: "__no_such_style__" }]) {
+      const result = assembleImageInput({
+        userPrompt: "  a knight \n",
+        provider: REF_PROVIDER,
+        direction,
+      })
+      expect(result.prompt).toBe("  a knight \n")
+    }
+  })
+
+  it("folds a registry key that predates no legacy field (style) end to end", () => {
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      direction: { style: "anime" },
+    })
+    expect(result.prompt).toBe(`a knight. ${getStylePromptHint("anime")}`)
+  })
+
+  it("blends a multi-pick dimension into ONE clause", () => {
+    const blended = buildMoodHints({ mood: ["happy", "joyful"] }, "full")
+    expect(blended).toHaveLength(1)
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      direction: { mood: ["happy", "joyful"] },
+    })
+    expect(result.prompt).toBe(`a knight. ${blended[0]}`)
+  })
+
+  it("folds in TABLE order, not the caller's object-literal order", () => {
+    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")}`,
+    )
+  })
+
+  it("keeps the five pre-registry keys byte-identical to the old inlined fold", () => {
+    const direction = {
+      framingId: "wide-shot",
+      framingAngleId: "low-angle",
+      lightingId: "golden-hour",
+      lensId: "wide-24mm",
+      cameraFormatId: "16mm-film",
+    }
+    const result = assembleImageInput({
+      userPrompt: "a knight",
+      provider: REF_PROVIDER,
+      direction,
+    })
+    // The exact string the pre-registry `composePromptText` produced: the same
+    // five clauses, in the same order, joined with the same ". ".
+    expect(result.prompt).toBe(
+      [
+        "a knight",
+        getFramingPromptHint("wide-shot"),
+        getFramingPromptHint("low-angle"),
+        getLightingPromptHint("golden-hour"),
+        getLensPromptHint("wide-24mm"),
+        getCameraFormatPromptHint("16mm-film"),
+      ].join(". "),
+    )
+  })
+
+  it("keeps the structured fragment LAST, after every direction clause", () => {
+    const result = assembleImageInput({
+      userPrompt: "a portrait",
+      provider: REF_PROVIDER,
+      direction: { style: "anime" },
+      structured: { person: { age: 30, gender: "woman", expression: "calm" } },
+    })
+    expect(result.prompt).toBe(
+      `a portrait. ${getStylePromptHint("anime")}. Subject: 30 years old, woman, calm expression.`,
+    )
+  })
 })
 
 describe("assembleImageInput — empty-prompt throw (opt-in)", () => {