@nodaro/prompts 1.7.3 → 1.8.1

package/src/exposure-settings.ts

@@ -19,6 +19,8 @@
  * the backend orchestrator.
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export type ExposureCategory = "aperture" | "shutter-speed" | "iso"
 
 export interface ExposureSettings {
@@ -27,35 +29,54 @@ export interface ExposureSettings {
   readonly category: ExposureCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * Optional authored compact term (see `term.ts`). Authored on nearly every
+   * dial value, because the mechanical derivation mangles all three
+   * categories — the f-stop slash reads as a UI compound ("f/1.2"), the
+   * shutter fraction loses its unit and its annotation ("1/1000 (action
+   * freeze)" → "1/1000"), and the ISO annotation is stripped ("ISO 3200
+   * (heavy grain)" → "iso 3200").
+   *
+   * Each term is the terse trade phrase a photographer writes — the dial
+   * value plus its category noun ("f/2.8 aperture", "1/500s shutter speed",
+   * "iso 1600 film speed") — and NOT the visual consequence: that is what
+   * `promptHint` is for, and a comma-bearing term would split into unrelated
+   * items once compact terms are joined into a comma-delimited list.
+   *
+   * ISO 400 / ISO 800 need nothing: their labels already read as the term.
+   * The three annotated ISO labels carry the category noun only because the
+   * guard requires an authored term to differ from the derivation.
+   */
+  readonly term?: string
 }
 
 export const EXPOSURE_SETTINGS: ReadonlyArray<ExposureSettings> = [
   // ---------------------------- Aperture ----------------------------
   // Wide-open primes through medium tele, then deep landscape stops.
-  { id: "aperture-f1-2",  label: "f/1.2",  category: "aperture", description: "Razor-thin DOF, dreamy bokeh",   promptHint: "shot wide open at f/1.2 — paper-thin depth of field with the subject's eyes in razor focus and everything else dissolving into creamy bokeh" },
-  { id: "aperture-f1-4",  label: "f/1.4",  category: "aperture", description: "Aggressive subject isolation",  promptHint: "shot at f/1.4 — extremely shallow depth of field, aggressive subject isolation against a smoothly melted background" },
-  { id: "aperture-f1-8",  label: "f/1.8",  category: "aperture", description: "Classic portrait separation",   promptHint: "shot at f/1.8 — shallow depth of field with the classic portrait separation between subject and softly defocused background" },
-  { id: "aperture-f2-8",  label: "f/2.8",  category: "aperture", description: "Subject sharp, BG soft",         promptHint: "shot at f/2.8 — subject crisply sharp with a gently defocused background, working aperture for low-light portraiture" },
-  { id: "aperture-f4",    label: "f/4",    category: "aperture", description: "Balanced everyday DOF",          promptHint: "shot at f/4 — balanced depth of field where the subject is fully in focus and the background is suggested rather than detailed" },
-  { id: "aperture-f5-6",  label: "f/5.6",  category: "aperture", description: "Sharp across the subject",      promptHint: "shot at f/5.6 — comfortable working aperture with edge-to-edge subject sharpness and a moderately rendered background" },
-  { id: "aperture-f8",    label: "f/8",    category: "aperture", description: "Sweet-spot sharpness",           promptHint: "shot at f/8 — peak optical sharpness across the frame, the photographer's sweet spot for storytelling and editorial work" },
-  { id: "aperture-f11",   label: "f/11",   category: "aperture", description: "Deep landscape DOF",             promptHint: "shot at f/11 — deep depth of field with foreground and distant elements both rendered crisply, classic landscape stop" },
-  { id: "aperture-f16",   label: "f/16",   category: "aperture", description: "Hyperfocal, sun-stars",          promptHint: "shot stopped down to f/16 — hyperfocal depth of field with everything sharp, sunlight rendered as crisp diffraction stars on bright highlights" },
+  { id: "aperture-f1-2",  label: "f/1.2",  category: "aperture", description: "Razor-thin DOF, dreamy bokeh",   promptHint: "shot wide open at f/1.2 — paper-thin depth of field with the subject's eyes in razor focus and everything else dissolving into creamy bokeh", term: "f/1.2 aperture" },
+  { id: "aperture-f1-4",  label: "f/1.4",  category: "aperture", description: "Aggressive subject isolation",  promptHint: "shot at f/1.4 — extremely shallow depth of field, aggressive subject isolation against a smoothly melted background", term: "f/1.4 aperture" },
+  { id: "aperture-f1-8",  label: "f/1.8",  category: "aperture", description: "Classic portrait separation",   promptHint: "shot at f/1.8 — shallow depth of field with the classic portrait separation between subject and softly defocused background", term: "f/1.8 aperture" },
+  { id: "aperture-f2-8",  label: "f/2.8",  category: "aperture", description: "Subject sharp, BG soft",         promptHint: "shot at f/2.8 — subject crisply sharp with a gently defocused background, working aperture for low-light portraiture", term: "f/2.8 aperture" },
+  { id: "aperture-f4",    label: "f/4",    category: "aperture", description: "Balanced everyday DOF",          promptHint: "shot at f/4 — balanced depth of field where the subject is fully in focus and the background is suggested rather than detailed", term: "f/4 aperture" },
+  { id: "aperture-f5-6",  label: "f/5.6",  category: "aperture", description: "Sharp across the subject",      promptHint: "shot at f/5.6 — comfortable working aperture with edge-to-edge subject sharpness and a moderately rendered background", term: "f/5.6 aperture" },
+  { id: "aperture-f8",    label: "f/8",    category: "aperture", description: "Sweet-spot sharpness",           promptHint: "shot at f/8 — peak optical sharpness across the frame, the photographer's sweet spot for storytelling and editorial work", term: "f/8 aperture" },
+  { id: "aperture-f11",   label: "f/11",   category: "aperture", description: "Deep landscape DOF",             promptHint: "shot at f/11 — deep depth of field with foreground and distant elements both rendered crisply, classic landscape stop", term: "f/11 aperture" },
+  { id: "aperture-f16",   label: "f/16",   category: "aperture", description: "Hyperfocal, sun-stars",          promptHint: "shot stopped down to f/16 — hyperfocal depth of field with everything sharp, sunlight rendered as crisp diffraction stars on bright highlights", term: "f/16 aperture" },
 
   // ---------------------------- Shutter Speed ----------------------------
-  { id: "shutter-1-30",       label: "1/30 (handheld blur)", category: "shutter-speed", description: "Hint of handheld motion",  promptHint: "captured at 1/30s — a hint of handheld motion blur on moving subjects, slight camera shake suggesting an in-the-moment documentary feel" },
-  { id: "shutter-1-60",       label: "1/60",                 category: "shutter-speed", description: "Standard everyday shutter", promptHint: "captured at 1/60s — standard everyday shutter speed, sharp on still subjects with subtle blur on fast motion" },
-  { id: "shutter-1-200",      label: "1/200",                category: "shutter-speed", description: "Crisp on most subjects",    promptHint: "captured at 1/200s — crisp on most subjects, the working shutter speed for portraits and general photography" },
-  { id: "shutter-1-500",      label: "1/500",                category: "shutter-speed", description: "Sharp on quick action",     promptHint: "captured at 1/500s — sharp rendering of quick human action, hair and fabric mid-motion frozen with clean edges" },
-  { id: "shutter-1-1000",     label: "1/1000 (action freeze)", category: "shutter-speed", description: "Frozen sports/wildlife",  promptHint: "captured at 1/1000s — frozen mid-air action, water droplets suspended in space, every fast motion crystallized with clinical sharpness" },
-  { id: "shutter-long-1s",    label: "Long exposure (1s)",   category: "shutter-speed", description: "Streaks and motion trails", promptHint: "captured with a one-second long exposure — flowing motion rendered as smooth light trails and streaks, static subjects sharp while moving elements paint across the frame" },
+  { id: "shutter-1-30",       label: "1/30 (handheld blur)", category: "shutter-speed", description: "Hint of handheld motion",  promptHint: "captured at 1/30s — a hint of handheld motion blur on moving subjects, slight camera shake suggesting an in-the-moment documentary feel", term: "1/30s shutter speed" },
+  { id: "shutter-1-60",       label: "1/60",                 category: "shutter-speed", description: "Standard everyday shutter", promptHint: "captured at 1/60s — standard everyday shutter speed, sharp on still subjects with subtle blur on fast motion", term: "1/60s shutter speed" },
+  { id: "shutter-1-200",      label: "1/200",                category: "shutter-speed", description: "Crisp on most subjects",    promptHint: "captured at 1/200s — crisp on most subjects, the working shutter speed for portraits and general photography", term: "1/200s shutter speed" },
+  { id: "shutter-1-500",      label: "1/500",                category: "shutter-speed", description: "Sharp on quick action",     promptHint: "captured at 1/500s — sharp rendering of quick human action, hair and fabric mid-motion frozen with clean edges", term: "1/500s shutter speed" },
+  { id: "shutter-1-1000",     label: "1/1000 (action freeze)", category: "shutter-speed", description: "Frozen sports/wildlife",  promptHint: "captured at 1/1000s — frozen mid-air action, water droplets suspended in space, every fast motion crystallized with clinical sharpness", term: "1/1000s shutter speed" },
+  { id: "shutter-long-1s",    label: "Long exposure (1s)",   category: "shutter-speed", description: "Streaks and motion trails", promptHint: "captured with a one-second long exposure — flowing motion rendered as smooth light trails and streaks, static subjects sharp while moving elements paint across the frame", term: "one-second long exposure" },
 
   // ---------------------------- ISO ----------------------------
-  { id: "iso-100",   label: "ISO 100 (clean)",        category: "iso", description: "Minimal noise, fine grain",         promptHint: "ISO 100 — pristinely clean image with virtually no noise, ultra-fine grain structure and rich tonal latitude" },
+  { id: "iso-100",   label: "ISO 100 (clean)",        category: "iso", description: "Minimal noise, fine grain",         promptHint: "ISO 100 — pristinely clean image with virtually no noise, ultra-fine grain structure and rich tonal latitude", term: "iso 100 film speed" },
   { id: "iso-400",   label: "ISO 400",                category: "iso", description: "Slight texture, daily-driver ISO", promptHint: "ISO 400 — subtle film-like grain texture, the daily-driver sensitivity that retains detail with a hint of organic noise" },
   { id: "iso-800",   label: "ISO 800",                category: "iso", description: "Visible but pleasant grain",       promptHint: "ISO 800 — visible but pleasant grain pattern, evening-indoor sensitivity with a touch of analog character" },
-  { id: "iso-1600",  label: "ISO 1600 (visible grain)", category: "iso", description: "Editorial low-light texture",   promptHint: "ISO 1600 — clearly visible grain, editorial low-light feel with rich texture and slightly muted shadows" },
-  { id: "iso-3200",  label: "ISO 3200 (heavy grain)", category: "iso", description: "Pushed, gritty documentary feel", promptHint: "ISO 3200 — heavy push-processed grain, gritty documentary character with elevated shadow noise and a raw, journalistic texture" },
+  { id: "iso-1600",  label: "ISO 1600 (visible grain)", category: "iso", description: "Editorial low-light texture",   promptHint: "ISO 1600 — clearly visible grain, editorial low-light feel with rich texture and slightly muted shadows", term: "iso 1600 film speed" },
+  { id: "iso-3200",  label: "ISO 3200 (heavy grain)", category: "iso", description: "Pushed, gritty documentary feel", promptHint: "ISO 3200 — heavy push-processed grain, gritty documentary character with elevated shadow noise and a raw, journalistic texture", term: "iso 3200 film speed" },
 ] as const
 
 export const EXPOSURE_CATEGORY_ORDER: ReadonlyArray<ExposureCategory> = [
@@ -90,6 +111,19 @@ export function getExposurePromptHint(id: string | undefined | null): string {
   return getExposure(id)?.promptHint ?? ""
 }
 
+/**
+ * Compact professional TERM for an exposure id — the short phrase a
+ * photographer would write in a prompt ("f/1.4 aperture"), as opposed to the
+ * sentence-long `promptHint`.
+ *
+ * Same lookup and same empty-string-on-miss behavior as
+ * `getExposurePromptHint`, so the two can never disagree about which entry
+ * they describe.
+ */
+export function getExposureTerm(id: string | undefined | null): string {
+  return resolveTerm(getExposure(id))
+}
+
 export const EXPOSURE_IDS: ReadonlyArray<string> = EXPOSURE_SETTINGS.map((e) => e.id)
 
 /**
@@ -130,7 +164,9 @@ export function buildExposureHints(
     shutterSpeed?: unknown
     isoValue?: unknown
   },
+  mode: PickerHintMode = "full",
 ): string[] {
+  if (mode === "compact") return buildExposureTerms(data)
   const hints: string[] = []
   for (const [field] of EXPOSURE_FIELDS_IN_ORDER) {
     const id = data[field]
@@ -140,3 +176,25 @@ export function buildExposureHints(
   }
   return hints
 }
+
+/**
+ * Compact-mode mirror of `buildExposureHints`: the same per-category fields in
+ * the same canonical order (aperture, shutter-speed, iso), resolved to their
+ * short professional terms instead of their sentence-long hints.
+ */
+export function buildExposureTerms(
+  data: Record<string, unknown> & {
+    aperture?: unknown
+    shutterSpeed?: unknown
+    isoValue?: unknown
+  },
+): string[] {
+  const terms: string[] = []
+  for (const [field] of EXPOSURE_FIELDS_IN_ORDER) {
+    const id = data[field]
+    if (typeof id !== "string" || id.length === 0) continue
+    const term = getExposureTerm(id)
+    if (term) terms.push(term)
+  }
+  return terms
+}

package/src/framing.ts

@@ -9,6 +9,8 @@
  * frontend DAG executor and the backend orchestrator.
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export type FramingCategory =
   | "shot-size"
   | "angle"
@@ -22,6 +24,18 @@ export interface Framing {
   readonly category: FramingCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * Optional authored compact term (see `term.ts`). Authored only where the
+   * lowercased label is not the phrase a cinematographer would write in a
+   * prompt — a UI compound ("Golden Spiral / Fibonacci"), an annotation
+   * ("ECU: Eye"), a reversed pair ("Headroom Tight" → "tight headroom"), a
+   * bare word that needs its shot noun ("Insert" → "insert shot"), or a trade
+   * phrase whose bare form reads as something else entirely once the trade
+   * context is stripped ("Choker" the neckwear, "Dirty Single" the grime,
+   * "Single" the continuous take). Everywhere else the label IS the term and
+   * nothing is authored.
+   */
+  readonly term?: string
 }
 
 export const FRAMINGS: ReadonlyArray<Framing> = [
@@ -46,6 +60,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "Subject from the knees up",
     promptHint: "medium wide shot, subject framed from the knees up",
+    term: "medium wide shot",
   },
   {
     id: "medium-shot",
@@ -81,6 +96,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "Sergio Leone-style ECU on a single eye",
     promptHint: "Sergio Leone-style extreme close-up tight on a single eye, iris filling the frame, every eyelash and reflection visible",
+    term: "extreme close-up on a single eye",
   },
   {
     id: "ecu-mouth",
@@ -88,6 +104,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "ECU tight on the mouth",
     promptHint: "extreme close-up tight on the mouth, lips and teeth filling the frame, breath visible",
+    term: "extreme close-up on the lips and mouth",
   },
   {
     id: "ecu-hands",
@@ -95,6 +112,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "ECU tight on the hands",
     promptHint: "extreme close-up tight on the hands, every finger and crease visible",
+    term: "extreme close-up on the hands",
   },
   {
     id: "big-close-up",
@@ -102,6 +120,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "Tighter than CU: chin to forehead, no headroom",
     promptHint: "big close-up, tighter than a standard close-up with just the face from chin to forehead, no headroom",
+    term: "big close-up, chin to forehead",
   },
   {
     id: "choker",
@@ -109,6 +128,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "Head and neck only, intimate intensity",
     promptHint: "choker shot, framed at the throat with head and neck only, intimate intensity",
+    term: "choker shot, head and neck only",
   },
   {
     id: "italian-shot",
@@ -116,6 +136,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "Sergio Leone Western: ECU at the eyes alone",
     promptHint: "Italian shot, Sergio Leone Western trope, extreme close-up cropping at the eyes alone leaving the rest of the face out of frame",
+    term: "extreme close-up cropped at the eyes",
   },
   {
     id: "insert",
@@ -123,6 +144,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "Detail shot of an object",
     promptHint: "insert shot, tight on a specific object or detail relevant to the scene",
+    term: "insert shot",
   },
   {
     id: "macro",
@@ -130,6 +152,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "Extreme close detail of a small subject",
     promptHint: "macro shot, extreme close-up of fine detail filling the frame, magnifying small subject features",
+    term: "macro shot",
   },
   {
     id: "full-shot",
@@ -143,14 +166,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     label: "Cowboy Shot",
     category: "shot-size",
     description: "Mid-thigh up, classic Western framing",
-    promptHint: "cowboy shot, subject framed from mid-thigh up, classic Western framing that leaves the holster visible",
-  },
-  {
-    id: "head-to-knees",
-    label: "Head to Knees",
-    category: "shot-size",
-    description: "From head down to the knees",
-    promptHint: "head-to-knees framing, subject visible from the top of the head down to just above the knees",
+    promptHint: "cowboy shot, subject framed from mid-thigh up, classic Western framing",
   },
   {
     id: "head-to-hip",
@@ -158,6 +174,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "From head down to the hips",
     promptHint: "head-to-hip framing, subject visible from the top of the head down to the hipline, slightly tighter than waist-up",
+    term: "head-to-hip framing",
   },
   {
     id: "half-body",
@@ -165,6 +182,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "shot-size",
     description: "Clean waist-up portrait",
     promptHint: "half body portrait, subject framed from the waist up with clean portrait composition",
+    term: "half-body portrait",
   },
 
   // Angle (camera height / orientation)
@@ -195,6 +213,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "angle",
     description: "Direct top-down god's eye view",
     promptHint: "overhead shot, direct top-down god's eye view looking straight down at the scene",
+    term: "overhead shot, looking straight down",
   },
   {
     id: "worms-eye-angle",
@@ -202,6 +221,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "angle",
     description: "Extreme low angle from the ground",
     promptHint: "worm's eye view, extreme low angle from ground level looking up",
+    term: "worm's eye view",
   },
   {
     id: "dutch-angle",
@@ -216,6 +236,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "angle",
     description: "High aerial overhead view",
     promptHint: "bird's eye view, high aerial perspective looking down on the scene from far above",
+    term: "bird's eye view",
   },
   {
     id: "slightly-downward",
@@ -223,6 +244,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "angle",
     description: "Gentle tilt from above, selfie-style",
     promptHint: "slightly downward angle, camera tilted gently down toward the subject from just above their eyeline, the natural angle of a held-out phone",
+    term: "slightly downward angle, just above the eyeline",
   },
 
   // Coverage (dialog / multi-subject framing)
@@ -232,6 +254,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "coverage",
     description: "Clean shot of one subject",
     promptHint: "single shot, clean framing of one subject with nothing else in frame",
+    term: "clean single, one subject in frame",
   },
   {
     id: "two-shot",
@@ -253,6 +276,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "coverage",
     description: "Past one subject's shoulder onto another",
     promptHint: "over the shoulder framing, camera looks past one character's shoulder onto the subject opposite them",
+    term: "over-the-shoulder shot",
   },
   {
     id: "reverse-shot",
@@ -267,6 +291,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "coverage",
     description: "Through subject's eyes",
     promptHint: "POV framing, scene viewed through the subject's own eyes, first person perspective",
+    term: "pov shot, first-person perspective",
   },
   {
     id: "selfie-framing",
@@ -274,6 +299,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "coverage",
     description: "Arm's-length self-portrait",
     promptHint: "selfie framing, subject holding the camera at arm's length to frame themselves, slightly high angle from above, phone-camera perspective with the subject's face and upper body dominant in frame, arm or phone edge sometimes visible",
+    term: "arm's-length selfie framing",
   },
   {
     id: "mirror-selfie",
@@ -295,6 +321,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "coverage",
     description: "Framed through a foreground glass pane",
     promptHint: "shot through a foreground pane of glass, subject seen with subtle optical refraction, reflections, and surface distortions across the image, glass texture frames the composition",
+    term: "shot through a pane of glass",
   },
   {
     id: "top-down-flat-lay",
@@ -316,6 +343,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "coverage",
     description: "Single with another character at the edge",
     promptHint: "dirty single framing, the shot is on one character but a slice of another character — a shoulder, ear, or back of head — intrudes into the foreground edge of frame",
+    term: "dirty single, foreground shoulder in frame",
   },
 
   // Composition (where the subject sits in the frame)
