@nodaro/prompts 1.11.0 → 1.13.0

package/src/assemble-video-input.ts

@@ -11,20 +11,40 @@
  *
  * 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
+ * its `Use these characters:` block, hybrid prepends the lock lines and extends
+ * the body's END with the canonical role phrases and extras (spliced in ahead of
+ * the `[style]` section, which stays last). 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 SHAPE IT EMITS: the body (prose, subject fold, MOTION clauses, structured
+ * fragment) and then a trailing `[style]` section carrying every LOOK clause —
+ * `prompt-style-section.ts` owns those bytes. Camera motion is shot prose, not
+ * style, so the whole motion family stays in the body; the boundary is the
+ * registry's `family` column, deliberately the same column the verbosity policy
+ * below splits on.
+ *
  * 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).
+ * (`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 direction and no structured fields the caller's
+ * 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 →
@@ -33,30 +53,131 @@
  * `__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` — ONE
- * renderer serves both surfaces, so the image and video folds cannot drift.
+ * 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.
+ * `renderSubjectHints` + `partitionStyleClauses` + `composeSectionedPrompt`
+ * directly (or `renderStyleSection` for the section alone).
  */
 import {
-  renderDirectionHints,
   VIDEO_HINT_MODE_DEFAULT,
   type DirectionFields,
   type DirectionHintMode,
 } from "./direction-registry.js"
-import { joinPromptHints } from "./prompt-hint-join.js"
+import {
+  renderSubjectHints,
+  SUBJECT_VIDEO_HINT_MODE_DEFAULT,
+  type SubjectFields,
+  type SubjectHintMode,
+} from "./subject-registry.js"
+import {
+  asBodyClauses,
+  composeSectionedPrompt,
+  partitionStyleClauses,
+  sectionedClauseCosts,
+} from "./prompt-style-section.js"
+import { keepableDirectionHints } from "./hint-shedding.js"
 import {
   renderStructuredFields,
   type StructuredPromptFields,
 } from "./prompt-builder-structured-fields.js"
 
 /**
- * Fold a video run's cinematic-direction ids (and optional structured fields)
- * into its prompt body.
+ * 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 that end its body. None of it is sheddable and all of it is inside
+ *    what the clamp measures, so a budget blind to it under-sheds and hands the
+ *    remainder to the order-blind cut. 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.
+ *
+ * IN THE BODY: the SUBJECT hints first (who is in the shot — the noun phrase the
+ * cinematography modifies), then the MOTION direction hints in the registry's
+ * canonical table order (camera motion leads), then the structured fragment —
+ * the same ordering `composePromptText` uses for stills. The LOOK hints leave
+ * the body for the `[style]` section that follows it.
+ *
+ * `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.
  *
- * The direction hints land first, in the registry's canonical table order
- * (camera motion leads), and the structured fragment lands LAST — the same
- * ordering `composePromptText` uses for stills.
+ * 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.
@@ -65,25 +186,79 @@ import {
  *   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 verbosity policy (a whole-fold
+ * @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 },
+  opts?: {
+    readonly hintMode?: DirectionHintMode
+    readonly subject?: SubjectFields
+    readonly subjectHintMode?: SubjectHintMode
+  } & VideoPromptCapOptions,
 ): string | undefined {
-  const hints = [
-    ...renderDirectionHints(direction, {
+  // 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 sheds identically.
+  //
+  // Each clause carries the SLOT it reads in, because survival order and string
+  // order are two different things once the look clauses lift into `[style]`.
+  const hintClauses = [
+    ...asBodyClauses(
+      renderSubjectHints(opts?.subject, {
+        surface: "video",
+        mode: opts?.subjectHintMode ?? SUBJECT_VIDEO_HINT_MODE_DEFAULT,
+      }),
+    ),
+    ...partitionStyleClauses(direction, {
       surface: "video",
       mode: opts?.hintMode ?? VIDEO_HINT_MODE_DEFAULT,
     }),
-    structured ? renderStructuredFields(structured) : "",
-  ].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.
-  if (hints.length === 0) return userPrompt
-  return joinPromptHints(userPrompt ?? "", hints)
+  ].filter((c) => c.text.length > 0)
+  // User CONTENT, not a garnish: never sheddable, always last IN THE BODY (the
+  // `[style]` section reads after it).
+  const structuredFragment = structured ? renderStructuredFields(structured) : ""
+
+  // Nothing folded — no body hint AND no section — returns the caller's value
+  // straight back, `undefined` included. A FULL shed lands there 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.
+  const composeWith = (kept: number): string | undefined =>
+    composeSectionedPrompt(userPrompt, hintClauses.slice(0, kept), structuredFragment)
+
+  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
+  if (framedLength <= cap) return body
+  // Priced only on the overflow path: the deltas cost a composition per clause
+  // and the fits-first-time case is the common one.
+  const costs = sectionedClauseCosts(userPrompt, hintClauses, structuredFragment)
+  const texts = hintClauses.map((c) => c.text)
+  while (framedLength > cap && kept > 0) {
+    kept = keepableDirectionHints(texts, kept, framedLength - cap, costs)
+    body = composeWith(kept)
+    framedLength = frame(body)?.length ?? 0
+  }
+  return body
 }

package/src/direction-registry.ts

@@ -32,7 +32,8 @@
  *    token, not a bare id. A single-id channel cannot carry it.
  *  - Subject / Styling / prop dimensions (`animal`, `heldProp`, `material`,
  *    Person, Styling) — a separate `subject` channel, deliberately out of scope
- *    here.
+ *    here. It now exists: `subject-registry.ts`, same table-driven shape, its
+ *    key set DISJOINT from this one (pinned by a test) so nothing folds twice.
  *
  * PACK BLINDNESS (parity, not a regression): `get*PromptHint` reads the frozen
  * base arrays, so ids added by a deployment-registered catalog pack resolve to
@@ -71,8 +72,23 @@ import { getLoopSubjectPromptHint, getLoopSubjectTerm } from "./loop-subject.js"
 
 /** Which generation stages fold a dimension. */
 export type DirectionSurface = "image" | "video" | "both"
-/** Verbosity family — the video policy folds `motion` compact, `look` full. */
+/**
+ * Verbosity family — the video policy folds `motion` compact, `look` full.
+ *
+ * It is ALSO the body/section split (`prompt-style-section.ts`): `motion` stays
+ * in the prompt body as shot prose, `look` moves to the `[style]` section. The
+ * two meanings are deliberately the same column: camera motion is part of the
+ * shot, not part of the look, on both axes, and a second column would let the
+ * verbosity policy and the section boundary drift apart one row at a time.
+ */
 export type DirectionFamily = "look" | "motion"
+/**
+ * Which `[style]` line a LOOK row renders on. `"film"` = the four dimensions
+ * that describe the CAPTURE (stock, grade, style, era) plus the legacy camera
+ * format key; every other look row falls to the scene line. Absent on `motion`
+ * rows, which never reach the section at all.
+ */
+export type DirectionStyleGroup = "film"
 
 export interface DirectionFieldSpec {
   /**
@@ -88,6 +104,12 @@ export interface DirectionFieldSpec {
   readonly surface: DirectionSurface
   /** Verbosity family. The video policy folds `motion` compact, `look` full. */
   readonly family: DirectionFamily
+  /**
+   * `[style]`-section line for a `look` row. Omitted = the scene line. Meaningless
+   * on a `motion` row (those stay in the body), which is why it is optional
+   * rather than a required column with a null member.
+   */
+  readonly styleGroup?: DirectionStyleGroup
   /** Ids honored per dimension. Extras are SLICED at render, never a 400. */
   readonly maxPicks: number
   /**
@@ -158,6 +180,26 @@ const temporal = perId(getTemporalPromptHint, getTemporalTerm)
  * so they are NOT aliases of `shotSize` / `lightingStyle`, and an alias table
  * would wrongly suppress a legal second selection. Overlap is handled instead
  * by the exact-string dedupe in `renderDirectionHints`.
+ *
+ * SECOND MEANING OF POSITION — SURVIVAL, NOT STRING POSITION: BOTH cap-aware
+ * assemblers — `assembleImageInput` (stills) and `composeVideoPromptText`
+ * (video) — shed hint clauses from the TAIL of this order when a provider's
+ * prompt cap overflows, through the one shared arithmetic in
+ * `hint-shedding.ts`. So a row's position is its survival order under the cap on
+ * EVERY surface: reordering rows for one surface silently changes what the other
+ * drops first, and the row a video-surface reorder would most likely touch
+ * (`cameraMotion`) leads the fold. What position is NOT any more is the clause's
+ * place in the assembled STRING: every `look` row is lifted out of the body into
+ * the trailing `[style]` section (`prompt-style-section.ts`), so a look clause
+ * reads after every motion clause however early it folds. That is a consequence
+ * of reusing the fold order, not a ranking — this table stays a compatibility
+ * order; anything that needs a real importance ranking should add an explicit
+ * priority column rather than reorder these rows.
+ *
+ * WHERE THIS TABLE SITS IN THE COMBINED ORDER: both assemblers fold the SUBJECT
+ * channel (`subject-registry.ts`) BEFORE this one and shed the combined list
+ * tail-first, so every direction row here is dropped before any subject clause.
+ * Deliberate — see `hint-shedding.ts` for the argument.
  */
 export const DIRECTION_FIELDS = [
   { key: "cameraMotion", surface: "video", family: "motion", maxPicks: 1, render: perId(getCameraMotionPromptHint, getCameraMotionTerm) },
@@ -172,7 +214,7 @@ export const DIRECTION_FIELDS = [
   { key: "compositionEffect", surface: "both", family: "look", maxPicks: 1, render: perId(getCompositionEffectPromptHint, getCompositionEffectTerm) },
 
   // Camera.
-  { key: "cameraFormat", surface: "both", family: "look", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) },
+  { key: "cameraFormat", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) },
   { key: "lens", surface: "both", family: "look", maxPicks: 1, render: perId(getLensPromptHint, getLensTerm) },
 
   // Exposure (stills only — a video's exposure rides its own temporal levers).
@@ -186,12 +228,12 @@ export const DIRECTION_FIELDS = [
   { key: "lightingDirection", surface: "both", family: "look", maxPicks: 1, render: lighting },
   { key: "lightingRatio", surface: "both", family: "look", maxPicks: 1, render: lighting },
   { key: "colorTemperature", surface: "both", family: "look", maxPicks: 1, render: lighting },
-  { key: "colorLook", surface: "both", family: "look", maxPicks: 1, render: perId(getColorLookPromptHint, getColorLookTerm) },
+  { key: "colorLook", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getColorLookPromptHint, getColorLookTerm) },
   { key: "atmosphere", surface: "both", family: "look", maxPicks: 2, render: viaListBuilder(buildAtmosphereHints) },
   { key: "postProcess", surface: "image", family: "look", maxPicks: 2, render: viaListBuilder(buildPostProcessHints) },
 
   // Style.
-  { key: "style", surface: "both", family: "look", maxPicks: 1, render: perId(getStylePromptHint, getStyleTerm) },
+  { key: "style", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getStylePromptHint, getStyleTerm) },
   { key: "mood", surface: "both", family: "look", maxPicks: 2, render: viaMood },
   { key: "aesthetic", surface: "both", family: "look", maxPicks: 2, render: viaStringBuilder(buildAestheticHints) },
   { key: "photoGenre", surface: "image", family: "look", maxPicks: 1, render: perId(getPhotoGenrePromptHint, getPhotoGenreTerm) },
@@ -200,7 +242,7 @@ export const DIRECTION_FIELDS = [
 
   // Scene.
   { key: "setting", surface: "both", family: "look", maxPicks: 1, render: perId(getSettingPromptHint, getSettingTerm) },
-  { key: "era", surface: "both", family: "look", maxPicks: 1, render: perId(getEraPromptHint, getEraTerm) },
+  { key: "era", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getEraPromptHint, getEraTerm) },
   { key: "backdrop", surface: "both", family: "look", maxPicks: 1, render: perId(getBackdropPromptHint, getBackdropTerm) },
 
   // Motion & time.
@@ -218,9 +260,17 @@ export const DIRECTION_FIELDS = [
   { key: "framingAngleId", surface: "both", family: "look", maxPicks: 1, render: framing },
   { key: "lightingId", surface: "both", family: "look", maxPicks: 1, render: lighting },
   { key: "lensId", surface: "both", family: "look", maxPicks: 1, render: perId(getLensPromptHint, getLensTerm) },
-  { key: "cameraFormatId", surface: "both", family: "look", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) },
+  { key: "cameraFormatId", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) },
 ] as const satisfies ReadonlyArray<DirectionFieldSpec>
 
+/**
+ * The table read at its DECLARED type. `styleGroup` is optional, so on the
+ * `as const` tuple only the rows that carry it have the property at all — a
+ * member-wise read would not compile. Every walk over the table goes through
+ * this binding.
+ */
+const DIRECTION_SPECS: ReadonlyArray<DirectionFieldSpec> = DIRECTION_FIELDS
+
 export type DirectionFieldRow = (typeof DIRECTION_FIELDS)[number]
 export type DirectionKey = DirectionFieldRow["key"]
 export type ImageDirectionKey = Extract<DirectionFieldRow, { surface: "image" | "both" }>["key"]
@@ -243,6 +293,16 @@ export type DirectionFields = { readonly [K in DirectionKey]?: string | readonly
  */
 export const DIRECTION_KEYS: ReadonlyArray<DirectionKey> = DIRECTION_FIELDS.map((f) => f.key)
 
+/**
+ * The rows that render on the `[style]` section's FILM line, in table order —
+ * derived from the table's `styleGroup` column so the grouping has exactly one
+ * definition. Exported for clients that render the section themselves; the
+ * platform's own renderer reads the column, not this list.
+ */
+export const FILM_STYLE_KEYS: ReadonlyArray<DirectionKey> = DIRECTION_SPECS.filter(
+  (f) => f.styleGroup === "film",
+).map((f) => f.key as DirectionKey)
+
 /** Verbosity for a whole fold, or split per family. */
 export type DirectionHintMode =
   | PickerHintMode
@@ -304,7 +364,51 @@ function normalizeDirectionIds(value: unknown, maxPicks: number): string[] {
 export function directionFieldsForSurface(
   surface: "image" | "video",
 ): ReadonlyArray<DirectionFieldSpec> {
-  return DIRECTION_FIELDS.filter((f) => f.surface === "both" || f.surface === surface)
+  return DIRECTION_SPECS.filter((f) => f.surface === "both" || f.surface === surface)
+}
+
+/** One rendered clause, still carrying the table attributes it came from. */
+export interface DirectionHintClause {
+  readonly key: DirectionKey
+  readonly family: DirectionFamily
+  readonly styleGroup?: DirectionStyleGroup
+  readonly text: string
+}
+
+/**
+ * `renderDirectionHints` with the row each clause came from still attached —
+ * what the `[style]` section needs to decide which line a clause belongs on
+ * without a second table. Same order, same surface filter, same dedupe; the
+ * plain renderer is this one's `.text` projection, so the two cannot drift.
+ */
+export function renderDirectionHintClauses(
+  direction: DirectionFields | undefined,
+  opts: { surface: "image" | "video"; mode?: DirectionHintMode },
+): DirectionHintClause[] {
+  if (!direction) return []
+  const mode = opts.mode ?? "full"
+  const out: DirectionHintClause[] = []
+  const seen = new Set<string>()
+  for (const spec of DIRECTION_SPECS) {
+    if (spec.surface !== "both" && spec.surface !== opts.surface) continue
+    const ids = normalizeDirectionIds(
+      (direction as Record<string, unknown>)[spec.key],
+      spec.maxPicks,
+    )
+    if (ids.length === 0) continue
+    for (const hint of spec.render(ids, modeForFamily(mode, spec.family))) {
+      if (hint.length > 0 && !seen.has(hint)) {
+        seen.add(hint)
+        out.push({
+          key: spec.key as DirectionKey,
+          family: spec.family,
+          ...(spec.styleGroup !== undefined ? { styleGroup: spec.styleGroup } : {}),
+          text: hint,
+        })
+      }
+    }
+  }
+  return out
 }
 
 /**
@@ -326,29 +430,13 @@ export function directionFieldsForSurface(
  * exactly as two wired picker nodes of one family behave today.
  *
  * Exported so a client's "will inject into prompt" preview renders the exact
- * server output instead of re-implementing the fold.
+ * clauses the server does instead of re-implementing the fold. A preview of the
+ * assembled STRING needs `prompt-style-section.ts` on top: the look clauses in
+ * this list do not read in this position any more.
  */
 export function renderDirectionHints(
   direction: DirectionFields | undefined,
   opts: { surface: "image" | "video"; mode?: DirectionHintMode },
 ): string[] {
-  if (!direction) return []
-  const mode = opts.mode ?? "full"
-  const out: string[] = []
-  const seen = new Set<string>()
-  for (const spec of DIRECTION_FIELDS) {
-    if (spec.surface !== "both" && spec.surface !== opts.surface) continue
-    const ids = normalizeDirectionIds(
-      (direction as Record<string, unknown>)[spec.key],
-      spec.maxPicks,
-    )
-    if (ids.length === 0) continue
-    for (const hint of spec.render(ids, modeForFamily(mode, spec.family))) {
-      if (hint.length > 0 && !seen.has(hint)) {
-        seen.add(hint)
-        out.push(hint)
-      }
-    }
-  }
-  return out
+  return renderDirectionHintClauses(direction, opts).map((c) => c.text)
 }

package/src/hint-shedding.ts

@@ -0,0 +1,87 @@
+/**
+ * The shed arithmetic shared by the image (`assembleImageInput`) and video
+ * (`composeVideoPromptText`) cap-aware assemblers, so the two surfaces cannot
+ * drift in WHICH clause goes first when a provider's prompt cap overflows.
+ *
+ * Only the arithmetic lives here. Each surface keeps its own loop, because what
+ * they MEASURE differs: the image side reads `buildImagePrompt`'s
+ * `overflowChars` (the cap clamp reports how much it cut), while the video side
+ * measures the resolver-FRAMED body against the route's effective ceiling. Both
+ * hand this function the same question — "how many of the first `kept` clauses
+ * may stay if `deficit` characters have to leave the body?" — and both re-assemble
+ * and re-check afterwards.
+ *
+ * WHAT COUNTS AS A SHEDDABLE CLAUSE (both surfaces, one answer): every clause
+ * the platform RENDERED from catalog ids — the SUBJECT fold and the cinematic
+ * DIRECTION fold alike. They are decoration of the same class, so exempting
+ * either would not save it: the overflow would simply land in the provider's
+ * order-blind tail clamp, severing reference bindings or the end of the user's
+ * prose instead — precisely the bug this machinery exists to prevent. Never
+ * sheddable: the user's prose, the bound references and the framing text the
+ * reference resolver adds, and the structured fragment (user CONTENT).
+ *
+ * THE LIST IS A SURVIVAL ORDER, NOT A STRING ORDER. It was both until the
+ * `[style]` section landed; now a look clause is lifted out of the body and
+ * reads after every motion clause however early it folds
+ * (`prompt-style-section.ts`). Position here still answers exactly one question
+ * — who leaves first — and `clauseCosts` is how the caller tells this function
+ * what a clause actually costs in a shape it can no longer infer from the
+ * clause text alone.
+ */
+import { PROMPT_HINT_SEPARATOR } from "./prompt-hint-join.js"
+
+/**
+ * How many of the first `kept` hint clauses may STAY if `deficit`
+ * characters have to leave the body. Walks the fold order from the TAIL,
+ * subtracting each clause plus the separator it brought, and stops as soon as
+ * enough has been reclaimed.
+ *
+ * The name is historical (direction was the first and for a while the only
+ * channel); the list both callers pass is now the COMBINED fold —
+ * `[...subject, ...direction]` on both surfaces — so the shed order is that
+ * combined order REVERSED: the direction block empties first, then the subject
+ * block. Deliberate, and the reason the two folds share one list: a fully
+ * specified person renders ~30 clauses, so a subject fold left unsheddable
+ * would be the single biggest way to push an overflow into the order-blind
+ * clamp, while a decorative grade or ISO value survives.
+ *
+ * Within the direction block the order is `DIRECTION_FIELDS` order REVERSED
+ * (and within the subject block, `SUBJECT_FIELDS` reversed). Note what that
+ * is and is not: each table's order is a COMPATIBILITY order (grouped by family,
+ * with the legacy `DirectionFields` block pinned last so every pre-registry
+ * caller's fold stays byte-identical) — it is NOT a ranking of how load-bearing
+ * a dimension is, and this function does not claim one. Tail-first is chosen
+ * because it is deterministic, matches the fold order the API documents, and
+ * needs no second ordering to drift out of sync with the table. A caller mixing
+ * legacy keys with the newer ones can therefore lose e.g. `lightingId` before a
+ * decorative `isoValue` clause; if that ever matters, the fix is an explicit
+ * priority column on `DIRECTION_FIELDS`, not a second hand-kept list here.
+ *
+ * `clauseCosts[i]` is what clause `i` really adds to the assembled prompt.
+ * Without it each clause is charged its text plus one separator, which is what
+ * a clause folded inline costs — but a clause that lands in the `[style]`
+ * section carries section bytes too (the first one carries the whole header),
+ * and under-charging it makes this walk cover the deficit with MORE clauses
+ * than it needs. Both in-package callers pass exact composed-length deltas
+ * (`sectionedClauseCosts`); the default keeps the pre-section arithmetic for
+ * anyone else.
+ *
+ * Still deliberately approximate (assembly is not perfectly additive — a
+ * downstream frame can grow or shrink around the body); the caller re-assembles
+ * and re-checks, and this function strictly decreases `kept` whenever
+ * `deficit > 0`, so that loop terminates however the costs are priced.
+ */
+export function keepableDirectionHints(
+  hintClauses: readonly string[],
+  kept: number,
+  deficit: number,
+  clauseCosts?: readonly number[],
+): number {
+  let remaining = deficit
+  let next = kept
+  while (next > 0 && remaining > 0) {
+    next -= 1
+    remaining -= clauseCosts?.[next] ?? hintClauses[next]!.length + PROMPT_HINT_SEPARATOR.length
+  }
+  return next
+}

package/src/index.ts

@@ -19,7 +19,10 @@ export * from "./brand-tokens.js"
 export * from "./prompt-builder.js"
 export * from "./prompt-builder-structured-fields.js"
 export * from "./direction-registry.js"
+export * from "./subject-registry.js"
 export * from "./prompt-hint-join.js"
+export * from "./prompt-style-section.js"
+export * from "./hint-shedding.js"
 export * from "./video-reference-resolver.js"
 export * from "./sound-aggregator.js"
 export * from "./assemble-suno-input.js"

package/src/parameter-prompt-hint.ts

@@ -38,7 +38,7 @@ import { composeCameraMotionHintFromConnections } from "./camera-motions.js"
 import { composeTransitionHintFromConnections, type TransitionDuration, type TransitionIntensity, type TransitionPosition, type TransitionTiming } from "./transitions.js"
 import { composeCharacterFxHintFromConnections, type CharacterFxDuration, type CharacterFxIntensity, type CharacterFxPosition, type CharacterFxTiming } from "./character-fx.js"
 import { buildMaterialHints } from "./materials.js"
-import { getAnimal } from "@nodaro/shared"
+import { getAnimalPromptHint, getAnimalTerm } from "@nodaro/shared"
 import { getVehicle } from "@nodaro/shared"
 import { getWeapon } from "@nodaro/shared"
 import { getFurniture } from "@nodaro/shared"
@@ -322,15 +322,16 @@ function resolveBaseHint(
       return withCustomText(data, byMode(mode, getLoopSubjectPromptHint, getLoopSubjectTerm)(asStr(data.loopSubject)))
     case "material":
       return withCustomText(data, buildMaterialHints(data.material, mode))
-    case "animal": {
-      const animal = getAnimal(asStr(data.animal))
+    // Animal is the one Object-entity catalog whose phrasing has a single
+    // owner: `@nodaro/shared`'s `getAnimalPromptHint` / `getAnimalTerm`, which
+    // the picker-catalog funnel calls too. Both getters already return "" on a
+    // miss, so the entry lookup and the `animal ? … : ""` guard are the
+    // getters' job now, not this switch's.
+    case "animal":
       return withCustomText(
         data,
-        animal
-          ? byMode(mode, `featuring a ${animal.label.toLowerCase()}, ${animal.description}`, objectEntityTerm(animal))
-          : "",
+        byMode(mode, getAnimalPromptHint, getAnimalTerm)(asStr(data.animal)),
       )
-    }
     case "vehicle": {
       const vehicle = getVehicle(asStr(data.vehicle))
       return withCustomText(