@nodaro/prompts 1.7.3 → 1.8.1

package/src/picker-catalogs.ts

@@ -59,6 +59,7 @@ import { ANIMALS, ANIMAL_SUBCATEGORY_LABELS, ANIMAL_SUBCATEGORY_ORDER } from "@n
 import { VEHICLES, VEHICLE_SUBCATEGORY_LABELS, VEHICLE_SUBCATEGORY_ORDER } from "@nodaro/shared"
 import { WEAPONS, WEAPON_SUBCATEGORY_LABELS, WEAPON_SUBCATEGORY_ORDER } from "@nodaro/shared"
 import { FURNITURE, FURNITURE_SUBCATEGORY_LABELS, FURNITURE_SUBCATEGORY_ORDER } from "@nodaro/shared"
+import type { ProjectedCatalog, ProjectedCatalogOption, ProjectedCatalogDimension } from "@nodaro/shared"
 import { HELD_PROPS, HELD_PROP_CATEGORY_LABELS, HELD_PROP_CATEGORY_ORDER } from "./held-prop.js"
 import { FRAMINGS, FRAMING_FIELD_BY_CATEGORY, FRAMING_CATEGORY_LABELS } from "./framing.js"
 import { LIGHTINGS, LIGHTING_FIELD_BY_CATEGORY, LIGHTING_CATEGORY_ORDER, LIGHTING_CATEGORY_LABELS } from "./lighting.js"
@@ -71,6 +72,8 @@ import { MUSIC_ENERGIES, MUSIC_EMOTIONS, MUSIC_VIBES } from "./music-mood.js"
 import { INSTRUMENTS, PRODUCTION_STYLES, VOCAL_PRESENCE, SINGING_STYLES } from "./instrumentation.js"
 import { VOICE_AGES, VOICE_GENDERS, VOICE_LANGUAGES, VOICE_ACCENTS, VOICE_TIMBRES } from "./voice-character.js"
 import { VOICE_PACES, VOICE_EMOTIONS, VOICE_ARCHETYPES } from "./voice-delivery.js"
+import { composePickerCatalogs, getRegisteredCatalogPacks, catalogPacksVersion } from "./catalog-packs.js"
+import { deriveTerm, resolveTerm } from "./term.js"
 
 export interface PickerOption {
   readonly id: string
@@ -79,6 +82,15 @@ export interface PickerOption {
   /** The group id (matches `categoryOrder` / `categoryLabels`). */
   readonly category?: string
   readonly promptHint: string
+  /**
+   * The short professional term this id injects in COMPACT hint mode ("whip
+   * pan left" where `promptHint` is the full mechanism sentence). Always
+   * present and already RESOLVED via `resolveTerm` — an authored `term` when
+   * the catalog entry carries one, the derived label otherwise, and `""` for
+   * a no-op ("auto"/"none") entry that injects nothing. Consumers render
+   * `label` and inject `term`; they never derive it themselves.
+   */
+  readonly term: string
   /** Only present if the source catalog entry already carries a data icon/emoji/thumbnail field. */
   readonly icon?: string
 }
@@ -125,6 +137,8 @@ interface BaseCatalogEntry {
   readonly label: string
   readonly description: string
   readonly promptHint: string
+  /** Optional authored compact term (see `term.ts` for the convention). */
+  readonly term?: string
 }
 
 /**
@@ -145,6 +159,10 @@ function toOptions<T extends BaseCatalogEntry>(
       id: e.id,
       label: e.label,
       promptHint: e.promptHint,
+      // Resolved here — never at the consumer — so an authored `term` on the
+      // catalog entry flows through automatically and a no-op entry resolves
+      // to "".
+      term: resolveTerm(e),
     }
     if (e.description) opt.description = e.description
     if (categoryField) opt.category = e[categoryField] as unknown as string
@@ -164,6 +182,8 @@ interface ObjectCatalogEntry {
   readonly label: string
   readonly subcategory: string
   readonly description: string
+  /** Optional authored compact term (see `term.ts` for the convention). */
+  readonly term?: string
 }
 function objectOptions(
   arr: ReadonlyArray<ObjectCatalogEntry>,
@@ -175,6 +195,17 @@ function objectOptions(
     description: e.description,
     category: e.subcategory,
     promptHint: phrase(e.label.toLowerCase(), e.description),
+    // 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
+    // professional term for a concrete object ("golden retriever", "katana").
+    // The fallback goes through `deriveTerm` — NOT a bare `toLowerCase()` — so
+    // a parenthetical label ("Rifle (bolt-action)") is stripped the same way
+    // every other catalog strips it. That also keeps the guard test honest:
+    // it treats `term !== deriveTerm(label)` as proof a human authored the
+    // term, so a fallback that diverges from `deriveTerm` would make a mangled
+    // value look authored and ship it.
+    term: e.term ?? deriveTerm(e.label),
   }))
 }
 
