@nodaro/prompts 1.11.0 → 1.12.0

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

@@ -0,0 +1,312 @@
+/**
+ * The subject registry is the platform-owned contract for the flat `subject`
+ * wire channel: WHICH keys ride it, in WHAT order the rows fold, and HOW each
+ * catalog renders its selection. Every assertion here is a pin on that
+ * contract — a failure means a reorder / retable was intentional and the
+ * changeset has to say so.
+ *
+ * Two pins are load-bearing beyond mere table hygiene:
+ *  - the FLAT-BAG dedupe (`lipState` suppressing `makeup-bold-lips`), which is
+ *    the reason the wire is flat and which fails on any future nesting;
+ *  - the GRAMMAR pin (person/styling arrive as ONE comma-joined clause, never N
+ *    `". "`-joined fragments), which is why those rows are `kind: "group"`.
+ */
+import { describe, it, expect } from "vitest"
+import {
+  MAX_SUBJECT_KEYS,
+  SUBJECT_ARRAY_CEILING,
+  SUBJECT_CUSTOM_AGE_KEY,
+  SUBJECT_FIELDS,
+  SUBJECT_FOLD_KEYS,
+  SUBJECT_ID_MAX_CHARS,
+  SUBJECT_IMAGE_HINT_MODE_DEFAULT,
+  SUBJECT_KEYS,
+  SUBJECT_VIDEO_HINT_MODE_DEFAULT,
+  normalizeSubjectFields,
+  renderSubjectHints,
+  subjectFieldsForSurface,
+} from "../subject-registry.js"
+import {
+  DIRECTION_ARRAY_CEILING,
+  DIRECTION_ID_MAX_CHARS,
+  DIRECTION_KEYS,
+} from "../direction-registry.js"
+import {
+  PERSON_DIMENSION_ORDER,
+  PERSON_FIELD_BY_DIMENSION,
+  buildPersonHints,
+  getPersonPromptHint,
+  getPersonTerm,
+} from "../person.js"
+import {
+  STYLING_DIMENSION_ORDER,
+  STYLING_FIELD_BY_DIMENSION,
+  getStylingPromptHint,
+} from "../styling.js"
+import { getHeldPropPromptHint } from "../held-prop.js"
+import { getAnimalPromptHint, getAnimalTerm } from "@nodaro/shared"
+
+const IMAGE = { surface: "image" } as const
+const VIDEO = { surface: "video" } as const
+
+// Real catalog ids — every getter returns "" on a miss, so a fake id would make
+// most of these assertions vacuously pass.
+const NO_SUCH_ID = "__no_such_id__"
+
+describe("SUBJECT_FIELDS — table integrity", () => {
+  it("has unique row keys", () => {
+    const keys = SUBJECT_FIELDS.map((f) => f.key)
+    expect(new Set(keys).size).toBe(keys.length)
+  })
+
+  it("gives every row a render function, and every ids row a positive maxPicks", () => {
+    for (const spec of SUBJECT_FIELDS) {
+      expect(typeof spec.render, spec.key).toBe("function")
+      if (spec.kind === "ids") expect(spec.maxPicks, spec.key).toBeGreaterThanOrEqual(1)
+    }
+  })
+
+  it("exports SUBJECT_FOLD_KEYS in table order", () => {
+    expect(SUBJECT_FOLD_KEYS).toEqual(SUBJECT_FIELDS.map((f) => f.key))
+  })
+
+  it("pins the fold order (a reorder is a deliberate, changeset-worthy change)", () => {
+    expect(SUBJECT_FOLD_KEYS).toEqual(["person", "styling", "heldProp", "material", "animal"])
+  })
+
+  it("folds both group rows before any prop row", () => {
+    const lastGroup = SUBJECT_FIELDS.map((f) => f.kind).lastIndexOf("group")
+    const firstIds = SUBJECT_FIELDS.map((f) => f.kind).indexOf("ids")
+    expect(lastGroup).toBeLessThan(firstIds)
+  })
+
+  it("folds every row on both surfaces today", () => {
+    expect(subjectFieldsForSurface("image").map((f) => f.key)).toEqual([...SUBJECT_FOLD_KEYS])
+    expect(subjectFieldsForSurface("video").map((f) => f.key)).toEqual([...SUBJECT_FOLD_KEYS])
+  })
+
+  it("takes its bounds FROM the direction registry (one literal, both channels)", () => {
+    expect(SUBJECT_ID_MAX_CHARS).toBe(DIRECTION_ID_MAX_CHARS)
+    expect(SUBJECT_ARRAY_CEILING).toBe(DIRECTION_ARRAY_CEILING)
+  })
+
+  it("defaults image to full clauses and video to compact terms", () => {
+    expect(SUBJECT_IMAGE_HINT_MODE_DEFAULT).toBe("full")
+    expect(SUBJECT_VIDEO_HINT_MODE_DEFAULT).toBe("compact")
+  })
+})
+
+describe("SUBJECT_KEYS — the derived wire vocabulary", () => {
+  it("is unique and fits the record bound", () => {
+    expect(new Set(SUBJECT_KEYS).size).toBe(SUBJECT_KEYS.length)
+    expect(SUBJECT_KEYS.length).toBeLessThanOrEqual(MAX_SUBJECT_KEYS)
+  })
+
+  it("carries every person field, every styling field, customAge and the three props", () => {
+    for (const d of PERSON_DIMENSION_ORDER) {
+      expect(SUBJECT_KEYS, d).toContain(PERSON_FIELD_BY_DIMENSION[d])
+    }
+    for (const d of STYLING_DIMENSION_ORDER) {
+      expect(SUBJECT_KEYS, d).toContain(STYLING_FIELD_BY_DIMENSION[d])
+    }
+    expect(SUBJECT_KEYS).toContain(SUBJECT_CUSTOM_AGE_KEY)
+    expect(SUBJECT_KEYS).toContain("heldProp")
+    expect(SUBJECT_KEYS).toContain("material")
+    expect(SUBJECT_KEYS).toContain("animal")
+    expect(SUBJECT_KEYS.length).toBe(
+      PERSON_DIMENSION_ORDER.length + STYLING_DIMENSION_ORDER.length + 1 + 3,
+    )
+  })
+
+  it("excludes the free-text pre/post fields (the v1 carve-out)", () => {
+    expect(SUBJECT_KEYS).not.toContain("preText")
+    expect(SUBJECT_KEYS).not.toContain("postText")
+  })
+
+  it("is DISJOINT from DIRECTION_KEYS — nothing folds twice", () => {
+    const direction = new Set<string>(DIRECTION_KEYS)
+    expect(SUBJECT_KEYS.filter((k) => direction.has(k))).toEqual([])
+  })
+})
+
+describe("renderSubjectHints — inertness", () => {
+  it("returns [] for undefined, {} and a non-object", () => {
+    expect(renderSubjectHints(undefined, IMAGE)).toEqual([])
+    expect(renderSubjectHints({}, IMAGE)).toEqual([])
+    expect(renderSubjectHints([] as never, IMAGE)).toEqual([])
+  })
+
+  it("ignores unknown wire keys", () => {
+    expect(renderSubjectHints({ notAField: "man", hairColor: NO_SUCH_ID }, IMAGE)).toEqual([])
+  })
+
+  it("skips unknown ids instead of 400ing on them", () => {
+    expect(renderSubjectHints({ type: NO_SUCH_ID, animal: NO_SUCH_ID }, IMAGE)).toEqual([])
+  })
+
+  it("drops preText / postText — the carve-out that stops a double emission", () => {
+    expect(
+      renderSubjectHints(
+        { preText: "a lone wanderer", postText: "seen from behind" } as never,
+        IMAGE,
+      ),
+    ).toEqual([])
+    const withPerson = renderSubjectHints(
+      { type: "woman", preText: "a lone wanderer" } as never,
+      IMAGE,
+    )
+    expect(withPerson).toEqual([getPersonPromptHint("woman")])
+  })
+})
+
+describe("renderSubjectHints — grammar (the R4 pin)", () => {
+  it("emits person as ONE comma-joined clause, not N fragments", () => {
+    const bag = { type: "woman", ethnicity: "east-asian", hairBase: "base-short-straight" }
+    const out = renderSubjectHints(bag, IMAGE)
+    expect(out).toHaveLength(1)
+    expect(out[0]).toBe(buildPersonHints(bag, "full").join(", "))
+    expect(out[0]).toContain(", ")
+  })
+
+  it("emits styling as its own single clause, after person", () => {
+    const out = renderSubjectHints({ type: "woman", makeup: "makeup-smoky" }, IMAGE)
+    expect(out).toEqual([getPersonPromptHint("woman"), getStylingPromptHint("makeup-smoky")])
+  })
+
+  it("folds the prop rows after both group rows, in table order", () => {
+    const out = renderSubjectHints(
+      { type: "man", heldProp: "smartphone", material: "silk", animal: "dog-corgi" },
+      IMAGE,
+    )
+    expect(out[0]).toBe(getPersonPromptHint("man"))
+    expect(out).toContain(getHeldPropPromptHint("smartphone"))
+    expect(out[out.length - 1]).toBe(getAnimalPromptHint("dog-corgi"))
+  })
+
+  it("renders compact terms in compact mode", () => {
+    const bag = { type: "not-defined", animal: "dog-corgi" }
+    expect(renderSubjectHints(bag, { ...VIDEO, mode: "compact" })).toEqual([
+      getPersonTerm("not-defined"),
+      getAnimalTerm("dog-corgi"),
+    ])
+  })
+})
+
+describe("renderSubjectHints — the flat-bag behaviors", () => {
+  it("dedupes the lipstick clause across the person and styling catalogs (R3)", () => {
+    const out = renderSubjectHints(
+      { lipState: "lip-state-bold-red", makeup: "makeup-bold-lips" },
+      IMAGE,
+    )
+    expect(out).toEqual([getPersonPromptHint("lip-state-bold-red")])
+    expect(out.join(" ")).not.toContain(getStylingPromptHint("makeup-bold-lips"))
+  })
+
+  it("keeps a NON-twin makeup pick alongside the bold-red lip state", () => {
+    const out = renderSubjectHints(
+      { lipState: "lip-state-bold-red", makeup: "makeup-smoky" },
+      IMAGE,
+    )
+    expect(out).toEqual([
+      getPersonPromptHint("lip-state-bold-red"),
+      getStylingPromptHint("makeup-smoky"),
+    ])
+  })
+
+  it("folds midriff + navel into the single neutral safety clause", () => {
+    const out = renderSubjectHints(
+      { distinctiveFeature: ["feature-midriff-visible", "feature-navel-visible"] },
+      IMAGE,
+    )
+    expect(out).toEqual(["wearing a cropped style, midriff and navel visible"])
+  })
+
+  it("de-duplicates an exact repeated clause, first occurrence winning", () => {
+    const out = renderSubjectHints({ heldProp: ["smartphone", "smartphone"] }, IMAGE)
+    expect(out).toEqual([getHeldPropPromptHint("smartphone")])
+  })
+})
+
+describe("normalizeSubjectFields — the cap the builders do not apply", () => {
+  it("slices a multi-pick dimension to its registry limit (jewelry = 3)", () => {
+    const ids = ["jewelry-subtle", "jewelry-statement", "jewelry-gold", "jewelry-silver", "jewelry-layered"]
+    expect(normalizeSubjectFields({ jewelry: ids })).toEqual({ jewelry: ids.slice(0, 3) })
+    const out = renderSubjectHints({ jewelry: ids }, IMAGE)
+    expect(out).toHaveLength(1)
+    expect(out[0]).toBe(ids.slice(0, 3).map(getStylingPromptHint).join(", "))
+    expect(out[0]).not.toContain(getStylingPromptHint("jewelry-silver"))
+  })
+
+  it("slices a 2-pick dimension handed the full array ceiling", () => {
+    const eight = Array.from({ length: SUBJECT_ARRAY_CEILING }, (_, i) => `texture-${i}`)
+    const normalized = normalizeSubjectFields({ skinTexture: eight }) as Record<string, unknown>
+    expect(normalized.skinTexture).toEqual(eight.slice(0, 2))
+  })
+
+  it("slices the prop rows to their row maxPicks", () => {
+    const props = ["smartphone", "smartphone-raised", "polaroid-camera"]
+    const normalized = normalizeSubjectFields({ heldProp: props }) as Record<string, unknown>
+    expect(normalized.heldProp).toEqual(props.slice(0, 2))
+  })
+
+  it("collapses a single-pick dimension's array to a bare string — without this it folds to NOTHING", () => {
+    expect(normalizeSubjectFields({ hairBase: ["base-buzz"] })).toEqual({ hairBase: "base-buzz" })
+    expect(renderSubjectHints({ hairBase: ["base-buzz"] }, IMAGE)).toEqual([
+      getPersonPromptHint("base-buzz"),
+    ])
+  })
+
+  it("drops unknown keys, so the persisted input_data stays platform vocabulary", () => {
+    expect(normalizeSubjectFields({ type: "man", notAField: "x", preText: "y" })).toEqual({
+      type: "man",
+    })
+  })
+
+  it("drops empty strings and non-string entries", () => {
+    expect(normalizeSubjectFields({ type: "", jewelry: ["", 7 as never, "jewelry-gold"] })).toEqual({
+      jewelry: "jewelry-gold",
+    })
+  })
+
+  it("returns undefined for an empty or all-unknown bag (never {})", () => {
+    expect(normalizeSubjectFields(undefined)).toBeUndefined()
+    expect(normalizeSubjectFields({})).toBeUndefined()
+    expect(normalizeSubjectFields({ notAField: "x" })).toBeUndefined()
+  })
+
+  it("never mutates the caller's object", () => {
+    const bag = { jewelry: ["jewelry-subtle", "jewelry-statement", "jewelry-gold", "jewelry-silver"] }
+    const before = JSON.stringify(bag)
+    normalizeSubjectFields(bag)
+    expect(JSON.stringify(bag)).toBe(before)
+  })
+
+  it("is idempotent (a door may normalize before the renderer does)", () => {
+    const bag = { type: "man", jewelry: ["jewelry-gold", "jewelry-silver"], customAge: 34.6 }
+    const once = normalizeSubjectFields(bag)
+    expect(normalizeSubjectFields(once)).toEqual(once)
+  })
+})
+
+describe("customAge — the one number on the wire", () => {
+  it("renders the literal age when age === 'age-custom'", () => {
+    expect(renderSubjectHints({ age: "age-custom", customAge: 34 }, IMAGE)).toEqual([
+      "34 years old",
+    ])
+  })
+
+  it("emits nothing for age-custom with no customAge", () => {
+    expect(renderSubjectHints({ age: "age-custom" }, IMAGE)).toEqual([])
+  })
+
+  it("clamps and rounds to a whole 0..120", () => {
+    expect(normalizeSubjectFields({ customAge: 34.6 })).toEqual({ customAge: 35 })
+    expect(normalizeSubjectFields({ customAge: -5 })).toEqual({ customAge: 0 })
+    expect(normalizeSubjectFields({ customAge: 9999 })).toEqual({ customAge: 120 })
+  })
+
+  it("drops a non-finite or non-number customAge", () => {
+    expect(normalizeSubjectFields({ customAge: Number.NaN })).toBeUndefined()
+    expect(normalizeSubjectFields({ customAge: "34" })).toBeUndefined()
+  })
+})

