@nodaro/prompts 1.11.0 → 1.13.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(
@@ -10214,6 +10217,218 @@ function applyTemplate(template, vars) {
     template
   );
 }
+
+// src/prompt-hint-join.ts
+var PROMPT_HINT_SEPARATOR = ". ";
+function joinPromptHints(userPrompt, hints) {
+  if (hints.length === 0) return userPrompt;
+  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(PROMPT_HINT_SEPARATOR);
+}
+
+// src/direction-registry.ts
+var perId = (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 viaListBuilder = (build) => (ids, mode) => build(ids.length === 1 ? ids[0] : [...ids], mode).filter((s) => s.length > 0);
+var viaStringBuilder = (build) => (ids, mode) => {
+  const s = build(ids.length === 1 ? ids[0] : [...ids], mode);
+  return s.length > 0 ? [s] : [];
+};
+var viaMood = (ids, mode) => buildMoodHints({ mood: ids.length === 1 ? ids[0] : [...ids] }, mode).filter(
+  (s) => s.length > 0
+);
+var framing = perId(getFramingPromptHint, getFramingTerm);
+var lighting = perId(getLightingPromptHint, getLightingTerm);
+var exposure = perId(getExposurePromptHint, getExposureTerm);
+var temporal = perId(getTemporalPromptHint, getTemporalTerm);
+var DIRECTION_FIELDS = [
+  { key: "cameraMotion", surface: "video", family: "motion", maxPicks: 1, render: perId(getCameraMotionPromptHint, getCameraMotionTerm) },
+  // Composition (the Framing catalog, one row per category).
+  { key: "shotSize", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "angle", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "coverage", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "composition", surface: "both", family: "look", maxPicks: 2, render: framing },
+  { key: "vantage", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "pose", surface: "both", family: "look", maxPicks: 1, render: perId(getPosePromptHint, getPoseTerm) },
+  { key: "compositionEffect", surface: "both", family: "look", maxPicks: 1, render: perId(getCompositionEffectPromptHint, getCompositionEffectTerm) },
+  // Camera.
+  { key: "cameraFormat", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) },
+  { key: "lens", surface: "both", family: "look", maxPicks: 1, render: perId(getLensPromptHint, getLensTerm) },
+  // Exposure (stills only — a video's exposure rides its own temporal levers).
+  { key: "aperture", surface: "image", family: "look", maxPicks: 1, render: exposure },
+  { key: "shutterSpeed", surface: "image", family: "look", maxPicks: 1, render: exposure },
+  { key: "isoValue", surface: "image", family: "look", maxPicks: 1, render: exposure },
+  // Light (the Lighting catalog, one row per category).
+  { key: "timeOfDay", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "lightingStyle", surface: "both", family: "look", maxPicks: 2, render: lighting },
+  { key: "lightingDirection", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "lightingRatio", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "colorTemperature", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "colorLook", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getColorLookPromptHint, getColorLookTerm) },
+  { key: "atmosphere", surface: "both", family: "look", maxPicks: 2, render: viaListBuilder(buildAtmosphereHints) },
+  { key: "postProcess", surface: "image", family: "look", maxPicks: 2, render: viaListBuilder(buildPostProcessHints) },
+  // Style.
+  { key: "style", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getStylePromptHint, getStyleTerm) },
+  { key: "mood", surface: "both", family: "look", maxPicks: 2, render: viaMood },
+  { key: "aesthetic", surface: "both", family: "look", maxPicks: 2, render: viaStringBuilder(buildAestheticHints) },
+  { key: "photoGenre", surface: "image", family: "look", maxPicks: 1, render: perId(getPhotoGenrePromptHint, getPhotoGenreTerm) },
+  { key: "photographer", surface: "image", family: "look", maxPicks: 2, render: viaStringBuilder(buildPhotographerHints) },
+  { key: "renderQuality", surface: "image", family: "look", maxPicks: 1, render: perId(getRenderQualityPromptHint, getRenderQualityTerm) },
+  // Scene.
+  { key: "setting", surface: "both", family: "look", maxPicks: 1, render: perId(getSettingPromptHint, getSettingTerm) },
+  { key: "era", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getEraPromptHint, getEraTerm) },
+  { key: "backdrop", surface: "both", family: "look", maxPicks: 1, render: perId(getBackdropPromptHint, getBackdropTerm) },
+  // Motion & time.
+  { key: "actionFx", surface: "video", family: "motion", maxPicks: 2, render: viaListBuilder(buildActionFxHints) },
+  { key: "temporalSpeed", surface: "video", family: "motion", maxPicks: 1, render: temporal },
+  { key: "temporalFreeze", surface: "video", family: "motion", maxPicks: 1, render: temporal },
+  { key: "temporalDirection", surface: "video", family: "motion", maxPicks: 1, render: temporal },
+  { key: "temporalShutter", surface: "video", family: "motion", maxPicks: 1, render: temporal },
+  { key: "transition", surface: "video", family: "motion", maxPicks: 2, render: perId(getTransitionPromptHint, getTransitionTerm) },
+  { key: "loopSubject", surface: "video", family: "motion", maxPicks: 1, render: perId(getLoopSubjectPromptHint, getLoopSubjectTerm) },
+  // ── LEGACY BLOCK — see the table doc above. Placed LAST, in today's exact
+  //    `composePromptText` order, so every pre-registry caller is byte-identical.
+  { key: "framingId", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "framingAngleId", surface: "both", family: "look", maxPicks: 1, render: framing },
+  { key: "lightingId", surface: "both", family: "look", maxPicks: 1, render: lighting },
+  { key: "lensId", surface: "both", family: "look", maxPicks: 1, render: perId(getLensPromptHint, getLensTerm) },
+  { key: "cameraFormatId", surface: "both", family: "look", styleGroup: "film", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) }
+];
+var DIRECTION_SPECS = DIRECTION_FIELDS;
+var DIRECTION_KEYS = DIRECTION_FIELDS.map((f) => f.key);
+var FILM_STYLE_KEYS = DIRECTION_SPECS.filter(
+  (f) => f.styleGroup === "film"
+).map((f) => f.key);
+var IMAGE_HINT_MODE_DEFAULT = "full";
+var VIDEO_HINT_MODE_DEFAULT = { look: "full", motion: "compact" };
+function modeForFamily(mode, family) {
+  return typeof mode === "string" ? mode : family === "motion" ? mode.motion : mode.look;
+}
+var DIRECTION_ARRAY_CEILING = 8;
+var DIRECTION_ID_MAX_CHARS = 100;
+function normalizeDirectionIds(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 directionFieldsForSurface(surface) {
+  return DIRECTION_SPECS.filter((f) => f.surface === "both" || f.surface === surface);
+}
+function renderDirectionHintClauses(direction, opts) {
+  if (!direction) return [];
+  const mode = opts.mode ?? "full";
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const spec of DIRECTION_SPECS) {
+    if (spec.surface !== "both" && spec.surface !== opts.surface) continue;
+    const ids = normalizeDirectionIds(
+      direction[spec.key],
+      spec.maxPicks
+    );
+    if (ids.length === 0) continue;
+    for (const hint of spec.render(ids, modeForFamily(mode, spec.family))) {
+      if (hint.length > 0 && !seen.has(hint)) {
+        seen.add(hint);
+        out.push({
+          key: spec.key,
+          family: spec.family,
+          ...spec.styleGroup !== void 0 ? { styleGroup: spec.styleGroup } : {},
+          text: hint
+        });
+      }
+    }
+  }
+  return out;
+}
+function renderDirectionHints(direction, opts) {
+  return renderDirectionHintClauses(direction, opts).map((c) => c.text);
+}
+
+// src/prompt-style-section.ts
+var STYLE_SECTION_HEADER = "[style]:";
+var STYLE_SECTION_GAP = "\n\n";
+var STYLE_SECTION_OPENING = `${STYLE_SECTION_GAP}${STYLE_SECTION_HEADER}
+`;
+function splitStyleSection(prompt) {
+  const at = prompt.lastIndexOf(STYLE_SECTION_OPENING);
+  if (at >= 0) {
+    return { body: prompt.slice(0, at), section: prompt.slice(at + STYLE_SECTION_GAP.length) };
+  }
+  return prompt.startsWith(`${STYLE_SECTION_HEADER}
+`) ? { body: "", section: prompt } : { body: prompt, section: "" };
+}
+function insertBeforeStyleSection(prompt, lines) {
+  if (lines.length === 0) return prompt;
+  const block = lines.join("\n");
+  const { body, section } = splitStyleSection(prompt);
+  if (section.length === 0) return `${prompt}
+${block}`;
+  return `${body.length > 0 ? `${body}
+${block}` : block}${STYLE_SECTION_GAP}${section}`;
+}
+function endsInsideStyleSection(prompt) {
+  const at = prompt.lastIndexOf(STYLE_SECTION_GAP);
+  const lastBlock = at >= 0 ? prompt.slice(at + STYLE_SECTION_GAP.length) : prompt;
+  return lastBlock.startsWith(`${STYLE_SECTION_HEADER}
+`);
+}
+function styleSlotFor(row) {
+  if (row.family === "motion") return "body";
+  return row.styleGroup === "film" ? "film" : "scene";
+}
+function asBodyClauses(texts) {
+  return texts.map((text) => ({ text, slot: "body" }));
+}
+function partitionStyleClauses(direction, opts) {
+  return renderDirectionHintClauses(direction, opts).map((clause) => ({
+    text: clause.text,
+    slot: styleSlotFor(clause)
+  }));
+}
+function styleSectionFromClauses(clauses) {
+  const line = (slot) => clauses.filter((c) => c.slot === slot).map((c) => c.text).join(PROMPT_HINT_SEPARATOR);
+  const lines = [line("film"), line("scene")].filter((l) => l.length > 0);
+  return lines.length === 0 ? "" : `${STYLE_SECTION_HEADER}
+${lines.join("\n")}`;
+}
+function renderStyleSection(direction, opts) {
+  return styleSectionFromClauses(partitionStyleClauses(direction, opts));
+}
+function composeSectionedPrompt(userPrompt, clauses, structuredFragment) {
+  const bodyHints = [
+    ...clauses.filter((c) => c.slot === "body").map((c) => c.text),
+    structuredFragment
+  ].filter((p) => p.length > 0);
+  const section = styleSectionFromClauses(clauses);
+  if (section.length === 0) {
+    return bodyHints.length === 0 ? userPrompt : joinPromptHints(userPrompt ?? "", bodyHints);
+  }
+  const body = bodyHints.length > 0 ? joinPromptHints(userPrompt ?? "", bodyHints) : (userPrompt ?? "").trim();
+  return body.length > 0 ? `${body}${STYLE_SECTION_GAP}${section}` : section;
+}
+function sectionedClauseCosts(userPrompt, clauses, structuredFragment) {
+  const lengthAt = (kept) => composeSectionedPrompt(userPrompt, clauses.slice(0, kept), structuredFragment)?.length ?? 0;
+  const costs = [];
+  let below = lengthAt(0);
+  for (let i = 0; i < clauses.length; i++) {
+    const at = lengthAt(i + 1);
+    costs.push(at - below);
+    below = at;
+  }
+  return costs;
+}
 function composeIdentityDescPart(subject, canonicalDesc, elementInjection) {
   const parts = [];
   const c = canonicalDesc?.trim();
@@ -10284,6 +10499,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 +10542,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 +10573,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 +10669,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 +10683,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 +10732,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 +10750,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 +10962,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();
@@ -10840,9 +11118,29 @@ function reconcileBodySegments(body, bodySegments) {
   }
   return [{ text: body, origin: "user" }];
 }