@@ -332,6 +360,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "composition",
     description: "Subject dead center, symmetrical",
     promptHint: "centered composition, subject positioned exactly in the middle of the frame, symmetrical",
+    term: "centered composition",
   },
   {
     id: "headroom-tight",
@@ -339,6 +368,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "composition",
     description: "Subject's head near top of frame",
     promptHint: "tight headroom, subject's head positioned near the top of the frame with little space above",
+    term: "tight headroom",
   },
   {
     id: "negative-space",
@@ -360,6 +390,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "composition",
     description: "Subject in a 3×3 grid of variations",
     promptHint: "3 by 3 grid collage layout, nine equal-sized panels arranged in a three-by-three grid, each cell shows the same subject in a different pose, expression, or outfit, clean white gutters between panels",
+    term: "3x3 grid collage, nine equal panels",
   },
   {
     id: "diptych",
@@ -381,6 +412,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "composition",
     description: "Face built from a mosaic of small tiles",
     promptHint: "multi-frame mosaic, the subject's face assembled from many small photographic tiles arranged in a grid, each tile a tiny image that combines from a distance into the larger portrait",
+    term: "photo mosaic built from small image tiles",
   },
   {
     id: "contact-sheet",
@@ -394,14 +426,15 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     label: "Magazine Spread",
     category: "composition",
     description: "Two-page magazine layout with typography",
-    promptHint: "magazine spread layout, two-page editorial composition with bold display typography overlaid on the image, headline and pull quotes integrated with the photograph, visible page gutter down the middle",
+    promptHint: "magazine spread layout, two-page editorial composition with a visible page gutter down the middle",
   },
   {
     id: "cutaway-cross-section",
     label: "Cutaway / Cross-Section",
     category: "composition",
     description: "Architectural cross-section with walls peeled away",
-    promptHint: "cutaway cross-section composition, the building's near wall peeled away to reveal the interior in dollhouse fashion, multiple rooms visible at once with floors and furnishings exposed in clean architectural section, the subject inhabiting one of the rooms",
+    promptHint: "cutaway cross-section composition, the near surface peeled away to reveal the interior in clean cross-section, the inner layers and hidden structure exposed at once",
+    term: "cutaway cross-section, near surface removed",
   },
   {
     id: "golden-spiral",
@@ -409,6 +442,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "composition",
     description: "Composition on the Fibonacci spiral",
     promptHint: "composed on the golden spiral / Fibonacci ratio, the eye guided through a nested logarithmic curve from the focal subject outward through progressively larger arcs",
+    term: "golden spiral composition",
   },
   {
     id: "frame-within-frame",
@@ -423,6 +457,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "composition",
     description: "Sinuous diagonal flow through the frame",
     promptHint: "S-curve serpentine composition, a sinuous diagonal flow winds through the frame, the eye guided along the curve from foreground to background",
+    term: "s-curve composition",
   },
   {
     id: "diagonal-composition",
@@ -444,6 +479,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "composition",
     description: "Exact left-right symmetry",
     promptHint: "symmetrical mirror composition, exact left-right symmetry across a central vertical axis, both halves of the frame mirror each other in shape, mass, and tone",
+    term: "symmetrical mirrored composition",
   },
   {
     id: "vignette-composition",
@@ -460,6 +496,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "vantage",
     description: "Subject facing camera",
     promptHint: "front-on shot, subject facing the camera directly",
+    term: "front-on view, subject facing camera",
   },
   {
     id: "three-quarter-front",
@@ -467,6 +504,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "vantage",
     description: "Slightly off-axis from front",
     promptHint: "three-quarter view of the subject, camera slightly off-axis from the front",
+    term: "three-quarter front view",
   },
   {
     id: "profile-left",
@@ -474,6 +512,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "vantage",
     description: "Side view, subject's left",
     promptHint: "profile shot from the subject's left side",
+    term: "left profile view",
   },
   {
     id: "profile-right",
@@ -481,6 +520,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "vantage",
     description: "Side view, subject's right",
     promptHint: "profile shot from the subject's right side",
+    term: "right profile view",
   },
   {
     id: "three-quarter-back",
@@ -488,6 +528,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "vantage",
     description: "Off-axis from behind",
     promptHint: "three-quarter view from behind, camera angled off-axis from the rear",
+    term: "three-quarter rear view",
   },
   {
     id: "behind",
@@ -495,6 +536,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "vantage",
     description: "Direct rear view",
     promptHint: "shot from directly behind the subject, looking at their back",
+    term: "rear view from behind the subject",
   },
   {
     id: "side-back-angle",
@@ -502,6 +544,7 @@ export const FRAMINGS: ReadonlyArray<Framing> = [
     category: "vantage",
     description: "3/4 view from behind one shoulder",
     promptHint: "side-back angle, three-quarter view from behind one shoulder of the subject, partial face visible in profile, the back and shoulder line dominate the framing",
+    term: "three-quarter view from behind one shoulder",
   },
 ]
 