package/src/assemble-image-input.ts

@@ -16,17 +16,17 @@
  * This wrapper collapses them into one.
  *
  * THE NO-OP CONTRACT (load-bearing — the platform-caller parity relies on it):
- * a node that carries NO stored `direction` / `structured` (every workflow
- * authored before the canvas honored them) still reaches here with both absent,
- * and `composePromptText` MUST return the caller's `userPrompt` byte-for-byte
- * unchanged, so the wrapper degenerates to exactly the `buildImagePrompt(...)`
- * call those sites made before. The platform callers (`execute-node` /
- * `payload-builder`) compose their prompt from the canvas GRAPH themselves and
- * ALSO forward a node's STORED `direction` / `structured` when it carries them
- * (`readDirectionFields` / `readStructuredFields`); those nodes get the id-hint
- * composition on top, ADDITIVE to the graph-wired cinematography hints the
- * caller already folded into `userPrompt`. Studio and the MCP route supply the
- * same two levers directly.
+ * a node that carries NO stored `subject` / `direction` / `structured` (every
+ * workflow authored before the canvas honored them) still reaches here with all
+ * three absent, and `composePromptText` MUST return the caller's `userPrompt`
+ * byte-for-byte unchanged, so the wrapper degenerates to exactly the
+ * `buildImagePrompt(...)` call those sites made before. The platform callers
+ * (`execute-node` / `payload-builder`) compose their prompt from the canvas GRAPH themselves and
+ * ALSO forward a node's STORED `subject` / `direction` / `structured` when it
+ * carries them (`readSubjectFields` / `readDirectionFields` /
+ * `readStructuredFields`); those nodes get the id-hint composition on top,
+ * ADDITIVE to the graph-wired cinematography hints the caller already folded
+ * into `userPrompt`. Studio and the MCP route supply the levers directly.
  *
  * THE EMPTY-CHECK FLAG (also load-bearing for parity): `execute-node` rejects a
  * truly-empty assembled prompt (its "type one, mention a character, or connect
@@ -36,7 +36,7 @@
  * guard (frontend, Studio, route) pass `throwOnEmpty: true`.
  */
 import {
-  buildImagePrompt,
+  buildImagePromptWithOverflow,
   type BuildImagePromptResult,
 } from "./prompt-builder.js"
 import {
@@ -48,7 +48,13 @@ import {
   IMAGE_HINT_MODE_DEFAULT,
   type DirectionFields,
 } from "./direction-registry.js"
+import {
+  renderSubjectHints,
+  SUBJECT_IMAGE_HINT_MODE_DEFAULT,
+  type SubjectFields,
+} from "./subject-registry.js"
 import { joinPromptHints } from "./prompt-hint-join.js"
+import { keepableDirectionHints } from "./hint-shedding.js"
 import type { CharacterDef, ConnectedReference, IdentityMeta } from "@nodaro/shared"
 
 /**
@@ -62,6 +68,14 @@ import type { CharacterDef, ConnectedReference, IdentityMeta } from "@nodaro/sha
  */
 export type { DirectionFields }
 
+/**
+ * Flat SUBJECT ids (Person / Styling / prop catalogs) — the companion channel
+ * to `direction`, describing WHO is in the shot rather than how it is shot. Its
+ * table, fold order and per-catalog rendering live in `subject-registry.ts`;
+ * this re-export keeps one import path for a consumer that takes both levers.
+ */
+export type { SubjectFields }
+
 /**
  * Input to `assembleImageInput`. A faithful SUPERSET of what the two platform
  * callers pass to `buildImagePrompt` today (so they can route through this
@@ -86,6 +100,13 @@ export interface AssembleImageInput {
    * is a no-op for it and the result is byte-identical to today).
    */
   direction?: DirectionFields
+  /**
+   * Flat subject ids (Person / Styling / props) → folded into the prompt AHEAD
+   * of the direction clauses: the subject is the noun phrase the cinematography
+   * then modifies. Same provenance as `direction` — Studio / MCP-route, or the
+   * platform callers' narrow-read of a node's STORED `data.subject`.
+   */
+  subject?: SubjectFields
   /** Path-1 structured fields → composed fragment appended to the prompt. */
   structured?: StructuredPromptFields
   /**
@@ -143,15 +164,66 @@ export interface AssembleImageInput {
 }
 
 /**
- * Compose the cinematic-direction hints + structured-field fragment with the
- * user's prompt. `renderDirectionHints` folds the `direction` ids in the
- * registry's canonical table order (unknown keys and unknown ids contribute
- * nothing), and `renderStructuredFields` returns "" when nothing is populated —
- * so the structured fragment always lands LAST.
+ * The hint pieces a fold contributes, split by whether the assembler may SHED
+ * them under a provider prompt cap.
  *
- * EXACT NO-OP CONTRACT: when there are no cinematic/structured hint pieces (the
- * platform-caller case for a node that carries no stored `direction`/
- * `structured` — every workflow authored before the canvas honored them), the
+ * `hintClauses` are the catalog-rendered clauses — the SUBJECT fold first, then
+ * the cinematic direction fold — decorative garnish next to a reference
+ * directive or the user's own prose, and the only thing this assembler drops
+ * when the prompt won't fit. They are ONE list because the shed walks it from
+ * the TAIL: direction leaves before subject, which is the right order (who is
+ * in the shot outranks how it is lit). `structuredFragment` is user CONTENT (a
+ * Path-1 structured field the caller populated), so it is sticky and always
+ * lands LAST, exactly as before.
+ */
+interface ImageHintPieces {
+  /** Subject clauses then direction clauses, each in its registry's fold order. */
+  readonly hintClauses: readonly string[]
+  /** The structured-field fragment ("" when nothing is populated). */
+  readonly structuredFragment: string
+}
+
+/**
+ * Render the fold's hint pieces once, so the cap-aware retry can re-join a
+ * SUBSET of them without re-rendering the catalogs. Each renderer folds its own
+ * channel in its registry's canonical table order (unknown keys and unknown ids
+ * contribute nothing), and `renderStructuredFields` returns "" when nothing is
+ * populated. Never mutates inputs.
+ *
+ * SUBJECT LEADS DIRECTION: the subject is the noun phrase ("a woman in her
+ * 30s, …") the cinematographic clauses then modify. With no `subject` the list
+ * IS the direction fold, so every existing caller's prompt is byte-identical.
+ */
+function renderImageHintPieces(
+  subject: SubjectFields | undefined,
+  direction: DirectionFields | undefined,
+  structured: StructuredPromptFields | undefined,
+): ImageHintPieces {
+  return {
+    hintClauses: [
+      ...renderSubjectHints(subject, {
+        surface: "image",
+        mode: SUBJECT_IMAGE_HINT_MODE_DEFAULT,
+      }),
+      ...renderDirectionHints(direction, {
+        surface: "image",
+        mode: IMAGE_HINT_MODE_DEFAULT,
+      }),
+    ].filter((p) => p.length > 0),
+    structuredFragment: structured ? renderStructuredFields(structured) : "",
+  }
+}
+
+/**
+ * Compose the subject + cinematic-direction hints and the structured-field
+ * fragment with the user's prompt, keeping the FIRST `keptHintClauses` clauses
+ * (the full count on the first pass; fewer only when the provider cap forced a
+ * shed). The structured fragment always lands LAST.
+ *
+ * EXACT NO-OP CONTRACT: when there are no subject/cinematic/structured hint
+ * pieces (the platform-caller case for a node that carries no stored `subject`/
+ * `direction`/`structured` — every workflow authored before the canvas honored
+ * them), the
  * user's prompt is returned **verbatim, untrimmed** by `joinPromptHints`. This
  * is load-bearing for parity: the old platform path passed the prompt straight
  * to `buildImagePrompt`, which never trims, so trimming here would change the
@@ -164,12 +236,12 @@ export interface AssembleImageInput {
  */
 function composePromptText(
   userPrompt: string,
-  direction: DirectionFields | undefined,
-  structured: StructuredPromptFields | undefined,
+  pieces: ImageHintPieces,
+  keptHintClauses: number,
 ): string {
   const hints = [
-    ...renderDirectionHints(direction, { surface: "image", mode: IMAGE_HINT_MODE_DEFAULT }),
-    structured ? renderStructuredFields(structured) : "",
+    ...pieces.hintClauses.slice(0, keptHintClauses),
+    pieces.structuredFragment,
   ].filter((p) => p.length > 0)
   return joinPromptHints(userPrompt, hints)
 }
@@ -178,17 +250,32 @@ function composePromptText(
  * Assemble a node's image-generation inputs into a `BuildImagePromptResult`
  * (`{ prompt, nativeNegativePrompt, referenceImageUrls }`).
  *
- * Order: (1) compose the prompt text (no-op when no direction/structured),
+ * Order: (1) compose the prompt text (no-op when no subject/direction/structured),
  * (2) `buildImagePrompt(...)` — exactly the call the three sites make today,
- * (3) optional post-assembly empty-prompt throw (gated by `throwOnEmpty`).
+ * (3) shed hint clauses and re-assemble while the provider cap overflows,
+ * (4) optional post-assembly empty-prompt throw (gated by `throwOnEmpty`).
+ *
+ * TRUNCATION ORDERING (step 3): `buildImagePrompt`'s cap clamp cuts the TAIL,
+ * which is ORDER-BLIND — on a low-cap provider (seedream = 3000) a maximal
+ * direction fold renders ~3.3K characters of clauses and the cut can sever a
+ * reference directive, mention-resolved text or the user's own prose while a
+ * decorative clause survives. So the ASSEMBLER decides instead: it knows which
+ * clauses are hints because it just built them, and drops them last-folded
+ * first until the prompt fits. Everything else — references, prose, the
+ * structured fragment, the Style/Avoid suffixes — outranks a hint. A body that
+ * still overflows with ZERO hints (long prose or many directives on its own)
+ * falls back to the builder's clamp, unchanged.
+ *
+ * UNDER-CAP PARITY: the first pass folds every hint, so a prompt that fits is
+ * byte-identical to before — the retry only ever runs on an over-cap assembly.
  */
 export function assembleImageInput(
   input: AssembleImageInput,
 ): BuildImagePromptResult {
-  const prompt = composePromptText(input.userPrompt, input.direction, input.structured)
+  const pieces = renderImageHintPieces(input.subject, input.direction, input.structured)
 
-  const result = buildImagePrompt({
-    prompt,
+  const assembleWith = (keptHintClauses: number) => buildImagePromptWithOverflow({
+    prompt: composePromptText(input.userPrompt, pieces, keptHintClauses),
     provider: input.provider,
     ...(input.connectedReferences !== undefined
       ? { connectedReferences: input.connectedReferences }
@@ -222,8 +309,24 @@ export function assembleImageInput(
       : {}),
   })
 
+  // Fold everything first (the under-cap byte-parity pass), then shed hints
+  // from the tail of the COMBINED fold order (subject clauses first in the list,
+  // therefore last to leave) while the assembled prompt overflows the provider
+  // cap. `keepableDirectionHints` — the one shed arithmetic, shared with
+  // `composeVideoPromptText` — strictly decreases `kept` whenever there IS an
+  // overflow, so this terminates at `kept === 0` in the worst case, at which
+  // point the body overflows on its own and the builder's clamp stands.
+  let kept = pieces.hintClauses.length
+  let fitted = assembleWith(kept)
+  while (fitted.overflowChars > 0 && kept > 0) {
+    kept = keepableDirectionHints(pieces.hintClauses, kept, fitted.overflowChars)
+    fitted = assembleWith(kept)
+  }
+  // `overflowChars` is assembly bookkeeping, not part of the callers' contract.
+  const { overflowChars, ...result } = fitted
+
   // Post-assembly empty-prompt check (opt-in): a bound entity / `@`-mention /
-  // direction chip could have filled the assembled prompt even if the user
+  // subject or direction chip could have filled the assembled prompt even if the user
   // typed nothing — so only reject when the FINAL prompt is truly empty.
   if (input.throwOnEmpty && !result.prompt.trim()) {
     throw new Error(