@nodaro/prompts 1.10.0 → 1.12.0

package/src/assemble-image-input.ts

@@ -16,13 +16,17 @@
  * This wrapper collapses them into one.
  *
  * THE NO-OP CONTRACT (load-bearing — the platform-caller parity relies on it):
- * the two platform callers (`execute-node` / `payload-builder`) compose their
- * prompt from the canvas graph themselves and pass NO cinematic `direction`
- * ids and NO `structured` fields. In that case `composePromptText` MUST return
- * the caller's `userPrompt` byte-for-byte unchanged, so the wrapper degenerates
- * to exactly the `buildImagePrompt(...)` call those sites make today. Studio
- * (and the MCP route) supply `direction` / `structured` and get the id-hint
- * composition on top.
+ * 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
@@ -32,34 +36,45 @@
  * guard (frontend, Studio, route) pass `throwOnEmpty: true`.
  */
 import {
-  buildImagePrompt,
+  buildImagePromptWithOverflow,
   type BuildImagePromptResult,
 } 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 {
   renderStructuredFields,
   type StructuredPromptFields,
 } from "./prompt-builder-structured-fields.js"
+import {
+  renderDirectionHints,
+  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"
 
 /**
- * Flat cinematic-direction ids the Studio framing UI (and the MCP route)
- * expose — all optional. Promoted here from Studio's `assembly.ts` so the
- * id → hint composition lives in one place. The platform callers pass none of
- * these (they fold their hints from the graph into `userPrompt` themselves).
+ * Flat cinematic-direction ids the Studio framing UI, the MCP route and the
+ * canvas node data expose — all optional. The dimensions, their canonical fold
+ * ORDER and their per-catalog rendering live in `direction-registry.ts`; this
+ * re-export keeps the import path stable for existing consumers. The platform
+ * callers fold their GRAPH-WIRED hints into `userPrompt` themselves and pass
+ * these only when the node carries them as stored data (Studio-emitted graphs,
+ * spec D3).
  */
-export interface DirectionFields {
-  /** Shot Type — the FRAMINGS shot-size/coverage/composition/vantage dimensions. */
-  framingId?: string
-  /** Angle — the FRAMINGS angle dimension (separate pill, so it can coexist with Shot Type). */
-  framingAngleId?: string
-  lightingId?: string
-  lensId?: string
-  cameraFormatId?: string
-}
+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
@@ -80,10 +95,18 @@ export interface AssembleImageInput {
   connectedReferences?: ConnectedReference[]
   /**
    * Flat cinematic-direction ids → folded into the prompt as hints. Studio /
-   * MCP-route use; the platform callers pass none (so `composePromptText` is a
-   * no-op for them and the result is byte-identical to today).
+   * MCP-route use, and the platform callers' narrow-read of a node's STORED
+   * `data.direction`; absent on a node that carries none (so `composePromptText`
+   * 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
   /**
@@ -141,55 +164,118 @@ export interface AssembleImageInput {
 }
 
 /**
- * Compose the cinematic-direction hints + structured-field fragment with the
- * user's prompt. Each `get*PromptHint` returns "" on a miss, and
- * `renderStructuredFields` returns "" when nothing is populated.
+ * 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 — execute-node / payload-builder never pass `direction`/
- * `structured`), the user's prompt is returned **verbatim, untrimmed**. 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
- * assembled prompt (and the recorded `jobs.input_data`) byte-for-byte. We only
- * trim the user prompt when joining it WITH hints, so it reads cleanly
- * ("prompt. hint", not "prompt . hint"). Never mutates inputs.
+ * `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.
  */
-function composePromptText(
-  userPrompt: string,
+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
+ * assembled prompt (and the recorded `jobs.input_data`) byte-for-byte. Never
+ * mutates inputs.
+ *
+ * A node that DOES carry `direction`/`structured` takes the join branch and is
+ * therefore trimmed + `". "`-joined — intended, and asserted at the caller
+ * level by the payload-builder before/after test.
+ */
+function composePromptText(
+  userPrompt: string,
+  pieces: ImageHintPieces,
+  keptHintClauses: number,
 ): string {
   const hints = [
-    getFramingPromptHint(direction?.framingId),
-    getFramingPromptHint(direction?.framingAngleId),
-    getLightingPromptHint(direction?.lightingId),
-    getLensPromptHint(direction?.lensId),
-    getCameraFormatPromptHint(direction?.cameraFormatId),
-    structured ? renderStructuredFields(structured) : "",
+    ...pieces.hintClauses.slice(0, keptHintClauses),
+    pieces.structuredFragment,
   ].filter((p) => p.length > 0)
-  // No hints → verbatim (exact no-op = platform parity). With hints → trim the
-  // user prompt so the ". " join is clean. The trailing filter drops a blank
-  // user prompt so the join never starts with ". " (parity-critical — don't
-  // remove it as "redundant": `hints` is pre-filtered but `userPrompt` is not).
-  if (hints.length === 0) return userPrompt
-  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(". ")
+  return joinPromptHints(userPrompt, hints)
 }
 
 /**
  * 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 }
@@ -223,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(

package/src/assemble-video-input.ts

@@ -0,0 +1,244 @@
+/**
+ * `composeVideoPromptText` — the video twin of `assemble-image-input.ts`'s
+ * `composePromptText`: fold cinematic-direction picker IDS into the prompt BODY,
+ * server-side, at the model call.
+ *
+ * WHY THIS EXISTS: `/v1/generate-video` had no structured direction channel, so
+ * every client baked the hint TEXT itself. A copied scene then carried stale
+ * catalog wording forever, a re-generate double-baked it, and each client
+ * re-implemented the fold with its own separator and its own order. The wire
+ * now carries ids; the platform renders the clauses.
+ *
+ * WHERE IT RUNS (load-bearing): on the prompt BODY, BEFORE
+ * `resolveVideoReferenceCore`. That resolver FRAMES the body — legacy prepends
+ * its `Use these characters:` block, hybrid prepends the lock lines and APPENDS
+ * the canonical role phrases and extras. Folding afterwards would push the
+ * scene/look description PAST the identity directives, a worse version of the
+ * bug this channel exists to fix. The image side is structurally identical
+ * (`assembleImageInput` = `composePromptText` → `buildImagePrompt`).
+ *
+ * That ordering is also why cap-aware shedding here takes a `frame` callback
+ * rather than a provider id: the shed must run at the FOLD site (before the
+ * resolver) but be decided on the RESOLVED length (after it), so the binding
+ * text the resolver adds is inside the budget and can never be the thing that
+ * gets dropped. See {@link VideoPromptCapOptions}. Both catalog channels —
+ * SUBJECT and direction — fold into the one sheddable list that budget walks.
+ *
+ * THE VERBOSITY POLICY LIVES HERE, NOT IN THE CLIENT: motion dimensions render
+ * their compact professional term, look dimensions their full clause
+ * (`VIDEO_HINT_MODE_DEFAULT`, resolved per row's `family` by the registry). The
+ * SUBJECT fold has its own policy — compact on video
+ * (`SUBJECT_VIDEO_HINT_MODE_DEFAULT`), because a fully specified person at full
+ * verbosity is ~30 paragraph clauses and the start frame already carries the
+ * subject's identity into the clip.
+ * It is a threaded PARAMETER with a pure default — never deployment state:
+ * `__tests__/content-free-contract.test.ts` hard-fails any environment read
+ * under `packages/prompts/src`, and this module has nothing to read anyway.
+ *
+ * EXACT NO-OP CONTRACT: with no subject, no direction and no structured fields
+ * the caller's
+ * `userPrompt` comes back VERBATIM AND UNTRIMMED — `undefined` included, since
+ * a video prompt is optional on the route. That is what keeps every existing
+ * caller byte-identical (the "backward-compatible: no connectedReferences →
+ * prompt + flat refs pass through unchanged" oracle in
+ * `backend/src/routes/__tests__/generate-video.test.ts`, restated locally in
+ * `__tests__/assemble-video-input.test.ts`).
+ *
+ * WHAT IS DELIBERATELY NOT HERE: the dimension table, the fold order, the
+ * dedupe and the surface filter all live in `direction-registry.ts` (and
+ * `subject-registry.ts` for the subject channel) — ONE renderer per channel
+ * serves both surfaces, so the image and video folds cannot drift.
+ * Clients render their "will inject into prompt" preview by importing
+ * `renderDirectionHints` + `joinPromptHints` directly.
+ */
+import {
+  renderDirectionHints,
+  VIDEO_HINT_MODE_DEFAULT,
+  type DirectionFields,
+  type DirectionHintMode,
+} from "./direction-registry.js"
+import {
+  renderSubjectHints,
+  SUBJECT_VIDEO_HINT_MODE_DEFAULT,
+  type SubjectFields,
+  type SubjectHintMode,
+} from "./subject-registry.js"
+import { joinPromptHints } from "./prompt-hint-join.js"
+import { keepableDirectionHints } from "./hint-shedding.js"
+import {
+  renderStructuredFields,
+  type StructuredPromptFields,
+} from "./prompt-builder-structured-fields.js"
+
+/**
+ * Cap-aware shedding, opt-in. Absent → the composer is exactly what it always
+ * was (every existing caller stays byte-identical, and the no-op path below is
+ * never even reached differently).
+ *
+ * WHY A NUMBER AND A CALLBACK, NOT A PROVIDER ID — the two halves of the video
+ * surface's problem, which the image half did not have:
+ *
+ *  - `cap` is the caller's EFFECTIVE ceiling, not `getMaxVideoPromptChars` read
+ *    here. The routes compute it with `effectiveVideoPromptCeiling`, which
+ *    mirrors `applyVideoNegativePrompt`'s reservation of the `"\nAvoid: …"`
+ *    suffix for a provider with no native negative param. Re-deriving the cap
+ *    inside this package would put a second copy of that reservation one
+ *    refactor away from drifting from the clamp it is supposed to predict.
+ *
+ *  - `frame` is the REFERENCE RESOLVER, and it is what makes the shed correct
+ *    end-to-end. The fold runs BEFORE `resolveVideoReferenceCore` (see the
+ *    module header — folding afterwards strands the scene description past the
+ *    identity directives). The resolver then ADDS binding text: legacy's
+ *    "Use these characters:" block, hybrid's lock lines and the canonical role
+ *    phrases it APPENDS. That added text is exactly what an order-blind tail cut
+ *    destroys first, so it must be inside the budget — but it must never be
+ *    shed. Measuring THROUGH the caller's framing gives both properties at once:
+ *    the shed decision sees the final length, while the only thing it can drop
+ *    is a hint clause it rendered itself.
+ *
+ * Re-framing a SUBSET of the hints is sound because a hint can never change how
+ * the resolver reads the rest of the body: no registered catalog hint, term or
+ * label contains a `{image:N}` / `{ref:` / `@slug:N` shape
+ * (`__tests__/direction-hint-token-safety.test.ts` pins that for every catalog),
+ * so dropping one cannot renumber or unbind a reference.
+ */
+export interface VideoPromptCapOptions {
+  /**
+   * The maximum length the FRAMED prompt may reach. Sheds only while the framed
+   * body exceeds it; `undefined` (the default) disables shedding entirely.
+   */
+  readonly cap?: number
+  /**
+   * The downstream framing the cap is measured through — the caller's reference
+   * assembly. Identity when omitted (a caller with a cap but no references).
+   * Must be PURE: it is called once per shed iteration, and the caller re-runs
+   * its own real assembly on the returned body afterwards.
+   */
+  readonly frame?: (body: string | undefined) => string | undefined
+}
+
+/**
+ * Fold a video run's subject and cinematic-direction ids (and optional
+ * structured fields) into its prompt body.
+ *
+ * The SUBJECT hints land first (who is in the shot — the noun phrase the
+ * cinematography modifies), then the direction hints in the registry's
+ * canonical table order (camera motion leads), and the structured fragment
+ * lands LAST — the same ordering `composePromptText` uses for stills.
+ *
+ * `subject` rides `opts` rather than a fourth positional parameter on purpose:
+ * every existing caller passes `(prompt, direction)` or
+ * `(prompt, direction, structured)` positionally, and a new positional would
+ * have made the two levers' order a memorization test.
+ *
+ * TRUNCATION ORDERING (opt-in via `opts.cap`): the provider clamp
+ * (`applyVideoNegativePrompt`) slices the prompt TAIL, which is ORDER-BLIND —
+ * on a low-cap provider (kling = 1000) a broad direction renders more than the
+ * whole ceiling and the cut severs reference bindings and the end of the user's
+ * prose while decorative clauses survive. With a cap the composer decides
+ * instead: it knows which clauses are hints because it just rendered them, and
+ * drops them LAST-FOLDED FIRST until the framed prompt fits. Everything else —
+ * the user's prose, the structured fragment (user CONTENT, never a garnish) and
+ * every byte the resolver's framing adds — outranks a hint.
+ *
+ * SUBJECT CLAUSES ARE SHED CANDIDATES TOO, and they shed AFTER the direction
+ * clauses. Both folds are catalog decoration of the same class — ids the
+ * platform rendered into wording — so exempting one would just move the
+ * overflow into the order-blind clamp, which is the bug this machinery exists
+ * to prevent. They ride the SAME `hintClauses` list the shed already walks
+ * (subject first, direction second, tail-first shedding), so there is exactly
+ * one shed arithmetic (`hint-shedding.ts`) across both channels and both
+ * surfaces. Neither channel ever sheds before the prose, the references or the
+ * structured fragment.
+ *
+ * WHAT THE BUDGET DELIBERATELY EXCLUDES: the route's later opt-in identity
+ * injection (an async DB read that appends a canonical description) and any
+ * registered `applyPromptPolicies` transform both run AFTER the reference
+ * assembly and are not modelled here. Pricing them in would mean folding an
+ * await into this pure composer; instead the provider clamp stays their last
+ * resort, exactly as today. Same for a body that still overflows with ZERO
+ * hints left — long prose, or many bound references on their own.
+ *
+ * UNDER-CAP PARITY: the first pass folds every hint, so a prompt that fits is
+ * byte-identical to a capless call, and a caller with no
+ * `subject`/`direction`/`structured` takes the same exact no-op path it always
+ * did.
+ *
+ * @param userPrompt The user's prompt. Optional: an image-to-video run may
+ *   legitimately have none, and it is returned as-is when nothing folds.
+ * @param direction Flat catalog ids. Unknown keys, off-surface keys (an
+ *   image-only dimension sent to a video run) and unknown ids all contribute
+ *   nothing — never a throw.
+ * @param structured Path-1 structured fields. Not a `/v1/generate-video` wire
+ *   field today; the canvas orchestrator passes it directly.
+ * @param opts.hintMode Override the direction verbosity policy (a whole-fold
+ *   `PickerHintMode`, or a `{ look, motion }` split).
+ * @param opts.subject Flat subject ids (Person / Styling / props), same
+ *   inertness contract as `direction`.
+ * @param opts.subjectHintMode Override the subject verbosity policy.
+ * @param opts.cap / `opts.frame` See {@link VideoPromptCapOptions}.
+ */
+export function composeVideoPromptText(
+  userPrompt: string | undefined,
+  direction: DirectionFields | undefined,
+  structured?: StructuredPromptFields,
+  opts?: {
+    readonly hintMode?: DirectionHintMode
+    readonly subject?: SubjectFields
+    readonly subjectHintMode?: SubjectHintMode
+  } & VideoPromptCapOptions,
+): string | undefined {
+  // ONE sheddable list, subject FIRST then direction — because the shed walks it
+  // from the TAIL, so this order IS the survival order: a direction clause
+  // leaves before a subject clause. Deliberate, and the same order the image
+  // side uses (`renderImageHintPieces`): the subject is the noun phrase the
+  // cinematography modifies, so losing "who is in the shot" to keep a
+  // decorative grade would be the wrong trade. With no `subject` the list IS
+  // the direction fold, so every pre-subject caller is byte-identical.
+  const hintClauses = [
+    ...renderSubjectHints(opts?.subject, {
+      surface: "video",
+      mode: opts?.subjectHintMode ?? SUBJECT_VIDEO_HINT_MODE_DEFAULT,
+    }),
+    ...renderDirectionHints(direction, {
+      surface: "video",
+      mode: opts?.hintMode ?? VIDEO_HINT_MODE_DEFAULT,
+    }),
+  ].filter((p) => p.length > 0)
+  // User CONTENT, not a garnish: never sheddable, always last.
+  const structuredFragment = structured ? renderStructuredFields(structured) : ""
+
+  const composeWith = (kept: number): string | undefined => {
+    const hints = [...hintClauses.slice(0, kept), structuredFragment].filter(
+      (p) => p.length > 0,
+    )
+    // Nothing to fold → the caller's value straight back, `undefined` included.
+    // Do NOT collapse this into `joinPromptHints(userPrompt ?? "", hints)`: that
+    // would turn an absent prompt into `""` and break the no-op contract above.
+    // A FULL shed lands here too, which is what keeps the no-op contract intact
+    // at `kept === 0` — the route's `composed !== prompt` guard then correctly
+    // leaves `input_data.userPrompt` unpinned.
+    if (hints.length === 0) return userPrompt
+    return joinPromptHints(userPrompt ?? "", hints)
+  }
+
+  const cap = opts?.cap
+  if (cap === undefined) return composeWith(hintClauses.length)
+
+  // Fold everything first (the under-cap byte-parity pass), then shed from the
+  // tail of the fold order while the FRAMED prompt overflows the ceiling.
+  // `keepableDirectionHints` — the ONE shed arithmetic, shared with the image
+  // assembler — strictly decreases `kept` whenever there is a deficit, so this
+  // terminates at `kept === 0` in the worst case, at which point nothing
+  // droppable is left and the provider clamp stands.
+  const frame = opts?.frame ?? ((body: string | undefined) => body)
+  let kept = hintClauses.length
+  let body = composeWith(kept)
+  let framedLength = frame(body)?.length ?? 0
+  while (framedLength > cap && kept > 0) {
+    kept = keepableDirectionHints(hintClauses, kept, framedLength - cap)
+    body = composeWith(kept)
+    framedLength = frame(body)?.length ?? 0
+  }
+  return body
+}