@nodaro/prompts 1.12.0 → 1.13.0

package/src/assemble-image-input.ts

@@ -44,7 +44,6 @@ import {
   type StructuredPromptFields,
 } from "./prompt-builder-structured-fields.js"
 import {
-  renderDirectionHints,
   IMAGE_HINT_MODE_DEFAULT,
   type DirectionFields,
 } from "./direction-registry.js"
@@ -53,7 +52,13 @@ import {
   SUBJECT_IMAGE_HINT_MODE_DEFAULT,
   type SubjectFields,
 } from "./subject-registry.js"
-import { joinPromptHints } from "./prompt-hint-join.js"
+import {
+  asBodyClauses,
+  composeSectionedPrompt,
+  partitionStyleClauses,
+  sectionedClauseCosts,
+  type SlottedPromptClause,
+} from "./prompt-style-section.js"
 import { keepableDirectionHints } from "./hint-shedding.js"
 import type { CharacterDef, ConnectedReference, IdentityMeta } from "@nodaro/shared"
 
@@ -174,17 +179,23 @@ export interface AssembleImageInput {
  * 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.
+ * ends the BODY, exactly as before — the `[style]` section reads after it.
+ *
+ * Each clause carries the SLOT it reads in. The list order is the SURVIVAL
+ * order; it stopped being the string order when the look clauses lifted into
+ * the section (`prompt-style-section.ts`). On this surface every direction row
+ * is `look` — the registry has no image-surface motion row — so an image
+ * `[style]` section carries the whole direction fold.
  */
 interface ImageHintPieces {
   /** Subject clauses then direction clauses, each in its registry's fold order. */
-  readonly hintClauses: readonly string[]
+  readonly hintClauses: readonly SlottedPromptClause[]
   /** 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
+ * Render the fold's hint pieces once, so the cap-aware retry can re-compose 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
@@ -192,7 +203,7 @@ interface ImageHintPieces {
  *
  * 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.
+ * IS the direction fold, so every existing caller sheds identically.
  */
 function renderImageHintPieces(
   subject: SubjectFields | undefined,
@@ -201,15 +212,17 @@ function renderImageHintPieces(
 ): ImageHintPieces {
   return {
     hintClauses: [
-      ...renderSubjectHints(subject, {
-        surface: "image",
-        mode: SUBJECT_IMAGE_HINT_MODE_DEFAULT,
-      }),
-      ...renderDirectionHints(direction, {
+      ...asBodyClauses(
+        renderSubjectHints(subject, {
+          surface: "image",
+          mode: SUBJECT_IMAGE_HINT_MODE_DEFAULT,
+        }),
+      ),
+      ...partitionStyleClauses(direction, {
         surface: "image",
         mode: IMAGE_HINT_MODE_DEFAULT,
       }),
-    ].filter((p) => p.length > 0),
+    ].filter((c) => c.text.length > 0),
     structuredFragment: structured ? renderStructuredFields(structured) : "",
   }
 }
@@ -218,32 +231,34 @@ function renderImageHintPieces(
  * 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.
+ * shed). The structured fragment always ends the body; the look clauses that
+ * survived follow it in the `[style]` section.
  *
  * 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
+ * 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. 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.
+ * A node that DOES carry `direction`/`structured` takes the fold branch and is
+ * therefore trimmed — a `[style]` section counts as folded even when the body
+ * gained nothing. 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 = [
-    ...pieces.hintClauses.slice(0, keptHintClauses),
+  return composeSectionedPrompt(
+    userPrompt,
+    pieces.hintClauses.slice(0, keptHintClauses),
     pieces.structuredFragment,
-  ].filter((p) => p.length > 0)
-  return joinPromptHints(userPrompt, hints)
+  )
 }
 
 /**
@@ -318,9 +333,19 @@ export function assembleImageInput(
   // 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)
+  if (fitted.overflowChars > 0) {
+    // 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(
+      input.userPrompt,
+      pieces.hintClauses,
+      pieces.structuredFragment,
+    )
+    const texts = pieces.hintClauses.map((c) => c.text)
+    while (fitted.overflowChars > 0 && kept > 0) {
+      kept = keepableDirectionHints(texts, kept, fitted.overflowChars, costs)
+      fitted = assembleWith(kept)
+    }
   }
   // `overflowChars` is assembly bookkeeping, not part of the callers' contract.
   const { overflowChars, ...result } = fitted

package/src/assemble-video-input.ts

@@ -11,8 +11,9 @@
  *
  * 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`).
@@ -24,6 +25,13 @@
  * 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). The
@@ -49,10 +57,10 @@
  * `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,
@@ -63,7 +71,12 @@ import {
   type SubjectFields,
   type SubjectHintMode,
 } from "./subject-registry.js"
-import { joinPromptHints } from "./prompt-hint-join.js"
+import {
+  asBodyClauses,
+  composeSectionedPrompt,
+  partitionStyleClauses,
+  sectionedClauseCosts,
+} from "./prompt-style-section.js"
 import { keepableDirectionHints } from "./hint-shedding.js"
 import {
   renderStructuredFields,
@@ -90,9 +103,10 @@ import {
  *    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:
+ *    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.
  *
@@ -121,10 +135,11 @@ export interface VideoPromptCapOptions {
  * 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.
+ * 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
@@ -194,33 +209,33 @@ export function composeVideoPromptText(
   // 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.
+  // 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 = [
-    ...renderSubjectHints(opts?.subject, {
-      surface: "video",
-      mode: opts?.subjectHintMode ?? SUBJECT_VIDEO_HINT_MODE_DEFAULT,
-    }),
-    ...renderDirectionHints(direction, {
+    ...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,
     }),
-  ].filter((p) => p.length > 0)
-  // User CONTENT, not a garnish: never sheddable, always last.
+  ].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) : ""
 
-  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)
-  }
+  // 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)
@@ -235,8 +250,13 @@ export function composeVideoPromptText(
   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(hintClauses, kept, framedLength - cap)
+    kept = keepableDirectionHints(texts, kept, framedLength - cap, costs)
     body = composeWith(kept)
     framedLength = frame(body)?.length ?? 0
   }

package/src/direction-registry.ts

@@ -72,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 {
   /**
@@ -89,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
   /**
@@ -160,16 +181,20 @@ const temporal = perId(getTemporalPromptHint, getTemporalTerm)
  * would wrongly suppress a legal second selection. Overlap is handled instead
  * by the exact-string dedupe in `renderDirectionHints`.
  *
- * SECOND MEANING OF 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 also 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. 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.
+ * 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
@@ -189,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).
@@ -203,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) },
@@ -217,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.
@@ -235,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"]
@@ -260,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
@@ -321,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
 }
 
 /**
@@ -343,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

@@ -19,6 +19,14 @@
  * 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"
 
@@ -49,20 +57,31 @@ import { PROMPT_HINT_SEPARATOR } from "./prompt-hint-join.js"
  * decorative `isoValue` clause; if that ever matters, the fix is an explicit
  * priority column on `DIRECTION_FIELDS`, not a second hand-kept list here.
  *
- * Deliberately approximate (assembly is not perfectly additive); the caller
- * re-assembles and re-checks, and this function strictly decreases `kept`
- * whenever `deficit > 0`, so that loop terminates.
+ * `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 -= hintClauses[next]!.length + PROMPT_HINT_SEPARATOR.length
+    remaining -= clauseCosts?.[next] ?? hintClauses[next]!.length + PROMPT_HINT_SEPARATOR.length
   }
   return next
 }

package/src/index.ts

@@ -21,6 +21,7 @@ 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"