+function controlSuffixes(body, styleLine, avoidLine) {
+  const separator = (text) => endsInsideStyleSection(text) ? STYLE_SECTION_GAP : "\n";
+  const styleSuffix = styleLine ? `${separator(body)}${styleLine}` : "";
+  const avoidSuffix = avoidLine ? `${separator(body + styleSuffix)}${avoidLine}` : "";
+  return { styleSuffix, avoidSuffix };
+}
 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 +11162,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 +11209,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 +11283,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 +11383,7 @@ ${promptForNext}`;
           ...hybridLockLines,
           ...hybridLocationLockLines,
           ...hybridImageLockLines,
+          ...hybridEntityLockLines,
           ...canonical.lockLines,
           ...extrasRendered.lockLines
         ])];
@@ -11070,6 +11391,7 @@ ${promptForNext}`;
           ...hybridElementDirectives,
           ...hybridLocationElementDirectives,
           ...hybridImageElementDirectives,
+          ...hybridEntityElementDirectives,
           ...canonical.phrases,
           ...canonical.elementDirectives,
           ...extrasRendered.bodyLines,
@@ -11078,9 +11400,7 @@ ${promptForNext}`;
         const lockBlock = allLockLines.length > 0 ? `${allLockLines.join("\n")}
 
 ` : "";
-        const trailingBlock = trailingLines.length > 0 ? `
-${trailingLines.join("\n")}` : "";
-        promptForNext = `${lockBlock}${promptForNext}${trailingBlock}`;
+        promptForNext = `${lockBlock}${insertBeforeStyleSection(promptForNext, trailingLines)}`;
       }
       config2 = {
         ...config2,
@@ -11116,7 +11436,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")}
 
@@ -11127,9 +11448,7 @@ ${trailingLines.join("\n")}` : "";
         ...locCanon.elementDirectives,
         ...objCanon.elementDirectives
       ];
