@nodaro/prompts 1.16.0 → 1.17.0

package/dist/index.cjs

@@ -10344,32 +10344,6 @@ function resolveBrandInput(brand) {
   return brand;
 }
 
-// src/prompt-templates.ts
-var DEFAULT_TEMPLATES = {
-  "character-description": "Include character '{name}': {description}.",
-  "object-description": "Include object '{name}': {description}.",
-  "location-description": "Include location '{name}': {description}.",
-  "face-description": "Include the exact face and facial features of '{name}' from the reference image. Maintain perfect likeness and facial identity.",
-  // `-generation` templates drive standalone entity generation routes
-  // (`/v1/generate-character`, `/v1/generate-face`, etc.). Duplicated between
-  // frontend and backend historically; consolidated here so the backend DAG
-  // orchestrator produces the same prompt as a single-node HTTP call.
-  "character-generation": "Create a full-body character portrait: {description}. Style: {style}. Gender: {gender}. High quality, detailed, consistent lighting, neutral background.",
-  "object-generation": "Create a product photo of: {description}. Category: {category}. Clean background, professional studio lighting, high detail.",
-  "location-generation": "Create a cinematic scene of: {description}. Category: {category}. Atmospheric lighting, high detail, wide angle.",
-  "face-generation": "Create a professional close-up face portrait headshot: {description}. Style: {style}. Looking directly at camera, sharp focus on facial features, clean background, studio lighting, high resolution. Maintain exact facial identity and features from the reference image.",
-  "generate-image-wrapper": "{userPrompt}\n{assetDescriptions}"
-};
-function resolveTemplate(key, userTemplates, flowTemplates) {
-  return flowTemplates?.[key] ?? userTemplates?.[key] ?? DEFAULT_TEMPLATES[key] ?? "";
-}
-function applyTemplate(template, vars) {
-  return Object.entries(vars).reduce(
-    (result, [key, value]) => result.replaceAll(`{${key}}`, value || ""),
-    template
-  );
-}
-
 // src/prompt-hint-join.ts
 var PROMPT_HINT_SEPARATOR = ". ";
 function joinPromptHints(userPrompt, hints) {
@@ -10581,6 +10555,87 @@ function sectionedClauseCosts(userPrompt, clauses, structuredFragment) {
   }
   return costs;
 }
