@nodaro/prompts 1.11.0 → 1.12.0

package/dist/index.cjs

@@ -9241,7 +9241,7 @@ function objectOptions(arr, phrase) {
     label: e.label,
     description: e.description,
     category: e.subcategory,
-    promptHint: phrase(e.label.toLowerCase(), e.description),
+    promptHint: phrase(e),
     // Object entities have no `promptHint` field of their own (it is
     // synthesized above), so the term cannot come from `resolveTerm`'s
     // empty-hint rule: an authored `term` wins, and otherwise the label IS the
@@ -9573,7 +9573,7 @@ var SINGLE_CATALOGS = [
     defaultValue: "dog-golden-retriever",
     categoryOrder: shared.ANIMAL_SUBCATEGORY_ORDER,
     categoryLabels: shared.ANIMAL_SUBCATEGORY_LABELS,
-    options: objectOptions(shared.ANIMALS, (label, description) => `featuring a ${label}, ${description}`)
+    options: objectOptions(shared.ANIMALS, (e) => shared.getAnimalPromptHint(e.id))
   },
   {
     nodeType: "vehicle",
@@ -9584,7 +9584,7 @@ var SINGLE_CATALOGS = [
     defaultValue: "sedan",
     categoryOrder: shared.VEHICLE_SUBCATEGORY_ORDER,
     categoryLabels: shared.VEHICLE_SUBCATEGORY_LABELS,
-    options: objectOptions(shared.VEHICLES, (label, description) => `featuring a ${label}, ${description}`)
+    options: objectOptions(shared.VEHICLES, (e) => `featuring a ${e.label.toLowerCase()}, ${e.description}`)
   },
   {
     nodeType: "weapon",
@@ -9595,7 +9595,7 @@ var SINGLE_CATALOGS = [
     defaultValue: "katana",
     categoryOrder: shared.WEAPON_SUBCATEGORY_ORDER,
     categoryLabels: shared.WEAPON_SUBCATEGORY_LABELS,
-    options: objectOptions(shared.WEAPONS, (label, description) => `with a ${label}, ${description}`)
+    options: objectOptions(shared.WEAPONS, (e) => `with a ${e.label.toLowerCase()}, ${e.description}`)
   },
   {
     nodeType: "furniture",
@@ -9606,7 +9606,7 @@ var SINGLE_CATALOGS = [
     defaultValue: "sofa",
     categoryOrder: shared.FURNITURE_SUBCATEGORY_ORDER,
     categoryLabels: shared.FURNITURE_SUBCATEGORY_LABELS,
-    options: objectOptions(shared.FURNITURE, (label, description) => `including a ${label}, ${description}`)
+    options: objectOptions(shared.FURNITURE, (e) => `including a ${e.label.toLowerCase()}, ${e.description}`)
   },
   {
     nodeType: "held-prop",
@@ -9974,13 +9974,16 @@ function resolveBaseHint(type, data, mode = "full") {
       return withCustomText(data, byMode(mode, getLoopSubjectPromptHint, getLoopSubjectTerm)(asStr(data.loopSubject)));
     case "material":
       return withCustomText(data, buildMaterialHints(data.material, mode));
-    case "animal": {
-      const animal = shared.getAnimal(asStr(data.animal));
+    // Animal is the one Object-entity catalog whose phrasing has a single
+    // owner: `@nodaro/shared`'s `getAnimalPromptHint` / `getAnimalTerm`, which
+    // the picker-catalog funnel calls too. Both getters already return "" on a
+    // miss, so the entry lookup and the `animal ? … : ""` guard are the
+    // getters' job now, not this switch's.
+    case "animal":
       return withCustomText(
         data,
-        animal ? byMode(mode, `featuring a ${animal.label.toLowerCase()}, ${animal.description}`, objectEntityTerm(animal)) : ""
+        byMode(mode, shared.getAnimalPromptHint, shared.getAnimalTerm)(asStr(data.animal))
       );
-    }
     case "vehicle": {
       const vehicle = shared.getVehicle(asStr(data.vehicle));
       return withCustomText(
@@ -10284,6 +10287,11 @@ ${resolvedPrompt}`;
   }
   return { prompt: resolvedPrompt, additionalUrls, mentionedCharacterSlugs };
 }
+function spliceMentionPhrase(prompt, offset, tokenLength, phrase) {
+  const before = prompt.slice(0, offset).replace(/(?<=\S)[^\S\r\n]{2,}$/, " ");
+  const after = prompt.slice(offset + tokenLength).replace(/^[^\S\r\n]{2,}/, " ");
+  return before + phrase + after;
+}
 function resolveCharacterMentionsHybrid(prompt, tokens, refs, existingUrls) {
   const bySlug = /* @__PURE__ */ new Map();
   const byVariant = /* @__PURE__ */ new Map();
@@ -10322,7 +10330,7 @@ function resolveCharacterMentionsHybrid(prompt, tokens, refs, existingUrls) {
   let resolvedPrompt = prompt;
   for (const m of [...matched].sort((a, b) => b.offset - a.offset)) {
     const phrase = shared.roleToPhrase(m.role, bindingFor(m.url));
-    resolvedPrompt = resolvedPrompt.slice(0, m.offset) + phrase + resolvedPrompt.slice(m.offset + m.token.length);
+    resolvedPrompt = spliceMentionPhrase(resolvedPrompt, m.offset, m.token.length, phrase);
   }
   const lockLines = [];
   const elementDirectives = [];
@@ -10353,16 +10361,21 @@ function locationModeDirective(mode) {
   }
 }
 function locationModeToRole(mode) {
-  switch (mode) {
-    case "identical":
-      return "background";
-    case "style":
-      return "style";
-    case "layout":
-      return "layout";
-    default:
-      return shared.defaultRoleForSource("wired-location");
-  }
+  return roleBearingLocationMode(mode) ?? shared.defaultRoleForSource("wired-location");
+}
+function roleBearingLocationMode(mode) {
+  const m = mode?.trim();
+  if (!m) return null;
+  return shared.REFERENCE_ROLE_PRESETS["wired-location"].includes(m) ? m : null;
+}
+function resolveLocationRole(tokenRole, tokenUsageMode, ref) {
+  const explicitRole = tokenRole?.trim();
+  if (explicitRole) return shared.normalizeRoleSlug(explicitRole);
+  const modeRole = roleBearingLocationMode(tokenUsageMode);
+  if (modeRole) return modeRole;
+  const nodeRole = ref.defaultRole?.trim();
+  if (nodeRole) return shared.normalizeRoleSlug(nodeRole);
+  return locationModeToRole(ref.defaultUsageMode ?? shared.DEFAULT_LOCATION_USAGE_MODE);
 }
 function resolveLocationMentions(prompt, tokens, refs) {
   const bySlug = /* @__PURE__ */ new Map();
@@ -10444,8 +10457,7 @@ function resolveLocationMentionsHybrid(prompt, tokens, refs, existingUrls) {
     mentionedLocationSlugs.add(t.locationSlug);
     refByUrl.set(match.url, match);
     if (t.lock !== void 0) lockOverrideByUrl.set(match.url, t.lock);
-    const mode = t.usageMode ?? match.defaultUsageMode ?? shared.DEFAULT_LOCATION_USAGE_MODE;
-    const role = t.role ? shared.normalizeRoleSlug(t.role) : locationModeToRole(mode);
+    const role = resolveLocationRole(t.role, t.usageMode, match);
     matched.push({ token: t.token, offset: t.offset, url: match.url, role });
   }
   const slotByUrl = /* @__PURE__ */ new Map();
@@ -10459,7 +10471,7 @@ function resolveLocationMentionsHybrid(prompt, tokens, refs, existingUrls) {
   let resolvedPrompt = prompt;
   for (const m of [...matched].sort((a, b) => b.offset - a.offset)) {
     const phrase = shared.roleToPhrase(m.role, bindingFor(m.url));
-    resolvedPrompt = resolvedPrompt.slice(0, m.offset) + phrase + resolvedPrompt.slice(m.offset + m.token.length);
+    resolvedPrompt = spliceMentionPhrase(resolvedPrompt, m.offset, m.token.length, phrase);
   }
   const lockLines = [];
   const elementDirectives = [];
@@ -10508,7 +10520,7 @@ function resolveImageMentionsHybrid(prompt, tokens, refs, existingUrls) {
   let resolvedPrompt = prompt;
   for (const m of [...matched].sort((a, b) => b.offset - a.offset)) {
     const phrase = shared.roleToPhrase(m.role, bindingFor(m.url));
-    resolvedPrompt = resolvedPrompt.slice(0, m.offset) + phrase + resolvedPrompt.slice(m.offset + m.token.length);
+    resolvedPrompt = spliceMentionPhrase(resolvedPrompt, m.offset, m.token.length, phrase);
   }
   const lockLines = [];
   const elementDirectives = [];
@@ -10526,6 +10538,60 @@ function resolveImageMentionsHybrid(prompt, tokens, refs, existingUrls) {
   }
   return { prompt: resolvedPrompt, additionalUrls, lockLines, elementDirectives };
 }
+function resolveEntityMentionsHybrid(prompt, tokens, refs, existingUrls) {
+  const bySlug = /* @__PURE__ */ new Map();
+  for (const source of ["wired-creature", "wired-object"]) {
+    for (const r of refs) {
+      if (r.source !== source) continue;
+      const slug = shared.entityMentionSlugForRef(r);
+      if (!slug) continue;
+      if (!bySlug.has(slug)) bySlug.set(slug, r);
+    }
+  }
+  const additionalUrls = [];
+  const mentionedUrls = /* @__PURE__ */ new Set();
+  const refByUrl = /* @__PURE__ */ new Map();
+  const lockOverrideByUrl = /* @__PURE__ */ new Map();
+  const matched = [];
+  for (const t of tokens) {
+    const match = bySlug.get(t.entitySlug);
+    if (!match || !match.url) continue;
+    additionalUrls.push(match.url);
+    mentionedUrls.add(match.url);
+    refByUrl.set(match.url, match);
+    if (t.lock !== void 0) lockOverrideByUrl.set(match.url, t.lock);
+    const role = (t.role ?? "").trim() || shared.resolveDefaultRole(match.defaultRole, match.defaultUsageMode, match.source);
+    matched.push({ token: t.token, offset: t.offset, url: match.url, role });
+  }
+  const slotByUrl = /* @__PURE__ */ new Map();
+  for (const u of [...existingUrls, ...additionalUrls]) {
+    if (!slotByUrl.has(u)) slotByUrl.set(u, slotByUrl.size + 1);
+  }
+  const bindingFor = (url2) => {
+    const slot = slotByUrl.get(url2);
+    return slot ? `reference image ${slotToLetter(slot)}` : "the reference image";
+  };
+  let resolvedPrompt = prompt;
+  for (const m of [...matched].sort((a, b) => b.offset - a.offset)) {
+    const phrase = shared.roleToPhrase(m.role, bindingFor(m.url));
+    resolvedPrompt = spliceMentionPhrase(resolvedPrompt, m.offset, m.token.length, phrase);
+  }
+  const lockLines = [];
+  const elementDirectives = [];
+  const seenUrls = /* @__PURE__ */ new Set();
+  for (const m of matched) {
+    if (seenUrls.has(m.url)) continue;
+    seenUrls.add(m.url);
+    const ref = refByUrl.get(m.url);
+    if (!ref) continue;
+    const binding = bindingFor(m.url);
+    const lock = buildIdentityLockLine(withForcedIdentityLock(ref, lockOverrideByUrl.get(m.url)), binding);
+    if (lock) lockLines.push(lock);
+    const inject = ref.elementInjection?.trim();
+    if (inject) elementDirectives.push(inject);
+  }
+  return { prompt: resolvedPrompt, additionalUrls, mentionedUrls, lockLines, elementDirectives };
+}
 function buildCanonicalFallback(refs, mentionedSlugs, startIndex) {
   const directiveLines = [];
   const urls = [];
@@ -10684,7 +10750,7 @@ function renderLocationCanonicalHybrid(nonCharacterRefs, finalIndexByUrl, covere
     if (!slot) continue;
     seenUrls.add(r.url);
     const binding = `reference image ${slotToLetter(slot)}`;
-    phrases.push(shared.roleToPhrase(locationModeToRole(r.defaultUsageMode), binding));
+    phrases.push(shared.roleToPhrase(resolveLocationRole(null, null, r), binding));
     const lock = buildIdentityLockLine(r, binding);
     if (lock) lockLines.push(lock);
     const inject = r.elementInjection?.trim();
@@ -10843,6 +10909,20 @@ function reconcileBodySegments(body, bodySegments) {
 function buildImagePrompt(config2) {
   return buildImagePromptInternal(config2);
 }
+function buildImagePromptWithOverflow(config2) {
+  const marks = newAssemblyMarks();
+  const result = buildImagePromptInternal(config2, marks);
+  return { ...result, overflowChars: marks.overflowChars };
+}
+function newAssemblyMarks() {
+  return {
+    directivesPrefix: "",
+    bodyBeforeSuffixes: "",
+    styleSuffix: "",
+    avoidSuffix: "",
+    overflowChars: 0
+  };
+}
 function buildImagePromptInternal(config2, marks) {
   let {
     provider,
@@ -10864,6 +10944,7 @@ function buildImagePromptInternal(config2, marks) {
   const suppressedCanonicalLocationIds = config2.suppressedCanonicalLocationIds ?? [];
   const isHybrid = config2.referenceFormat === "hybrid";
   let hybridBodyConverged = false;
+  const mentionedEntityUrls = /* @__PURE__ */ new Set();
   if (config2.skipCharacterMentions) {
     config2 = {
       ...config2,
@@ -10910,7 +10991,9 @@ function buildImagePromptInternal(config2, marks) {
     );
     const knownImageSlugs = shared.knownImageSlugsFromRefs(connectedReferences);
     const hasImageMentionTokens = isHybrid && knownImageSlugs.length > 0 && shared.findImageMentionTokens(config2.prompt, knownImageSlugs).length > 0;
-    if (knownCharacterSlugs.length > 0 || hasExtraRefs || knownLocationSlugs.length > 0 || hasImageMentionTokens) {
+    const knownEntitySlugs = shared.knownEntitySlugsFromRefs(connectedReferences);
+    const hasEntityMentionTokens = isHybrid && knownEntitySlugs.length > 0 && shared.findEntityMentionTokens(config2.prompt, knownEntitySlugs).length > 0;
+    if (knownCharacterSlugs.length > 0 || hasExtraRefs || knownLocationSlugs.length > 0 || hasImageMentionTokens || hasEntityMentionTokens) {
       const mentionTokens = knownCharacterSlugs.length > 0 ? shared.findCharacterMentionTokens(config2.prompt, knownCharacterSlugs) : [];
       let hybridLockLines = [];
       let hybridElementDirectives = [];
@@ -10982,6 +11065,25 @@ function buildImagePromptInternal(config2, marks) {
           if (hi.additionalUrls.length > 0) hybridBodyConverged = true;
         }
       }
+      let hybridEntityLockLines = [];
+      let hybridEntityElementDirectives = [];
+      if (hasEntityMentionTokens) {
+        const entityTokens = shared.findEntityMentionTokens(resolved.prompt, knownEntitySlugs);
+        if (entityTokens.length > 0) {
+          const he = resolveEntityMentionsHybrid(
+            resolved.prompt,
+            entityTokens,
+            connectedReferences,
+            [...referenceImageUrls || [], ...resolved.additionalUrls]
+          );
+          resolved.prompt = he.prompt;
+          resolved.additionalUrls = [...resolved.additionalUrls, ...he.additionalUrls];
+          hybridEntityLockLines = he.lockLines;
+          hybridEntityElementDirectives = he.elementDirectives;
+          for (const u of he.mentionedUrls) mentionedEntityUrls.add(u);
+          if (he.additionalUrls.length > 0) hybridBodyConverged = true;
+        }
+      }
       const prefixDedupedLength = [
         ...referenceImageUrls || [],
         ...resolved.additionalUrls
@@ -11063,6 +11165,7 @@ ${promptForNext}`;
           ...hybridLockLines,
           ...hybridLocationLockLines,
           ...hybridImageLockLines,
+          ...hybridEntityLockLines,
           ...canonical.lockLines,
           ...extrasRendered.lockLines
         ])];
@@ -11070,6 +11173,7 @@ ${promptForNext}`;
           ...hybridElementDirectives,
           ...hybridLocationElementDirectives,
           ...hybridImageElementDirectives,
+          ...hybridEntityElementDirectives,
           ...canonical.phrases,
           ...canonical.elementDirectives,
           ...extrasRendered.bodyLines,
@@ -11116,7 +11220,8 @@ ${trailingLines.join("\n")}` : "";
         if (coveredUrl) tokenCoveredUrls.add(coveredUrl);
       }
       const locCanon = renderLocationCanonicalHybrid(nonCharacterRefs, finalIndexByUrl, tokenCoveredUrls);
-      const objCanon = renderObjectCreatureCanonicalHybrid(nonCharacterRefs, finalIndexByUrl, tokenCoveredUrls);
+      const objCoveredUrls = mentionedEntityUrls.size > 0 ? /* @__PURE__ */ new Set([...tokenCoveredUrls, ...mentionedEntityUrls]) : tokenCoveredUrls;
+      const objCanon = renderObjectCreatureCanonicalHybrid(nonCharacterRefs, finalIndexByUrl, objCoveredUrls);
       const canonLockLines = [...locCanon.lockLines, ...objCanon.lockLines];
       const canonLockBlock = canonLockLines.length > 0 ? `${canonLockLines.join("\n")}
 
@@ -11175,11 +11280,13 @@ Avoid: ${negPrompt2}`;
     const maxLen2 = shared.getMaxImagePromptChars(provider);
     const reserved2 = styleSuffix2.length + avoidSuffix2.length;
     if (prompt2.length + reserved2 > maxLen2) {
+      if (marks) marks.overflowChars += prompt2.length + reserved2 - maxLen2;
       prompt2 = prompt2.slice(0, Math.max(0, maxLen2 - reserved2 - 3)) + "...";
     }
     if (marks) marks.bodyBeforeSuffixes = prompt2.slice(marks.directivesPrefix.length);
     prompt2 = prompt2 + styleSuffix2 + avoidSuffix2;
     if (prompt2.length > maxLen2) {
+      if (marks) marks.overflowChars += prompt2.length - maxLen2;
       prompt2 = prompt2.slice(0, maxLen2 - 3) + "...";
     }
     if (!isHybrid) {
@@ -11253,11 +11360,13 @@ Avoid: ${negPrompt}`;
   const maxLen = shared.getMaxImagePromptChars(provider);
   const reserved = styleSuffix.length + avoidSuffix.length;
   if (prompt.length + reserved > maxLen) {
+    if (marks) marks.overflowChars += prompt.length + reserved - maxLen;
     prompt = prompt.slice(0, Math.max(0, maxLen - reserved - 3)) + "...";
   }
   if (marks) marks.bodyBeforeSuffixes = prompt;
   prompt = prompt + styleSuffix + avoidSuffix;
   if (prompt.length > maxLen) {
+    if (marks) marks.overflowChars += prompt.length - maxLen;
     prompt = prompt.slice(0, maxLen - 3) + "...";
   }
   const allRefs = referenceImageUrls.length > 0 ? referenceImageUrls : ancestorRefs;
@@ -11267,12 +11376,7 @@ Avoid: ${negPrompt}`;
   return { prompt, nativeNegativePrompt, referenceImageUrls: refsToSend };
 }
 function buildImagePromptSegments(config2, bodySegments) {
-  const marks = {
-    directivesPrefix: "",
-    bodyBeforeSuffixes: "",
-    styleSuffix: "",
-    avoidSuffix: ""
-  };
+  const marks = newAssemblyMarks();
   const result = buildImagePromptInternal(config2, marks);
   let segments = [
     ...marks.directivesPrefix ? [{ text: marks.directivesPrefix, origin: "mention" }] : [],
@@ -11462,13 +11566,24 @@ function hybridRolePhrase(label, letter) {
   return `the ${label} from reference image ${letter}`;
 }
 function expandImageRefTokensHybrid(prompt, refs, finalIndexByUrl) {
-  return prompt.replace(IMAGE_TOKEN_PATTERN, (match, num, label) => {
-    const n = parseInt(num, 10);
+  const splices = [];
+  for (const m of prompt.matchAll(IMAGE_TOKEN_PATTERN)) {
+    const n = parseInt(m[1], 10);
     const ref = refs[n - 1];
     const finalIdx = ref?.url ? finalIndexByUrl.get(ref.url) : void 0;
-    if (!finalIdx) return match;
-    return hybridRolePhrase((label ?? "").trim(), slotToLetter(finalIdx));
-  });
+    if (!finalIdx) continue;
+    splices.push({
+      offset: m.index ?? 0,
+      length: m[0].length,
+      phrase: hybridRolePhrase((m[2] ?? "").trim(), slotToLetter(finalIdx))
+    });
+  }
+  let resolved = prompt;
+  for (let i = splices.length - 1; i >= 0; i--) {
+    const s = splices[i];
+    resolved = spliceMentionPhrase(resolved, s.offset, s.length, s.phrase);
+  }
+  return resolved;
 }
 function capitalizeLineInitial(line) {
   return line.replace(/[a-zA-Z]/, (c) => c.toUpperCase());
@@ -11811,6 +11926,129 @@ function renderDirectionHints(direction, opts) {
   }
   return out;
 }
+var viaFragmentBuilder = (build) => (subject, mode) => {
+  const clause = build(subject, mode).filter((s) => s.length > 0).join(", ");
+  return clause.length > 0 ? [clause] : [];
+};
+var viaListBuilder2 = (build) => (ids, mode) => build(ids.length === 1 ? ids[0] : [...ids], mode).filter((s) => s.length > 0);
+var viaStringBuilder2 = (build) => (ids, mode) => {
+  const s = build(ids.length === 1 ? ids[0] : [...ids], mode);
+  return s.length > 0 ? [s] : [];
+};
+var perId2 = (full, compact) => (ids, mode) => {
+  const out = [];
+  for (const id of ids) {
+    const frag = mode === "compact" ? compact(id) : full(id);
+    if (frag.length > 0) out.push(frag);
+  }
+  return out;
+};
+var SUBJECT_FIELDS = [
+  { key: "person", kind: "group", surface: "both", render: viaFragmentBuilder(buildPersonHints) },
+  { key: "styling", kind: "group", surface: "both", render: viaFragmentBuilder(buildStylingHints) },
+  { key: "heldProp", kind: "ids", surface: "both", maxPicks: 2, render: viaListBuilder2(buildHeldPropHints) },
+  { key: "material", kind: "ids", surface: "both", maxPicks: 2, render: viaStringBuilder2(buildMaterialHints) },
+  { key: "animal", kind: "ids", surface: "both", maxPicks: 1, render: perId2(shared.getAnimalPromptHint, shared.getAnimalTerm) }
+];
+var SUBJECT_FOLD_KEYS = SUBJECT_FIELDS.map((f) => f.key);
+var IDS_ROWS = SUBJECT_FIELDS.filter((f) => f.kind === "ids");
+var SUBJECT_CUSTOM_AGE_KEY = "customAge";
+var CUSTOM_AGE_MIN = 0;
+var CUSTOM_AGE_MAX = 120;
+var SUBJECT_KEYS = [
+  ...PERSON_DIMENSION_ORDER.map((d) => PERSON_FIELD_BY_DIMENSION[d]),
+  SUBJECT_CUSTOM_AGE_KEY,
+  ...STYLING_DIMENSION_ORDER.map((d) => STYLING_FIELD_BY_DIMENSION[d]),
+  ...IDS_ROWS.map((f) => f.key)
+];
+function getRegisteredSubjectKeys() {
+  const fieldByDimension = getRegisteredPersonFieldByDimension();
+  const personFields = [];
+  for (const dimension of getRegisteredPersonDimensionOrder()) {
+    const field = fieldByDimension[dimension];
+    if (field) personFields.push(field);
+  }
+  return [
+    ...personFields,
+    SUBJECT_CUSTOM_AGE_KEY,
+    ...STYLING_DIMENSION_ORDER.map((d) => STYLING_FIELD_BY_DIMENSION[d]),
+    ...IDS_ROWS.map((f) => f.key)
+  ];
+}
+var SUBJECT_IMAGE_HINT_MODE_DEFAULT = "full";
+var SUBJECT_VIDEO_HINT_MODE_DEFAULT = "compact";
+var SUBJECT_ARRAY_CEILING = DIRECTION_ARRAY_CEILING;
+var SUBJECT_ID_MAX_CHARS = DIRECTION_ID_MAX_CHARS;
+var MAX_SUBJECT_KEYS = 128;
+var SUBJECT_KEY_MAX_CHARS = 64;
+function normalizeIds(value, maxPicks) {
+  const ids = [];
+  if (typeof value === "string") {
+    if (value) ids.push(value);
+  } else if (Array.isArray(value)) {
+    for (const v of value) {
+      if (ids.length >= maxPicks) break;
+      if (typeof v === "string" && v && !ids.includes(v)) ids.push(v);
+    }
+  }
+  return ids.slice(0, maxPicks);
+}
+function limitByField() {
+  const out = /* @__PURE__ */ new Map();
+  const personFieldByDimension = getRegisteredPersonFieldByDimension();
+  for (const dimension of getRegisteredPersonDimensionOrder()) {
+    const field = personFieldByDimension[dimension];
+    if (field) out.set(field, getPersonDimensionLimit(dimension));
+  }
+  for (const dimension of STYLING_DIMENSION_ORDER) {
+    out.set(
+      STYLING_FIELD_BY_DIMENSION[dimension],
+      getStylingDimensionLimit(dimension)
+    );
+  }
+  for (const row of IDS_ROWS) out.set(row.key, row.maxPicks);
+  return out;
+}
+function normalizeSubjectFields(subject) {
+  if (!subject || typeof subject !== "object" || Array.isArray(subject)) return void 0;
+  const src = subject;
+  const limits = limitByField();
+  const out = {};
+  const rawAge = src[SUBJECT_CUSTOM_AGE_KEY];
+  if (typeof rawAge === "number" && Number.isFinite(rawAge)) {
+    out[SUBJECT_CUSTOM_AGE_KEY] = Math.max(
+      CUSTOM_AGE_MIN,
+      Math.min(CUSTOM_AGE_MAX, Math.round(rawAge))
+    );
+  }
+  for (const [field, limit] of limits) {
+    const ids = normalizeIds(src[field], limit);
+    if (ids.length === 0) continue;
+    out[field] = ids.length === 1 ? ids[0] : ids;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function subjectFieldsForSurface(surface) {
+  return SUBJECT_FIELDS.filter((f) => f.surface === "both" || f.surface === surface);
+}
+function renderSubjectHints(subject, opts) {
+  const bag = normalizeSubjectFields(subject);
+  if (!bag) return [];
+  const mode = opts.mode ?? "full";
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const spec of SUBJECT_FIELDS) {
+    if (spec.surface !== "both" && spec.surface !== opts.surface) continue;
+    const hints = spec.kind === "group" ? spec.render(bag, mode) : spec.render(normalizeIds(bag[spec.key], spec.maxPicks), mode);
+    for (const hint of hints) {
+      if (hint.length > 0 && !seen.has(hint)) {
+        seen.add(hint);
+        out.push(hint);
+      }
+    }
+  }
+  return out;
+}
 
 // src/prompt-hint-join.ts
 var PROMPT_HINT_SEPARATOR = ". ";
@@ -11819,6 +12057,17 @@ function joinPromptHints(userPrompt, hints) {
   return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(PROMPT_HINT_SEPARATOR);
 }
 
+// src/hint-shedding.ts
+function keepableDirectionHints(hintClauses, kept, deficit) {
+  let remaining = deficit;
+  let next = kept;
+  while (next > 0 && remaining > 0) {
+    next -= 1;
+    remaining -= hintClauses[next].length + PROMPT_HINT_SEPARATOR.length;
+  }
+  return next;
+}
+
 // src/ref-binding.ts
 function identityRefsSentence(firstOrdinal, lastOrdinal) {
   return firstOrdinal === lastOrdinal ? `${REF_BINDING.ordinal(firstOrdinal)} is an identity reference for this shot's subjects \u2014 match its subject's exact appearance; it is not a frame.` : `${REF_BINDING.ordinal(firstOrdinal)} through ${REF_BINDING.ordinal(lastOrdinal)} are identity references for this shot's subjects \u2014 match each subject's exact appearance; they are not frames.`;
@@ -12404,17 +12653,32 @@ function assembleSunoInput(input) {
 }
 
 // src/assemble-image-input.ts
-function composePromptText(userPrompt, direction, structured) {
+function renderImageHintPieces(subject, direction, structured) {
+  return {
+    hintClauses: [
+      ...renderSubjectHints(subject, {
+        surface: "image",
+        mode: SUBJECT_IMAGE_HINT_MODE_DEFAULT
+      }),
+      ...renderDirectionHints(direction, {
+        surface: "image",
+        mode: IMAGE_HINT_MODE_DEFAULT
+      })
+    ].filter((p) => p.length > 0),
+    structuredFragment: structured ? renderStructuredFields(structured) : ""
+  };
+}
+function composePromptText(userPrompt, pieces, keptHintClauses) {
   const hints = [
-    ...renderDirectionHints(direction, { surface: "image", mode: IMAGE_HINT_MODE_DEFAULT }),
-    structured ? renderStructuredFields(structured) : ""
+    ...pieces.hintClauses.slice(0, keptHintClauses),
+    pieces.structuredFragment
   ].filter((p) => p.length > 0);
   return joinPromptHints(userPrompt, hints);
 }
 function assembleImageInput(input) {
-  const prompt = composePromptText(input.userPrompt, input.direction, input.structured);
-  const result = buildImagePrompt({
-    prompt,
+  const pieces = renderImageHintPieces(input.subject, input.direction, input.structured);
+  const assembleWith = (keptHintClauses) => buildImagePromptWithOverflow({
+    prompt: composePromptText(input.userPrompt, pieces, keptHintClauses),
     provider: input.provider,
     ...input.connectedReferences !== void 0 ? { connectedReferences: input.connectedReferences } : {},
     // Manual uploads / direct refs ride the builder's reference-URL channel so
@@ -12437,6 +12701,13 @@ function assembleImageInput(input) {
     ...input.sourceNodeIdById !== void 0 ? { sourceNodeIdById: input.sourceNodeIdById } : {},
     ...input.skipCharacterMentions !== void 0 ? { skipCharacterMentions: input.skipCharacterMentions } : {}
   });
+  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);
+  }
+  const { overflowChars, ...result } = fitted;
   if (input.throwOnEmpty && !result.prompt.trim()) {
     throw new Error(
       "No prompt \u2014 type one, bind a character, or pick a cinematography direction"
@@ -12447,15 +12718,36 @@ function assembleImageInput(input) {
 
 // src/assemble-video-input.ts
 function composeVideoPromptText(userPrompt, direction, structured, opts) {
-  const hints = [
+  const hintClauses = [
+    ...renderSubjectHints(opts?.subject, {
+      surface: "video",
+      mode: opts?.subjectHintMode ?? SUBJECT_VIDEO_HINT_MODE_DEFAULT
+    }),
     ...renderDirectionHints(direction, {
       surface: "video",
       mode: opts?.hintMode ?? VIDEO_HINT_MODE_DEFAULT
-    }),
-    structured ? renderStructuredFields(structured) : ""
+    })
   ].filter((p) => p.length > 0);
-  if (hints.length === 0) return userPrompt;
-  return joinPromptHints(userPrompt ?? "", hints);
+  const structuredFragment = structured ? renderStructuredFields(structured) : "";
+  const composeWith = (kept2) => {
+    const hints = [...hintClauses.slice(0, kept2), structuredFragment].filter(
+      (p) => p.length > 0
+    );
+    if (hints.length === 0) return userPrompt;
+    return joinPromptHints(userPrompt ?? "", hints);
+  };
+  const cap = opts?.cap;
+  if (cap === void 0) return composeWith(hintClauses.length);
+  const frame = opts?.frame ?? ((body2) => body2);
+  let kept = hintClauses.length;
+  let body = composeWith(kept);
+  let framedLength = frame(body)?.length ?? 0;
+  while (framedLength > cap && kept > 0) {
+    kept = keepableDirectionHints(hintClauses, kept, framedLength - cap);
+    body = composeWith(kept);
+    framedLength = frame(body)?.length ?? 0;
+  }
+  return body;
 }
 
 // src/read-node-direction.ts
@@ -12480,6 +12772,31 @@ function readDirectionFields(value) {
   }
   return Object.keys(out).length > 0 ? out : void 0;
 }
+function readSubjectFields(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const src = value;
+  const out = {};
+  for (const key of getRegisteredSubjectKeys()) {
+    const v = src[key];
+    if (key === SUBJECT_CUSTOM_AGE_KEY) {
+      if (typeof v === "number" && Number.isFinite(v)) out[key] = v;
+      continue;
+    }
+    if (typeof v === "string") {
+      if (v.length > 0 && v.length <= SUBJECT_ID_MAX_CHARS) out[key] = v;
+    } else if (Array.isArray(v)) {
+      const kept = [];
+      for (const x of v) {
+        if (kept.length >= SUBJECT_ARRAY_CEILING) break;
+        if (typeof x === "string" && x.length > 0 && x.length <= SUBJECT_ID_MAX_CHARS) {
+          kept.push(x);
+        }
+      }
+      if (kept.length > 0) out[key] = kept;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
 var GENDERS = ["man", "woman", "child", "non-binary"];
 var MAX_STRUCTURED_VALUE_CHARS = 200;
 var PERSON_FIELDS2 = {
@@ -33839,6 +34156,7 @@ exports.MATERIAL_IDS = MATERIAL_IDS;
 exports.MAX_SELECTED_BY_DIMENSION = MAX_SELECTED_BY_DIMENSION;
 exports.MAX_SELECTED_BY_FRAMING_CATEGORY = MAX_SELECTED_BY_FRAMING_CATEGORY;
 exports.MAX_SELECTED_BY_STYLING_DIMENSION = MAX_SELECTED_BY_STYLING_DIMENSION;
+exports.MAX_SUBJECT_KEYS = MAX_SUBJECT_KEYS;
 exports.MOODS = MOODS;
 exports.MOOD_CATEGORY_LABELS = MOOD_CATEGORY_LABELS;
 exports.MOOD_CATEGORY_ORDER = MOOD_CATEGORY_ORDER;
@@ -33918,6 +34236,15 @@ exports.STYLING_DIMENSION_LABELS = STYLING_DIMENSION_LABELS;
 exports.STYLING_DIMENSION_ORDER = STYLING_DIMENSION_ORDER;
 exports.STYLING_FIELD_BY_DIMENSION = STYLING_FIELD_BY_DIMENSION;
 exports.STYLING_IDS = STYLING_IDS;
+exports.SUBJECT_ARRAY_CEILING = SUBJECT_ARRAY_CEILING;
+exports.SUBJECT_CUSTOM_AGE_KEY = SUBJECT_CUSTOM_AGE_KEY;
+exports.SUBJECT_FIELDS = SUBJECT_FIELDS;
+exports.SUBJECT_FOLD_KEYS = SUBJECT_FOLD_KEYS;
+exports.SUBJECT_ID_MAX_CHARS = SUBJECT_ID_MAX_CHARS;
+exports.SUBJECT_IMAGE_HINT_MODE_DEFAULT = SUBJECT_IMAGE_HINT_MODE_DEFAULT;
+exports.SUBJECT_KEYS = SUBJECT_KEYS;
+exports.SUBJECT_KEY_MAX_CHARS = SUBJECT_KEY_MAX_CHARS;
+exports.SUBJECT_VIDEO_HINT_MODE_DEFAULT = SUBJECT_VIDEO_HINT_MODE_DEFAULT;
 exports.TEMPORALS = TEMPORALS;
 exports.TEMPORAL_CATEGORY_LABELS = TEMPORAL_CATEGORY_LABELS;
 exports.TEMPORAL_CATEGORY_ORDER = TEMPORAL_CATEGORY_ORDER;
@@ -33978,6 +34305,7 @@ exports.buildIdentityDirectives = buildIdentityDirectives;
 exports.buildIdentityLockLine = buildIdentityLockLine;
 exports.buildImagePrompt = buildImagePrompt;
 exports.buildImagePromptSegments = buildImagePromptSegments;
+exports.buildImagePromptWithOverflow = buildImagePromptWithOverflow;
 exports.buildInstrumentationHints = buildInstrumentationHints;
 exports.buildInstrumentationTerms = buildInstrumentationTerms;
 exports.buildLightingHints = buildLightingHints;
@@ -34168,6 +34496,7 @@ exports.getRegisteredPersonDimensionLabels = getRegisteredPersonDimensionLabels;
 exports.getRegisteredPersonDimensionOrder = getRegisteredPersonDimensionOrder;
 exports.getRegisteredPersonFieldByDimension = getRegisteredPersonFieldByDimension;
 exports.getRegisteredPickerCatalogs = getRegisteredPickerCatalogs;
+exports.getRegisteredSubjectKeys = getRegisteredSubjectKeys;
 exports.getRenderQuality = getRenderQuality;
 exports.getRenderQualityLabel = getRenderQualityLabel;
 exports.getRenderQualityPromptHint = getRenderQualityPromptHint;
@@ -34228,12 +34557,14 @@ exports.isVantageFraming = isVantageFraming;
 exports.isWizardSupported = isWizardSupported;
 exports.joinPromptHints = joinPromptHints;
 exports.joinPromptParts = joinPromptParts;
+exports.keepableDirectionHints = keepableDirectionHints;
 exports.listPickerCatalogs = listPickerCatalogs;
 exports.migratePersonValue = migratePersonValue;
 exports.modeForFamily = modeForFamily;
 exports.nodeHasInlinePrompt = nodeHasInlinePrompt;
 exports.nodeHasPromptField = nodeHasPromptField;
 exports.nodeSupportsPromptAffixes = nodeSupportsPromptAffixes;
+exports.normalizeSubjectFields = normalizeSubjectFields;
 exports.personPacksVersion = personPacksVersion;
 exports.pickerFanoutTargets = pickerFanoutTargets;
 exports.projectAllCatalogs = projectAllCatalogs;
@@ -34244,11 +34575,13 @@ exports.promptFieldCarriesAffixes = promptFieldCarriesAffixes;
 exports.promptPartSeparator = promptPartSeparator;
 exports.readDirectionFields = readDirectionFields;
 exports.readStructuredFields = readStructuredFields;
+exports.readSubjectFields = readSubjectFields;
 exports.referenceRulesBlock = referenceRulesBlock;
 exports.registerCatalogPack = registerCatalogPack;
 exports.registerPersonPack = registerPersonPack;
 exports.renderDirectionHints = renderDirectionHints;
 exports.renderStructuredFields = renderStructuredFields;
+exports.renderSubjectHints = renderSubjectHints;
 exports.resetCatalogPacks = resetCatalogPacks;
 exports.resetPersonPacks = resetPersonPacks;
 exports.resolveBrandInput = resolveBrandInput;
@@ -34263,6 +34596,7 @@ exports.resolveTemplate = resolveTemplate;
 exports.resolveTerm = resolveTerm;
 exports.resolveVeoI2vInputs = resolveVeoI2vInputs;
 exports.resolveVideoReferenceCore = resolveVideoReferenceCore;
+exports.subjectFieldsForSurface = subjectFieldsForSurface;
 exports.summarizePickerCatalogs = summarizePickerCatalogs;
 exports.toIdentityLockMode = toIdentityLockMode;
 exports.truncateForField = truncateForField;