-      const canonTrailingBlock = canonTrailingLines.length > 0 ? `
-${canonTrailingLines.join("\n")}` : "";
-      const composedScene = `${canonLockBlock}${scene}${canonTrailingBlock}`;
+      const composedScene = `${canonLockBlock}${insertBeforeStyleSection(scene, canonTrailingLines)}`;
       prompt2 = config2.referenceLockSnippet ? `${config2.referenceLockSnippet}
 ${composedScene}` : composedScene;
       if (marks) marks.directivesPrefix = "";
@@ -11155,31 +11474,33 @@ ${directives}`;
       }
     }
     const styleText2 = style?.trim();
-    const styleSuffix2 = styleText2 ? `
-Style: ${getStylePromptHint(styleText2) || styleText2}` : "";
+    const styleLine2 = styleText2 ? `Style: ${getStylePromptHint(styleText2) || styleText2}` : "";
     const negPrompt2 = negativePrompt?.trim();
     let nativeNegativePrompt2;
-    let avoidSuffix2 = "";
+    let avoidLine2 = "";
     if (negPrompt2) {
       if (shared.NATIVE_NEGATIVE_PROMPT_MODELS.has(provider)) {
         nativeNegativePrompt2 = negPrompt2.slice(0, shared.getMaxNegativePromptChars(provider));
       } else {
-        avoidSuffix2 = `
-Avoid: ${negPrompt2}`;
+        avoidLine2 = `Avoid: ${negPrompt2}`;
       }
     }
-    if (marks) {
-      marks.styleSuffix = styleSuffix2;
-      marks.avoidSuffix = avoidSuffix2;
-    }
     const maxLen2 = shared.getMaxImagePromptChars(provider);
-    const reserved2 = styleSuffix2.length + avoidSuffix2.length;
+    const preCut2 = controlSuffixes(prompt2, styleLine2, avoidLine2);
+    const reserved2 = preCut2.styleSuffix.length + preCut2.avoidSuffix.length;
     if (prompt2.length + reserved2 > maxLen2) {
+      if (marks) marks.overflowChars += prompt2.length + reserved2 - maxLen2;
       prompt2 = prompt2.slice(0, Math.max(0, maxLen2 - reserved2 - 3)) + "...";
     }
+    const { styleSuffix: styleSuffix2, avoidSuffix: avoidSuffix2 } = controlSuffixes(prompt2, styleLine2, avoidLine2);
+    if (marks) {
+      marks.styleSuffix = styleSuffix2;
+      marks.avoidSuffix = avoidSuffix2;
+    }
     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) {
@@ -11227,37 +11548,41 @@ Avoid: ${negPrompt2}`;
   let prompt = config2.prompt;
   if (charDescs.length > 0) {
     const wrapperTemplate = resolveTemplate("generate-image-wrapper", userTemplates, flowTemplates);
-    prompt = applyTemplate(wrapperTemplate, {
-      userPrompt: prompt,
+    const { body, section } = splitStyleSection(prompt);
+    const wrapped = applyTemplate(wrapperTemplate, {
+      userPrompt: body,
       assetDescriptions: charDescs.join(" ")
     });
+    prompt = section.length > 0 ? `${wrapped}${STYLE_SECTION_GAP}${section}` : wrapped;
   }
   const styleText = style?.trim();
-  const styleSuffix = styleText ? `
-Style: ${getStylePromptHint(styleText) || styleText}` : "";
+  const styleLine = styleText ? `Style: ${getStylePromptHint(styleText) || styleText}` : "";
   const negPrompt = negativePrompt?.trim();
   let nativeNegativePrompt;
-  let avoidSuffix = "";
+  let avoidLine = "";
   if (negPrompt) {
     if (shared.NATIVE_NEGATIVE_PROMPT_MODELS.has(provider)) {
       nativeNegativePrompt = negPrompt.slice(0, shared.getMaxNegativePromptChars(provider));
     } else {
-      avoidSuffix = `
-Avoid: ${negPrompt}`;
+      avoidLine = `Avoid: ${negPrompt}`;
     }
   }
-  if (marks) {
-    marks.styleSuffix = styleSuffix;
-    marks.avoidSuffix = avoidSuffix;
-  }
   const maxLen = shared.getMaxImagePromptChars(provider);
-  const reserved = styleSuffix.length + avoidSuffix.length;
+  const preCut = controlSuffixes(prompt, styleLine, avoidLine);
+  const reserved = preCut.styleSuffix.length + preCut.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)) + "...";
   }
