@nodaro/prompts 1.15.0 → 1.17.0

package/src/__tests__/person-exposure-hints.test.ts

@@ -14,15 +14,15 @@ describe("exposure hint collapsing", () => {
     const hints = buildPersonHints({
       distinctiveFeature: ["feature-midriff-visible", "feature-navel-visible"],
     } as never)
-    const exposure = hints.filter((h) => /midriff|navel|stomach/i.test(h))
-    expect(exposure).toEqual(["wearing a cropped style, midriff and navel visible"])
+    const exposure = hints.filter((h) => /cropped hemline|navel|stomach/i.test(h))
+    expect(exposure).toEqual(["with a cropped hemline and the navel showing"])
   })
 
   it("each alone keeps its own (softened, garment-language) hint", () => {
     const midriffOnly = buildPersonHints({
       distinctiveFeature: ["feature-midriff-visible"],
     } as never)
-    expect(midriffOnly).toContain("wearing a cropped style with the midriff visible")
+    expect(midriffOnly).toContain("with a cropped hemline")
     expect(midriffOnly.join(" ")).not.toMatch(/bare stomach/i)
 
     const navelOnly = buildPersonHints({
@@ -40,7 +40,7 @@ describe("exposure hint collapsing", () => {
         "feature-freckles",
       ],
     } as never)
-    expect(hints.filter((h) => /midriff/i.test(h))).toHaveLength(1)
+    expect(hints.filter((h) => /cropped hemline/i.test(h))).toHaveLength(1)
     expect(hints.length).toBeGreaterThan(1)
   })
 })
@@ -59,3 +59,58 @@ describe("bold-lips cross-catalog dedupe", () => {
     expect(hints.join(" ")).toMatch(/bold lips/i)
   })
 })
+
+describe("cropped-clause de-stack across the person↔styling boundary (W1-b)", () => {
+  it("the midriff person clause suppresses BOTH styling cropped twins on the shared bag", () => {
+    const hints = buildStylingHints({
+      distinctiveFeature: ["feature-midriff-visible"],
+      top: "top-crop-top",
+      wardrobeState: ["state-cropped"],
+    } as never)
+    const joined = hints.join(", ")
+    expect(joined).not.toMatch(/cropped top|cropped above the midriff/i)
+  })
+
+  it("without the person clause, the garment wins and the modifier yields", () => {
+    const hints = buildStylingHints({
+      top: "top-crop-top",
+      wardrobeState: ["state-cropped"],
+    } as never)
+    const joined = hints.join(", ")
+    expect(joined).toMatch(/wearing a cropped top that ends above the midriff/i)
+    expect(joined).not.toMatch(/the top cropped above the midriff with the stomach visible/i)
+  })
+
+  it("a MINOR who picks midriff + crop-top still gets exactly one cropped clause", () => {
+    // The person clause is dropped by the floor (feature-midriff-visible is
+    // adultOnly), so the styling twin must NOT be suppressed — otherwise the
+    // floor silently deletes a garment detail instead of a body detail.
+    const hints = buildStylingHints({
+      age: "age-child",
+      distinctiveFeature: ["feature-midriff-visible"],
+      top: "top-crop-top",
+    } as never)
+    expect(hints.join(", ")).toMatch(/wearing a cropped top that ends above the midriff/i)
+  })
+
+  it("either styling id alone is untouched (no person clause, no twin)", () => {
+    expect(buildStylingHints({ wardrobeState: ["state-cropped"] } as never).join(", "))
+      .toMatch(/the top cropped above the midriff/i)
+    expect(buildStylingHints({ top: "top-crop-top" } as never).join(", "))
+      .toMatch(/wearing a cropped top/i)
+  })
+
+  it("de-stacks a BARE-STRING wardrobeState too, not just the array form", () => {
+    // `wardrobeState` is a single-pick-or-multi field (string | string[]), and
+    // `normalizeSubjectFields` unwraps a lone array pick to a bare string
+    // before the styling collector ever sees it — the single-pick case is the
+    // common one, not an edge case, so the suppression must not be array-only.
+    const hints = buildStylingHints({
+      distinctiveFeature: "feature-midriff-visible",
+      top: "top-crop-top",
+      wardrobeState: "state-cropped",
+    } as never)
+    const joined = hints.join(", ")
+    expect(joined).not.toMatch(/cropped top|cropped above the midriff/i)
+  })
+})