@@ -279,11 +310,11 @@ function perFieldDims(
  */
 function musicGenreDims(fields: ReadonlyArray<string>): ReadonlyArray<PickerDimension> {
   const optionsByField: Record<string, ReadonlyArray<PickerOption>> = {
-    genre: MUSIC_GENRES.map((g) => ({ id: g.id, label: g.label, description: g.description, category: g.category, promptHint: g.promptHint })),
+    genre: MUSIC_GENRES.map((g) => ({ id: g.id, label: g.label, description: g.description, category: g.category, promptHint: g.promptHint, term: resolveTerm(g) })),
     subgenre: MUSIC_GENRES.flatMap((g) =>
-      g.subgenres.map((s) => ({ id: s.id, label: s.label, promptHint: s.promptHint })),
+      g.subgenres.map((s) => ({ id: s.id, label: s.label, promptHint: s.promptHint, term: resolveTerm(s) })),
     ),
-    era: MUSIC_ERAS.map((e) => ({ id: e.id, label: e.label, description: e.description, promptHint: e.promptHint })),
+    era: MUSIC_ERAS.map((e) => ({ id: e.id, label: e.label, description: e.description, promptHint: e.promptHint, term: resolveTerm(e) })),
   }
   return fields.map((field) => {
     const options = optionsByField[field]
@@ -719,21 +750,46 @@ const MULTI_CATALOGS: readonly PickerCatalog[] = [
   },
 ]
 
-export const PICKER_CATALOGS: readonly PickerCatalog[] = [
+/**
+ * The frozen upstream base — the pure-data catalogs as authored, never mutated
+ * in place. Deployment curation is additive-by-registration (catalog packs);
+ * `getRegisteredPickerCatalogs()` is the pack-composed view every enumerating
+ * consumer reads.
+ */
+export const PICKER_CATALOGS: readonly PickerCatalog[] = Object.freeze([
   ...SINGLE_CATALOGS,
   ...MULTI_CATALOGS,
-]
+])
+
+let _registeredMemo: { v: number; catalogs: readonly PickerCatalog[] } | null = null
+/**
+ * The pack-composed picker catalogs — the single funnel every enumerating
+ * consumer (funnel getters, /v1/catalogs, MCP, completeness tests) reads.
+ * Memoized on the pack registry version so late registration is reflected.
+ *
+ * DEFERRED PLUG-IN POINT (do not build in Phase 0): a future `CatalogPolicy`
+ * filter (deny-by-tag / override, per read kind) applies HERE, after pack
+ * composition, e.g. `applyCatalogPolicy(composed, runtimePolicy())`.
+ */
+export function getRegisteredPickerCatalogs(): readonly PickerCatalog[] {
+  const v = catalogPacksVersion()
+  if (_registeredMemo && _registeredMemo.v === v) return _registeredMemo.catalogs
+  const catalogs = composePickerCatalogs(PICKER_CATALOGS, getRegisteredCatalogPacks())
+  _registeredMemo = { v, catalogs }
+  return catalogs
+}
 
 /** Resolve a catalog by `nodeType` first, then by `catalogId`. */
 export function getPickerCatalog(nodeTypeOrCatalogId: string): PickerCatalog | undefined {
+  const all = getRegisteredPickerCatalogs()
   return (
-    PICKER_CATALOGS.find((c) => c.nodeType === nodeTypeOrCatalogId) ??
-    PICKER_CATALOGS.find((c) => c.catalogId === nodeTypeOrCatalogId)
+    all.find((c) => c.nodeType === nodeTypeOrCatalogId) ??
+    all.find((c) => c.catalogId === nodeTypeOrCatalogId)
   )
 }
 
 export function listPickerCatalogs(): readonly PickerCatalog[] {
-  return PICKER_CATALOGS
+  return getRegisteredPickerCatalogs()
 }
 
 // ─── Summary + projection (for MCP / REST exposure) ──────────────────────────
@@ -753,7 +809,7 @@ export interface PickerCatalogSummary {
 
 /** Lightweight directory of every picker catalog — no option payloads. */
 export function summarizePickerCatalogs(): readonly PickerCatalogSummary[] {
-  return PICKER_CATALOGS.map((c) => ({
+  return getRegisteredPickerCatalogs().map((c) => ({
     nodeType: c.nodeType,
     label: c.label,
     catalogId: c.catalogId,
@@ -778,38 +834,18 @@ export interface ProjectPickerCatalogOptions {
   readonly field?: string
 }
 
-/** An option after projection — description/promptHint present only when detail="full". */
-export interface ProjectedPickerOption {
-  readonly id: string
-  readonly label: string
-  readonly description?: string
-  readonly category?: string
-  readonly promptHint?: string
-  readonly icon?: string
-}
-
-export interface ProjectedPickerDimension {
-  readonly field: string
-  readonly label: string
-  readonly options: readonly ProjectedPickerOption[]
-}
-
-export interface ProjectedPickerCatalog {
-  readonly nodeType: string
-  readonly label: string
-  readonly catalogId: string
-  readonly kind: "single" | "multi"
-  readonly valueField?: string
-  readonly defaultValue?: string
-  readonly categoryOrder?: readonly string[]
-  readonly categoryLabels?: Readonly<Record<string, string>>
-  readonly options?: readonly ProjectedPickerOption[]
-  readonly fields?: readonly string[]
-  readonly dimensions?: readonly ProjectedPickerDimension[]
-  readonly detail: PickerCatalogDetail
-}
+// The projection shape now lives in `@nodaro/shared` (Apache) as the tag-free
+// `/v1/catalogs` wire contract — the ONLY catalog type that crosses that
+// boundary. These prompts-side names are kept as aliases so existing importers
+// (backend route, MCP, SDK mirror) are unaffected.
+export type ProjectedPickerOption = ProjectedCatalogOption
+export type ProjectedPickerDimension = ProjectedCatalogDimension
+export type ProjectedPickerCatalog = ProjectedCatalog
 
 function projectOption(o: PickerOption, detail: PickerCatalogDetail): ProjectedPickerOption {
+  // `term` rides at BOTH detail levels: a thin client renders `label` and
+  // injects `term`, so compact must carry it — it is what makes compact hint
+  // mode possible without a second round-trip for the full payload.
   return detail === "full"
     ? {
         id: o.id,
@@ -817,9 +853,10 @@ function projectOption(o: PickerOption, detail: PickerCatalogDetail): ProjectedP
         description: o.description,
         category: o.category,
         promptHint: o.promptHint,
+        term: o.term,
         icon: o.icon,
       }
-    : { id: o.id, label: o.label, category: o.category, icon: o.icon }
+    : { id: o.id, label: o.label, category: o.category, term: o.term, icon: o.icon }
 }
 
 /** Project a catalog to the wire shape: compact by default, optional category/field filter. */
@@ -856,3 +893,12 @@ export function projectPickerCatalog(
     })),
   }
 }
+
+/**
+ * Project every REGISTERED (pack-composed) catalog to the tag-free
+ * `/v1/catalogs` wire shape. This is what the `GET /v1/catalogs` route and its
+ * SDK resource serve, so a deployment's vendored packs are reflected verbatim.
+ */
+export function projectAllCatalogs(opts: { detail?: PickerCatalogDetail } = {}): ProjectedCatalog[] {
+  return getRegisteredPickerCatalogs().map((c) => projectPickerCatalog(c, { detail: opts.detail }))
+}

package/src/pose.ts

@@ -20,6 +20,8 @@
  * backend orchestrator.
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export type PoseCategory =
   | "standing"
   | "seated"
@@ -37,6 +39,15 @@ export interface Pose {
   readonly category: PoseCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * Compact professional term injected instead of `promptHint` in compact hint
+   * mode. Authored only where the lowercased label is not what a photographer
+   * would write for the pose — bare sub-dimension modifiers ("Tilted Side"),
+   * labels that collide with a different meaning in a generation prompt
+   * ("Painting"), and telegraphic UI phrasings ("Head Over Shoulder").
+   * Everywhere else the derived label already IS the term.
+   */
+  readonly term?: string
 }
 
 export const POSES: ReadonlyArray<Pose> = [
@@ -45,23 +56,23 @@ export const POSES: ReadonlyArray<Pose> = [
   { id: "confident-stance",   label: "Confident Stance",   category: "standing", description: "Feet apart, shoulders back",  promptHint: "standing in a confident stance with feet apart, shoulders back, and head up" },
   { id: "hands-on-hips",      label: "Hands on Hips",      category: "standing", description: "Hands on hips",               promptHint: "standing with hands on hips" },
   { id: "arms-crossed",       label: "Arms Crossed",       category: "standing", description: "Arms folded across chest",    promptHint: "standing with arms crossed over the chest" },
-  { id: "leaning",            label: "Leaning",            category: "standing", description: "Leaning against something",   promptHint: "leaning casually against a wall or surface" },
+  { id: "leaning",            label: "Leaning",            category: "standing", description: "Leaning against something",   promptHint: "leaning casually against a wall or surface", term: "leaning casually against a surface" },
   { id: "hero-pose",          label: "Hero Pose",          category: "standing", description: "Dramatic heroic stance",      promptHint: "standing in a dramatic heroic pose, chest out, looking forward with purpose" },
   { id: "contrapposto",       label: "Contrapposto",       category: "standing", description: "Hip tilted, weight on one leg", promptHint: "standing in contrapposto, weight shifted to one leg with the opposite hip tilted out" },
-  { id: "leaning-against-wall", label: "Leaning Against Wall", category: "standing", description: "Casually leaning on a wall", promptHint: "leaning casually against a wall, shoulder or back resting on the surface" },
-  { id: "hands-behind-head",  label: "Hands Behind Head",  category: "standing", description: "Both hands clasped behind head", promptHint: "standing with both hands clasped behind the head, elbows out" },
-  { id: "hands-behind-back",  label: "Hands Behind Back",  category: "standing", description: "Hands clasped behind back",   promptHint: "standing with hands clasped behind the back, posture upright" },
+  { id: "leaning-against-wall", label: "Leaning Against Wall", category: "standing", description: "Casually leaning on a wall", promptHint: "leaning casually against a wall, shoulder or back resting on the surface", term: "leaning against a wall" },
+  { id: "hands-behind-head",  label: "Hands Behind Head",  category: "standing", description: "Both hands clasped behind head", promptHint: "standing with both hands clasped behind the head, elbows out", term: "hands clasped behind the head" },
+  { id: "hands-behind-back",  label: "Hands Behind Back",  category: "standing", description: "Hands clasped behind back",   promptHint: "standing with hands clasped behind the back, posture upright", term: "hands clasped behind the back" },
 
   // -------------------- Seated --------------------
   { id: "sitting",            label: "Sitting",            category: "seated",   description: "Sitting naturally",           promptHint: "sitting naturally" },
-  { id: "cross-legged",       label: "Cross-legged",       category: "seated",   description: "Seated cross-legged on floor", promptHint: "sitting cross-legged on the ground" },
+  { id: "cross-legged",       label: "Cross-legged",       category: "seated",   description: "Seated cross-legged on floor", promptHint: "sitting cross-legged on the ground", term: "sitting cross-legged" },
   { id: "kneeling",           label: "Kneeling",           category: "seated",   description: "Kneeling on the ground",      promptHint: "kneeling on one or both knees" },
   { id: "crouching",          label: "Crouching",          category: "seated",   description: "Crouched low",                promptHint: "crouched low with knees bent" },
   { id: "lounging",           label: "Lounging",           category: "seated",   description: "Reclined, relaxed sitting",   promptHint: "lounging in a relaxed, reclined position" },
-  { id: "sitting-edge-of-bed", label: "Sitting on Edge of Bed", category: "seated", description: "Perched on the edge of a bed", promptHint: "perched on the edge of a bed, hands resting on the mattress" },
-  { id: "chair-arm-drape",    label: "Legs Draped Over Chair", category: "seated", description: "Legs draped over chair arm", promptHint: "sitting sideways in a chair with legs draped casually over one arm" },
-  { id: "elbow-propped",      label: "Cheek on Propped Elbow", category: "seated", description: "Cheek resting on a propped elbow", promptHint: "seated with cheek resting against a propped-up elbow, contemplative" },
-  { id: "lying-on-stomach-reading", label: "Lying Prone Reading", category: "seated", description: "Lying prone, propped on elbows reading", promptHint: "lying on the stomach, propped up on elbows while reading" },
+  { id: "sitting-edge-of-bed", label: "Sitting on Edge of Bed", category: "seated", description: "Perched on the edge of a bed", promptHint: "perched on the edge of a bed, hands resting on the mattress", term: "sitting on the edge of a bed" },
+  { id: "chair-arm-drape",    label: "Legs Draped Over Chair", category: "seated", description: "Legs draped over chair arm", promptHint: "sitting sideways in a chair with legs draped casually over one arm", term: "legs draped over the chair arm" },
+  { id: "elbow-propped",      label: "Cheek on Propped Elbow", category: "seated", description: "Cheek resting on a propped elbow", promptHint: "seated with cheek resting against a propped-up elbow, contemplative", term: "cheek resting on a propped elbow" },
+  { id: "lying-on-stomach-reading", label: "Lying Prone Reading", category: "seated", description: "Lying prone, propped on elbows reading", promptHint: "lying on the stomach, propped up on elbows while reading", term: "lying prone propped on elbows, reading" },
 
   // -------------------- Movement --------------------
   { id: "walking",            label: "Walking",            category: "movement", description: "Mid-stride walking",          promptHint: "walking, caught mid-stride" },
@@ -74,20 +85,20 @@ export const POSES: ReadonlyArray<Pose> = [
   { id: "stretching",         label: "Stretching",         category: "movement", description: "Full-body stretch, arms overhead", promptHint: "in a full-body stretch with both arms reaching overhead" },
   { id: "reaching-up",        label: "Reaching Up",        category: "movement", description: "Arms extended overhead",      promptHint: "one or both arms extended overhead, reaching upward" },
   { id: "kissing",            label: "Kissing",            category: "movement", description: "Locked in a kiss",            promptHint: "locked in a kiss, faces close and eyes closed" },
-  { id: "riding",             label: "Riding",             category: "movement", description: "Riding a bike, horse, or motorcycle", promptHint: "riding astride a bike, horse, or motorcycle, hands gripping forward" },
-  { id: "driving",            label: "Driving",            category: "movement", description: "Behind the wheel of a vehicle", promptHint: "behind the wheel of a vehicle, hands on the steering wheel, gaze forward" },
+  { id: "riding",             label: "Riding",             category: "movement", description: "Riding a bike, horse, or motorcycle", promptHint: "riding astride a bike, horse, or motorcycle, hands gripping forward", term: "riding astride" },
+  { id: "driving",            label: "Driving",            category: "movement", description: "Behind the wheel of a vehicle", promptHint: "behind the wheel of a vehicle, hands on the steering wheel, gaze forward", term: "driving, hands on the wheel" },
 
   // -------------------- Action --------------------
   { id: "fighting-stance",    label: "Fighting Stance",    category: "action",   description: "Combat-ready stance",         promptHint: "in a combat-ready fighting stance, tensed and focused" },
-  { id: "reaching",           label: "Reaching",           category: "action",   description: "Reaching outward",            promptHint: "reaching outward with one arm extended" },
-  { id: "throwing",           label: "Throwing",           category: "action",   description: "Mid-throw motion",            promptHint: "caught mid-throw, body coiled and releasing" },
+  { id: "reaching",           label: "Reaching",           category: "action",   description: "Reaching outward",            promptHint: "reaching outward with one arm extended", term: "reaching outward, arm extended" },
+  { id: "throwing",           label: "Throwing",           category: "action",   description: "Mid-throw motion",            promptHint: "caught mid-throw, body coiled and releasing", term: "caught mid-throw" },
   { id: "leaping",            label: "Leaping",            category: "action",   description: "Leaping forward dynamically", promptHint: "leaping forward dynamically with body extended" },
-  { id: "dramatic-action",    label: "Dramatic Action",    category: "action",   description: "Exaggerated action pose",     promptHint: "in a dramatic, exaggerated action pose full of motion" },
-  { id: "biting-lip",         label: "Biting Lip",         category: "action",   description: "Slight playful lip-bite",     promptHint: "biting the lower lip with a subtle playful expression" },
+  { id: "dramatic-action",    label: "Dramatic Action",    category: "action",   description: "Exaggerated action pose",     promptHint: "in a dramatic, exaggerated action pose full of motion", term: "dramatic exaggerated action pose" },
+  { id: "biting-lip",         label: "Biting Lip",         category: "action",   description: "Slight playful lip-bite",     promptHint: "biting the lower lip with a subtle playful expression", term: "biting the lower lip" },
   { id: "mid-laugh",          label: "Mid-Laugh",          category: "action",   description: "Caught mid-laugh, head back", promptHint: "caught mid-laugh with head tipped back, eyes crinkled" },
-  { id: "pointing-at-camera", label: "Pointing at Camera", category: "action",   description: "Pointing directly at camera", promptHint: "pointing one finger directly at the camera, arm extended" },
+  { id: "pointing-at-camera", label: "Pointing at Camera", category: "action",   description: "Pointing directly at camera", promptHint: "pointing one finger directly at the camera, arm extended", term: "pointing directly at the camera" },
   { id: "tongue-out",         label: "Sticking Tongue Out", category: "action",  description: "Playful tongue-out expression", promptHint: "sticking the tongue out playfully" },
-  { id: "thinking",           label: "Thinking",           category: "action",   description: "Hand on chin, contemplative", promptHint: "in a thinking pose with hand on chin, gaze contemplative" },
+  { id: "thinking",           label: "Thinking",           category: "action",   description: "Hand on chin, contemplative", promptHint: "in a thinking pose with hand on chin, gaze contemplative", term: "thinking pose, hand on chin" },
 
   // -------------------- Resting --------------------
   { id: "lying-down",         label: "Lying Down",         category: "resting",  description: "Lying flat",                  promptHint: "lying down flat, relaxed" },
@@ -96,48 +107,48 @@ export const POSES: ReadonlyArray<Pose> = [
   { id: "looking-away",       label: "Looking Away",       category: "resting",  description: "Head turned, looking away",   promptHint: "head turned, looking off away from the camera" },
   { id: "looking-up",         label: "Looking Up",         category: "resting",  description: "Gazing up at the sky",        promptHint: "gazing upward at the sky or off-camera, chin slightly raised" },
   { id: "looking-down",       label: "Looking Down",       category: "resting",  description: "Eyes downcast",               promptHint: "eyes downcast, gaze turned softly to the ground" },
-  { id: "head-over-shoulder", label: "Head Over Shoulder", category: "resting",  description: "Looking back over shoulder",  promptHint: "head turned to look back over one shoulder toward the camera" },
+  { id: "head-over-shoulder", label: "Head Over Shoulder", category: "resting",  description: "Looking back over shoulder",  promptHint: "head turned to look back over one shoulder toward the camera", term: "looking back over the shoulder" },
   { id: "wading-in-water",    label: "Wading in Water",    category: "resting",  description: "Wading mid-thigh deep in water", promptHint: "wading mid-thigh deep through water, ripples around the legs" },
 
   // -------------------- Hand Position --------------------
   { id: "hands-in-pockets",        label: "Hands in Pockets",        category: "hand-position", description: "Both hands tucked in pockets",        promptHint: "with both hands tucked into pockets" },
   { id: "hand-on-hip",             label: "Hand on Hip",             category: "hand-position", description: "One hand on hip",                     promptHint: "with one hand resting on the hip" },
-  { id: "hand-position-hands-on-hips", label: "Hands on Hips",       category: "hand-position", description: "Both hands on hips",                  promptHint: "with both hands planted on the hips" },
+  { id: "hand-position-hands-on-hips", label: "Hands on Hips",       category: "hand-position", description: "Both hands on hips",                  promptHint: "with both hands planted on the hips", term: "both hands planted on the hips" },
   { id: "hand-on-chin",            label: "Hand on Chin",            category: "hand-position", description: "Hand resting under the chin",         promptHint: "with one hand resting under the chin, fingers framing the jaw" },
   { id: "hand-on-collarbone",      label: "Hand on Collarbone",      category: "hand-position", description: "Hand resting across collarbone",      promptHint: "with one hand resting lightly across the collarbone" },
-  { id: "hand-brushing-hair",      label: "Hand Brushing Hair",      category: "hand-position", description: "Hand running through the hair",       promptHint: "with a hand running through the hair, fingers caught mid-strand" },
-  { id: "finger-to-lip",           label: "Finger to Lip",           category: "hand-position", description: "Fingertip pressed against lower lip", promptHint: "with one fingertip pressed gently against the lower lip" },
-  { id: "arms-wrapped-around-self", label: "Arms Wrapped Around Self", category: "hand-position", description: "Self-hug, arms around torso",       promptHint: "arms wrapped around the torso in a self-hug" },
-  { id: "hands-clasped",           label: "Hands Clasped",           category: "hand-position", description: "Both hands clasped at the front",     promptHint: "with both hands clasped at the front" },
+  { id: "hand-brushing-hair",      label: "Hand Brushing Hair",      category: "hand-position", description: "Hand running through the hair",       promptHint: "with a hand running through the hair, fingers caught mid-strand", term: "hand running through the hair" },
+  { id: "finger-to-lip",           label: "Finger to Lip",           category: "hand-position", description: "Fingertip pressed against lower lip", promptHint: "with one fingertip pressed gently against the lower lip", term: "fingertip pressed to the lower lip" },
+  { id: "arms-wrapped-around-self", label: "Arms Wrapped Around Self", category: "hand-position", description: "Self-hug, arms around torso",       promptHint: "arms wrapped around the torso in a self-hug", term: "arms wrapped around the torso" },
+  { id: "hands-clasped",           label: "Hands Clasped",           category: "hand-position", description: "Both hands clasped at the front",     promptHint: "with both hands clasped at the front", term: "hands clasped in front" },
 
   // -------------------- Body Lean --------------------
-  { id: "leaning-back",            label: "Leaning Back",            category: "body-lean",     description: "Torso leaning back slightly",         promptHint: "with the torso leaning back at a slight backward angle" },
-  { id: "leaning-forward",         label: "Leaning Forward",         category: "body-lean",     description: "Torso leaning toward camera",         promptHint: "with the torso leaning forward toward the camera" },
-  { id: "body-lean-contrapposto",  label: "Contrapposto",            category: "body-lean",     description: "Weight on one leg, hip pushed out",   promptHint: "with the weight on one leg and one hip pushed out, classical contrapposto" },
+  { id: "leaning-back",            label: "Leaning Back",            category: "body-lean",     description: "Torso leaning back slightly",         promptHint: "with the torso leaning back at a slight backward angle", term: "torso leaning slightly back" },
+  { id: "leaning-forward",         label: "Leaning Forward",         category: "body-lean",     description: "Torso leaning toward camera",         promptHint: "with the torso leaning forward toward the camera", term: "torso leaning forward" },
+  { id: "body-lean-contrapposto",  label: "Contrapposto",            category: "body-lean",     description: "Weight on one leg, hip pushed out",   promptHint: "with the weight on one leg and one hip pushed out, classical contrapposto", term: "contrapposto, hip pushed out" },
   { id: "arched-back",             label: "Arched Back",             category: "body-lean",     description: "Back gently arched, chest forward",   promptHint: "with the back gently arched, chest forward" },
-  { id: "shoulder-rolled-forward", label: "Shoulder Rolled Forward", category: "body-lean",     description: "One shoulder rolled forward",         promptHint: "with one shoulder rolled forward, asymmetric stance" },
+  { id: "shoulder-rolled-forward", label: "Shoulder Rolled Forward", category: "body-lean",     description: "One shoulder rolled forward",         promptHint: "with one shoulder rolled forward, asymmetric stance", term: "one shoulder rolled forward" },
 
   // -------------------- Head Tilt --------------------
-  { id: "tilted-up",               label: "Tilted Up",               category: "head-tilt",     description: "Head tipped slightly upward",         promptHint: "with the head tipped slightly upward" },
-  { id: "tilted-down",             label: "Tilted Down",             category: "head-tilt",     description: "Head tipped slightly downward",       promptHint: "with the head tipped slightly downward" },
-  { id: "tilted-side",             label: "Tilted Side",             category: "head-tilt",     description: "Head tilted toward shoulder",         promptHint: "with the head tilted toward one shoulder" },
-  { id: "tilted-back",             label: "Tilted Back",             category: "head-tilt",     description: "Head fully back, throat exposed",     promptHint: "with the head tipped fully back, exposing the throat" },
-  { id: "chin-up",                 label: "Chin Up",                 category: "head-tilt",     description: "Chin lifted, looking down nose",      promptHint: "with the chin lifted, looking down the nose" },
+  { id: "tilted-up",               label: "Tilted Up",               category: "head-tilt",     description: "Head tipped slightly upward",         promptHint: "with the head tipped slightly upward", term: "head tipped slightly up" },
+  { id: "tilted-down",             label: "Tilted Down",             category: "head-tilt",     description: "Head tipped slightly downward",       promptHint: "with the head tipped slightly downward", term: "head tipped slightly down" },
+  { id: "tilted-side",             label: "Tilted Side",             category: "head-tilt",     description: "Head tilted toward shoulder",         promptHint: "with the head tilted toward one shoulder", term: "head tilted toward one shoulder" },
+  { id: "tilted-back",             label: "Tilted Back",             category: "head-tilt",     description: "Head fully back, throat exposed",     promptHint: "with the head tipped fully back, exposing the throat", term: "head tipped fully back" },
+  { id: "chin-up",                 label: "Chin Up",                 category: "head-tilt",     description: "Chin lifted, looking down nose",      promptHint: "with the chin lifted, looking down the nose", term: "chin lifted" },
   { id: "chin-tucked",             label: "Chin Tucked",             category: "head-tilt",     description: "Chin tucked toward chest",            promptHint: "with the chin tucked toward the chest" },
 
   // -------------------- Activity (what the subject is doing in the world) --------------------
-  { id: "activity-smoking",            label: "Smoking",            category: "activity",      description: "Holding and smoking a cigarette",     promptHint: "holding and smoking a cigarette, smoke curling up from the lit tip" },
-  { id: "activity-drinking",           label: "Drinking",           category: "activity",      description: "Drinking from a glass or cup",        promptHint: "raising a glass or cup to the lips and drinking from it" },
+  { id: "activity-smoking",            label: "Smoking",            category: "activity",      description: "Holding and smoking a cigarette",     promptHint: "holding and smoking a cigarette, smoke curling up from the lit tip", term: "smoking a cigarette" },
+  { id: "activity-drinking",           label: "Drinking",           category: "activity",      description: "Drinking from a glass or cup",        promptHint: "raising a glass or cup to the lips and drinking from it", term: "drinking from a glass" },
   { id: "activity-eating",             label: "Eating",             category: "activity",      description: "Caught mid-bite",                     promptHint: "caught mid-bite, eating with a piece of food halfway to the mouth" },
-  { id: "activity-talking-on-phone",   label: "Talking on Phone",   category: "activity",      description: "Phone held to ear, speaking",         promptHint: "holding a phone to one ear and speaking into it, eyes focused mid-conversation" },
+  { id: "activity-talking-on-phone",   label: "Talking on Phone",   category: "activity",      description: "Phone held to ear, speaking",         promptHint: "holding a phone to one ear and speaking into it, eyes focused mid-conversation", term: "talking on the phone" },
   { id: "activity-texting",            label: "Texting",            category: "activity",      description: "Looking down at phone, thumbs typing", promptHint: "looking down at a phone held in both hands, thumbs busy typing a message" },
-  { id: "activity-typing-laptop",      label: "Typing on Laptop",   category: "activity",      description: "Hands on keyboard, focused on screen", promptHint: "typing at a laptop with hands on the keyboard, focused on the glowing screen" },
+  { id: "activity-typing-laptop",      label: "Typing on Laptop",   category: "activity",      description: "Hands on keyboard, focused on screen", promptHint: "typing at a laptop with hands on the keyboard, focused on the glowing screen", term: "typing on a laptop" },
   { id: "activity-reading",            label: "Reading",            category: "activity",      description: "Holding open a book or magazine",     promptHint: "holding open a book or magazine in both hands, eyes following the page" },
-  { id: "activity-writing",            label: "Writing",            category: "activity",      description: "Writing in a notebook with a pen",    promptHint: "writing in a notebook, pen in hand, head bent slightly over the page" },
-  { id: "activity-painting",           label: "Painting",           category: "activity",      description: "Painting on a canvas with a brush",   promptHint: "painting on a canvas, brush in hand mid-stroke, palette held in the other" },
-  { id: "activity-playing-instrument", label: "Playing Instrument", category: "activity",      description: "Playing a musical instrument",        promptHint: "playing a musical instrument, hands and fingers engaged with strings or keys, fully absorbed in the performance" },
+  { id: "activity-writing",            label: "Writing",            category: "activity",      description: "Writing in a notebook with a pen",    promptHint: "writing in a notebook, pen in hand, head bent slightly over the page", term: "writing in a notebook" },
+  { id: "activity-painting",           label: "Painting",           category: "activity",      description: "Painting on a canvas with a brush",   promptHint: "painting on a canvas, brush in hand mid-stroke, palette held in the other", term: "painting on a canvas" },
+  { id: "activity-playing-instrument", label: "Playing Instrument", category: "activity",      description: "Playing a musical instrument",        promptHint: "playing a musical instrument, hands and fingers engaged with strings or keys, fully absorbed in the performance", term: "playing a musical instrument" },
   { id: "activity-cooking",            label: "Cooking",            category: "activity",      description: "Cooking at a kitchen counter or stove", promptHint: "cooking at a kitchen counter or stove, hands actively working with food, steam rising from a pan" },
-  { id: "activity-driving",            label: "Driving",            category: "activity",      description: "Behind the wheel, hands gripping",    promptHint: "behind the wheel of a vehicle, both hands on the steering wheel, gaze fixed on the road ahead" },
+  { id: "activity-driving",            label: "Driving",            category: "activity",      description: "Behind the wheel, hands gripping",    promptHint: "behind the wheel of a vehicle, both hands on the steering wheel, gaze fixed on the road ahead", term: "behind the wheel of a vehicle" },
 ] as const
 
 const poseById = new Map<string, Pose>(POSES.map((p) => [p.id, p]))
@@ -158,6 +169,16 @@ export function getPosePromptHint(id: string | undefined | null): string {
   return getPose(id)?.promptHint ?? ""
 }
 
+/**
+ * Compact counterpart of `getPosePromptHint`: the short professional term this
+ * pose injects in compact hint mode ("mid-throw" where the hint is the full
+ * body-mechanics sentence). Empty string for an unknown id and for any entry
+ * that injects no hint at all.
+ */
+export function getPoseTerm(id: string | undefined | null): string {
+  return resolveTerm(getPose(id))
+}
+
 export const POSE_IDS: ReadonlyArray<string> = POSES.map((p) => p.id)
 
 export const POSE_CATEGORY_LABELS: Readonly<Record<PoseCategory, string>> = {
@@ -212,7 +233,9 @@ export interface PoseValue {
  */
 export function buildPoseHints(
   data: Record<string, unknown> & PoseValue,
+  mode: PickerHintMode = "full",
 ): string[] {
+  if (mode === "compact") return buildPoseTerms(data)
   const hints: string[] = []
 
   const pre = typeof data.preText === "string" ? data.preText.trim() : ""
@@ -244,3 +267,45 @@ export function buildPoseHints(
 
   return hints
 }
+
+/**
+ * Compact counterpart of `buildPoseHints`: the same pre-text → pose →
+ * hand-position → body-lean → head-tilt → activity → post-text order, emitted
+ * as short professional terms instead of full mechanism sentences
+ * ("mid-throw, hands clasped behind the head"). Free-text pre/post fields are
+ * user prose and pass through unchanged in both modes.
+ */
+export function buildPoseTerms(
+  data: Record<string, unknown> & PoseValue,
+): string[] {
+  const terms: string[] = []
+
+  const pre = typeof data.preText === "string" ? data.preText.trim() : ""
+  if (pre) terms.push(pre)
+
+  const poseId = typeof data.pose === "string" ? data.pose : ""
+  const poseTerm = getPoseTerm(poseId)
+  if (poseTerm) terms.push(poseTerm)
+
+  const handPositionId =
+    typeof data.handPosition === "string" ? data.handPosition : ""
+  const handPositionTerm = getPoseTerm(handPositionId)
+  if (handPositionTerm) terms.push(handPositionTerm)
+
+  const bodyLeanId = typeof data.bodyLean === "string" ? data.bodyLean : ""
+  const bodyLeanTerm = getPoseTerm(bodyLeanId)
+  if (bodyLeanTerm) terms.push(bodyLeanTerm)
+
+  const headTiltId = typeof data.headTilt === "string" ? data.headTilt : ""
+  const headTiltTerm = getPoseTerm(headTiltId)
+  if (headTiltTerm) terms.push(headTiltTerm)
+
+  const activityId = typeof data.activity === "string" ? data.activity : ""
+  const activityTerm = getPoseTerm(activityId)
+  if (activityTerm) terms.push(activityTerm)
+
+  const post = typeof data.postText === "string" ? data.postText.trim() : ""
+  if (post) terms.push(post)
+
+  return terms
+}

package/src/post-process-effects.ts

@@ -21,32 +21,42 @@
  * executor and the backend orchestrator.
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export interface PostProcessEffect {
   readonly id: string
   readonly label: string
   readonly description: string
   readonly promptHint: string
+  /**
+   * Optional authored compact term (see `term.ts`). Authored only where the
+   * lowercased label is not the phrase a colorist / retoucher would write in a
+   * prompt — "Bloom Glow" and "Color Fringe" are UI compounds, the trade terms
+   * are "highlight bloom" and "color fringing". Everywhere else the label IS
+   * the term.
+   */
+  readonly term?: string
 }
 
 export const POST_PROCESS_EFFECTS: ReadonlyArray<PostProcessEffect> = [
   { id: "vignette-soft",        label: "Soft Vignette",          description: "Gentle corner darkening",          promptHint: "soft dark vignette gently darkening the corners of the frame, drawing the eye toward the center without calling attention to itself" },
   { id: "vignette-heavy",       label: "Heavy Vignette",         description: "Dramatic black corners",            promptHint: "heavy black vignette circumscribing the subject in a dramatic dark oval, deep falloff at the edges that nearly crushes to black" },
-  { id: "dodge-and-burn",       label: "Dodge & Burn",           description: "Sculpted highlight/shadow",         promptHint: "aggressive dodge-and-burn shaping with sculpted highlight and shadow chiaroscuro, hand-painted-style local contrast carving form into the subject" },
+  { id: "dodge-and-burn",       label: "Dodge & Burn",           description: "Sculpted highlight/shadow",         promptHint: "aggressive dodge-and-burn shaping with sculpted highlight and shadow chiaroscuro, hand-painted-style local contrast carving form into the subject", term: "dodge and burn" },
   { id: "film-grain-fine",      label: "Fine Film Grain",        description: "Subtle 35mm-style grain",           promptHint: "fine film grain overlay across the entire image, classic 35mm character with delicate organic noise that softens digital edges" },
   { id: "film-grain-heavy",     label: "Heavy Film Grain",       description: "Coarse push-processed grain",       promptHint: "heavy coarse grain like push-processed high-ISO film, gritty texture across midtones and dense noise in the shadows" },
-  { id: "halation-glow",        label: "Halation Glow",          description: "Cinestill red-halo bloom",          promptHint: "warm halation glow blooming around bright highlights, signature cinestill-style red halo bleeding from light sources and tungsten practicals" },
-  { id: "bloom-glow",           label: "Bloom Glow",             description: "Romantic dreamy highlight bloom",   promptHint: "dreamy soft-focus bloom on highlights, romantic glow that wraps around bright areas and lifts the overall mood with a hazy halo" },
+  { id: "halation-glow",        label: "Halation Glow",          description: "Cinestill red-halo bloom",          promptHint: "warm halation glow blooming around bright highlights, signature cinestill-style red halo bleeding from light sources and tungsten practicals", term: "warm halation glow" },
+  { id: "bloom-glow",           label: "Bloom Glow",             description: "Romantic dreamy highlight bloom",   promptHint: "dreamy soft-focus bloom on highlights, romantic glow that wraps around bright areas and lifts the overall mood with a hazy halo", term: "highlight bloom" },
   { id: "chromatic-aberration", label: "Chromatic Aberration",   description: "Red/cyan fringe on edges",          promptHint: "visible chromatic aberration with red and cyan fringing on contrast edges, lens-imperfection look that reads as authentic optical character" },
   { id: "light-leak",           label: "Light Leak",             description: "Warm streak across the frame",      promptHint: "warm orange light leak streaking across one edge of the frame, fogged film aesthetic with a soft amber wash bleeding into the image" },
   { id: "film-burn",            label: "Film Burn",              description: "Vintage Super-8 corner flare",      promptHint: "film burn flare in the corner with a vintage Super-8 aesthetic, charred edge bleeding orange and white light into the frame" },
-  { id: "scratched-emulsion",   label: "Scratched Emulsion",     description: "Aged film scratches + dust",        promptHint: "vertical scratches and dust marks like aged film emulsion, hairline streaks running through the frame and scattered dust specks across the image" },
-  { id: "color-fringe",         label: "Color Fringe",           description: "Subtle high-contrast fringing",     promptHint: "subtle color fringing on high-contrast edges, gentle prismatic shimmer that adds optical authenticity without overwhelming the image" },
+  { id: "scratched-emulsion",   label: "Scratched Emulsion",     description: "Aged film scratches + dust",        promptHint: "vertical scratches and dust marks like aged film emulsion, hairline streaks running through the frame and scattered dust specks across the image", term: "scratched, dusty film emulsion" },
+  { id: "color-fringe",         label: "Color Fringe",           description: "Subtle high-contrast fringing",     promptHint: "subtle color fringing on high-contrast edges, gentle prismatic shimmer that adds optical authenticity without overwhelming the image", term: "subtle color fringing" },
   { id: "soft-focus-diffusion", label: "Soft-Focus Diffusion",   description: "Hazy dreamy highlight bloom",       promptHint: "soft-focus diffusion filter — slightly hazy dreamy bloom on highlights, glowing skin tones and a romantic veil across the entire image" },
   { id: "contrast-boost",       label: "Contrast Boost",         description: "Crushed shadows + pushed highlights", promptHint: "aggressive contrast boost, deepened shadows crushing toward black and pushed highlights, punchy editorial-grade tonal separation" },
   { id: "sharpening",           label: "Heavy Sharpening",       description: "Aggressive edge-sharpening pass, crisp micro-detail", promptHint: "aggressive edge-sharpening pass with crisp micro-detail emphasized, hardened edges and pronounced texture acutance across the entire image" },
   { id: "clarity-boost",        label: "Clarity Boost",          description: "Mid-tone clarity enhancement, increased local contrast", promptHint: "mid-tone clarity enhancement with increased local contrast, deepened textural definition and punchy structural detail without crushing shadows or highlights" },
-  { id: "dehaze",               label: "Dehaze",                 description: "Atmospheric dehaze applied, removing softness and lifting contrast through fog", promptHint: "atmospheric dehaze applied across the frame, removing veiling softness and lifting contrast through haze and fog with restored color saturation in distant tones" },
-  { id: "lift-gamma-gain",      label: "Lift-Gamma-Gain Grade",  description: "Three-way color grading wheels — shadow lift, midtone gamma, highlight gain", promptHint: "three-way color grading with lift-gamma-gain wheels shaping shadow lift, midtone gamma and highlight gain independently, professional colorist-grade tonal sculpting" },
+  { id: "dehaze",               label: "Dehaze",                 description: "Atmospheric dehaze applied, removing softness and lifting contrast through fog", promptHint: "atmospheric dehaze applied across the frame, removing veiling softness and lifting contrast through haze and fog with restored color saturation in distant tones", term: "atmospheric dehaze" },
+  { id: "lift-gamma-gain",      label: "Lift-Gamma-Gain Grade",  description: "Three-way color grading wheels — shadow lift, midtone gamma, highlight gain", promptHint: "three-way color grading with lift-gamma-gain wheels shaping shadow lift, midtone gamma and highlight gain independently, professional colorist-grade tonal sculpting", term: "three-way lift gamma gain grade" },
 ] as const
 
 const postProcessById = new Map<string, PostProcessEffect>(
@@ -69,13 +79,24 @@ export function getPostProcessEffectPromptHint(id: string | undefined | null): s
   return getPostProcessEffect(id)?.promptHint ?? ""
 }
 
+/**
+ * Compact counterpart of `getPostProcessEffectPromptHint`: the short
+ * professional term this pass injects in compact hint mode ("dodge and burn"
+ * where the hint is the full mechanism sentence). Empty string for an unknown
+ * id and for any entry that injects no hint at all.
+ */
+export function getPostProcessEffectTerm(id: string | undefined | null): string {
+  return resolveTerm(getPostProcessEffect(id))
+}
+
 /**
  * Multi-pick: 1-2 post-process effect ids → composite grading clause.
  * Common pairs: vignette + film-grain, halation + bloom, dodge-burn +
  * chromatic-aberration. Each entry already describes a complete grading
  * pass, so we emit independently and let the comma-join compose them.
  */
-export function buildPostProcessHints(value: unknown): string[] {
+export function buildPostProcessHints(value: unknown, mode: PickerHintMode = "full"): string[] {
+  if (mode === "compact") return buildPostProcessTerms(value)
   const ids: string[] = []
   if (typeof value === "string" && value) ids.push(value)
   else if (Array.isArray(value)) {
@@ -91,4 +112,26 @@ export function buildPostProcessHints(value: unknown): string[] {
   return out
 }
 
+/**
+ * Compact counterpart of `buildPostProcessHints`: the same 1-2 id multi-pick,
+ * emitted as short professional terms instead of full mechanism sentences
+ * ("soft vignette", "fine film grain"). Same collection order, same
+ * skip-the-no-ops behavior.
+ */
+export function buildPostProcessTerms(value: unknown): string[] {
+  const ids: string[] = []
+  if (typeof value === "string" && value) ids.push(value)
+  else if (Array.isArray(value)) {
+    for (const v of value) {
+      if (typeof v === "string" && v && !ids.includes(v)) ids.push(v)
+    }
+  }
+  const out: string[] = []
+  for (const id of ids) {
+    const term = getPostProcessEffectTerm(id)
+    if (term) out.push(term)
+  }
+  return out
+}
+
 export const POST_PROCESS_EFFECT_IDS: ReadonlyArray<string> = POST_PROCESS_EFFECTS.map((p) => p.id)

package/src/prompt-builder.ts

@@ -1655,7 +1655,22 @@ function buildImagePromptInternal(config: BuildImagePromptConfig, marks?: Assemb
     if (refCap > 0) {
       const structuredBudget = Math.max(0, refCap - referenceImageUrls.length)
       if (connectedReferences.length > structuredBudget) {
-        connectedReferences = connectedReferences.slice(0, structuredBudget)
+        // ATTACH-PRIORITY slice, not raw order. The raw list interleaves each
+        // wired character's canonical with its whole variant array, and an
+        // unmentioned VARIANT never attaches — yet a raw slice let one
+        // variant-rich character fill the budget and evict every character
+        // wired after it ENTIRELY, canonical included (the "two characters
+        // wired, one sent" incident: 1 canonical + 7 variants consumed
+        // nano-banana-pro's cap of 8, and the second character vanished
+        // while the provider received TWO urls total). Non-variant entries
+        // (canonicals, manual refs, extra-refs) take the budget first;
+        // variants fill what remains as mention candidates. Survivors keep
+        // their original relative order, so slot numbering is unchanged for
+        // every graph that fit the budget before.
+        const nonVariants = connectedReferences.filter((r) => !r.variantSlug || r.isExtraRef === true)
+        const variants = connectedReferences.filter((r) => r.variantSlug && r.isExtraRef !== true)
+        const kept = new Set([...nonVariants, ...variants].slice(0, structuredBudget))
+        connectedReferences = connectedReferences.filter((r) => kept.has(r))
       }
     }
   }