+  const { styleSuffix, avoidSuffix } = controlSuffixes(prompt, styleLine, avoidLine);
+  if (marks) {
+    marks.styleSuffix = styleSuffix;
+    marks.avoidSuffix = avoidSuffix;
+  }
   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 +11592,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,19 +11782,35 @@ 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());
 }
 function buildHybridScene(prompt, refs, finalIndexByUrl) {
-  return prompt.split("\n").map((line) => capitalizeLineInitial(expandImageRefTokensHybrid(line, refs, finalIndexByUrl))).join("\n");
+  const lines = prompt.split("\n");
+  const sectionAt = lines.indexOf(STYLE_SECTION_HEADER);
+  return lines.map((line, i) => {
+    const expanded = expandImageRefTokensHybrid(line, refs, finalIndexByUrl);
+    return sectionAt >= 0 && i >= sectionAt ? expanded : capitalizeLineInitial(expanded);
+  }).join("\n");
 }
 function buildIdentityDirectives(prompt, refs, meta3 = [], suppressedCanonicalLocationIds) {
   return collectIdentities(prompt, refs, meta3).map((id) => buildIdentityDirective(id, suppressedCanonicalLocationIds)).filter((s) => s.length > 0).join("\n");
@@ -11692,9 +12028,16 @@ function renderLens(l) {
   if (l.aperture) bits.push(`f/${l.aperture}`);
   return bits.length > 0 ? `Lens: ${bits.join(", ")}.` : "";
 }
-
-// src/direction-registry.ts
-var perId = (full, compact) => (ids, mode) => {
+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);
@@ -11702,80 +12045,45 @@ var perId = (full, compact) => (ids, mode) => {
   }
   return out;
 };