package/src/__tests__/retired-hint-strings.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest"
+import { getAdultOnlyHintStrings, RETIRED_ADULT_ONLY_HINT_STRINGS } from "../age-floor.js"
+
+/**
+ * W1-b (spec 2026-09-01 §3.3) rewords 17 catalog hints that W1-a (PR 2) had
+ * flagged `adultOnly`. The backend `minor-age-floor` policy strips sentences
+ * by STRING, so a rewording silently narrows the floor for every consumer
+ * still on the pre-rephrase `@nodaro/prompts` — including person.nodaro.ai,
+ * whose client-assembled `seedPrompt` is precisely how the 2026-07-30 P0
+ * prompts carried `state-fitted`'s clause to the provider.
+ *
+ * The retired strings therefore stay in the strip set forever. A retired
+ * string can only over-strip, and only for a subject already judged a minor.
+ */
+describe("retired adult-only wording stays inside the floor", () => {
+  it("every retired string is still returned by getAdultOnlyHintStrings()", () => {
+    const live = new Set(getAdultOnlyHintStrings())
+    const missing = RETIRED_ADULT_ONLY_HINT_STRINGS.filter((s) => !live.has(s.toLowerCase()))
+    expect(missing, "retired strings dropped out of the floor").toEqual([])
+  })
+
+  it("the 2026-07-30 incident clause is in the set by name", () => {
+    expect(getAdultOnlyHintStrings()).toContain(
+      "the clothing fitted and form-conscious, hugging the contours of the body",
+    )
+    expect(getAdultOnlyHintStrings()).toContain("wearing a cropped style, midriff and navel visible")
+    expect(getAdultOnlyHintStrings()).toContain("with lips slightly parted, taking a soft breath")
+  })
+
+  it("the NEW wording is a live needle too — the floor tracks the rephrase forward", () => {
+    // The derivation makes this true by construction, but nothing else states
+    // it: a future edit that drops a hint under the `length >= 8` filter, or
+    // an entry quietly losing `adultOnly`, would narrow the floor silently.
+    // (Green only after Task 5; see that task's Step 7 run set.)
+    const strings = getAdultOnlyHintStrings()
+    expect(strings).toContain("tailored, close-fitting clothing")
+    expect(strings).toContain("with a cropped hemline")
+  })
+
+  it("no bare derived TERM leaked into the needle set (the promptHint-only contract)", () => {
+    const strings = getAdultOnlyHintStrings()
+    for (const t of ["lounging", "cropped top", "school uniform", "lying down", "wet clothing", "bare shoulders"]) {
+      expect(strings, `term "${t}" must never be a needle`).not.toContain(t)
+    }
+  })
+
+  it("every retired string is lower-case and long enough to survive the length filter", () => {
+    for (const s of RETIRED_ADULT_ONLY_HINT_STRINGS) {
+      expect(s, s).toBe(s.toLowerCase())
+      expect(s.length, s).toBeGreaterThanOrEqual(8)
+    }
+  })
+
+  it("the set covers all 15 flagged rephrased entries plus the fold literal", () => {
+    // 15 flagged promptHints (the 14 flagged person/styling entries plus the
+    // pose twin) + the hard-coded fold literal = 16. `promptHint`s only —
+    // never terms. A change to the count must be a deliberate edit here, not
+    // a silent drift.
+    expect(RETIRED_ADULT_ONLY_HINT_STRINGS.length).toBe(16)
+  })
+
+  it("the list is longest-first, matching getAdultOnlyHintStrings' contract", () => {
+    const strings = getAdultOnlyHintStrings()
+    for (let i = 1; i < strings.length; i++) {
+      expect(strings[i - 1].length).toBeGreaterThanOrEqual(strings[i].length)
+    }
+  })
+})

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