@@ -539,6 +582,16 @@ export function getFramingPromptHint(id: string | undefined | null): string {
   return getFraming(id)?.promptHint ?? ""
 }
 
+/**
+ * The compact professional term for a framing id (see `term.ts`): the short
+ * phrase this framing injects in compact hint mode ("tight headroom" where the
+ * hint is the full clause). Empty string for an unknown id and for any entry
+ * that injects no hint at all.
+ */
+export function getFramingTerm(id: string | undefined | null): string {
+  return resolveTerm(getFraming(id))
+}
+
 export const FRAMING_IDS: ReadonlyArray<string> = FRAMINGS.map((f) => f.id)
 
 export function isVantageFraming(id: string | undefined | null): boolean {
@@ -611,7 +664,9 @@ export function buildFramingHints(
     vantage?: unknown
   },
   skipVantage = false,
+  mode: PickerHintMode = "full",
 ): string[] {
+  if (mode === "compact") return buildFramingTerms(data, skipVantage)
   const hints: string[] = []
   for (const category of FRAMING_CATEGORY_ORDER) {
     if (category === "vantage" && skipVantage) continue
@@ -632,3 +687,40 @@ export function buildFramingHints(
   }
   return hints
 }
+
+/**
+ * Compact counterpart of `buildFramingHints`: the same per-category walk in the
+ * same canonical order and with the same `skipVantage` gate, emitted as short
+ * professional terms instead of full mechanism clauses ("medium close-up",
+ * "tight headroom"). Entries that inject no hint contribute no term either.
+ */
+export function buildFramingTerms(
+  data: Record<string, unknown> & {
+    shotSize?: unknown
+    angle?: unknown
+    coverage?: unknown
+    composition?: unknown
+    vantage?: unknown
+  },
+  skipVantage = false,
+): string[] {
+  const terms: string[] = []
+  for (const category of FRAMING_CATEGORY_ORDER) {
+    if (category === "vantage" && skipVantage) continue
+    const field = FRAMING_FIELD_BY_CATEGORY[category]
+    const raw = data[field]
+    // composition accepts string | string[] (multi-pick max 2). Other
+    // categories are single-pick; arrays are tolerated defensively.
+    if (typeof raw === "string" && raw.length > 0) {
+      const term = getFramingTerm(raw)
+      if (term) terms.push(term)
+    } else if (Array.isArray(raw)) {
+      for (const item of raw) {
+        if (typeof item !== "string" || item.length === 0) continue
+        const term = getFramingTerm(item)
+        if (term) terms.push(term)
+      }
+    }
+  }
+  return terms
+}