-var viaListBuilder = (build) => (ids, mode) => build(ids.length === 1 ? ids[0] : [...ids], mode).filter((s) => s.length > 0);
-var viaStringBuilder = (build) => (ids, mode) => {
-  const s = build(ids.length === 1 ? ids[0] : [...ids], mode);
-  return s.length > 0 ? [s] : [];
-};
-var viaMood = (ids, mode) => buildMoodHints({ mood: ids.length === 1 ? ids[0] : [...ids] }, mode).filter(
-  (s) => s.length > 0
-);
-var framing = perId(getFramingPromptHint, getFramingTerm);
-var lighting = perId(getLightingPromptHint, getLightingTerm);
-var exposure = perId(getExposurePromptHint, getExposureTerm);
-var temporal = perId(getTemporalPromptHint, getTemporalTerm);
-var DIRECTION_FIELDS = [
-  { key: "cameraMotion", surface: "video", family: "motion", maxPicks: 1, render: perId(getCameraMotionPromptHint, getCameraMotionTerm) },
-  // Composition (the Framing catalog, one row per category).
-  { key: "shotSize", surface: "both", family: "look", maxPicks: 1, render: framing },
-  { key: "angle", surface: "both", family: "look", maxPicks: 1, render: framing },
-  { key: "coverage", surface: "both", family: "look", maxPicks: 1, render: framing },
-  { key: "composition", surface: "both", family: "look", maxPicks: 2, render: framing },
-  { key: "vantage", surface: "both", family: "look", maxPicks: 1, render: framing },
-  { key: "pose", surface: "both", family: "look", maxPicks: 1, render: perId(getPosePromptHint, getPoseTerm) },
-  { key: "compositionEffect", surface: "both", family: "look", maxPicks: 1, render: perId(getCompositionEffectPromptHint, getCompositionEffectTerm) },
-  // Camera.
-  { key: "cameraFormat", surface: "both", family: "look", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) },
-  { key: "lens", surface: "both", family: "look", maxPicks: 1, render: perId(getLensPromptHint, getLensTerm) },
-  // Exposure (stills only — a video's exposure rides its own temporal levers).
-  { key: "aperture", surface: "image", family: "look", maxPicks: 1, render: exposure },
-  { key: "shutterSpeed", surface: "image", family: "look", maxPicks: 1, render: exposure },
-  { key: "isoValue", surface: "image", family: "look", maxPicks: 1, render: exposure },
-  // Light (the Lighting catalog, one row per category).
-  { key: "timeOfDay", surface: "both", family: "look", maxPicks: 1, render: lighting },
-  { key: "lightingStyle", surface: "both", family: "look", maxPicks: 2, render: lighting },
-  { key: "lightingDirection", surface: "both", family: "look", maxPicks: 1, render: lighting },
-  { key: "lightingRatio", surface: "both", family: "look", maxPicks: 1, render: lighting },
-  { key: "colorTemperature", surface: "both", family: "look", maxPicks: 1, render: lighting },
-  { key: "colorLook", surface: "both", family: "look", maxPicks: 1, render: perId(getColorLookPromptHint, getColorLookTerm) },
-  { key: "atmosphere", surface: "both", family: "look", maxPicks: 2, render: viaListBuilder(buildAtmosphereHints) },
-  { key: "postProcess", surface: "image", family: "look", maxPicks: 2, render: viaListBuilder(buildPostProcessHints) },
-  // Style.
-  { key: "style", surface: "both", family: "look", maxPicks: 1, render: perId(getStylePromptHint, getStyleTerm) },
-  { key: "mood", surface: "both", family: "look", maxPicks: 2, render: viaMood },
-  { key: "aesthetic", surface: "both", family: "look", maxPicks: 2, render: viaStringBuilder(buildAestheticHints) },
-  { key: "photoGenre", surface: "image", family: "look", maxPicks: 1, render: perId(getPhotoGenrePromptHint, getPhotoGenreTerm) },
-  { key: "photographer", surface: "image", family: "look", maxPicks: 2, render: viaStringBuilder(buildPhotographerHints) },
-  { key: "renderQuality", surface: "image", family: "look", maxPicks: 1, render: perId(getRenderQualityPromptHint, getRenderQualityTerm) },
-  // Scene.
-  { key: "setting", surface: "both", family: "look", maxPicks: 1, render: perId(getSettingPromptHint, getSettingTerm) },
-  { key: "era", surface: "both", family: "look", maxPicks: 1, render: perId(getEraPromptHint, getEraTerm) },
-  { key: "backdrop", surface: "both", family: "look", maxPicks: 1, render: perId(getBackdropPromptHint, getBackdropTerm) },
-  // Motion & time.
-  { key: "actionFx", surface: "video", family: "motion", maxPicks: 2, render: viaListBuilder(buildActionFxHints) },
-  { key: "temporalSpeed", surface: "video", family: "motion", maxPicks: 1, render: temporal },
-  { key: "temporalFreeze", surface: "video", family: "motion", maxPicks: 1, render: temporal },
-  { key: "temporalDirection", surface: "video", family: "motion", maxPicks: 1, render: temporal },
-  { key: "temporalShutter", surface: "video", family: "motion", maxPicks: 1, render: temporal },
-  { key: "transition", surface: "video", family: "motion", maxPicks: 2, render: perId(getTransitionPromptHint, getTransitionTerm) },
-  { key: "loopSubject", surface: "video", family: "motion", maxPicks: 1, render: perId(getLoopSubjectPromptHint, getLoopSubjectTerm) },
-  // ── LEGACY BLOCK — see the table doc above. Placed LAST, in today's exact
-  //    `composePromptText` order, so every pre-registry caller is byte-identical.
-  { key: "framingId", surface: "both", family: "look", maxPicks: 1, render: framing },
-  { key: "framingAngleId", surface: "both", family: "look", maxPicks: 1, render: framing },
-  { key: "lightingId", surface: "both", family: "look", maxPicks: 1, render: lighting },
-  { key: "lensId", surface: "both", family: "look", maxPicks: 1, render: perId(getLensPromptHint, getLensTerm) },
-  { key: "cameraFormatId", surface: "both", family: "look", maxPicks: 1, render: perId(getCameraFormatPromptHint, getCameraFormatTerm) }
+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 DIRECTION_KEYS = DIRECTION_FIELDS.map((f) => f.key);
-var IMAGE_HINT_MODE_DEFAULT = "full";
-var VIDEO_HINT_MODE_DEFAULT = { look: "full", motion: "compact" };
-function modeForFamily(mode, family) {
-  return typeof mode === "string" ? mode : family === "motion" ? mode.motion : mode.look;
+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 DIRECTION_ARRAY_CEILING = 8;
-var DIRECTION_ID_MAX_CHARS = 100;
-function normalizeDirectionIds(value, maxPicks) {
+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);
@@ -11787,22 +12095,54 @@ function normalizeDirectionIds(value, maxPicks) {
   }
   return ids.slice(0, maxPicks);
 }