@@ -218,7 +218,7 @@ describe("renderSubjectHints — the flat-bag behaviors", () => {
       { distinctiveFeature: ["feature-midriff-visible", "feature-navel-visible"] },
       IMAGE,
     )
-    expect(out).toEqual(["wearing a cropped style, midriff and navel visible"])
+    expect(out).toEqual(["with a cropped hemline and the navel showing"])
   })
 
   it("de-duplicates an exact repeated clause, first occurrence winning", () => {

package/src/__tests__/w1b-rephrase.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest"
+import { PEOPLE } from "../person.js"
+import { STYLINGS } from "../styling.js"
+import { POSES } from "../pose.js"
+import { PICKER_CATALOGS } from "../picker-catalogs.js"
+import { RETIRED_ADULT_ONLY_HINT_STRINGS } from "../age-floor.js"
+
+/**
+ * W1-b — spec 2026-09-01-app-reports-triage-design.md §3.3, wording approved
+ * by §10 decisions 1 and 6.
+ *
+ * 12 adult `generate-character` prompts were refused by the provider's safety
+ * filter because stacked picker fragments read as sexualized. The principle:
+ * describe the garment or the look, not exposed skin; drop
+ * "wet / sheen / exposed / bare / hugging / soft breath"; keep the attribute
+ * renderable.
+ *
+ * SCOPE RULING, LATER RESOLVED (replay-harness verdict, internal validation
+ * results, 2026-09-02): the go/no-go criterion initially failed for TWO
+ * entries — `eye-state-half-lidded` and `feature-collarbone-visible`
+ * rendered their attribute 0/10 and 0/22 times under either wording, so
+ * their approved rewording could not be validated at the time and both
+ * shipped byte-identical in the original W1-b PR. A follow-up replay on
+ * staging found wordings that DO render, approved 2026-09-03. Both are now
+ * included in PERSON_EXPECTED below with BOTH `promptHint` and `term`
+ * reworded, like every other entry — the compact-mode term is not left
+ * carrying the old wording.
+ *
+ * This file pins BOTH fields of every reworded entry — `promptHint` (verbose
+ * mode) and `term` (compact mode) — because a rephrase that touched only one
+ * of them would leave the old wording reachable through the other. The last
+ * test is the ratchet: no retired string may reappear anywhere in the
+ * catalog corpus.
+ */
+
+interface Expected {
+  readonly id: string
+  readonly promptHint: string
+  readonly term: string
+}
+
+const PERSON_EXPECTED: ReadonlyArray<Expected> = [
+  { id: "bust-very-full", promptHint: "a fuller bust", term: "fuller bust" },
+  { id: "silhouette-hourglass", promptHint: "an hourglass figure", term: "hourglass figure" },
+  { id: "waist-defined", promptHint: "a defined waistline", term: "defined waistline" },
+  { id: "lip-state-glossy", promptHint: "with a glossy lip finish", term: "glossy lips" },
+  { id: "lip-state-parted", promptHint: "with lips relaxed and slightly open, as if mid-sentence", term: "lips slightly open" },
+  { id: "lip-state-bitten", promptHint: "lightly biting the lower lip", term: "biting lower lip" },
+  { id: "eye-state-staring-camera", promptHint: "looking directly into the camera", term: "direct gaze to camera" },
+  { id: "eye-state-half-lidded", promptHint: "with drowsy, partly closed eyes, the lids sitting low over the iris", term: "drowsy, partly closed eyes" },
+  { id: "texture-dewy", promptHint: "with dewy, luminous skin", term: "dewy skin" },
+  { id: "texture-glistening", promptHint: "with a light glistening sheen on the skin", term: "glistening sheen" },
+  { id: "texture-baby-soft", promptHint: "with soft, fine-pored skin", term: "soft fine-pored skin" },
+  { id: "texture-shower-fresh-wet", promptHint: "with fresh, water-dappled skin as if just out of the shower", term: "water-dappled skin" },
+  { id: "feature-bare-shoulders", promptHint: "with the shoulders uncovered", term: "shoulders uncovered" },
+  { id: "feature-collarbone-visible", promptHint: "with an open neckline that leaves the collarbones uncovered", term: "open neckline, collarbones uncovered" },
+  { id: "feature-midriff-visible", promptHint: "with a cropped hemline", term: "cropped hemline" },
+]
+
+const STYLING_EXPECTED: ReadonlyArray<Expected> = [
+  { id: "state-fitted", promptHint: "tailored, close-fitting clothing", term: "close-fitting clothing" },
+  { id: "state-wet", promptHint: "the clothing soaked through and dripping", term: "soaked clothing" },
+]
+
+const POSE_EXPECTED: ReadonlyArray<Expected> = [
+  { id: "biting-lip", promptHint: "lightly biting the lower lip, a subtle playful expression", term: "biting lower lip" },
+]
+
+function check(catalog: ReadonlyArray<{ id: string; promptHint: string; term?: string }>, expected: ReadonlyArray<Expected>) {
+  for (const want of expected) {
+    const entry = catalog.find((e) => e.id === want.id)
+    expect(entry, `missing entry ${want.id}`).toBeDefined()
+    expect(entry!.promptHint, `${want.id}.promptHint`).toBe(want.promptHint)
+    expect(entry!.term, `${want.id}.term (authored, not label-derived)`).toBe(want.term)
+  }
+}
+
+describe("W1-b rephrase — the 17 reworded entries plus the pose twin", () => {
+  it("person entries carry the approved promptHint and term", () => {
+    check(PEOPLE, PERSON_EXPECTED)
+  })
+
+  it("eye-state-half-lidded and feature-collarbone-visible keep adultOnly through the rework", () => {
+    const halfLidded = PEOPLE.find((e) => e.id === "eye-state-half-lidded")
+    expect(halfLidded?.adultOnly).toBe(true)
+
+    const collarbone = PEOPLE.find((e) => e.id === "feature-collarbone-visible")
+    expect(collarbone?.adultOnly).toBe(true)
+  })
+
+  it("styling entries carry the approved promptHint and term", () => {
+    check(STYLINGS, STYLING_EXPECTED)
+  })
+
+  it("the pose twin of lip-state-bitten is reworded to match", () => {
+    check(POSES, POSE_EXPECTED)
+  })
+
+  it("all 18 ids are covered — the count is deliberate, not incidental", () => {
+    expect(PERSON_EXPECTED.length + STYLING_EXPECTED.length + POSE_EXPECTED.length).toBe(18)
+  })
+
+  it("RATCHET: no retired string survives anywhere in the catalog corpus", () => {
+    const offenders: string[] = []
+    for (const cat of PICKER_CATALOGS) {
+      const options = [...(cat.options ?? []), ...(cat.dimensions ?? []).flatMap((d) => d.options)]
+      for (const o of options) {
+        for (const retired of RETIRED_ADULT_ONLY_HINT_STRINGS) {
+          // The fold literal is not an entry field; it is pinned separately in
+          // person-exposure-hints.test.ts.
+          if (o.promptHint === retired || o.term === retired) {
+            offenders.push(`${cat.catalogId} • ${o.id} • "${retired}"`)
+          }
+        }
+      }
+    }
+    expect(offenders, `retired wording is still live:\n${offenders.join("\n")}`).toEqual([])
+  })
+})

package/src/age-floor.ts

@@ -65,10 +65,73 @@ export function getAdultOnlyIds(): ReadonlySet<string> {
   return new Set(getAdultOnlyEntries().map((e) => e.id))
 }
 
+/**
+ * The pre-rework `promptHint` of every `adultOnly` entry the spec
+ * (2026-09-01-app-reports-triage-design §3.3) listed for rewording — including
+ * `eye-state-half-lidded` and `feature-collarbone-visible`, which the W1-b
+ * harness initially left byte-identical (0/10 and 0/22 render rate under
+ * either wording) and a 2026-09-03 replay then found renderable wordings for
+ * — plus the hard-coded midriff+navel fold clause. These strings are permanently part of the strip
+ * set: a consumer that has not bumped `@nodaro/prompts` still emits them, and
+ * the client-assembled `seedPrompt` path is exactly how the 2026-07-30
+ * minor-age prompts reached a provider. Retiring can only ever cause an EXTRA
+ * strip, and only for a subject `isMinorAge` has already judged a minor — so
+ * the list only grows, never shrinks.
+ *
+ * `promptHint` ONLY, for the same reason `getAdultOnlyHintStrings` gives:
+ * `term` is short display vocabulary and the composed-catalog projection
+ * back-fills a derived `term` for every option, so terms collide with benign
+ * everyday text. Assembled prompts and client seedPrompts are built from
+ * hints, never from terms. The three W1-b entries that are NOT flagged —
+ * `texture-dewy`, `texture-baby-soft`, `eye-state-staring-camera` (spec
+ * §3.3's "deliberately not flagged" list) — are absent: their old wording
+ * never belonged to the floor.
+ *
+ * 15 flagged hints + the fold literal = 16.
+ */
+export const RETIRED_ADULT_ONLY_HINT_STRINGS: ReadonlyArray<string> = [
+  // bust-very-full
+  "very full bust",
+  // silhouette-hourglass
+  "hourglass silhouette",
+  // waist-defined
+  "defined waist",
+  // lip-state-glossy
+  "with high-shine glossy wet-look lips",
+  // lip-state-parted
+  "with lips slightly parted, taking a soft breath",
+  // lip-state-bitten
+  "playfully biting the lower lip",
+  // eye-state-half-lidded
+  "with heavy half-lidded sleepy eyes",
+  // texture-glistening
+  "with glistening skin, sweat or oil catching the light",
+  // texture-shower-fresh-wet
+  "with just-out-of-the-shower wet skin, water beading on the surface and rolling in slow droplets down the curves of the body",
+  // feature-bare-shoulders
+  "with bare shoulders exposed, the line of the collarbone and shoulder muscles uncovered",
+  // feature-collarbone-visible
+  "with a prominent collarbone clearly defined and catching the light",
+  // feature-midriff-visible
+  "wearing a cropped style with the midriff visible",
+  // state-fitted — the 2026-07-30 incident clause
+  "the clothing fitted and form-conscious, hugging the contours of the body",
+  // state-wet
+  "the clothing soaked and wet, the fabric clinging to the body and dripping water",
+  // pose `biting-lip` (the lip-state-bitten twin)
+  "biting the lower lip with a subtle playful expression",
+  // the hard-coded midriff+navel fold in emitIndependentFragments — not any
+  // entry's hint, so retiring it ADDS a needle for a clause that really is
+  // emitted verbatim.
+  "wearing a cropped style, midriff and navel visible",
+]
+
 /** Every full prompt-hint string a flagged entry can inject, lower-cased,
  *  longest first — the backend policy strips text that contains any of them
  *  (Layer 2), which is how flagged wording arriving inside free text (a
- *  client-assembled seedPrompt) is caught.
+ *  client-assembled seedPrompt) is caught. Seeded with
+ *  `RETIRED_ADULT_ONLY_HINT_STRINGS` so a catalog rewording can never narrow
+ *  the strip set for a consumer still shipping the pre-rephrase wording.
  *
  *  `promptHint` ONLY, deliberately — `term` is analyzer/UI vocabulary
  *  (compact-mode display), and `picker-catalogs.ts`'s composed-catalog
@@ -81,7 +144,7 @@ export function getAdultOnlyIds(): ReadonlySet<string> {
  *  can actually arrive verbatim in free text — terms don't need to be (and
  *  must not be) swept here. */
 export function getAdultOnlyHintStrings(): ReadonlyArray<string> {
-  const out = new Set<string>()
+  const out = new Set<string>(RETIRED_ADULT_ONLY_HINT_STRINGS)
   for (const e of getAdultOnlyEntries()) {
     if (e.promptHint) out.add(e.promptHint.toLowerCase())
   }

package/src/assemble-image-input.ts

@@ -60,7 +60,7 @@ import {
   type SlottedPromptClause,
 } from "./prompt-style-section.js"
 import { keepableDirectionHints } from "./hint-shedding.js"
-import type { CharacterDef, ConnectedReference, IdentityMeta } from "@nodaro/shared"
+import type { CharacterDef, ConnectedReference, DescribedReference, IdentityMeta } from "@nodaro/shared"
 
 /**
  * Flat cinematic-direction ids the Studio framing UI, the MCP route and the
@@ -98,6 +98,13 @@ export interface AssembleImageInput {
    * (gated per provider there). Omit when the caller wires only raw URLs.
    */
   connectedReferences?: ConnectedReference[]
+  /**
+   * References the caller can NAME and DESCRIBE but has no media for — an
+   * un-bound cast role, an analysis slot. They attach no URL and claim no
+   * `Image N` slot; `buildImagePrompt` renders them as prose. Present with no
+   * `connectedReferences` is the normal case, so they are forwarded on their own.
+   */
+  describedReferences?: readonly DescribedReference[]
   /**
    * Flat cinematic-direction ids → folded into the prompt as hints. Studio /
    * MCP-route use, and the platform callers' narrow-read of a node's STORED
@@ -295,6 +302,9 @@ export function assembleImageInput(
     ...(input.connectedReferences !== undefined
       ? { connectedReferences: input.connectedReferences }
       : {}),
+    ...(input.describedReferences !== undefined
+      ? { describedReferences: input.describedReferences }
+      : {}),
     // Manual uploads / direct refs ride the builder's reference-URL channel so
     // the per-provider reference gate filters them alongside bound entities.
     // Omit the field entirely when absent so the builder's default ([]) kicks

package/src/described-references.ts

@@ -0,0 +1,138 @@
+/**
+ * Described references + per-reference description overrides + rail captions —
+ * the ONE place either lane phrases "what this reference IS".
+ *
+ * Three shapes, one grammar (`<subject> — <description>.`) plus the caption's
+ * `<binding>: <caption>.`:
+ *
+ *   - a DESCRIBED reference (`DescribedReference`, no media) → `Natalie — a
+ *     tall woman in a red coat.` The subject is the NAME, because a described
+ *     reference has no seat to bind to: correlation with the prose is by name,
+ *     which is why the caller leaves the name in the prompt rather than an
+ *     indexed `@slug:N` mention (that grammar is url-gated).
+ *   - a per-use `descriptionOverride` on a reference the HYBRID format gives no
+ *     description slot (a mention / canonical-fallback / location / object role
+ *     phrase carries none) → `reference image A — a tall woman in a red coat.`
+ *     Same grammar, the BINDING as the subject. Where a description slot DOES
+ *     exist (every legacy bullet, and the hybrid extras' `, <desc>` clause) the
+ *     override fills THAT slot instead, so the model is never told twice.
+ *   - a rail CAPTION for a video / audio reference → `@video_1: the establishing
+ *     drone shot.` Index-aligned with the caller's url array.
+ *
+ * Rendering is separate from JOINING on purpose: the lines are format-agnostic
+ * text, and each lane already owns where a trailing directive goes (the image
+ * hybrid's `trailingLines`, the video core's `trailingLines` /
+ * `allFallbackLines`). `appendReferenceLines` is the joiner for the call sites
+ * that have no such array to push into — it bullets the lines into the legacy
+ * "Use these characters:" block or lands them ahead of the `[style]` section in
+ * hybrid, matching what each lane's own assembly does.
+ */
+
+import type { DescribedReference } from "@nodaro/shared"
+import { insertBeforeStyleSection } from "./prompt-style-section.js"
+
+/** Which reference-prompt format the lines are being rendered for. */
+export type ReferenceLineFormat = "legacy" | "hybrid"
+
+/** The legacy directive block every lane consolidates its bullets into. */
+const CHARACTER_BLOCK_HEADER = "Use these characters:"
+
+/**
+ * The ONE phrasing for "this subject is described as …":
+ * `<subject> — <description>.`
+ *
+ * `subject` is the name for a described reference and the reference's binding
+ * (`reference image A` / `@image_2`) for a per-use description override. Both
+ * halves are trimmed; an empty half yields `""` (the caller drops the line).
+ */
+export function referenceDescriptionLine(
+  subject: string,
+  description: string | null | undefined,
+): string {
+  const s = subject.trim()
+  const d = description?.trim()
+  if (!s || !d) return ""
+  return `${s} — ${d}.`
+}
+
+/**
+ * Render the described references (name + description, no media) as trailing
+ * lines. Entries missing either half contribute nothing; entries repeating a
+ * name (case-insensitively) render once — a description a caller sent twice
+ * says nothing new to the model, and every sibling renderer in both lanes
+ * dedups the same way.
+ */
+export function renderDescribedReferenceLines(
+  refs: readonly DescribedReference[] | undefined,
+): string[] {
+  if (!refs || refs.length === 0) return []
+  const lines: string[] = []
+  const seen = new Set<string>()
+  for (const r of refs) {
+    const key = r.name?.trim().toLowerCase()
+    if (!key || seen.has(key)) continue
+    const line = referenceDescriptionLine(r.name, r.description)
+    if (!line) continue
+    seen.add(key)
+    lines.push(line)
+  }
+  return lines
+}
+
+/**
+ * Render the video / audio rail captions as `@video_N: <caption>.` /
+ * `@audio_N: <caption>.` lines, index-aligned with the caller's url arrays.
+ *
+ * Each list is bounded by the count of references of that kind that actually
+ * ship, so a caption for a url the provider cap dropped never binds a phantom
+ * `@video_N`. Blank captions are holes in an aligned array, not lines.
+ */
+export function renderReferenceCaptionLines(
+  videoCaptions: readonly string[] | undefined,
+  audioCaptions: readonly string[] | undefined,
+  counts: { readonly video: number; readonly audio: number },
+): string[] {
+  const lines: string[] = []
+  const render = (captions: readonly string[] | undefined, kind: "video" | "audio", cap: number) => {
+    if (!captions) return
+    for (let i = 0; i < captions.length && i < cap; i++) {
+      const text = captions[i]?.trim()
+      if (!text) continue
+      lines.push(`@${kind}_${i + 1}: ${text}.`)
+    }
+  }
+  render(videoCaptions, "video", counts.video)
+  render(audioCaptions, "audio", counts.audio)
+  return lines
+}
+
+/**
+ * Append reference lines to an assembled prompt the way the surrounding lane
+ * would have.
+ *
+ *   - hybrid → trailing scene directives ahead of the `[style]` section (the
+ *     section has no terminator, so a flat append would read as one more look
+ *     clause).
+ *   - legacy → `- ` bullets consolidated into the existing
+ *     "Use these characters:" block, or a new block prepended ahead of the
+ *     body — the same splice-or-create both lanes already do for their
+ *     canonical-fallback and extra-ref bullets.
+ *
+ * No lines → the prompt is returned unchanged, byte-for-byte.
+ */
+export function appendReferenceLines(
+  prompt: string,
+  lines: readonly string[],
+  format: ReferenceLineFormat,
+): string {
+  if (lines.length === 0) return prompt
+  if (format === "hybrid") return insertBeforeStyleSection(prompt, lines)
+  const bullets = lines.map((l) => `- ${l}`).join("\n")
+  if (prompt.startsWith(`${CHARACTER_BLOCK_HEADER}\n`)) {
+    const splitIdx = prompt.indexOf("\n\n")
+    if (splitIdx === -1) return `${prompt}\n${bullets}`
+    return `${prompt.slice(0, splitIdx)}\n${bullets}${prompt.slice(splitIdx)}`
+  }
+  const block = `${CHARACTER_BLOCK_HEADER}\n${bullets}`
+  return prompt ? `${block}\n\n${prompt}` : block
+}

package/src/index.ts

@@ -16,6 +16,7 @@ export * from "./term.js"
 export * from "./parameter-prompt-hint.js"
 export * from "./entity-prompts.js"
 export * from "./brand-tokens.js"
+export * from "./described-references.js"
 export * from "./prompt-builder.js"
 export * from "./prompt-builder-structured-fields.js"
 export * from "./direction-registry.js"