+
+// src/described-references.ts
+var CHARACTER_BLOCK_HEADER = "Use these characters:";
+function referenceDescriptionLine(subject, description) {
+  const s = subject.trim();
+  const d = description?.trim();
+  if (!s || !d) return "";
+  return `${s} \u2014 ${d}.`;
+}
+function renderDescribedReferenceLines(refs) {
+  if (!refs || refs.length === 0) return [];
+  const lines = [];
+  const seen = /* @__PURE__ */ new Set();
+  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;
+}
+function renderReferenceCaptionLines(videoCaptions, audioCaptions, counts) {
+  const lines = [];
+  const render = (captions, kind, cap) => {
+    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;
+}
+function appendReferenceLines(prompt, lines, format) {
+  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}
+`)) {
+    const splitIdx = prompt.indexOf("\n\n");
+    if (splitIdx === -1) return `${prompt}
+${bullets}`;
+    return `${prompt.slice(0, splitIdx)}
+${bullets}${prompt.slice(splitIdx)}`;
+  }
+  const block = `${CHARACTER_BLOCK_HEADER}
+${bullets}`;
+  return prompt ? `${block}
+
+${prompt}` : block;
+}
+
+// src/prompt-templates.ts
+var DEFAULT_TEMPLATES = {
+  "character-description": "Include character '{name}': {description}.",
+  "object-description": "Include object '{name}': {description}.",
+  "location-description": "Include location '{name}': {description}.",
+  "face-description": "Include the exact face and facial features of '{name}' from the reference image. Maintain perfect likeness and facial identity.",
+  // `-generation` templates drive standalone entity generation routes
+  // (`/v1/generate-character`, `/v1/generate-face`, etc.). Duplicated between
+  // frontend and backend historically; consolidated here so the backend DAG
+  // orchestrator produces the same prompt as a single-node HTTP call.
+  "character-generation": "Create a full-body character portrait: {description}. Style: {style}. Gender: {gender}. High quality, detailed, consistent lighting, neutral background.",
+  "object-generation": "Create a product photo of: {description}. Category: {category}. Clean background, professional studio lighting, high detail.",
+  "location-generation": "Create a cinematic scene of: {description}. Category: {category}. Atmospheric lighting, high detail, wide angle.",
+  "face-generation": "Create a professional close-up face portrait headshot: {description}. Style: {style}. Looking directly at camera, sharp focus on facial features, clean background, studio lighting, high resolution. Maintain exact facial identity and features from the reference image.",
+  "generate-image-wrapper": "{userPrompt}\n{assetDescriptions}"
+};
+function resolveTemplate(key, userTemplates, flowTemplates) {
+  return flowTemplates?.[key] ?? userTemplates?.[key] ?? DEFAULT_TEMPLATES[key] ?? "";
+}
+function applyTemplate(template, vars) {
+  return Object.entries(vars).reduce(
+    (result, [key, value]) => result.replaceAll(`{${key}}`, value || ""),
+    template
+  );
+}
 function composeIdentityDescPart(subject, canonicalDesc, elementInjection) {
   const parts = [];
   const c = canonicalDesc?.trim();
@@ -10589,6 +10644,10 @@ function composeIdentityDescPart(subject, canonicalDesc, elementInjection) {
   if (e) parts.push(e);
   return parts.length > 0 ? `${subject} \u2014 ${parts.join(". ")}` : subject;
 }
+function pushOverrideDirective(out, ref, binding) {
+  const line = referenceDescriptionLine(binding, ref.descriptionOverride);
+  if (line) out.push(line);
+}
 function resolveCharacterMentions(prompt, tokens, refs) {
   const bySlug = /* @__PURE__ */ new Map();
   const byVariant = /* @__PURE__ */ new Map();
@@ -10629,7 +10688,7 @@ function resolveCharacterMentions(prompt, tokens, refs) {
       const includeCanonicalDesc = effectiveMode === "identical" || effectiveMode === "face-pose";
       const descPart = composeIdentityDescPart(
         subject,
-        includeCanonicalDesc ? match.characterCanonicalDescription : void 0,
+        match.descriptionOverride?.trim() || (includeCanonicalDesc ? match.characterCanonicalDescription : void 0),
         match.elementInjection
       );
       directiveLines.push(`- ${descPart}.${directive ? ` ${directive}` : ""}`);
@@ -10707,6 +10766,7 @@ function resolveCharacterMentionsHybrid(prompt, tokens, refs, existingUrls) {
     const binding = bindingFor(m.url);
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding);
     if (lock) lockLines.push(lock);
+    pushOverrideDirective(elementDirectives, ref, binding);
     const inject = ref.elementInjection?.trim();
     if (inject) elementDirectives.push(inject);
   }
@@ -10780,7 +10840,8 @@ function resolveLocationMentions(prompt, tokens, refs) {
     const subject = `Image ${t.imageIndex} (${displayName})`;
     const includeCanonicalDesc = effectiveMode === "identical";
     const canonicalDesc = match.locationCanonicalDescription?.trim();
-    const descPart = includeCanonicalDesc && canonicalDesc ? `${subject} \u2014 ${canonicalDesc}` : subject;
+    const shownDesc = match.descriptionOverride?.trim() || (includeCanonicalDesc ? canonicalDesc : void 0);
+    const descPart = shownDesc ? `${subject} \u2014 ${shownDesc}` : subject;
     directiveLines.push(`- ${descPart}.${directive ? ` ${directive}` : ""}`);
     if (t.bucket && t.variant && match.locationVariantDisplayName && match.locationVariantDisplayName !== "canonical") {
       directiveLines.push(`  (in this image: ${match.locationVariantDisplayName})`);
@@ -10848,6 +10909,7 @@ function resolveLocationMentionsHybrid(prompt, tokens, refs, existingUrls) {
     const binding = bindingFor(m.url);
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding);
     if (lock) lockLines.push(lock);
+    pushOverrideDirective(elementDirectives, ref, binding);
     const inject = ref.elementInjection?.trim();
     if (inject) elementDirectives.push(inject);
   }
@@ -10897,10 +10959,11 @@ function resolveImageMentionsHybrid(prompt, tokens, refs, existingUrls) {
     const binding = bindingFor(m.url);
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding);
     if (lock) lockLines.push(lock);
+    pushOverrideDirective(elementDirectives, ref, binding);
     const inject = ref.elementInjection?.trim();
     if (inject) elementDirectives.push(inject);
   }
-  return { prompt: resolvedPrompt, additionalUrls, lockLines, elementDirectives };
+  return { prompt: resolvedPrompt, additionalUrls, mentionedUrls: seenUrls, lockLines, elementDirectives };
 }
 function resolveEntityMentionsHybrid(prompt, tokens, refs, existingUrls) {
   const bySlug = /* @__PURE__ */ new Map();
@@ -10951,6 +11014,7 @@ function resolveEntityMentionsHybrid(prompt, tokens, refs, existingUrls) {
     const binding = bindingFor(m.url);
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding);
     if (lock) lockLines.push(lock);
+    pushOverrideDirective(elementDirectives, ref, binding);
     const inject = ref.elementInjection?.trim();
     if (inject) elementDirectives.push(inject);
   }
@@ -10986,7 +11050,7 @@ function buildCanonicalFallback(refs, mentionedSlugs, startIndex) {
     const subject = `Image ${cursor} (${displayName})`;
     const descPart = composeIdentityDescPart(
       subject,
-      includeCanonicalDesc ? r.characterCanonicalDescription : void 0,
+      r.descriptionOverride?.trim() || (includeCanonicalDesc ? r.characterCanonicalDescription : void 0),
       r.elementInjection
     );
     directiveLines.push(`- ${descPart}.${directive ? ` ${directive}` : ""}`);
@@ -11002,7 +11066,7 @@ function buildExtraRefDirectives(refs, emittedCharacterPositions, startIndex) {
   for (const r of refs) {
     if (!r.isExtraRef) continue;
     if (!r.url) continue;
-    const description = (r.description ?? r.variantDescription ?? "").trim();
+    const description = (r.descriptionOverride ?? "").trim() || (r.description ?? r.variantDescription ?? "").trim();
     if (r.source === "wired-character" && r.characterSlug) {
       const effectiveMode = r.defaultUsageMode ?? shared.DEFAULT_USAGE_MODE;
       const earlierPos = positionsByChar.get(r.characterSlug);
@@ -11066,6 +11130,7 @@ function renderCanonicalFallbackHybrid(refs, letterForUrl) {
     phrases.push(shared.roleToPhrase(shared.resolveDefaultRole(r.defaultRole, r.defaultUsageMode, r.source), binding));
     const lock = buildIdentityLockLine(r, binding);
     if (lock) lockLines.push(lock);
+    pushOverrideDirective(elementDirectives, r, binding);
     const inject = r.elementInjection?.trim();
     if (inject) elementDirectives.push(inject);
   }
@@ -11080,7 +11145,7 @@ function renderExtraRefsHybrid(extraRefs, letterForUrl, seedLetterByChar) {
     if (!r.url) continue;
     const letter = letterForUrl(r.url);
     const binding = `reference image ${letter}`;
-    const description = (r.description ?? r.variantDescription ?? "").trim();
+    const description = (r.descriptionOverride ?? "").trim() || (r.description ?? r.variantDescription ?? "").trim();
     if (r.source === "wired-character" && r.characterSlug) {
       const earlier = firstLetterByChar.get(r.characterSlug);
       if (earlier !== void 0 && earlier !== letter) {
@@ -11117,10 +11182,11 @@ function renderLocationCanonicalHybrid(nonCharacterRefs, finalIndexByUrl, covere
     phrases.push(shared.roleToPhrase(resolveLocationRole(null, null, r), binding));
     const lock = buildIdentityLockLine(r, binding);
     if (lock) lockLines.push(lock);
+    pushOverrideDirective(elementDirectives, r, binding);
     const inject = r.elementInjection?.trim();
     if (inject) elementDirectives.push(inject);
   }
-  return { phrases, lockLines, elementDirectives };
+  return { phrases, lockLines, elementDirectives, renderedUrls: seenUrls };
 }
 function renderObjectCreatureCanonicalHybrid(nonCharacterRefs, finalIndexByUrl, coveredUrls) {
   const phrases = [];
@@ -11137,10 +11203,24 @@ function renderObjectCreatureCanonicalHybrid(nonCharacterRefs, finalIndexByUrl,
     phrases.push(shared.roleToPhrase(shared.defaultRoleForSource(r.source), binding));
     const lock = buildIdentityLockLine(r, binding);
     if (lock) lockLines.push(lock);
+    pushOverrideDirective(elementDirectives, r, binding);
     const inject = r.elementInjection?.trim();
     if (inject) elementDirectives.push(inject);
   }
-  return { phrases, lockLines, elementDirectives };
+  return { phrases, lockLines, elementDirectives, renderedUrls: seenUrls };
+}
+function renderUntoldOverridesHybrid(nonCharacterRefs, finalIndexByUrl, toldUrls) {
+  const lines = [];
+  const sweptUrls = /* @__PURE__ */ new Set();
+  for (const r of nonCharacterRefs) {
+    if (!r.url || toldUrls.has(r.url) || sweptUrls.has(r.url)) continue;
+    const slot = finalIndexByUrl.get(r.url);
+    if (!slot) continue;
+    const before = lines.length;
+    pushOverrideDirective(lines, r, `reference image ${slotToLetter(slot)}`);
+    if (lines.length > before) sweptUrls.add(r.url);
+  }
+  return lines;
 }
 function buildTileIdForUrl(urls, refs, prompt, sourceNodeIdById) {
   const knownSlugs = Array.from(
@@ -11313,8 +11393,10 @@ function buildImagePromptInternal(config2, marks) {
   );
   const suppressedCanonicalLocationIds = config2.suppressedCanonicalLocationIds ?? [];
   const isHybrid = config2.referenceFormat === "hybrid";
+  const describedLines = renderDescribedReferenceLines(config2.describedReferences);
   let hybridBodyConverged = false;
   const mentionedEntityUrls = /* @__PURE__ */ new Set();
+  const mentionedImageUrls = /* @__PURE__ */ new Set();
   if (config2.skipCharacterMentions) {
     config2 = {
       ...config2,
@@ -11432,6 +11514,7 @@ function buildImagePromptInternal(config2, marks) {
           resolved.additionalUrls = [...resolved.additionalUrls, ...hi.additionalUrls];
           hybridImageLockLines = hi.lockLines;
           hybridImageElementDirectives = hi.elementDirectives;
+          for (const u of hi.mentionedUrls) mentionedImageUrls.add(u);
           if (hi.additionalUrls.length > 0) hybridBodyConverged = true;
         }
       }
@@ -11562,9 +11645,13 @@ ${promptForNext}`;
       referenceImageUrls = config2.referenceImageUrls || [];
     }
   }