-function directionFieldsForSurface(surface) {
-  return DIRECTION_FIELDS.filter((f) => f.surface === "both" || f.surface === surface);
+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 renderDirectionHints(direction, opts) {
-  if (!direction) return [];
+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 DIRECTION_FIELDS) {
+  for (const spec of SUBJECT_FIELDS) {
     if (spec.surface !== "both" && spec.surface !== opts.surface) continue;
-    const ids = normalizeDirectionIds(
-      direction[spec.key],
-      spec.maxPicks
-    );
-    if (ids.length === 0) continue;
-    for (const hint of spec.render(ids, modeForFamily(mode, spec.family))) {
+    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);
@@ -11812,11 +12152,15 @@ function renderDirectionHints(direction, opts) {
   return out;
 }
 
-// src/prompt-hint-join.ts
-var PROMPT_HINT_SEPARATOR = ". ";
-function joinPromptHints(userPrompt, hints) {
-  if (hints.length === 0) return userPrompt;
-  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(PROMPT_HINT_SEPARATOR);
+// src/hint-shedding.ts
+function keepableDirectionHints(hintClauses, kept, deficit, clauseCosts) {
+  let remaining = deficit;
+  let next = kept;
+  while (next > 0 && remaining > 0) {
+    next -= 1;
+    remaining -= clauseCosts?.[next] ?? hintClauses[next].length + PROMPT_HINT_SEPARATOR.length;
+  }
+  return next;
 }
 
 // src/ref-binding.ts
@@ -12168,9 +12512,7 @@ function resolveVideoReferenceCore(args) {
     const lockBlock = lockLines.length > 0 ? `${lockLines.join("\n")}
 
 ` : "";
-    const trailingBlock = trailingLines.length > 0 ? `
-${trailingLines.join("\n")}` : "";
-    finalPrompt = `${lockBlock}${finalPrompt}${trailingBlock}`;
+    finalPrompt = `${lockBlock}${insertBeforeStyleSection(finalPrompt, trailingLines)}`;
   } else {
     const allFallbackLines = [...fallbackDirectiveLines, ...extraDirectiveLines];
     if (allFallbackLines.length > 0) {
@@ -12404,17 +12746,34 @@ function assembleSunoInput(input) {
 }
 
 // src/assemble-image-input.ts
-function composePromptText(userPrompt, direction, structured) {
-  const hints = [
-    ...renderDirectionHints(direction, { surface: "image", mode: IMAGE_HINT_MODE_DEFAULT }),
-    structured ? renderStructuredFields(structured) : ""
-  ].filter((p) => p.length > 0);
-  return joinPromptHints(userPrompt, hints);
+function renderImageHintPieces(subject, direction, structured) {
+  return {
+    hintClauses: [
+      ...asBodyClauses(
+        renderSubjectHints(subject, {
+          surface: "image",
+          mode: SUBJECT_IMAGE_HINT_MODE_DEFAULT
+        })
+      ),
+      ...partitionStyleClauses(direction, {
+        surface: "image",
+        mode: IMAGE_HINT_MODE_DEFAULT
+      })
+    ].filter((c) => c.text.length > 0),
+    structuredFragment: structured ? renderStructuredFields(structured) : ""
+  };
+}
+function composePromptText(userPrompt, pieces, keptHintClauses) {
+  return composeSectionedPrompt(
+    userPrompt,
+    pieces.hintClauses.slice(0, keptHintClauses),
+    pieces.structuredFragment
+  );
 }
 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 +12796,21 @@ 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);
+  if (fitted.overflowChars > 0) {
+    const costs = sectionedClauseCosts(
+      input.userPrompt,
+      pieces.hintClauses,
+      pieces.structuredFragment
+    );
+    const texts = pieces.hintClauses.map((c) => c.text);
+    while (fitted.overflowChars > 0 && kept > 0) {
+      kept = keepableDirectionHints(texts, kept, fitted.overflowChars, costs);
+      fitted = assembleWith(kept);
+    }
+  }
+  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 +12821,35 @@ function assembleImageInput(input) {
 
 // src/assemble-video-input.ts
 function composeVideoPromptText(userPrompt, direction, structured, opts) {
-  const hints = [
-    ...renderDirectionHints(direction, {
+  const hintClauses = [
+    ...asBodyClauses(
+      renderSubjectHints(opts?.subject, {
+        surface: "video",
+        mode: opts?.subjectHintMode ?? SUBJECT_VIDEO_HINT_MODE_DEFAULT
+      })
+    ),
+    ...partitionStyleClauses(direction, {
       surface: "video",
       mode: opts?.hintMode ?? VIDEO_HINT_MODE_DEFAULT
-    }),
-    structured ? renderStructuredFields(structured) : ""
-  ].filter((p) => p.length > 0);
-  if (hints.length === 0) return userPrompt;
-  return joinPromptHints(userPrompt ?? "", hints);
+    })
+  ].filter((c) => c.text.length > 0);
+  const structuredFragment = structured ? renderStructuredFields(structured) : "";
+  const composeWith = (kept2) => composeSectionedPrompt(userPrompt, hintClauses.slice(0, kept2), structuredFragment);
+  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;
+  if (framedLength <= cap) return body;
+  const costs = sectionedClauseCosts(userPrompt, hintClauses, structuredFragment);
+  const texts = hintClauses.map((c) => c.text);
+  while (framedLength > cap && kept > 0) {
+    kept = keepableDirectionHints(texts, kept, framedLength - cap, costs);
+    body = composeWith(kept);
+    framedLength = frame(body)?.length ?? 0;
+  }
+  return body;
 }
 
 // src/read-node-direction.ts
@@ -12480,6 +12874,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 = {
@@ -33804,6 +34223,7 @@ exports.EXPOSURE_SETTINGS = EXPOSURE_SETTINGS;
 exports.FACTORY_PRESETS = FACTORY_PRESETS;
 exports.FACTORY_SNIPPETS = FACTORY_SNIPPETS;
 exports.FILM_STILL_PREFIX = FILM_STILL_PREFIX;
+exports.FILM_STYLE_KEYS = FILM_STYLE_KEYS;
 exports.FRAMINGS = FRAMINGS;
 exports.FRAMING_CATEGORY_LABELS = FRAMING_CATEGORY_LABELS;
 exports.FRAMING_CATEGORY_ORDER = FRAMING_CATEGORY_ORDER;
@@ -33839,6 +34259,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;
@@ -33913,11 +34334,22 @@ exports.SNIPPET_MEDIA_VALUES = SNIPPET_MEDIA_VALUES;
 exports.STYLES = STYLES;
 exports.STYLE_IDS = STYLE_IDS;
 exports.STYLE_PRESETS = STYLE_PRESETS;
+exports.STYLE_SECTION_GAP = STYLE_SECTION_GAP;
+exports.STYLE_SECTION_HEADER = STYLE_SECTION_HEADER;
 exports.STYLINGS = STYLINGS;
 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;
@@ -33956,6 +34388,7 @@ exports.applyPickerJson = applyPickerJson;
 exports.applyPromptAffixes = applyPromptAffixes;
 exports.applyReferenceOrderToVideo = applyReferenceOrderToVideo;
 exports.applyTemplate = applyTemplate;
+exports.asBodyClauses = asBodyClauses;
 exports.assembleImageInput = assembleImageInput;
 exports.assembleSunoInput = assembleSunoInput;
 exports.buildActionFxHints = buildActionFxHints;
@@ -33978,6 +34411,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;
@@ -34028,6 +34462,7 @@ exports.composeCameraMotionTermFromConnections = composeCameraMotionTermFromConn
 exports.composeCharacterFxHintFromConnections = composeCharacterFxHintFromConnections;
 exports.composeNegative = composeNegative;
 exports.composePickerCatalogs = composePickerCatalogs;
+exports.composeSectionedPrompt = composeSectionedPrompt;
 exports.composeSoundHintFromConnections = composeSoundHintFromConnections;
 exports.composeTransitionHintFromConnections = composeTransitionHintFromConnections;
 exports.composeVideoPromptText = composeVideoPromptText;
@@ -34036,6 +34471,7 @@ exports.computeNodePrompt = computeNodePrompt;
 exports.computePackSidecarCoverage = computePackSidecarCoverage;
 exports.deriveTerm = deriveTerm;
 exports.directionFieldsForSurface = directionFieldsForSurface;
+exports.endsInsideStyleSection = endsInsideStyleSection;
 exports.expandImagePositionRefs = expandImagePositionRefs;
 exports.expandImageRefTokens = expandImageRefTokens;
 exports.filmStillPrefix = filmStillPrefix;
@@ -34168,6 +34604,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;
@@ -34221,6 +34658,7 @@ exports.getWardrobePromptHint = getWardrobePromptHint;
 exports.groupFactoryPresets = groupFactoryPresets;
 exports.hasUpstreamCharacter = hasUpstreamCharacter;
 exports.identityRefsSentence = identityRefsSentence;
+exports.insertBeforeStyleSection = insertBeforeStyleSection;
 exports.isAnalyzablePicker = isAnalyzablePicker;
 exports.isInstrumentalVocal = isInstrumentalVocal;
 exports.isSuspiciousDerivedTerm = isSuspiciousDerivedTerm;
@@ -34228,12 +34666,15 @@ 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.partitionStyleClauses = partitionStyleClauses;
 exports.personPacksVersion = personPacksVersion;
 exports.pickerFanoutTargets = pickerFanoutTargets;
 exports.projectAllCatalogs = projectAllCatalogs;
@@ -34244,11 +34685,15 @@ 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.renderDirectionHintClauses = renderDirectionHintClauses;
 exports.renderDirectionHints = renderDirectionHints;
 exports.renderStructuredFields = renderStructuredFields;
+exports.renderStyleSection = renderStyleSection;
+exports.renderSubjectHints = renderSubjectHints;
 exports.resetCatalogPacks = resetCatalogPacks;
 exports.resetPersonPacks = resetPersonPacks;
 exports.resolveBrandInput = resolveBrandInput;
@@ -34263,6 +34708,11 @@ exports.resolveTemplate = resolveTemplate;
 exports.resolveTerm = resolveTerm;
 exports.resolveVeoI2vInputs = resolveVeoI2vInputs;
 exports.resolveVideoReferenceCore = resolveVideoReferenceCore;
+exports.sectionedClauseCosts = sectionedClauseCosts;
+exports.splitStyleSection = splitStyleSection;
+exports.styleSectionFromClauses = styleSectionFromClauses;
+exports.styleSlotFor = styleSlotFor;
+exports.subjectFieldsForSurface = subjectFieldsForSurface;
 exports.summarizePickerCatalogs = summarizePickerCatalogs;
 exports.toIdentityLockMode = toIdentityLockMode;
 exports.truncateForField = truncateForField;