@nodaro/prompts 1.7.2 → 1.8.0

package/src/lighting.ts

@@ -10,6 +10,8 @@
  * frontend DAG executor and the backend orchestrator.
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export type LightingCategory =
   | "time-of-day"
   | "style"
@@ -23,93 +25,102 @@ export interface Lighting {
   readonly category: LightingCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * Compact professional term injected in compact hint mode (see `term.ts`).
+   *
+   * Lighting labels are bare MODIFIERS — "Short", "Broad", "Loop", "Split",
+   * "Hard" mean nothing on their own and collide head-on with common English
+   * words, so nearly every entry here authors the trade phrasing that carries
+   * its category noun ("short lighting", "1:4 lighting ratio").
+   */
+  readonly term?: string
 }
 
 export const LIGHTINGS: ReadonlyArray<Lighting> = [
   // Time of day (15)
-  { id: "dawn",          label: "Dawn",          category: "time-of-day", description: "Pre-sunrise pale glow",         promptHint: "dawn lighting, the pre-sunrise pale glow with deep blue ambient tones transitioning to soft pink and orange at the horizon, low contrast, cool ambient" },
-  { id: "sunrise",       label: "Sunrise",       category: "time-of-day", description: "Warm low sun, long shadows",   promptHint: "sunrise lighting, warm low-angle sun with long shadows and soft golden tones" },
-  { id: "morning",       label: "Morning",       category: "time-of-day", description: "Bright fresh morning light",    promptHint: "morning lighting, bright fresh ambient daylight with soft directional sun, warm white tones and clean shadows" },
-  { id: "noon",          label: "Noon",          category: "time-of-day", description: "Harsh overhead midday sun",     promptHint: "midday noon lighting, harsh overhead sun with high contrast and strong vertical shadows" },
-  { id: "harsh-midday",  label: "Harsh Midday",  category: "time-of-day", description: "Bleached white-sun zenith",     promptHint: "harsh midday white-sun lighting, sun directly overhead at zenith, blown-out white highlights and short hard shadows pooled directly beneath the subject" },
-  { id: "afternoon",     label: "Afternoon",     category: "time-of-day", description: "Warm late afternoon glow",      promptHint: "afternoon lighting, warm directional late-afternoon sun with elongated shadows, saturated amber tones leading into golden hour" },
-  { id: "overcast",      label: "Overcast",      category: "time-of-day", description: "Soft diffused daylight",        promptHint: "overcast daylight, soft diffused light from a uniformly cloudy sky with no harsh shadows" },
+  { id: "dawn",          label: "Dawn",          category: "time-of-day", description: "Pre-sunrise pale glow",         promptHint: "dawn lighting, the pre-sunrise pale glow with deep blue ambient tones transitioning to soft pink and orange at the horizon, low contrast, cool ambient", term: "dawn lighting" },
+  { id: "sunrise",       label: "Sunrise",       category: "time-of-day", description: "Warm low sun, long shadows",   promptHint: "sunrise lighting, warm low-angle sun with long shadows and soft golden tones", term: "sunrise lighting" },
+  { id: "morning",       label: "Morning",       category: "time-of-day", description: "Bright fresh morning light",    promptHint: "morning lighting, bright fresh ambient daylight with soft directional sun, warm white tones and clean shadows", term: "morning lighting" },
+  { id: "noon",          label: "Noon",          category: "time-of-day", description: "Harsh overhead midday sun",     promptHint: "midday noon lighting, harsh overhead sun with high contrast and strong vertical shadows", term: "overhead noon sun" },
+  { id: "harsh-midday",  label: "Harsh Midday",  category: "time-of-day", description: "Bleached white-sun zenith",     promptHint: "harsh midday white-sun lighting, sun directly overhead at zenith, blown-out white highlights and short hard shadows pooled directly beneath the subject", term: "harsh midday sun" },
+  { id: "afternoon",     label: "Afternoon",     category: "time-of-day", description: "Warm late afternoon glow",      promptHint: "afternoon lighting, warm directional late-afternoon sun with elongated shadows, saturated amber tones leading into golden hour", term: "afternoon lighting" },
+  { id: "overcast",      label: "Overcast",      category: "time-of-day", description: "Soft diffused daylight",        promptHint: "overcast daylight, soft diffused light from a uniformly cloudy sky with no harsh shadows", term: "overcast daylight" },
   { id: "golden-hour",   label: "Golden Hour",   category: "time-of-day", description: "Warm sunset glow",              promptHint: "golden hour lighting, warm sunset glow with soft directional sunlight and saturated golden tones" },
-  { id: "dusk",          label: "Dusk",          category: "time-of-day", description: "Post-sunset fading light",      promptHint: "dusk lighting, the post-sunset fading light with deepening blue sky, residual warm horizon glow, and rising ambient cool tones" },
+  { id: "dusk",          label: "Dusk",          category: "time-of-day", description: "Post-sunset fading light",      promptHint: "dusk lighting, the post-sunset fading light with deepening blue sky, residual warm horizon glow, and rising ambient cool tones", term: "dusk lighting" },
   { id: "blue-hour",     label: "Blue Hour",     category: "time-of-day", description: "Cool dusk twilight",            promptHint: "blue hour twilight lighting, cool desaturated tones just after sunset with soft ambient light" },
-  { id: "twilight",      label: "Twilight",      category: "time-of-day", description: "Between blue hour and night",   promptHint: "twilight lighting, the transitional dusk between blue hour and full night, deep indigo sky with the last residual ambient glow on the horizon and emerging artificial city lights" },
-  { id: "night",         label: "Night",         category: "time-of-day", description: "Deep night, low ambient",       promptHint: "night lighting, deep dark scene with minimal ambient illumination and high contrast highlights" },
-  { id: "midnight",      label: "Midnight",      category: "time-of-day", description: "Deepest night, near-black sky", promptHint: "midnight lighting, the deepest part of night with a near-black sky, minimal ambient illumination, scattered cool moonlight or starlight as the only natural source" },
-  { id: "moonlight",     label: "Moonlight",     category: "time-of-day", description: "Cool blue moonlit scene",       promptHint: "moonlight, cool blue ambient illumination with soft directional moonlit highlights and deep shadows" },
-  { id: "neon-night",    label: "Neon Night",    category: "time-of-day", description: "Saturated neon city night",     promptHint: "neon night lighting, saturated magenta and cyan neon glow against deep night ambient, urban cyberpunk feel" },
+  { id: "twilight",      label: "Twilight",      category: "time-of-day", description: "Between blue hour and night",   promptHint: "twilight lighting, the transitional dusk between blue hour and full night, deep indigo sky with the last residual ambient glow on the horizon and emerging artificial city lights", term: "twilight lighting" },
+  { id: "night",         label: "Night",         category: "time-of-day", description: "Deep night, low ambient",       promptHint: "night lighting, deep dark scene with minimal ambient illumination and high contrast highlights", term: "night lighting" },
+  { id: "midnight",      label: "Midnight",      category: "time-of-day", description: "Deepest night, near-black sky", promptHint: "midnight lighting, the deepest part of night with a near-black sky, minimal ambient illumination, scattered cool moonlight or starlight as the only natural source", term: "midnight lighting" },
+  { id: "moonlight",     label: "Moonlight",     category: "time-of-day", description: "Cool blue moonlit scene",       promptHint: "moonlight, cool blue ambient illumination with soft directional moonlit highlights and deep shadows", term: "cool blue moonlight" },
+  { id: "neon-night",    label: "Neon Night",    category: "time-of-day", description: "Saturated neon city night",     promptHint: "neon night lighting, saturated magenta and cyan neon glow against deep night ambient, urban cyberpunk feel", term: "neon night lighting" },
 
   // Style (31)
-  { id: "three-point",   label: "Three-Point",   category: "style",       description: "Classic key + fill + back",    promptHint: "three-point lighting setup, balanced key light with fill and rim back-light, classical studio look" },
-  { id: "rembrandt",     label: "Rembrandt",     category: "style",       description: "Triangle of light on cheek",   promptHint: "Rembrandt lighting, distinctive triangle of light on the shadow-side cheek, painterly chiaroscuro" },
-  { id: "chiaroscuro",   label: "Chiaroscuro",   category: "style",       description: "Strong light/dark contrast",   promptHint: "chiaroscuro lighting, dramatic strong contrast between deep shadows and bright highlights" },
-  { id: "silhouette",    label: "Silhouette",    category: "style",       description: "Subject as pure shape",        promptHint: "silhouette lighting, subject rendered as a pure dark shape against a much brighter background" },
-  { id: "high-key",      label: "High-Key",      category: "style",       description: "Bright, low-contrast",         promptHint: "high-key lighting, bright low-contrast scene with minimal shadows and a light overall tone" },
-  { id: "low-key",       label: "Low-Key",       category: "style",       description: "Dark, high-contrast",          promptHint: "low-key lighting, dark high-contrast scene with deep shadows and selective highlights" },
-  { id: "split",         label: "Split",         category: "style",       description: "Half-lit half-shadow face",    promptHint: "split lighting, light hitting only one half of the face with the other half in deep shadow" },
+  { id: "three-point",   label: "Three-Point",   category: "style",       description: "Classic key + fill + back",    promptHint: "three-point lighting setup, balanced key light with fill and rim back-light, classical studio look", term: "three-point lighting" },
+  { id: "rembrandt",     label: "Rembrandt",     category: "style",       description: "Triangle of light on cheek",   promptHint: "Rembrandt lighting, distinctive triangle of light on the shadow-side cheek, painterly chiaroscuro", term: "rembrandt lighting" },
+  { id: "chiaroscuro",   label: "Chiaroscuro",   category: "style",       description: "Strong light/dark contrast",   promptHint: "chiaroscuro lighting, dramatic strong contrast between deep shadows and bright highlights", term: "chiaroscuro lighting" },
+  { id: "silhouette",    label: "Silhouette",    category: "style",       description: "Subject as pure shape",        promptHint: "silhouette lighting, subject rendered as a pure dark shape against a much brighter background", term: "silhouette lighting" },
+  { id: "high-key",      label: "High-Key",      category: "style",       description: "Bright, low-contrast",         promptHint: "high-key lighting, bright low-contrast scene with minimal shadows and a light overall tone", term: "high-key lighting" },
+  { id: "low-key",       label: "Low-Key",       category: "style",       description: "Dark, high-contrast",          promptHint: "low-key lighting, dark high-contrast scene with deep shadows and selective highlights", term: "low-key lighting" },
+  { id: "split",         label: "Split",         category: "style",       description: "Half-lit half-shadow face",    promptHint: "split lighting, light hitting only one half of the face with the other half in deep shadow", term: "split lighting" },
   // Classical portrait lighting setups
-  { id: "butterfly",     label: "Butterfly",     category: "style",       description: "Glamour, nose-shadow butterfly", promptHint: "butterfly portrait lighting, key light placed directly above and slightly in front of the subject casting a small symmetrical butterfly-shaped shadow under the nose, classic Hollywood glamour with even illumination across both cheeks" },
-  { id: "loop",          label: "Loop",          category: "style",       description: "Most natural portrait setup",   promptHint: "loop portrait lighting, key light slightly to one side and above eye level casting a small loop-shaped nose shadow on the cheek that does not touch the shadow side, the most natural and flattering classical portrait setup" },
-  { id: "broad",         label: "Broad",         category: "style",       description: "Wider face, friendly key",      promptHint: "broad portrait lighting, key light striking the side of the face turned toward the camera so the larger lit cheek dominates the frame, makes the face appear wider and more open with a friendly approachable feel" },
-  { id: "short",         label: "Short",         category: "style",       description: "Slimming, dramatic key",        promptHint: "short portrait lighting, key light striking the side of the face turned away from the camera so the larger plane of the face falls into shadow, slims the face and adds dramatic dimension favored in editorial and male portraiture" },
-  { id: "hatchet",       label: "Hatchet",       category: "style",       description: "Overhead skim, deep side shadow", promptHint: "hatchet portrait lighting, hard overhead light skimming the face from one side and leaving the opposite side in deep unrelieved shadow, theatrical and severe with a sharply divided contour" },
-  { id: "clamshell",     label: "Clamshell",     category: "style",       description: "Beauty key + bottom reflector", promptHint: "clamshell beauty lighting, soft key light above the subject paired with a reflector or fill below the chin sandwiching the face evenly between two light sources, glossy commercial beauty look with twin catchlights and minimal shadow under the jaw" },
-  { id: "hard",          label: "Hard",          category: "style",       description: "Sharp-edged shadows",          promptHint: "hard lighting, sharp-edged crisp shadows from an undiffused direct light source" },
-  { id: "soft",          label: "Soft",          category: "style",       description: "Diffused gentle light",        promptHint: "soft diffused lighting, gentle wraparound light with smooth shadow transitions" },
-  { id: "practical",     label: "Practical",     category: "style",       description: "In-scene visible lights",      promptHint: "practical lighting, illumination from visible in-scene sources (lamps, windows, screens, candles)" },
+  { id: "butterfly",     label: "Butterfly",     category: "style",       description: "Glamour, nose-shadow butterfly", promptHint: "butterfly portrait lighting, key light placed directly above and slightly in front of the subject casting a small symmetrical butterfly-shaped shadow under the nose, classic Hollywood glamour with even illumination across both cheeks", term: "butterfly lighting" },
+  { id: "loop",          label: "Loop",          category: "style",       description: "Most natural portrait setup",   promptHint: "loop portrait lighting, key light slightly to one side and above eye level casting a small loop-shaped nose shadow on the cheek that does not touch the shadow side, the most natural and flattering classical portrait setup", term: "loop lighting" },
+  { id: "broad",         label: "Broad",         category: "style",       description: "Wider face, friendly key",      promptHint: "broad portrait lighting, key light striking the side of the face turned toward the camera so the larger lit cheek dominates the frame, makes the face appear wider and more open with a friendly approachable feel", term: "broad lighting" },
+  { id: "short",         label: "Short",         category: "style",       description: "Slimming, dramatic key",        promptHint: "short portrait lighting, key light striking the side of the face turned away from the camera so the larger plane of the face falls into shadow, slims the face and adds dramatic dimension favored in editorial and male portraiture", term: "short lighting" },
+  { id: "hatchet",       label: "Hatchet",       category: "style",       description: "Overhead skim, deep side shadow", promptHint: "hatchet portrait lighting, hard overhead light skimming the face from one side and leaving the opposite side in deep unrelieved shadow, theatrical and severe with a sharply divided contour", term: "hatchet lighting" },
+  { id: "clamshell",     label: "Clamshell",     category: "style",       description: "Beauty key + bottom reflector", promptHint: "clamshell beauty lighting, soft key light above the subject paired with a reflector or fill below the chin sandwiching the face evenly between two light sources, glossy commercial beauty look with twin catchlights and minimal shadow under the jaw", term: "clamshell lighting" },
+  { id: "hard",          label: "Hard",          category: "style",       description: "Sharp-edged shadows",          promptHint: "hard lighting, sharp-edged crisp shadows from an undiffused direct light source", term: "hard light" },
+  { id: "soft",          label: "Soft",          category: "style",       description: "Diffused gentle light",        promptHint: "soft diffused lighting, gentle wraparound light with smooth shadow transitions", term: "soft diffused light" },
+  { id: "practical",     label: "Practical",     category: "style",       description: "In-scene visible lights",      promptHint: "practical lighting, illumination from visible in-scene sources (lamps, windows, screens, candles)", term: "practical lighting" },
   // Modern social-video lighting styles
   { id: "ring-light",        label: "Ring Light",        category: "style", description: "Beauty/vlog ring catchlight",  promptHint: "ring light setup, even frontal illumination with the unmistakable circular catchlight in the eyes typical of beauty and vlog content" },
   { id: "phone-screen-glow", label: "Phone Screen Glow", category: "style", description: "Cool screen underlight",       promptHint: "phone screen glow lighting, cool blue underlighting from a phone screen casting upward onto the subject's face" },
-  { id: "selfie-natural",    label: "Selfie Natural",    category: "style", description: "Window-light selfie",          promptHint: "window-light selfie aesthetic, soft natural daylight from a single window with casual handheld framing" },
-  { id: "natural",           label: "Natural",           category: "style", description: "Available ambient light",       promptHint: "natural lighting, available ambient light with no artificial setup, organic and unpolished" },
-  { id: "volumetric",        label: "Volumetric",        category: "style", description: "Visible light beams in haze",  promptHint: "volumetric lighting, visible god-ray light beams cutting through hazy atmosphere with strong directional shafts" },
-  { id: "noir",              label: "Noir",              category: "style", description: "High-contrast B&W film noir",  promptHint: "film noir lighting, high-contrast black-and-white aesthetic with hard chiaroscuro shadows, venetian-blind slat shadows, and crushed deep blacks" },
+  { id: "selfie-natural",    label: "Selfie Natural",    category: "style", description: "Window-light selfie",          promptHint: "window-light selfie aesthetic, soft natural daylight from a single window with casual handheld framing", term: "natural window-light selfie" },
+  { id: "natural",           label: "Natural",           category: "style", description: "Available ambient light",       promptHint: "natural lighting, available ambient light with no artificial setup, organic and unpolished", term: "natural available light" },
+  { id: "volumetric",        label: "Volumetric",        category: "style", description: "Visible light beams in haze",  promptHint: "volumetric lighting, visible god-ray light beams cutting through hazy atmosphere with strong directional shafts", term: "volumetric lighting" },
+  { id: "noir",              label: "Noir",              category: "style", description: "High-contrast B&W film noir",  promptHint: "film noir lighting, high-contrast black-and-white aesthetic with hard chiaroscuro shadows, venetian-blind slat shadows, and crushed deep blacks", term: "film noir lighting" },
   // Flash & camera-flash styles
   { id: "on-camera-flash",   label: "On-Camera Flash",   category: "style", description: "Paparazzi/iPhone direct flash", promptHint: "on-camera flash lighting, harsh direct frontal flash with blown-out highlights on skin, hard shadow falloff behind the subject and a darkened background, paparazzi and iPhone-flash signature" },
-  { id: "mirror-bounce-flash", label: "Mirror-Bounce Flash", category: "style", description: "Mirror-selfie flash bounce", promptHint: "mirror-selfie flash lighting, yellowish uneven LED-or-flash bouncing off the mirror surface with a hot flare spot, partially obscured face by the phone, classic mirror-selfie aesthetic" },
+  { id: "mirror-bounce-flash", label: "Mirror-Bounce Flash", category: "style", description: "Mirror-selfie flash bounce", promptHint: "mirror-selfie flash lighting, yellowish uneven LED-or-flash bouncing off the mirror surface with a hot flare spot, partially obscured face by the phone, classic mirror-selfie aesthetic", term: "mirror-selfie flash" },
   { id: "bounced-flash",     label: "Bounced Flash",     category: "style", description: "Soft ceiling-bounced fill",   promptHint: "bounced flash lighting, on-camera flash redirected off a ceiling or wall to create soft top-down fill with gentle shadows, even skin tones and natural ambient feel" },
-  { id: "softbox-key",       label: "Softbox Key",       category: "style", description: "Large diffused fashion key",   promptHint: "softbox key lighting, large diffused fashion-studio key light producing gentle wraparound illumination, soft falloff and clean even skin rendering" },
+  { id: "softbox-key",       label: "Softbox Key",       category: "style", description: "Large diffused fashion key",   promptHint: "softbox key lighting, large diffused fashion-studio key light producing gentle wraparound illumination, soft falloff and clean even skin rendering", term: "softbox key light" },
   { id: "beauty-dish",       label: "Beauty Dish",       category: "style", description: "Hero light, crisp falloff",    promptHint: "beauty dish lighting, semi-hard hero light with crisp shadow falloff and a distinctive round catchlight, slightly punchy contour and contrast favored in beauty and editorial portraits" },
   { id: "gridded-snoot",     label: "Gridded Snoot",     category: "style", description: "Tight focused pool of light",  promptHint: "gridded snoot lighting, tightly focused circular pool of light isolating the subject's face or shoulders against deep surrounding shadow, theatrical and controlled" },
   { id: "silk-diffusion",    label: "Silk Diffusion",    category: "style", description: "Silk-softened gentle key",     promptHint: "silk diffusion lighting, gentle key light passed through a large silk to soften shadow edges, producing creamy gradients and flattering skin tones" },
-  { id: "kicker-rim",        label: "Kicker / Rim Accent", category: "style", description: "Low-side accent separator",   promptHint: "kicker rim accent lighting, low side-rear accent light skimming the subject's edge to separate them from a darker background, adds dimension and depth" },
-  { id: "candlelight",       label: "Candlelight",       category: "style", description: "Warm flickering firelight",    promptHint: "candlelight or firelight, warm flickering tungsten glow with soft falloff, low color temperature and gentle dancing shadows on nearby surfaces" },
-  { id: "edison-tungsten",   label: "Edison Tungsten",   category: "style", description: "Cozy warm globe-bulb glow",    promptHint: "Edison-bulb tungsten lighting, warm low-CRI globe-bulb glow with visible filament hot-spots, cozy bar or cafe atmosphere with amber-orange ambient" },
-  { id: "dappled-light",     label: "Dappled / Leaf-Filtered", category: "style", description: "Speckled foliage light",  promptHint: "dappled leaf-filtered lighting, sunlight broken into a speckled pattern of bright spots and soft shadows as it passes through overhead foliage, organic and painterly" },
+  { id: "kicker-rim",        label: "Kicker / Rim Accent", category: "style", description: "Low-side accent separator",   promptHint: "kicker rim accent lighting, low side-rear accent light skimming the subject's edge to separate them from a darker background, adds dimension and depth", term: "kicker rim light" },
+  { id: "candlelight",       label: "Candlelight",       category: "style", description: "Warm flickering firelight",    promptHint: "candlelight or firelight, warm flickering tungsten glow with soft falloff, low color temperature and gentle dancing shadows on nearby surfaces", term: "warm flickering candlelight" },
+  { id: "edison-tungsten",   label: "Edison Tungsten",   category: "style", description: "Cozy warm globe-bulb glow",    promptHint: "Edison-bulb tungsten lighting, warm low-CRI globe-bulb glow with visible filament hot-spots, cozy bar or cafe atmosphere with amber-orange ambient", term: "warm edison-bulb tungsten glow" },
+  { id: "dappled-light",     label: "Dappled / Leaf-Filtered", category: "style", description: "Speckled foliage light",  promptHint: "dappled leaf-filtered lighting, sunlight broken into a speckled pattern of bright spots and soft shadows as it passes through overhead foliage, organic and painterly", term: "dappled leaf-filtered light" },
   { id: "raking-sidelight",  label: "Raking Sidelight",  category: "style", description: "Extreme low side, texture",    promptHint: "raking sidelight, extreme low-angle side light skimming across the surface to exaggerate texture and microcontour, long parallel shadows reveal every detail" },
   { id: "stage-spotlight",   label: "Stage Spotlight",   category: "style", description: "Single hard overhead spot",    promptHint: "stage spotlight lighting, single hard overhead theatre spotlight isolating the subject in a circular pool of light against pure black surroundings, dust motes catching the beam" },
   { id: "underwater-caustics", label: "Underwater Caustics", category: "style", description: "Rippled refracted patterns", promptHint: "underwater caustics lighting, rippled wavy refracted light patterns dancing across the subject and surroundings, cool aquatic blue-green palette with shimmering highlights" },
-  { id: "bioluminescence",   label: "Bioluminescence",   category: "style", description: "Cool eerie biological glow",   promptHint: "bioluminescence lighting, cool eerie cyan-green glow emanating from biological sources, soft self-illuminated highlights against deep ambient darkness, otherworldly atmosphere" },
+  { id: "bioluminescence",   label: "Bioluminescence",   category: "style", description: "Cool eerie biological glow",   promptHint: "bioluminescence lighting, cool eerie cyan-green glow emanating from biological sources, soft self-illuminated highlights against deep ambient darkness, otherworldly atmosphere", term: "bioluminescent glow" },
 
   // Direction (8)
-  { id: "front",         label: "Front",         category: "direction",   description: "Light from camera direction",  promptHint: "front lighting, light coming from the camera direction, flat even illumination across the subject" },
-  { id: "three-quarter", label: "3/4 Light",     category: "direction",   description: "Classic portrait key angle",   promptHint: "three-quarter light, classic portrait key angle split between front and side at roughly 45 degrees off-camera, sculpts the face with a visible shadow on the far cheek and a defined nose shadow" },
-  { id: "side",          label: "Side",          category: "direction",   description: "Light from one side",          promptHint: "side lighting, light coming from the side of the subject, emphasizing texture and form" },
-  { id: "back-rim",      label: "Back / Rim",    category: "direction",   description: "Backlight rim around subject", promptHint: "back-light or rim-light, light coming from behind the subject creating a bright rim around their silhouette" },
+  { id: "front",         label: "Front",         category: "direction",   description: "Light from camera direction",  promptHint: "front lighting, light coming from the camera direction, flat even illumination across the subject", term: "front lighting" },
+  { id: "three-quarter", label: "3/4 Light",     category: "direction",   description: "Classic portrait key angle",   promptHint: "three-quarter light, classic portrait key angle split between front and side at roughly 45 degrees off-camera, sculpts the face with a visible shadow on the far cheek and a defined nose shadow", term: "three-quarter key light" },
+  { id: "side",          label: "Side",          category: "direction",   description: "Light from one side",          promptHint: "side lighting, light coming from the side of the subject, emphasizing texture and form", term: "side lighting" },
+  { id: "back-rim",      label: "Back / Rim",    category: "direction",   description: "Backlight rim around subject", promptHint: "back-light or rim-light, light coming from behind the subject creating a bright rim around their silhouette", term: "rim backlight" },
   { id: "silhouette-backlight", label: "Silhouette Backlight", category: "direction", description: "Bright halo, dark subject", promptHint: "silhouette backlight, strong light source directly behind the subject rendering them as a dark shape with a luminous halo edge and bright background bloom, dramatic contour against the sky or window" },
-  { id: "top-overhead",  label: "Top / Overhead",category: "direction",   description: "Light from directly above",    promptHint: "top-down overhead lighting, light coming from directly above the subject creating shadows under the eyes and chin" },
-  { id: "under-uplight", label: "Under / Uplight",category: "direction",  description: "Light from below",             promptHint: "uplighting from below, light coming from below the subject creating an unsettling theatrical look" },
-  { id: "window",        label: "Window",        category: "direction",   description: "Soft sidelight from window",   promptHint: "window lighting, soft directional light from a single window source with natural falloff" },
+  { id: "top-overhead",  label: "Top / Overhead",category: "direction",   description: "Light from directly above",    promptHint: "top-down overhead lighting, light coming from directly above the subject creating shadows under the eyes and chin", term: "overhead top light" },
+  { id: "under-uplight", label: "Under / Uplight",category: "direction",  description: "Light from below",             promptHint: "uplighting from below, light coming from below the subject creating an unsettling theatrical look", term: "uplighting from below" },
+  { id: "window",        label: "Window",        category: "direction",   description: "Soft sidelight from window",   promptHint: "window lighting, soft directional light from a single window source with natural falloff", term: "window light" },
 
   // Lighting ratio (6) — relative key-to-shadow brightness
-  { id: "ratio-1-1",  label: "1:1",  category: "lighting-ratio", description: "Flat, no shadow contrast",       promptHint: "1:1 lighting ratio, flat even illumination across the subject with no contrast between key and fill, beauty and catalog look that flattens dimension" },
-  { id: "ratio-1-2",  label: "1:2",  category: "lighting-ratio", description: "Soft one-stop falloff",          promptHint: "1:2 lighting ratio, gentle soft modeling with roughly one stop of falloff from key to shadow side, classic flattering portraiture with mild dimension" },
-  { id: "ratio-1-3",  label: "1:3",  category: "lighting-ratio", description: "Moderate two-stop contrast",     promptHint: "1:3 lighting ratio, moderate contrast with about two stops between the lit and shadow sides, well-defined facial dimension and visible but recovered shadow detail" },
-  { id: "ratio-1-4",  label: "1:4",  category: "lighting-ratio", description: "Strong editorial contrast",      promptHint: "1:4 lighting ratio, strong contrast with deepening shadows on the unlit side, dramatic editorial feel with sculpted form and minimal shadow detail" },
-  { id: "ratio-1-8",  label: "1:8",  category: "lighting-ratio", description: "Extreme low-key chiaroscuro",    promptHint: "1:8 lighting ratio, extreme chiaroscuro with near-black shadow side balanced against a single bright key, classic low-key cinema atmosphere" },
-  { id: "ratio-1-16", label: "1:16", category: "lighting-ratio", description: "Single-source film-noir falloff", promptHint: "1:16 lighting ratio, single-source key against pitch-black shadow side, theatrical film-noir falloff with no fill and crushed unlit detail" },
+  { id: "ratio-1-1",  label: "1:1",  category: "lighting-ratio", description: "Flat, no shadow contrast",       promptHint: "1:1 lighting ratio, flat even illumination across the subject with no contrast between key and fill, beauty and catalog look that flattens dimension", term: "1:1 lighting ratio" },
+  { id: "ratio-1-2",  label: "1:2",  category: "lighting-ratio", description: "Soft one-stop falloff",          promptHint: "1:2 lighting ratio, gentle soft modeling with roughly one stop of falloff from key to shadow side, classic flattering portraiture with mild dimension", term: "1:2 lighting ratio" },
+  { id: "ratio-1-3",  label: "1:3",  category: "lighting-ratio", description: "Moderate two-stop contrast",     promptHint: "1:3 lighting ratio, moderate contrast with about two stops between the lit and shadow sides, well-defined facial dimension and visible but recovered shadow detail", term: "1:3 lighting ratio" },
+  { id: "ratio-1-4",  label: "1:4",  category: "lighting-ratio", description: "Strong editorial contrast",      promptHint: "1:4 lighting ratio, strong contrast with deepening shadows on the unlit side, dramatic editorial feel with sculpted form and minimal shadow detail", term: "1:4 lighting ratio" },
+  { id: "ratio-1-8",  label: "1:8",  category: "lighting-ratio", description: "Extreme low-key chiaroscuro",    promptHint: "1:8 lighting ratio, extreme chiaroscuro with near-black shadow side balanced against a single bright key, classic low-key cinema atmosphere", term: "1:8 lighting ratio" },
+  { id: "ratio-1-16", label: "1:16", category: "lighting-ratio", description: "Single-source film-noir falloff", promptHint: "1:16 lighting ratio, single-source key against pitch-black shadow side, theatrical film-noir falloff with no fill and crushed unlit detail", term: "1:16 lighting ratio" },
 
   // Color temperature (6) — Kelvin from warm to cool
-  { id: "temp-2700k", label: "2700K Candle",   category: "color-temperature", description: "Deep amber candle/tungsten",   promptHint: "2700K warm candle and low-tungsten color temperature, deep amber and orange cast across the scene, intimate and cozy mood with rich golden highlights" },
-  { id: "temp-3200k", label: "3200K Tungsten", category: "color-temperature", description: "Warm yellow interior",         promptHint: "3200K tungsten color temperature, warm yellow-orange cast typical of classic incandescent home interiors, lived-in domestic ambient" },
-  { id: "temp-4000k", label: "4000K Mixed",    category: "color-temperature", description: "Neutral white",                promptHint: "4000K neutral white color temperature, balanced midpoint between warm tungsten and cool daylight, clean office and mixed-source feel without strong color cast" },
-  { id: "temp-5600k", label: "5600K Daylight", category: "color-temperature", description: "Daylight-balanced midday sun", promptHint: "5600K daylight-balanced color temperature, neutral midday white sun with accurate color rendering and no warm or cool bias" },
-  { id: "temp-6500k", label: "6500K Overcast", category: "color-temperature", description: "Slightly cool blue cast",      promptHint: "6500K overcast-cool color temperature, slightly blue cast typical of overcast skies and high-noon shadow areas, subtly cool and clinical" },
-  { id: "temp-9000k", label: "9000K Shade",    category: "color-temperature", description: "Distinctly cool blue shade",   promptHint: "9000K open-shade color temperature, distinctly cool blue cast found in deep shade and cloud-shadowed mountain air, chilled and atmospheric" },
+  { id: "temp-2700k", label: "2700K Candle",   category: "color-temperature", description: "Deep amber candle/tungsten",   promptHint: "2700K warm candle and low-tungsten color temperature, deep amber and orange cast across the scene, intimate and cozy mood with rich golden highlights", term: "2700k candlelight color temperature" },
+  { id: "temp-3200k", label: "3200K Tungsten", category: "color-temperature", description: "Warm yellow interior",         promptHint: "3200K tungsten color temperature, warm yellow-orange cast typical of classic incandescent home interiors, lived-in domestic ambient", term: "3200k tungsten color temperature" },
+  { id: "temp-4000k", label: "4000K Mixed",    category: "color-temperature", description: "Neutral white",                promptHint: "4000K neutral white color temperature, balanced midpoint between warm tungsten and cool daylight, clean office and mixed-source feel without strong color cast", term: "4000k neutral white color temperature" },
+  { id: "temp-5600k", label: "5600K Daylight", category: "color-temperature", description: "Daylight-balanced midday sun", promptHint: "5600K daylight-balanced color temperature, neutral midday white sun with accurate color rendering and no warm or cool bias", term: "5600k daylight color temperature" },
+  { id: "temp-6500k", label: "6500K Overcast", category: "color-temperature", description: "Slightly cool blue cast",      promptHint: "6500K overcast-cool color temperature, slightly blue cast typical of overcast skies and high-noon shadow areas, subtly cool and clinical", term: "6500k overcast color temperature" },
+  { id: "temp-9000k", label: "9000K Shade",    category: "color-temperature", description: "Distinctly cool blue shade",   promptHint: "9000K open-shade color temperature, distinctly cool blue cast found in deep shade and cloud-shadowed mountain air, chilled and atmospheric", term: "9000k open-shade color temperature" },
 ] as const
 
 export const LIGHTING_CATEGORY_ORDER: ReadonlyArray<LightingCategory> = [
@@ -146,6 +157,16 @@ export function getLightingPromptHint(id: string | undefined | null): string {
   return getLighting(id)?.promptHint ?? ""
 }
 
+/**
+ * The COMPACT counterpart of `getLightingPromptHint`: the short professional
+ * term ("rembrandt lighting", "1:4 lighting ratio", "rim backlight") a
+ * consumer injects instead of the full mechanism description. Same lookup,
+ * same empty-string-on-miss behavior.
+ */
+export function getLightingTerm(id: string | undefined | null): string {
+  return resolveTerm(getLighting(id))
+}
+
 export const LIGHTING_IDS: ReadonlyArray<string> = LIGHTINGS.map((l) => l.id)
 
 /**
@@ -207,7 +228,9 @@ export function buildLightingHints(
     lightingRatio?: unknown
     colorTemperature?: unknown
   },
+  mode: PickerHintMode = "full",
 ): string[] {
+  if (mode === "compact") return buildLightingTerms(data)
   const hints: string[] = []
   for (const category of LIGHTING_CATEGORY_ORDER) {
     const field = LIGHTING_FIELD_BY_CATEGORY[category]
@@ -227,3 +250,41 @@ export function buildLightingHints(
   }
   return hints
 }
+
+/**
+ * The COMPACT counterpart of `buildLightingHints`: the same per-category walk
+ * in the same canonical order, emitting each selection's short professional
+ * term ("dusk lighting", "rembrandt lighting", "1:4 lighting ratio") instead
+ * of its full mechanism description.
+ *
+ * @param data the consumer data record (must include optional timeOfDay /
+ *   lightingStyle / lightingDirection fields)
+ */
+export function buildLightingTerms(
+  data: Record<string, unknown> & {
+    timeOfDay?: unknown
+    lightingStyle?: unknown
+    lightingDirection?: unknown
+    lightingRatio?: unknown
+    colorTemperature?: unknown
+  },
+): string[] {
+  const terms: string[] = []
+  for (const category of LIGHTING_CATEGORY_ORDER) {
+    const field = LIGHTING_FIELD_BY_CATEGORY[category]
+    const raw = data[field]
+    // lightingStyle accepts string | string[] (multi-pick max 2). Other
+    // categories are single-pick and may also tolerate arrays defensively.
+    if (typeof raw === "string" && raw.length > 0) {
+      const term = getLightingTerm(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 = getLightingTerm(item)
+        if (term) terms.push(term)
+      }
+    }
+  }
+  return terms
+}

package/src/loop-subject.ts

@@ -18,6 +18,8 @@
  * and lets us refine each library independently.
  */
 
+import { resolveTerm } from "./term.js"
+
 export type LoopSubjectCategory = "realistic" | "abstract"
 
 export interface LoopSubject {
@@ -28,6 +30,11 @@ export interface LoopSubject {
   /** Drop-in prompt text for Generate Image. Wired into the prompt input
    *  via FieldMappings, same as Setting / Motion / Mood Parameter nodes. */
   readonly promptHint: string
+  /** Compact professional term for hint-compact mode (see `term.ts`). Authored
+   *  only where the lowercased label is not what a professional would write —
+   *  the "Tunnel — Exciting" style UI compounds and the generic subject
+   *  labels ("Galaxy", "Underwater Light") that need their trade wording. */
+  readonly term?: string
 }
 
 export const LOOP_SUBJECT_CATEGORY_ORDER: ReadonlyArray<LoopSubjectCategory> = [
@@ -48,6 +55,7 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
     category: "realistic",
     description: "Aurora borealis ribbons over a horizon",
     promptHint: "aurora borealis ribbons in green and violet over a snowy mountain horizon, wide centered framing, low ambient starlight, deep cosmic backdrop, no foreground subject",
+    term: "aurora borealis",
   },
   {
     id: "clouds",
@@ -104,6 +112,7 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
     category: "realistic",
     description: "Spiral galaxy in deep space",
     promptHint: "spiral galaxy with swirling arms of stars and luminous gas, dust lanes radiating from a bright core, centered radial composition, deep cosmic black background, no perspective depth",
+    term: "spiral galaxy",
   },
   {
     id: "nebula",
@@ -118,6 +127,7 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
     category: "realistic",
     description: "Light rays through forest canopy",
     promptHint: "golden sunbeams cutting through a tall forest canopy with floating dust motes catching the light, centered vertical composition, deep green ambient tone, no human figures, no foreground subject",
+    term: "sunbeams through forest canopy",
   },
   {
     id: "cherry-blossoms",
@@ -132,6 +142,7 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
     category: "realistic",
     description: "Sunbeams and bubbles below water",
     promptHint: "sunbeams cutting down through deep blue ocean water with rising silver air bubbles and floating particulate, centered cathedral-light composition, no surface horizon visible, no foreground subject",
+    term: "underwater god rays",
   },
   {
     id: "embers",
@@ -148,6 +159,7 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
     category: "abstract",
     description: "Fractal neon tunnel with depth",
     promptHint: "infinite fractal tunnel of glowing neon ribbons receding into a vanishing point, centered symmetric composition, deep volumetric light, no foreground subject",
+    term: "infinite fractal neon tunnel",
   },
   {
     id: "tunnel-clean",
@@ -155,6 +167,7 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
     category: "abstract",
     description: "Periodic tunnel of geometric filaments",
     promptHint: "infinite fractal tunnel of glowing neon geometric filaments, self-similar repeating depth that recurses to infinity, centered symmetric composition, deep volumetric light, dark void background, no foreground subject",
+    term: "self-similar geometric neon tunnel",
   },
   {
     id: "kaleidoscope",
@@ -204,6 +217,7 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
     category: "abstract",
     description: "Pulsing audio visualizer",
     promptHint: "vertical audio equalizer bars in vibrant neon gradient pulsing at different heights, centered symmetric composition, dark backdrop with soft glow, repeating periodic structure, no foreground subject",
+    term: "audio equalizer bars",
   },
   {
     id: "dna-helix",
@@ -211,6 +225,7 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
     category: "abstract",
     description: "Rotating double helix",
     promptHint: "glowing neon DNA double helix structure with periodic identical rungs, centered vertical symmetric composition, electric cyan and magenta strands, dark void background, fractal repeating geometry, no foreground subject",
+    term: "dna double helix",
   },
   {
     id: "liquid-chrome",
@@ -260,10 +275,11 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
     category: "abstract",
     description: "Shifting platonic solids",
     promptHint: "abstract array of glowing neon platonic solid wireframes morphing through self-similar fractal subdivisions, centered radial symmetric composition, deep dark backdrop, electric rim lighting, no foreground subject",
+    term: "morphing platonic solid wireframes",
   },
 ]
 
-export function getLoopSubject(id: string): LoopSubject | undefined {
+export function getLoopSubject(id: string | undefined | null): LoopSubject | undefined {
   return LOOP_SUBJECTS.find((s) => s.id === id)
 }
 
@@ -274,3 +290,13 @@ export function getLoopSubjectLabel(id: string): string {
 export function getLoopSubjectPromptHint(id: string): string {
   return getLoopSubject(id)?.promptHint ?? ""
 }
+
+/**
+ * Compact professional term for the subject — the short phrase a VJ or
+ * cinematographer would write when the consumer wants a term instead of the
+ * full scene paragraph. Mirrors `getLoopSubjectPromptHint`'s lookup so the two
+ * can never describe different entries.
+ */
+export function getLoopSubjectTerm(id: string | undefined | null): string {
+  return resolveTerm(getLoopSubject(id))
+}