@nodaro/prompts 1.15.0 → 1.17.0

package/src/styling.ts

@@ -424,10 +424,10 @@ export const STYLINGS: ReadonlyArray<Styling> = [
 
   // -------------------- Wardrobe State (modifier — composes with any garment) --------------------
   { id: "state-oversized",     label: "Oversized",       dimension: "wardrobe-state", description: "Loose, oversized fit",      promptHint: "the clothing loose and oversized, draping freely well past the body", term: "oversized fit" },
-  { id: "state-fitted",        label: "Fitted",          dimension: "wardrobe-state", description: "Form-fitting silhouette",   promptHint: "the clothing fitted and form-conscious, hugging the contours of the body", term: "form-fitting clothing" , adultOnly: true },
+  { id: "state-fitted",        label: "Fitted",          dimension: "wardrobe-state", description: "Form-fitting silhouette",   promptHint: "tailored, close-fitting clothing", term: "close-fitting clothing" , adultOnly: true },
   { id: "state-cropped",       label: "Cropped",         dimension: "wardrobe-state", description: "Top cropped at midriff",    promptHint: "the top cropped above the midriff with the stomach visible", term: "cropped top" , adultOnly: true },
   { id: "state-sheer",         label: "Sheer",           dimension: "wardrobe-state", description: "Translucent fabric",        promptHint: "the fabric translucent and sheer, hinting at the silhouette underneath", term: "sheer clothing" , adultOnly: true },
-  { id: "state-wet",           label: "Wet",             dimension: "wardrobe-state", description: "Soaked, water-clinging",    promptHint: "the clothing soaked and wet, the fabric clinging to the body and dripping water", term: "wet clothing" , adultOnly: true },
+  { id: "state-wet",           label: "Wet",             dimension: "wardrobe-state", description: "Soaked, water-clinging",    promptHint: "the clothing soaked through and dripping", term: "soaked clothing" , adultOnly: true },
   { id: "state-ripped",        label: "Ripped",          dimension: "wardrobe-state", description: "Torn and frayed",           promptHint: "the fabric torn and ripped at the seams, with frayed edges", term: "ripped clothing" },
   { id: "state-distressed",    label: "Distressed",      dimension: "wardrobe-state", description: "Worn, faded, weathered",    promptHint: "the clothing distressed and weathered, with faded color and worn-down edges", term: "distressed clothing" },
   { id: "state-vintage",       label: "Vintage",         dimension: "wardrobe-state", description: "Worn, retro character",     promptHint: "the clothing carrying vintage character — softened color, broken-in fit, retro silhouette", term: "vintage clothing" },
@@ -651,6 +651,40 @@ function collectStylingFragments(
   const floored = isMinorAge(data as { age?: string; customAge?: number; type?: string })
   const emit = floored ? (id: string) => (getStyling(id)?.adultOnly === true ? "" : fragmentFor(id)) : fragmentFor
 
+  // W1-b (spec 2026-09-01 §3.3): three ids say "cropped" — the Person
+  // catalog's `feature-midriff-visible` and this catalog's `top-crop-top` and
+  // `state-cropped`. Stacked they read as three separate statements about a
+  // bare stomach, which is one of the compounds the safety classifiers flag.
+  // Same mechanism and same caveat as the bold-lips dedupe above: the subject
+  // fold hands BOTH builders one flat bag, so the person pick is readable
+  // here; a separate styling node carries no `distinctiveFeature` and this
+  // no-ops. Person leads the fold order, so the person clause wins; with no
+  // person clause the garment wins over the modifier.
+  const featureRaw = (data as Record<string, unknown>).distinctiveFeature
+  const midriffPicked = Array.isArray(featureRaw)
+    ? featureRaw.includes("feature-midriff-visible")
+    : featureRaw === "feature-midriff-visible"
+  // Gate on pick-minus-floor (`midriffPicked && !floored`), which equals EMISSION
+  // unless an overlay pack drops the entry — the same rule the midriff+navel fold
+  // uses (`fragmentFor(id) !== ""` inside `emitIndependentFragments`).
+  // `feature-midriff-visible` is `adultOnly`, so for a minor the person
+  // collector drops it; suppressing the styling twins as well would leave a
+  // minor who picked midriff AND crop-top with NO cropped clause at all.
+  // `floored` is the local computed just above from the same shared bag, so
+  // the two collectors cannot disagree.
+  const midriffAlready = midriffPicked && !floored
+  const cropTopPicked = (data as Record<string, unknown>).top === "top-crop-top"
+  // `top` is single-pick (always a bare string), but `wardrobeState` is
+  // declared `string | ReadonlyArray<string>` AND the subject-fold door
+  // (`normalizeSubjectFields`) unwraps a lone array pick down to a bare
+  // string — so a single "state-cropped" selection, the common case, arrives
+  // here as a plain string, not an array. The suppression must therefore be
+  // checked at BOTH emission sites below (the `typeof raw === "string"`
+  // branch and the `Array.isArray(raw)` branch), not just the array one.
+  const croppedSuppressed = (id: string): boolean =>
+    (id === "top-crop-top" && midriffAlready) ||
+    (id === "state-cropped" && (midriffAlready || cropTopPicked))
+
   for (const dimension of STYLING_DIMENSION_ORDER) {
     const field = STYLING_FIELD_BY_DIMENSION[dimension]
     const raw = data[field]
@@ -658,11 +692,13 @@ function collectStylingFragments(
     // jewelry / wardrobe-state / hair-state are multi-pick (string | string[]);
     // emit each id's fragment independently and let the comma-join compose.
     if (typeof raw === "string" && raw.length > 0) {
+      if (croppedSuppressed(raw)) continue
       const fragment = emit(raw)
       if (fragment) out.push(fragment)
     } else if (Array.isArray(raw)) {
       for (const item of raw) {
         if (typeof item !== "string" || item.length === 0) continue
+        if (croppedSuppressed(item)) continue
         const fragment = emit(item)
         if (fragment) out.push(fragment)
       }

package/src/video-reference-resolver.ts

@@ -32,7 +32,13 @@ import { findCharacterMentionTokens, type CharacterMentionTokenInfo } from "@nod
 import { resolveCharacterMentions, applyReferenceOrderToVideo } from "./prompt-builder.js"
 import { roleToPhrase, REFERENCE_ROLE_PRESETS, resolveDefaultRole } from "@nodaro/shared"
 import { buildIdentityLockLine, withForcedIdentityLock } from "./identity-lock.js"
-import type { ConnectedReference } from "@nodaro/shared"
+import type { ConnectedReference, DescribedReference } from "@nodaro/shared"
+import {
+  appendReferenceLines,
+  referenceDescriptionLine,
+  renderDescribedReferenceLines,
+  renderReferenceCaptionLines,
+} from "./described-references.js"
 import { REF_BINDING } from "./ref-binding.js"
 import { resolveRefIdTokens } from "./ref-id-tokens.js"
 import { insertBeforeStyleSection } from "./prompt-style-section.js"
@@ -152,6 +158,13 @@ export interface VideoExtraRef {
    * orchestrator extras leave this unset (they resolve via `CharacterMeta`).
    */
   defaultRole?: string
+  /**
+   * The `ConnectedReference.descriptionOverride` analogue — the PER-USE identity
+   * description for this extra. Fills the row's own description slot (the
+   * pair-back tail, the name-mode bullet, the first-sight descriptor), winning
+   * over `description`, which keeps its label semantics. Absent → unchanged.
+   */
+  descriptionOverride?: string
 }
 
 /**
@@ -230,6 +243,24 @@ export interface ResolveVideoReferenceCoreArgs {
    * The wired character refs' `defaultName`s are known without this.
    */
   refNamesById?: ReadonlyMap<string, string>
+  /**
+   * 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` seat: they are rendered as prose by `renderDescribedReferenceLines`
+   * and joined the way this lane joins its trailing directives. The
+   * described-ONLY request (no wired characters, no extras) is the normal case,
+   * so the early return below carries the join too.
+   */
+  describedReferences?: readonly DescribedReference[]
+  /**
+   * Captions for the node's video / audio rail references, INDEX-ALIGNED with
+   * the caller's `referenceVideoUrls` / `referenceAudioUrls`. Rendered as
+   * `@video_N: <caption>.` / `@audio_N: <caption>.` and bounded by
+   * `videoRefCount` / `audioRefCount`, so a caption for a url the provider cap
+   * dropped never binds a slot the payload does not ship.
+   */
+  videoCaptions?: readonly string[]
+  audioCaptions?: readonly string[]
 }
 
 /** Result of the HYBRID mention pass — inline role phrases + surfaced opt-in
@@ -368,6 +399,11 @@ function resolveVideoCharacterMentionsHybrid(
     const binding = bindingFor(m.url)
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding)
     if (lock) lockLines.push(lock)
+    // A per-use `descriptionOverride` has no slot in a hybrid role phrase, so it
+    // rides the trailing-directive channel as its own binding-subject line —
+    // exactly as on the image lane (`pushOverrideDirective`).
+    const overrideLine = referenceDescriptionLine(binding, ref.descriptionOverride)
+    if (overrideLine) elementDirectives.push(overrideLine)
     const inject = ref.elementInjection?.trim()
     if (inject) elementDirectives.push(inject)
   }
@@ -429,6 +465,18 @@ export function resolveVideoReferenceCore(
     video: args.videoRefCount ?? 0,
     audio: args.audioRefCount ?? 0,
   })
+  // Described references (name + description, no media) and the video/audio rail
+  // captions — rendered ONCE, ahead of every exit, because both the early return
+  // below and the main assembly have to carry them. They attach no URL and claim
+  // no `@image_N` seat, so they take no part in the numbering walk. Empty for
+  // every caller that sends neither → every existing output is untouched.
+  const describedAndCaptionLines = [
+    ...renderDescribedReferenceLines(args.describedReferences),
+    ...renderReferenceCaptionLines(args.videoCaptions, args.audioCaptions, {
+      video: args.videoRefCount ?? 0,
+      audio: args.audioRefCount ?? 0,
+    }),
+  ]
   let wiredCharRefs = [...args.wiredCharRefs]
   const suppressedSlugs = new Set(args.suppressedCanonicalCharacterIds ?? [])
   if (suppressedSlugs.size > 0) {
@@ -469,14 +517,20 @@ export function resolveVideoReferenceCore(
     // leading refs were passed); the leading URLs are returned for the payload.
     // Nothing was seated, so every `{ref:}` degrades (label → name → "").
     const counts = tokenCounts(leadingRefUrls.length)
+    // tokenCounts(leadingRefUrls.length) → image count == offset (no assets here):
+    // leadingRefUrls mode counts the leading refs; ordinalOffset mode counts the
+    // caller-owned leading refs the offset stands in for.
+    const resolved = resolveReferenceTokens(
+      resolveRefIdTokens(args.prompt, { slotById: slotByRefId, nameById: nameByRefId, imageCount: counts.image }),
+      counts,
+    )
     return {
-      // tokenCounts(leadingRefUrls.length) → image count == offset (no assets here):
-      // leadingRefUrls mode counts the leading refs; ordinalOffset mode counts the
-      // caller-owned leading refs the offset stands in for.
-      prompt: resolveReferenceTokens(
-        resolveRefIdTokens(args.prompt, { slotById: slotByRefId, nameById: nameByRefId, imageCount: counts.image }),
-        counts,
-      ),
+      // Described references and rail captions are the ONE thing this branch can
+      // still contribute: they need no seat, so a request that carries only them
+      // (a story landing before any entity exists) reaches the model here.
+      prompt: describedAndCaptionLines.length > 0
+        ? appendReferenceLines(resolved ?? "", describedAndCaptionLines, args.hybridRoles === true ? "hybrid" : "legacy")
+        : resolved,
       additionalUrls: [...leadingRefUrls],
     }
   }
@@ -579,6 +633,8 @@ export function resolveVideoReferenceCore(
       canonicalPhrases.push(roleToPhrase(resolveDefaultRole(r.defaultRole, r.defaultUsageMode, r.source), binding))
       const lock = buildIdentityLockLine(r, binding)
       if (lock) canonicalLockLines.push(lock)
+      const overrideLine = referenceDescriptionLine(binding, r.descriptionOverride)
+      if (overrideLine) canonicalElementDirectives.push(overrideLine)
       const inject = r.elementInjection?.trim()
       if (inject) canonicalElementDirectives.push(inject)
       continue
@@ -601,7 +657,13 @@ export function resolveVideoReferenceCore(
     // mirrors the shared image-side `composeIdentityDescPart`. The subject here
     // is the bare display name (video numbering is applied separately above).
     const descBodyParts: string[] = []
-    if (includeCanonicalDesc && r.characterCanonicalDescription?.trim()) {
+    // The per-use override IS the caller describing this subject for this run,
+    // so it fills the identity slot ahead of the stored canonical description —
+    // and rides every mode that emits a bullet at all ("none" returned above).
+    const canonicalOverride = r.descriptionOverride?.trim()
+    if (canonicalOverride) {
+      descBodyParts.push(canonicalOverride)
+    } else if (includeCanonicalDesc && r.characterCanonicalDescription?.trim()) {
       descBodyParts.push(r.characterCanonicalDescription.trim())
     }
     if (r.elementInjection?.trim()) descBodyParts.push(r.elementInjection.trim())
@@ -637,7 +699,9 @@ export function resolveVideoReferenceCore(
       if (!ex.url) continue
       position += 1
       if (ex.id && !slotByRefId.has(ex.id)) slotByRefId.set(ex.id, position)
-      const desc = (ex.description ?? "").trim()
+      // Per-use override fills this row's description slot; `description` keeps
+      // its own label semantics (mirrors the image extras).
+      const desc = (ex.descriptionOverride ?? "").trim() || (ex.description ?? "").trim()
       if (ex.characterSlug) {
         // First sight of this character via an extra. Resolution chain
         // matches the image side: per-ref override → upstream character
@@ -820,6 +884,17 @@ export function resolveVideoReferenceCore(
     if (u && !seen.has(u)) { seen.add(u); merged.push(u) }
   }
 
+  // Described references + rail captions — joined the way this format joins its
+  // own trailing directives (hybrid: ahead of the `[style]` section; legacy:
+  // bullets consolidated into the "Use these characters:" block the branch above
+  // may just have created). Ahead of the reorder, like every other assembled
+  // line; they carry no `@image_N` binding for the renumber to move.
+  finalPrompt = appendReferenceLines(
+    finalPrompt,
+    describedAndCaptionLines,
+    hybrid ? "hybrid" : "legacy",
+  )
+
   // `{ref:<id>}` tokens resolve HERE — after the walk has seated every reference
   // (the slot map is complete) and BEFORE the user reorder below, so the
   // reorder's `@image_N` renumber pass carries the freshly emitted binding to