-  if (connectedReferences) {
+  if (connectedReferences || describedLines.length > 0) {
+    const structuredRefs = connectedReferences ?? [];
     let prompt2 = config2.prompt;
-    const nonCharacterRefs = connectedReferences.filter(
+    if (!isHybrid && describedLines.length > 0) {
+      prompt2 = appendReferenceLines(prompt2, describedLines, "legacy");
+    }
+    const nonCharacterRefs = structuredRefs.filter(
       (r) => r.source !== "wired-character" && r.isExtraRef !== true
     );
     const nonCharacterUrls = nonCharacterRefs.map((r) => r.url).filter((u) => Boolean(u));
@@ -11594,11 +11681,23 @@ ${promptForNext}`;
       const canonLockBlock = canonLockLines.length > 0 ? `${canonLockLines.join("\n")}
 
 ` : "";
+      const toldOverrideUrls = /* @__PURE__ */ new Set([
+        ...locCanon.renderedUrls,
+        ...objCanon.renderedUrls,
+        ...mentionedEntityUrls,
+        ...mentionedImageUrls
+      ]);
+      const untoldOverrides = renderUntoldOverridesHybrid(
+        nonCharacterRefs,
+        finalIndexByUrl,
+        toldOverrideUrls
+      );
       const canonTrailingLines = [
         ...locCanon.phrases,
         ...objCanon.phrases,
         ...locCanon.elementDirectives,
-        ...objCanon.elementDirectives
+        ...objCanon.elementDirectives,
+        ...untoldOverrides
       ];
       const composedScene = `${canonLockBlock}${insertBeforeStyleSection(scene, canonTrailingLines)}`;
       prompt2 = config2.referenceLockSnippet ? `${config2.referenceLockSnippet}
@@ -11625,6 +11724,9 @@ ${directives}`;
         }
       }
     }
+    if (isHybrid && describedLines.length > 0) {
+      prompt2 = appendReferenceLines(prompt2, describedLines, "hybrid");
+    }
     const styleText2 = style?.trim();
     const styleLine2 = styleText2 && !isDeniedStyleId(styleText2) ? `Style: ${getStylePromptHint(styleText2) || styleText2}` : "";
     const negPrompt2 = negativePrompt?.trim();
@@ -11665,7 +11767,7 @@ ${directives}`;
       const reordered = applyReferenceOrder(
         assembledUrls,
         prompt2,
-        connectedReferences,
+        structuredRefs,
         referenceOrder,
         sourceNodeIdById
       );
@@ -11790,7 +11892,10 @@ function collectIdentities(prompt, refs, meta3) {
       label,
       fidelity: m?.fidelity ?? defaultFidelityForSource(ref?.source),
       customText: m?.customText?.trim() || void 0,
-      description: ref?.description,
+      // Per-use override ahead of the ref's own description; the directive
+      // builder's location-canonical fallback only fires when BOTH are absent,
+      // so an override outranks the stored location wording too.
+      description: ref?.descriptionOverride?.trim() || ref?.description,
       source: ref?.source,
       locationCanonicalDescription: ref?.locationCanonicalDescription,
       locationSlug: ref?.locationSlug,
@@ -11898,7 +12003,7 @@ function buildNonCharacterDirectives(prompt, nonCharacterRefs, identityMeta, fin
         // wired-object falls through to the strict "match exactly" verb.
         label: ref.source === "wired-location" ? "location" : ref.source === "wired-creature" ? "creature" : "object",
         fidelity: defaultFidelityForSource(ref.source),
-        description: ref.description?.trim() || void 0,
+        description: ref.descriptionOverride?.trim() || ref.description?.trim() || void 0,
         source: ref.source,
         locationCanonicalDescription: ref.locationCanonicalDescription,
         locationSlug: ref.locationSlug,
@@ -12425,6 +12530,8 @@ function resolveVideoCharacterMentionsHybrid(prompt, tokens, refs, offset) {
     const binding = bindingFor(m.url);
     const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding);
     if (lock) lockLines.push(lock);
+    const overrideLine = referenceDescriptionLine(binding, ref.descriptionOverride);
+    if (overrideLine) elementDirectives.push(overrideLine);
     const inject = ref.elementInjection?.trim();
     if (inject) elementDirectives.push(inject);
   }
@@ -12450,6 +12557,13 @@ function resolveVideoReferenceCore(args) {
     video: args.videoRefCount ?? 0,
     audio: args.audioRefCount ?? 0
   });
+  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) {
@@ -12474,14 +12588,15 @@ function resolveVideoReferenceCore(args) {
   const slotByRefId = /* @__PURE__ */ new Map();
   if (wiredCharRefs.length === 0 && !hasExtras) {
     const counts = tokenCounts(leadingRefUrls.length);
+    const resolved2 = 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(resolved2 ?? "", describedAndCaptionLines, args.hybridRoles === true ? "hybrid" : "legacy") : resolved2,
       additionalUrls: [...leadingRefUrls]
     };
   }
@@ -12539,6 +12654,8 @@ function resolveVideoReferenceCore(args) {
       canonicalPhrases.push(shared.roleToPhrase(shared.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;
@@ -12555,7 +12672,10 @@ function resolveVideoReferenceCore(args) {
     const directive = shared.usageModeDirective(effectiveMode);
     const includeCanonicalDesc = effectiveMode === "identical" || effectiveMode === "face-pose";
     const descBodyParts = [];
-    if (includeCanonicalDesc && r.characterCanonicalDescription?.trim()) {
+    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());
@@ -12572,7 +12692,7 @@ function resolveVideoReferenceCore(args) {
       if (!ex.url) continue;
       position += 1;
       if (ex.id && !slotByRefId.has(ex.id)) slotByRefId.set(ex.id, position);
-      const desc = (ex.description ?? "").trim();
+      const desc = (ex.descriptionOverride ?? "").trim() || (ex.description ?? "").trim();
       if (ex.characterSlug) {
         const meta3 = args.lookupCharacterBySlug?.(ex.characterSlug);
         const charDefaultMode = meta3?.defaultUsageMode;
@@ -12716,6 +12836,11 @@ ${finalPrompt}` : block;
       merged.push(u);
     }
   }
+  finalPrompt = appendReferenceLines(
+    finalPrompt,
+    describedAndCaptionLines,
+    hybrid ? "hybrid" : "legacy"
+  );
   finalPrompt = resolveRefIdTokens(finalPrompt, {
     slotById: slotByRefId,
     nameById: nameByRefId,
@@ -12930,6 +13055,7 @@ function assembleImageInput(input) {
     prompt: composePromptText(input.userPrompt, pieces, keptHintClauses),
     provider: input.provider,
     ...input.connectedReferences !== void 0 ? { connectedReferences: input.connectedReferences } : {},
+    ...input.describedReferences !== void 0 ? { 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
@@ -34866,6 +34992,7 @@ exports.WARDROBE_FIELD_BY_DIMENSION = WARDROBE_FIELD_BY_DIMENSION;
 exports.__resetCatalogIdGuardForTests = __resetCatalogIdGuardForTests;
 exports.appendField = appendField;
 exports.appendMusicMeta = appendMusicMeta;
+exports.appendReferenceLines = appendReferenceLines;
 exports.applyMinorAgeFloorToPickerValues = applyMinorAgeFloorToPickerValues;
 exports.applyPickerJson = applyPickerJson;
 exports.applyPromptAffixes = applyPromptAffixes;
@@ -35192,11 +35319,14 @@ exports.promptPartSeparator = promptPartSeparator;
 exports.readDirectionFields = readDirectionFields;
 exports.readStructuredFields = readStructuredFields;
 exports.readSubjectFields = readSubjectFields;
+exports.referenceDescriptionLine = referenceDescriptionLine;
 exports.referenceRulesBlock = referenceRulesBlock;
 exports.registerCatalogPack = registerCatalogPack;
 exports.registerPersonPack = registerPersonPack;
+exports.renderDescribedReferenceLines = renderDescribedReferenceLines;
 exports.renderDirectionHintClauses = renderDirectionHintClauses;
 exports.renderDirectionHints = renderDirectionHints;
+exports.renderReferenceCaptionLines = renderReferenceCaptionLines;
 exports.renderStructuredFields = renderStructuredFields;
 exports.renderStyleSection = renderStyleSection;
 exports.renderSubjectHints = renderSubjectHints;