@nodaro/prompts 1.7.3 → 1.8.1

package/src/character-fx.ts

@@ -18,6 +18,8 @@
  * null input is treated like undefined (falsy short-circuit → returns "")
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export type CharacterFxCategory =
   | "transformation"
   | "power"
@@ -31,6 +33,8 @@ export interface CharacterFx {
   readonly category: CharacterFxCategory
   readonly description: string
   readonly promptHint: string
+  /** Optional authored compact term (see `term.ts` for the convention). */
+  readonly term?: string
 }
 
 export type CharacterFxPosition  = "auto" | "start" | "middle" | "end" | "full"
@@ -51,37 +55,48 @@ export const CHARACTER_FX: ReadonlyArray<CharacterFx> = [
   { id: "auto",                 label: "Auto",                   category: "transformation", description: "Let the model choose", promptHint: "" },
   { id: "none",                 label: "None",                   category: "transformation", description: "No character effect", promptHint: "" },
   { id: "werewolf",             label: "Werewolf",               category: "transformation", description: "Transforms into a werewolf",
-    promptHint: "the subject transforms into a werewolf — fur sprouts across the skin, fangs and claws extend, the snout elongates, eyes glow yellow, body re-shapes with visible muscle and bone movement, clothing tears" },
+    promptHint: "the subject transforms into a werewolf — fur sprouts across the skin, fangs and claws extend, the snout elongates, eyes glow yellow, body re-shapes with visible muscle and bone movement, clothing tears",
+    term: "werewolf transformation" },
   { id: "vampire",              label: "Vampire",                category: "transformation", description: "Transforms into a vampire",
-    promptHint: "the subject transforms into a vampire — skin pales, fangs extend, eyes shift to crimson, pupils dilate, posture shifts predatory, with a faint mist drifting around the body" },
+    promptHint: "the subject transforms into a vampire — skin pales, fangs extend, eyes shift to crimson, pupils dilate, posture shifts predatory, with a faint mist drifting around the body",
+    term: "vampire transformation" },
   { id: "cyborg",               label: "Cyborg Reveal",          category: "transformation", description: "Skin peels back revealing cybernetics",
     promptHint: "the subject's skin peels open along seams to reveal glowing cybernetic mechanisms beneath — exposed circuit boards, hydraulic joints, blue LED indicators along the limbs and torso" },
   { id: "ghost-form",           label: "Ghost Form",             category: "transformation", description: "Body becomes translucent / ethereal",
     promptHint: "the subject becomes translucent and ethereal, body edges feathering into mist, faint inner glow visible through the skin, feet detaching from the ground in slow float" },
   { id: "statue-stone",         label: "Petrify to Stone",       category: "transformation", description: "Body petrifies into stone statue",
-    promptHint: "the subject's body petrifies into grey weathered stone starting from the extremities and creeping inward, fine cracks forming as the transformation locks the pose into a statue" },
+    promptHint: "the subject's body petrifies into grey weathered stone starting from the extremities and creeping inward, fine cracks forming as the transformation locks the pose into a statue",
+    term: "stone petrification" },
   { id: "liquid-metal",         label: "Liquid Metal",           category: "transformation", description: "T-1000 style liquid metal form",
-    promptHint: "the subject's body shifts into glossy chrome-silver liquid metal that reflects the environment, surface rippling, features re-forming with mirror-smooth fluid motion (T-1000 style)" },
+    promptHint: "the subject's body shifts into glossy chrome-silver liquid metal that reflects the environment, surface rippling, features re-forming with mirror-smooth fluid motion (T-1000 style)",
+    term: "liquid metal morph" },
   { id: "animalization",        label: "Animalization",          category: "transformation", description: "Morphs into an animal",
-    promptHint: "the subject morphs into a wild animal — body re-shaping, fur or feathers emerging, limbs reconfiguring, the head transforming into the animal's, eyes shifting to the animal's coloration" },
+    promptHint: "the subject morphs into a wild animal — body re-shaping, fur or feathers emerging, limbs reconfiguring, the head transforming into the animal's, eyes shifting to the animal's coloration",
+    term: "animal transformation" },
   { id: "gorilla-form",         label: "Gorilla Form",           category: "transformation", description: "Transforms into a gorilla",
-    promptHint: "the subject transforms into a massive silverback gorilla — body bulks up dramatically, dark fur sprouts, face re-shapes with a heavy brow, posture shifts to hunched primate stance" },
+    promptHint: "the subject transforms into a massive silverback gorilla — body bulks up dramatically, dark fur sprouts, face re-shapes with a heavy brow, posture shifts to hunched primate stance",
+    term: "gorilla transformation" },
   { id: "mystification",        label: "Mystification",          category: "transformation", description: "Magical aura wraps & transforms subject",
-    promptHint: "the subject is enveloped in swirling magical particles and arcane symbols that orbit the body, the form within visibly shifting until the aura clears revealing the transformed subject" },
+    promptHint: "the subject is enveloped in swirling magical particles and arcane symbols that orbit the body, the form within visibly shifting until the aura clears revealing the transformed subject",
+    term: "magical aura transformation" },
   { id: "gas-form",             label: "Gas Transformation",     category: "transformation", description: "Body dissipates into gaseous form",
     promptHint: "the subject's body dissolves into a swirling cloud of coloured gas that drifts and re-coalesces in the same space, the form re-condensing into a faintly altered version of the subject" },
   { id: "diamond-skin",         label: "Diamond Skin",           category: "transformation", description: "Body crystallizes into diamond facets",
-    promptHint: "the subject's body crystallizes into faceted diamond — skin hardening into reflective gem facets that refract light in rainbow caustics, the silhouette holding the same pose" },
+    promptHint: "the subject's body crystallizes into faceted diamond — skin hardening into reflective gem facets that refract light in rainbow caustics, the silhouette holding the same pose",
+    term: "skin crystallizing into diamond" },
   { id: "agent-reveal",         label: "Agent Reveal",           category: "transformation", description: "Suit and shades materialize on subject",
-    promptHint: "the subject's everyday clothing rapidly morphs into a sharp black suit, tie tightening, dark sunglasses materializing onto the face, posture stiffening into agent stance (Men-in-Black style)" },
+    promptHint: "the subject's everyday clothing rapidly morphs into a sharp black suit, tie tightening, dark sunglasses materializing onto the face, posture stiffening into agent stance (Men-in-Black style)",
+    term: "black suit and sunglasses materializing" },
 
   // ============================================================================
   // POWER — 12 entries — subject demonstrates a fantastical ability
   // ============================================================================
   { id: "fire-breathe",         label: "Fire Breathe",           category: "power", description: "Breathes a sustained jet of flame",
-    promptHint: "the subject opens their mouth and exhales a sustained jet of orange-yellow fire that arcs forward through the frame, with smoke trailing and embers scattering, lighting their face in warm reflected glow" },
+    promptHint: "the subject opens their mouth and exhales a sustained jet of orange-yellow fire that arcs forward through the frame, with smoke trailing and embers scattering, lighting their face in warm reflected glow",
+    term: "fire breathing" },
   { id: "ice-breathe",          label: "Ice Breathe",            category: "power", description: "Breathes a stream of freezing air",
-    promptHint: "the subject exhales a stream of frigid pale-blue air with visible ice crystals forming in the breath, surfaces in front of them rapidly frosting over with creeping ice patterns" },
+    promptHint: "the subject exhales a stream of frigid pale-blue air with visible ice crystals forming in the breath, surfaces in front of them rapidly frosting over with creeping ice patterns",
+    term: "ice breath" },
   { id: "air-bending",          label: "Air Bending",            category: "power", description: "Manipulates a swirling vortex of air",
     promptHint: "the subject's hands trace through the air and a visible swirling vortex of wind follows the gestures, dust and loose objects spiraling along the path of the conjured air currents" },
   { id: "water-bending",        label: "Water Bending",          category: "power", description: "Manipulates flowing water with gestures",
@@ -89,7 +104,8 @@ export const CHARACTER_FX: ReadonlyArray<CharacterFx> = [
   { id: "earth-bending",        label: "Earth Bending",          category: "power", description: "Raises stone slabs from the ground",
     promptHint: "the subject stomps or gestures downward and slabs of stone or earth tear upward from the ground around them in geometric shards, dust and debris falling away as the rock rises" },
   { id: "lightning-hands",      label: "Lightning Hands",        category: "power", description: "Arcs of electricity from hands",
-    promptHint: "the subject's hands crackle with bright blue-white electric arcs that branch outward in jagged forking patterns, the room flickering with the strobing illumination of the discharge" },
+    promptHint: "the subject's hands crackle with bright blue-white electric arcs that branch outward in jagged forking patterns, the room flickering with the strobing illumination of the discharge",
+    term: "electric arcs from the hands" },
   { id: "levitation",           label: "Levitation",             category: "power", description: "Rises off the ground, body horizontal or vertical",
     promptHint: "the subject rises slowly off the ground in a controlled vertical lift, hair and loose clothing drifting upward in zero-gravity sway, faint heat-haze air distortion visible below the feet" },
   { id: "telekinesis",          label: "Telekinesis",            category: "power", description: "Nearby objects float and orbit",
@@ -97,51 +113,66 @@ export const CHARACTER_FX: ReadonlyArray<CharacterFx> = [
   { id: "invisibility",         label: "Invisibility",           category: "power", description: "Body fades to transparent / refractive",
     promptHint: "the subject's body fades into transparency with a faint refractive shimmer at the edges, only a barely-visible heat-haze outline indicating where they stand as they vanish from sight" },
   { id: "hero-flight",          label: "Hero Flight",            category: "power", description: "Launches into the sky in flight pose",
-    promptHint: "the subject launches upward into the sky in a heroic superhero flight pose, arms forward, cape or clothing whipping behind, with a sonic-boom shockwave at the launch point" },
+    promptHint: "the subject launches upward into the sky in a heroic superhero flight pose, arms forward, cape or clothing whipping behind, with a sonic-boom shockwave at the launch point",
+    term: "superhero flight takeoff" },
   { id: "super-speed",          label: "Super Speed",            category: "power", description: "Blurs into super-fast motion",
     promptHint: "the subject blurs into super-fast motion leaving multiple trailing afterimages and lightning-streak motion lines, the surrounding scene appearing momentarily frozen against their speed" },
   { id: "soul-departure",       label: "Soul Departure",         category: "power", description: "Translucent soul rises from body",
-    promptHint: "a translucent luminous soul rises out of the subject's body, drifting upward as a ghost-like figure while the physical body remains in its pose, a faint silver thread connecting the two" },
+    promptHint: "a translucent luminous soul rises out of the subject's body, drifting upward as a ghost-like figure while the physical body remains in its pose, a faint silver thread connecting the two",
+    term: "soul leaving the body" },
 
   // ============================================================================
   // BODY-MOD — 9 entries — parts of the subject change / emerge / leave
   // ============================================================================
   { id: "wings-grow",           label: "Wings Grow",             category: "body-mod", description: "Wings sprout and unfurl from back",
-    promptHint: "the subject's back arches and two large wings — feathered angelic or leathery demonic — unfurl outward from the shoulder blades, extending to full span behind them" },
+    promptHint: "the subject's back arches and two large wings — feathered angelic or leathery demonic — unfurl outward from the shoulder blades, extending to full span behind them",
+    term: "wings unfurling from the back" },
   { id: "horns-grow",           label: "Horns Emerge",           category: "body-mod", description: "Horns push out from the head",
-    promptHint: "the subject's forehead furrows as two pointed horns push outward from the skull, growing in a curving arc above the brows with the skin parting cleanly as the bone emerges" },
+    promptHint: "the subject's forehead furrows as two pointed horns push outward from the skull, growing in a curving arc above the brows with the skin parting cleanly as the bone emerges",
+    term: "horns growing from the head" },
   { id: "tail-emerge",          label: "Tail Emerge",            category: "body-mod", description: "Tail extends from base of spine",
-    promptHint: "a tail — feline, reptilian, or demonic — extends rapidly from the base of the subject's spine, swishing into motion behind them once fully grown" },
+    promptHint: "a tail — feline, reptilian, or demonic — extends rapidly from the base of the subject's spine, swishing into motion behind them once fully grown",
+    term: "tail growing from the spine" },
   { id: "tentacles-emerge",     label: "Tentacles Emerge",       category: "body-mod", description: "Tentacles writhe out from back / body",
-    promptHint: "long writhing tentacles emerge from the subject's back or torso, slick and dark, snaking outward in undulating motion, the skin parting around the base of each appendage" },
+    promptHint: "long writhing tentacles emerge from the subject's back or torso, slick and dark, snaking outward in undulating motion, the skin parting around the base of each appendage",
+    term: "tentacles writhing from the back" },
   { id: "extra-eyes",           label: "Extra Eyes Open",        category: "body-mod", description: "Additional eyes open across face / body",
-    promptHint: "additional eyes open across the subject's face, forehead, and body — blinking in sequence and tracking independently, with the skin smoothly accommodating each new aperture" },
+    promptHint: "additional eyes open across the subject's face, forehead, and body — blinking in sequence and tracking independently, with the skin smoothly accommodating each new aperture",
+    term: "extra eyes opening on the face" },
   { id: "head-explode",         label: "Head Explosion",         category: "body-mod", description: "Head bursts apart violently (PG-13)",
-    promptHint: "the subject's head bursts apart in a violent explosion of light and abstract particles, the body remaining standing momentarily before the camera cuts away — stylized, non-graphic" },
+    promptHint: "the subject's head bursts apart in a violent explosion of light and abstract particles, the body remaining standing momentarily before the camera cuts away — stylized, non-graphic",
+    term: "stylized head explosion" },
   { id: "head-off",             label: "Head Removal",           category: "body-mod", description: "Head detaches and floats free (PG-13, stylized)",
-    promptHint: "the subject's head smoothly detaches from the neck and floats free above the body in stylized magical detachment, the body remaining poised and the head rotating to face the camera" },
+    promptHint: "the subject's head smoothly detaches from the neck and floats free above the body in stylized magical detachment, the body remaining poised and the head rotating to face the camera",
+    term: "stylized head detachment" },
   { id: "spiders-from-mouth",   label: "Spiders From Mouth",     category: "body-mod", description: "Spiders crawl out from open mouth (horror)",
-    promptHint: "the subject's mouth opens wide and a stream of dark spiders crawls outward across the lips and cheeks, scattering down the face and body in a horror-genre reveal" },
+    promptHint: "the subject's mouth opens wide and a stream of dark spiders crawls outward across the lips and cheeks, scattering down the face and body in a horror-genre reveal",
+    term: "spiders crawling from the mouth" },
   { id: "skin-surge",           label: "Skin Surge",             category: "body-mod", description: "Skin ripples with under-the-surface motion",
-    promptHint: "the subject's skin ripples with visible wave-like surges of motion underneath the surface, as if something is shifting through the body, the skin stretching and re-settling in pulsing rhythm" },
+    promptHint: "the subject's skin ripples with visible wave-like surges of motion underneath the surface, as if something is shifting through the body, the skin stretching and re-settling in pulsing rhythm",
+    term: "skin rippling with movement underneath" },
 
   // ============================================================================
   // FACE-EXPRESSION — 8 entries — face contorts / mask / eyes change
   // ============================================================================
   { id: "horror-face",          label: "Horror Face",            category: "face-expression", description: "Face contorts into horror expression",
-    promptHint: "the subject's face contorts into a horror expression — eyes widen and bulge, mouth stretches unnaturally wide, skin pales with visible veins emerging, jaw distending in unnatural proportions" },
+    promptHint: "the subject's face contorts into a horror expression — eyes widen and bulge, mouth stretches unnaturally wide, skin pales with visible veins emerging, jaw distending in unnatural proportions",
+    term: "contorted horror expression" },
   { id: "oni-mask",             label: "Oni Mask",               category: "face-expression", description: "Demon mask materializes over face",
     promptHint: "a red and gold oni demon mask materializes and slides into place over the subject's face, painted features sharp and menacing, with curling smoke and faint magical glyphs around the edges" },
   { id: "glowing-eyes",         label: "Glowing Eyes",           category: "face-expression", description: "Eyes ignite with internal light",
     promptHint: "the subject's eyes ignite with a brilliant internal glow — white, gold, or coloured — casting visible light beams outward and illuminating the bridge of the nose and upper cheeks" },
   { id: "floral-eyes",          label: "Floral Eyes",            category: "face-expression", description: "Flowers bloom from eye sockets",
-    promptHint: "delicate flowers bloom outward from the subject's eye sockets, petals unfurling in slow motion to replace the eyes, vines drifting down the cheeks in surreal botanical reveal" },
+    promptHint: "delicate flowers bloom outward from the subject's eye sockets, petals unfurling in slow motion to replace the eyes, vines drifting down the cheeks in surreal botanical reveal",
+    term: "flowers blooming from the eyes" },
   { id: "bloom-mouth",          label: "Bloom Mouth",            category: "face-expression", description: "Flowers bloom from open mouth",
-    promptHint: "the subject opens their mouth and a cascade of flowers and vines blooms outward from within, unfurling in slow motion across the lower face in a surreal botanical reveal" },
+    promptHint: "the subject opens their mouth and a cascade of flowers and vines blooms outward from within, unfurling in slow motion across the lower face in a surreal botanical reveal",
+    term: "flowers blooming from the mouth" },
   { id: "x-ray",                label: "X-Ray Reveal",           category: "face-expression", description: "Body becomes X-ray visible skeleton",
     promptHint: "the subject's body becomes semi-transparent in X-ray style, revealing the skeletal structure beneath with a faint cyan or green glow outlining bones and major internal organs" },
   { id: "agent-snap",           label: "Sunglasses Snap-On",     category: "face-expression", description: "Sunglasses materialize over eyes",
-    promptHint: "dark sunglasses snap into place over the subject's eyes with a sharp visual punctuation — sometimes accompanied by lens flare bloom and a tight zoom on the bridge of the nose" },
+    promptHint: "dark sunglasses snap into place over the subject's eyes with a sharp visual punctuation — sometimes accompanied by lens flare bloom and a tight zoom on the bridge of the nose",
+    term: "sunglasses snapping onto the face" },
   { id: "visor-x",              label: "Cyber Visor",            category: "face-expression", description: "Sci-fi cyber visor materializes",
     promptHint: "a futuristic cybernetic visor materializes across the subject's eyes — sleek, semi-transparent with internal HUD readouts visible, faint scanline shimmer across the surface" },
 
@@ -153,9 +184,11 @@ export const CHARACTER_FX: ReadonlyArray<CharacterFx> = [
   { id: "money-rain",           label: "Money Rain",             category: "aura-ambient", description: "Currency rains around subject",
     promptHint: "the subject stands or moves through a slow-motion cascade of currency notes raining down from above, bills fluttering and stacking around them, the money filling the air around the body" },
   { id: "color-rain",           label: "Color Rain",             category: "aura-ambient", description: "Brightly coloured rain around subject",
-    promptHint: "vivid brightly coloured raindrops or pigment streams fall around the subject from above, splashing on the ground and forming pools of saturated colour, the subject untouched by the cascade" },
+    promptHint: "vivid brightly coloured raindrops or pigment streams fall around the subject from above, splashing on the ground and forming pools of saturated colour, the subject untouched by the cascade",
+    term: "brightly coloured rain" },
   { id: "saint-glow",           label: "Saint Glow",             category: "aura-ambient", description: "Halo and divine glow around subject",
-    promptHint: "a soft golden halo glows behind the subject's head and warm celestial light radiates outward from the body, with faint dust motes drifting in the beams in a saintly halation" },
+    promptHint: "a soft golden halo glows behind the subject's head and warm celestial light radiates outward from the body, with faint dust motes drifting in the beams in a saintly halation",
+    term: "golden halo and divine glow" },
   { id: "fire-aura",            label: "Fire Aura",              category: "aura-ambient", description: "Flames lick around subject's body",
     promptHint: "flames lick and curl around the subject's body without burning them, the fire wrapping the silhouette in a halo of orange and yellow tongues with heat-haze distortion in the air around" },
   { id: "frost-aura",           label: "Frost Aura",             category: "aura-ambient", description: "Frost and ice radiate from subject",
@@ -163,19 +196,25 @@ export const CHARACTER_FX: ReadonlyArray<CharacterFx> = [
   { id: "shadow-aura",          label: "Shadow Aura",            category: "aura-ambient", description: "Dark shadow tendrils swirl around subject",
     promptHint: "dark shadow tendrils swirl and writhe around the subject's body, the surrounding light dimming as the inky aura coils outward from the silhouette in slow undulating motion" },
   { id: "electricity-aura",     label: "Electricity Aura",       category: "aura-ambient", description: "Tesla-coil electric arcs around subject",
-    promptHint: "bright blue-white electric arcs crackle around the subject's body in branching tesla-coil patterns, jumping between extremities and the surrounding air with rhythmic strobing flashes" },
+    promptHint: "bright blue-white electric arcs crackle around the subject's body in branching tesla-coil patterns, jumping between extremities and the surrounding air with rhythmic strobing flashes",
+    term: "crackling electric aura" },
   { id: "sparkles-around",      label: "Magical Sparkles",       category: "aura-ambient", description: "Magical sparkles orbit the subject",
     promptHint: "delicate magical sparkles and small star-shaped particles orbit and trail around the subject's body in slow-motion arcs, leaving faint light streaks in their path" },
   { id: "fairies-around",       label: "Fairies Around",         category: "aura-ambient", description: "Tiny glowing fairies flutter around subject",
-    promptHint: "tiny glowing fairies with translucent wings flutter around the subject in playful loops, each fairy leaving a faint trail of pixie-dust shimmer in their wake" },
+    promptHint: "tiny glowing fairies with translucent wings flutter around the subject in playful loops, each fairy leaving a faint trail of pixie-dust shimmer in their wake",
+    term: "tiny glowing fairies" },
   { id: "objects-orbit",        label: "Objects Orbit",          category: "aura-ambient", description: "Small objects float and orbit the subject",
-    promptHint: "small objects relevant to the subject — books, tools, fruits, gemstones — rise from the ground and orbit slowly around them in concentric rings of unsupported flight" },
+    promptHint: "small objects relevant to the subject — books, tools, fruits, gemstones — rise from the ground and orbit slowly around them in concentric rings of unsupported flight",
+    term: "objects orbiting in mid-air" },
   { id: "petals-around",        label: "Petals Around",          category: "aura-ambient", description: "Cherry blossom petals drift around subject",
-    promptHint: "soft cherry blossom petals drift gently around the subject from above, the petals catching in their hair and clothing in slow-motion pink-rose flurry" },
+    promptHint: "soft cherry blossom petals drift gently around the subject from above, the petals catching in their hair and clothing in slow-motion pink-rose flurry",
+    term: "cherry blossom petals drifting" },
   { id: "glow-trace",           label: "Glow Trace",             category: "aura-ambient", description: "Light trails follow subject's motion",
-    promptHint: "bright luminous trails follow every motion of the subject's body — limbs leaving glowing afterimage streaks that fade slowly behind, creating ribbons of light tracing the choreography" },
+    promptHint: "bright luminous trails follow every motion of the subject's body — limbs leaving glowing afterimage streaks that fade slowly behind, creating ribbons of light tracing the choreography",
+    term: "glowing motion trails" },
   { id: "tattoo-animation",     label: "Tattoo Animation",       category: "aura-ambient", description: "Tattoos glow and animate on skin",
-    promptHint: "tattoos on the subject's skin begin to glow with internal light and the linework animates in slow motion — scenes within the tattoos visibly moving, ink shifting position across the body" },
+    promptHint: "tattoos on the subject's skin begin to glow with internal light and the linework animates in slow motion — scenes within the tattoos visibly moving, ink shifting position across the body",
+    term: "glowing animated tattoos" },
 ]
 
 export const CHARACTER_FX_CATEGORY_ORDER: ReadonlyArray<CharacterFxCategory> = [
@@ -210,6 +249,17 @@ export function getCharacterFxPromptHint(id: string | undefined | null): string
   return getCharacterFx(id)?.promptHint ?? ""
 }
 
+/**
+ * Compact counterpart of `getCharacterFxPromptHint`: the short professional
+ * term this effect injects in compact hint mode ("werewolf transformation"
+ * where the hint is the full shot description). Same lookup and same
+ * empty-string-on-miss behavior — including the no-op "auto"/"none" entries,
+ * which inject nothing at either detail level.
+ */
+export function getCharacterFxTerm(id: string | undefined | null): string {
+  return resolveTerm(getCharacterFx(id))
+}
+
 export const CHARACTER_FX_IDS: ReadonlyArray<string> = CHARACTER_FX.map((c) => c.id)
 
 // ---------------------------------------------------------------------------
@@ -245,25 +295,48 @@ const INTENSITY_CLAUSES: Record<Exclude<CharacterFxIntensity, "auto">, string> =
  *
  * Substitution: each base hint has every `"the subject"` occurrence
  * rewritten to the target name BEFORE the join. Empty targetHints leaves
- * "the subject" intact in the prompt.
+ * "the subject" intact in the prompt. In compact hint mode the base is a bare
+ * `term` with no "the subject" to rewrite, so the target is named by an
+ * explicit `"{target}: {effects}"` prefix instead — the character is named in
+ * both modes.
+ *
+ * @param mode `"compact"` builds the base from each effect's short
+ *   professional `term` instead of its full shot description. The ", and "
+ *   multi-pick join and the position/duration/intensity clauses are emitted
+ *   identically in both modes. The TARGET is not: no `term` contains the
+ *   words "the subject" (a term names the effect, not a sentence about a
+ *   subject), so compact mode names the target with an explicit
+ *   `"{target}: {effects}"` prefix instead of substituting into the base.
+ *   Either way the wired character is always named.
  */
 export function composeCharacterFxHintFromConnections(
   effectId: string | ReadonlyArray<string> | undefined,
   targetHints: ReadonlyArray<string>,
   timing?: CharacterFxTiming,
+  mode: PickerHintMode = "full",
 ): string {
   const ids = Array.isArray(effectId)
     ? Array.from(new Set(effectId)).slice(0, 2)
     : effectId ? [effectId] : []
-  const baseHints = ids.map(getCharacterFxPromptHint).filter((h) => h.length > 0)
+  // The base fragment swaps in compact mode; the multi-pick join and the
+  // timing clauses below are identical either way. The TARGET has to be
+  // carried differently per mode: the full hints are sentences built around
+  // the words "the subject", so a name substitutes INTO them, while a term is
+  // a bare effect name with nothing to substitute into — naming the target
+  // there means prefixing it. Skipping that is how the wired character's name
+  // silently disappeared from every compact fragment.
+  const resolveBase = mode === "compact" ? getCharacterFxTerm : getCharacterFxPromptHint
+  const baseHints = ids.map(resolveBase).filter((h) => h.length > 0)
   if (baseHints.length === 0) return ""
 
   const targetClause = targetHints.filter((h) => h && h.length > 0).join(" and ")
-  const substituted = targetClause
+  const substituted = targetClause && mode !== "compact"
     ? baseHints.map((b) => b.replace(/\bthe subject\b/g, targetClause))
     : baseHints
 
-  const combinedBase = substituted.join(", and ")
+  const joined = substituted.join(", and ")
+  const combinedBase =
+    targetClause && mode === "compact" ? `${targetClause}: ${joined}` : joined
   const parts: string[] = [combinedBase]
 
   if (timing?.position  && timing.position  !== "auto") parts.push(POSITION_CLAUSES [timing.position])

package/src/color-look.ts

@@ -11,6 +11,8 @@
  * frontend DAG executor and the backend orchestrator.
  */
 
+import { resolveTerm } from "./term.js"
+
 export type ColorLookCategory = "palette" | "film-emulation" | "social-preset"
 
 export interface ColorLook {
@@ -19,23 +21,33 @@ export interface ColorLook {
   readonly category: ColorLookCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * Compact professional form injected in COMPACT hint mode ("warm color
+   * grade" where `promptHint` is the full sentence). Authored only where the
+   * lowercased label is not already what a colorist would write — e.g. bare
+   * grade adjectives ("Warm", "Sepia"), UI compounds ("Teal & Orange",
+   * "Agfa / ORWO"), annotated stock names ("Kodak Tri-X 400 (B&W)") and
+   * stacked modifiers with no head noun ("MTV 90s VHS"). See `term.ts`;
+   * resolve via `resolveTerm`.
+   */
+  readonly term?: string
 }
 
 export const COLOR_LOOKS: ReadonlyArray<ColorLook> = [
   // Palette (13)
-  { id: "warm",            label: "Warm",            category: "palette", description: "Warm orange/red tones",          promptHint: "warm color palette, orange and red tones throughout the image with golden highlights" },
-  { id: "cool",            label: "Cool",            category: "palette", description: "Cool blue/teal tones",            promptHint: "cool color palette, blue and teal tones throughout the image with subdued warm accents" },
-  { id: "teal-orange",     label: "Teal & Orange",   category: "palette", description: "Hollywood complementary grade",   promptHint: "teal and orange color grade, warm skin tones against cool teal shadows, Hollywood blockbuster look" },
+  { id: "warm",            label: "Warm",            category: "palette", description: "Warm orange/red tones",          promptHint: "warm color palette, orange and red tones throughout the image with golden highlights", term: "warm color grade" },
+  { id: "cool",            label: "Cool",            category: "palette", description: "Cool blue/teal tones",            promptHint: "cool color palette, blue and teal tones throughout the image with subdued warm accents", term: "cool color grade" },
+  { id: "teal-orange",     label: "Teal & Orange",   category: "palette", description: "Hollywood complementary grade",   promptHint: "teal and orange color grade, warm skin tones against cool teal shadows, Hollywood blockbuster look", term: "teal and orange grade" },
   { id: "split-toning",    label: "Split Toning",    category: "palette", description: "Cool shadows, warm highlights",   promptHint: "split-toning color grade, cool blue-green tinted shadows paired with warm amber highlights, nuanced tonal separation distinct from a flat teal-orange wash" },
   { id: "selective-color", label: "Selective Color", category: "palette", description: "B&W with one accent color",       promptHint: "selective color treatment, image rendered nearly monochromatic black-and-white with a single accent hue (such as red lipstick or a red dress) preserved in full saturation against the desaturated frame" },
-  { id: "faded-matte",     label: "Faded Matte",     category: "palette", description: "Lifted blacks, milky low-contrast", promptHint: "faded matte color grade, lifted blacks and milky low-contrast shadows with soft hazy highlights, flat Instagram-soft aesthetic with reduced dynamic range" },
-  { id: "log-flat",        label: "Log Flat",        category: "palette", description: "Pre-grade S-Log/V-Log neutral",   promptHint: "log-flat ungraded footage look, washed-out neutral S-Log or V-Log appearance with low contrast and desaturated muddy mids before any creative color grading is applied" },
-  { id: "desaturated",     label: "Desaturated",     category: "palette", description: "Low saturation, muted",           promptHint: "desaturated color grading, muted low-saturation tones throughout, almost monochromatic feel" },
-  { id: "monochrome-bw",   label: "Monochrome B&W",  category: "palette", description: "Pure black and white",            promptHint: "monochrome black and white, pure grayscale image with no color information" },
-  { id: "sepia",           label: "Sepia",           category: "palette", description: "Vintage brown tone",              promptHint: "sepia toned image, warm brown vintage monochrome with classic photographic feel" },
-  { id: "pastel",          label: "Pastel",          category: "palette", description: "Soft, low-contrast pastels",      promptHint: "pastel color palette, soft low-contrast pastel hues with light airy tones" },
-  { id: "high-contrast",   label: "High Contrast",   category: "palette", description: "Punchy contrast, deep blacks",   promptHint: "high contrast color grade, punchy saturated colors with crushed deep blacks and bright highlights" },
-  { id: "vibrant",         label: "Vibrant",         category: "palette", description: "Highly saturated colors",         promptHint: "vibrant saturated color palette, bold rich colors with high saturation throughout" },
+  { id: "faded-matte",     label: "Faded Matte",     category: "palette", description: "Lifted blacks, milky low-contrast", promptHint: "faded matte color grade, lifted blacks and milky low-contrast shadows with soft hazy highlights, flat Instagram-soft aesthetic with reduced dynamic range", term: "faded matte grade" },
+  { id: "log-flat",        label: "Log Flat",        category: "palette", description: "Pre-grade S-Log/V-Log neutral",   promptHint: "log-flat ungraded footage look, washed-out neutral S-Log or V-Log appearance with low contrast and desaturated muddy mids before any creative color grading is applied", term: "flat ungraded log footage" },
+  { id: "desaturated",     label: "Desaturated",     category: "palette", description: "Low saturation, muted",           promptHint: "desaturated color grading, muted low-saturation tones throughout, almost monochromatic feel", term: "desaturated color grade" },
+  { id: "monochrome-bw",   label: "Monochrome B&W",  category: "palette", description: "Pure black and white",            promptHint: "monochrome black and white, pure grayscale image with no color information", term: "black and white" },
+  { id: "sepia",           label: "Sepia",           category: "palette", description: "Vintage brown tone",              promptHint: "sepia toned image, warm brown vintage monochrome with classic photographic feel", term: "sepia tone" },
+  { id: "pastel",          label: "Pastel",          category: "palette", description: "Soft, low-contrast pastels",      promptHint: "pastel color palette, soft low-contrast pastel hues with light airy tones", term: "pastel color palette" },
+  { id: "high-contrast",   label: "High Contrast",   category: "palette", description: "Punchy contrast, deep blacks",   promptHint: "high contrast color grade, punchy saturated colors with crushed deep blacks and bright highlights", term: "high contrast color grade" },
+  { id: "vibrant",         label: "Vibrant",         category: "palette", description: "Highly saturated colors",         promptHint: "vibrant saturated color palette, bold rich colors with high saturation throughout", term: "vibrant saturated color palette" },
 
   // Film emulation (13)
   { id: "kodak-portra",    label: "Kodak Portra",    category: "film-emulation", description: "Soft skin tones, fine grain",  promptHint: "Kodak Portra film stock emulation, soft natural skin tones with fine grain and gentle pastel color rendering" },
@@ -44,30 +56,30 @@ export const COLOR_LOOKS: ReadonlyArray<ColorLook> = [
   { id: "fuji-pro-400h",   label: "Fuji Pro 400H",   category: "film-emulation", description: "Pastel greens and skies",      promptHint: "Fuji Pro 400H film stock emulation, soft pastel greens and creamy blue skies with gentle warm skin tones" },
   { id: "cinestill-800t",  label: "Cinestill 800T",  category: "film-emulation", description: "Tungsten film with red halation", promptHint: "Cinestill 800T film stock emulation, tungsten-balanced color with characteristic red halation around highlights" },
   { id: "bleach-bypass",   label: "Bleach Bypass",   category: "film-emulation", description: "High contrast, desaturated",   promptHint: "bleach bypass processing, high contrast with desaturated colors and silver-retention metallic look" },
-  { id: "technicolor",     label: "Technicolor 3-strip", category: "film-emulation", description: "Vivid retro Technicolor",  promptHint: "Technicolor 3-strip emulation, vivid saturated red/green/blue color separation with classic Hollywood golden-age look" },
+  { id: "technicolor",     label: "Technicolor 3-strip", category: "film-emulation", description: "Vivid retro Technicolor",  promptHint: "Technicolor 3-strip emulation, vivid saturated red/green/blue color separation with classic Hollywood golden-age look", term: "three-strip technicolor" },
   { id: "two-strip-technicolor", label: "Two-Strip Technicolor", category: "film-emulation", description: "1920s-30s red-blue Technicolor", promptHint: "two-strip Technicolor emulation, archaic 1920s and 1930s red-and-blue-only color process with limited green range, dusty rose reds against cyan blues, period-piece early-Hollywood feel distinct from later three-strip" },
   { id: "eastman-color",   label: "Eastman Color",   category: "film-emulation", description: "1950s/60s warm faded stock",   promptHint: "Eastman Color film stock emulation, mid-century 1950s and 1960s motion-picture color with slightly faded warm tonality, gentle red shift, soft contrast and the muted-pastel quality of aged Hollywood prints" },
-  { id: "hand-tinted",     label: "Hand-Tinted",     category: "film-emulation", description: "B&W with hand-painted color",  promptHint: "hand-tinted photograph aesthetic, base black-and-white image with hand-painted color accents applied selectively to lips, cheeks, garments and props, painterly translucent washes of pigment over the monochrome plate" },
-  { id: "agfa-orwo",       label: "Agfa / ORWO",     category: "film-emulation", description: "Eastern European cool greens", promptHint: "Agfa or ORWO film stock emulation, Eastern European film with cool muted greens, amber-leaning skin tones, slightly desaturated mids and a distinctive socialist-era documentary feel" },
-  { id: "day-for-night",   label: "Day-for-Night",   category: "film-emulation", description: "Daylight graded as night",     promptHint: "day-for-night color grading, daylight footage graded with deep blue tones and crushed shadows to simulate moonlit night" },
-  { id: "cross-processed", label: "Cross-Processed", category: "film-emulation", description: "Color shifts from xpro",        promptHint: "cross-processed film look, slide film developed in print chemistry causing surreal color shifts and pushed contrast" },
+  { id: "hand-tinted",     label: "Hand-Tinted",     category: "film-emulation", description: "B&W with hand-painted color",  promptHint: "hand-tinted photograph aesthetic, base black-and-white image with hand-painted color accents applied selectively to lips, cheeks, garments and props, painterly translucent washes of pigment over the monochrome plate", term: "hand-tinted black-and-white photograph" },
+  { id: "agfa-orwo",       label: "Agfa / ORWO",     category: "film-emulation", description: "Eastern European cool greens", promptHint: "Agfa or ORWO film stock emulation, Eastern European film with cool muted greens, amber-leaning skin tones, slightly desaturated mids and a distinctive socialist-era documentary feel", term: "orwo film stock" },
+  { id: "day-for-night",   label: "Day-for-Night",   category: "film-emulation", description: "Daylight graded as night",     promptHint: "day-for-night color grading, daylight footage graded with deep blue tones and crushed shadows to simulate moonlit night", term: "day-for-night grade" },
+  { id: "cross-processed", label: "Cross-Processed", category: "film-emulation", description: "Color shifts from xpro",        promptHint: "cross-processed film look, slide film developed in print chemistry causing surreal color shifts and pushed contrast", term: "cross-processed film look" },
   { id: "kodachrome-64",   label: "Kodachrome 64",   category: "film-emulation", description: "Saturated reds, golden warmth", promptHint: "graded with a Kodachrome 64 film palette, saturated reds and amber highlights with rich blue shadows, the classic National Geographic warmth and vintage slide-film signature with deep tonal density" },
   { id: "ektachrome-100",  label: "Ektachrome 100",  category: "film-emulation", description: "Cool clean blues, slide clarity", promptHint: "Ektachrome 100 slide film emulation, clean cool blues with a subtle magenta cast, crisp transparency-film clarity and natural daylight color rendition with fine grain and a slightly cyan-leaning neutral tonality" },
-  { id: "kodak-tri-x-400", label: "Kodak Tri-X 400 (B&W)", category: "film-emulation", description: "Pushed-grain B&W reportage", promptHint: "Kodak Tri-X 400 black-and-white film emulation, pushed-grain monochrome with gritty high contrast, deep blacks and bright highlights, classic 35mm street-photography and reportage feel with visible silver grain texture" },
-  { id: "aerochrome",      label: "Aerochrome / Color Infrared", category: "film-emulation", description: "Surreal pink-magenta foliage", promptHint: "Aerochrome color infrared film emulation, surreal false-color landscape where vegetation glows in vivid pink and magenta, blue skies stay deep, and foliage appears otherworldly hot-pink and crimson — distinctive infrared-sensitive emulsion signature" },
-  { id: "fuji-instax",     label: "Fuji Instax / Instant Film", category: "film-emulation", description: "Soft pastel instant-film", promptHint: "Fuji Instax instant film emulation, soft pastel midtones with a slight cool blue cast, gentle low-contrast rendering, square-format Polaroid-alternative aesthetic with creamy whites and dreamy diffuse color" },
+  { id: "kodak-tri-x-400", label: "Kodak Tri-X 400 (B&W)", category: "film-emulation", description: "Pushed-grain B&W reportage", promptHint: "Kodak Tri-X 400 black-and-white film emulation, pushed-grain monochrome with gritty high contrast, deep blacks and bright highlights, classic 35mm street-photography and reportage feel with visible silver grain texture", term: "kodak tri-x 400 black-and-white film" },
+  { id: "aerochrome",      label: "Aerochrome / Color Infrared", category: "film-emulation", description: "Surreal pink-magenta foliage", promptHint: "Aerochrome color infrared film emulation, surreal false-color landscape where vegetation glows in vivid pink and magenta, blue skies stay deep, and foliage appears otherworldly hot-pink and crimson — distinctive infrared-sensitive emulsion signature", term: "aerochrome color infrared film" },
+  { id: "fuji-instax",     label: "Fuji Instax / Instant Film", category: "film-emulation", description: "Soft pastel instant-film", promptHint: "Fuji Instax instant film emulation, soft pastel midtones with a slight cool blue cast, gentle low-contrast rendering, square-format Polaroid-alternative aesthetic with creamy whites and dreamy diffuse color", term: "fuji instax instant film" },
   { id: "cinestill-50d",   label: "Cinestill 50D",   category: "film-emulation", description: "Daylight cinema stock",         promptHint: "Cinestill 50D daylight-balanced cinema film emulation, controlled cool blues with creamy skin tones and fine grain, Christopher Doyle and Wong Kar-wai daylight-cinema aesthetic with smooth highlight rolloff and natural color separation" },
-  { id: "expired-film",    label: "Expired Film / Light-struck", category: "film-emulation", description: "Color shifts and light leaks", promptHint: "expired film and light-struck aesthetic, unpredictable color shifts with overexposed magenta and amber casts, visible light leaks and fogged edges, found-film degradation feel with elevated grain and unstable shifting hues" },
+  { id: "expired-film",    label: "Expired Film / Light-struck", category: "film-emulation", description: "Color shifts and light leaks", promptHint: "expired film and light-struck aesthetic, unpredictable color shifts with overexposed magenta and amber casts, visible light leaks and fogged edges, found-film degradation feel with elevated grain and unstable shifting hues", term: "expired light-struck film" },
 
   // Social-preset (modern social-video aesthetics — distinct from analog film emulations)
-  { id: "instagram-warm",     label: "Instagram Warm",     category: "social-preset", description: "Valencia-style warm filter",   promptHint: "Instagram-style warm filter aesthetic, slightly faded warm highlights with creamy mid-tones, Valencia-preset feel" },
-  { id: "tiktok-saturated",   label: "TikTok Saturated",   category: "social-preset", description: "Bright punchy social palette", promptHint: "TikTok-style oversaturated bright palette, punchy reds and blues with high contrast and vivid skin tones" },
-  { id: "youtube-vlog-flat",  label: "YouTube Vlog Flat",  category: "social-preset", description: "Clean vlog flat grade",        promptHint: "YouTube vlog clean flat color grade, neutral natural color rendition with even skin tones and pleasant ambient" },
+  { id: "instagram-warm",     label: "Instagram Warm",     category: "social-preset", description: "Valencia-style warm filter",   promptHint: "Instagram-style warm filter aesthetic, slightly faded warm highlights with creamy mid-tones, Valencia-preset feel", term: "warm instagram filter" },
+  { id: "tiktok-saturated",   label: "TikTok Saturated",   category: "social-preset", description: "Bright punchy social palette", promptHint: "TikTok-style oversaturated bright palette, punchy reds and blues with high contrast and vivid skin tones", term: "saturated tiktok look" },
+  { id: "youtube-vlog-flat",  label: "YouTube Vlog Flat",  category: "social-preset", description: "Clean vlog flat grade",        promptHint: "YouTube vlog clean flat color grade, neutral natural color rendition with even skin tones and pleasant ambient", term: "flat youtube vlog grade" },
   { id: "iphone-hdr",         label: "iPhone HDR",         category: "social-preset", description: "Computational HDR look",       promptHint: "iPhone computational HDR look with extended highlight range, lifted shadows, and slightly hyperreal local-contrast enhancement" },
-  { id: "y2k-saturated",      label: "Y2K Saturated",      category: "social-preset", description: "Early-2000s digital pop",      promptHint: "Y2K early-2000s digital saturation aesthetic, electric magenta and cyan punch, glossy compact-camera color, candy-bright primaries with a slightly crunchy CCD-sensor digital sharpness" },
-  { id: "mtv-90s-vhs",        label: "MTV 90s VHS",        category: "social-preset", description: "Oversaturated 90s VHS chroma", promptHint: "MTV 1990s VHS aesthetic, oversaturated cast with chroma bleed and color smearing, blown-out reds and electric blues, lo-fi tape-era saturation distinct from cleaner film emulations" },
-  { id: "polaroid-faded",     label: "Polaroid Faded",     category: "social-preset", description: "Magenta-tinted faded Polaroid", promptHint: "faded vintage Polaroid aesthetic, washed-out magenta and pink color cast, lifted milky shadows, yellowed highlights and the soft instant-film degradation of an aged SX-70 print, distinct from Kodak Portra negative-film emulation" },
-  { id: "lifestyle-warm-magazine", label: "Lifestyle Warm Magazine", category: "social-preset", description: "Modern warm editorial grade", promptHint: "modern lifestyle magazine warm-leaning grade, creamy honeyed highlights, gently warmed skin tones, soft golden mids and clean neutral shadows, contemporary editorial commercial aesthetic for fashion and food photography" },
+  { id: "y2k-saturated",      label: "Y2K Saturated",      category: "social-preset", description: "Early-2000s digital pop",      promptHint: "Y2K early-2000s digital saturation aesthetic, electric magenta and cyan punch, glossy compact-camera color, candy-bright primaries with a slightly crunchy CCD-sensor digital sharpness", term: "saturated y2k digital color" },
+  { id: "mtv-90s-vhs",        label: "MTV 90s VHS",        category: "social-preset", description: "Oversaturated 90s VHS chroma", promptHint: "MTV 1990s VHS aesthetic, oversaturated cast with chroma bleed and color smearing, blown-out reds and electric blues, lo-fi tape-era saturation distinct from cleaner film emulations", term: "90s mtv vhs look" },
+  { id: "polaroid-faded",     label: "Polaroid Faded",     category: "social-preset", description: "Magenta-tinted faded Polaroid", promptHint: "faded vintage Polaroid aesthetic, washed-out magenta and pink color cast, lifted milky shadows, yellowed highlights and the soft instant-film degradation of an aged SX-70 print, distinct from Kodak Portra negative-film emulation", term: "faded polaroid look" },
+  { id: "lifestyle-warm-magazine", label: "Lifestyle Warm Magazine", category: "social-preset", description: "Modern warm editorial grade", promptHint: "modern lifestyle magazine warm-leaning grade, creamy honeyed highlights, gently warmed skin tones, soft golden mids and clean neutral shadows, contemporary editorial commercial aesthetic for fashion and food photography", term: "warm lifestyle magazine grade" },
 ] as const
 
 export const COLOR_LOOK_CATEGORY_ORDER: ReadonlyArray<ColorLookCategory> = [
@@ -100,4 +112,9 @@ export function getColorLookPromptHint(id: string | undefined | null): string {
   return getColorLook(id)?.promptHint ?? ""
 }
 
+/** Compact sibling of `getColorLookPromptHint` — the short colorist term. */
+export function getColorLookTerm(id: string | undefined | null): string {
+  return resolveTerm(getColorLook(id))
+}
+
 export const COLOR_LOOK_IDS: ReadonlyArray<string> = COLOR_LOOKS.map((c) => c.id)

package/src/composition-effects.ts

@@ -15,26 +15,35 @@
  * executor and the backend orchestrator.
  */
 
+import { resolveTerm } from "./term.js"
+
 export interface CompositionEffect {
   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 retoucher / VFX artist would write in
+   * a prompt — "Doubled Mirror" reads as a doubled mirror, not as a mirrored
+   * duplicate of the subject. Everywhere else the label IS the term.
+   */
+  readonly term?: string
 }
 
 export const COMPOSITION_EFFECTS: ReadonlyArray<CompositionEffect> = [
-  { id: "bursting-through-frame", label: "Bursting Through Frame", description: "3D paper-tear breaking the frame",   promptHint: "the subject bursting forward through a torn paper frame in a 3D paper-tear effect, head and shoulders breaking the plane of the canvas with ragged paper edges curling outward" },
-  { id: "breaking-out-of-frame",  label: "Breaking Out of Frame",  description: "Limb extends past canvas border",     promptHint: "the subject's hand or limb extending past the canvas border, breaking the fourth wall and reaching beyond the frame's edge into the viewer's space" },
+  { id: "bursting-through-frame", label: "Bursting Through Frame", description: "3D paper-tear breaking the frame",   promptHint: "the subject bursting forward through a torn paper frame in a 3D paper-tear effect, head and shoulders breaking the plane of the canvas with ragged paper edges curling outward", term: "3d pop-out through a torn paper frame" },
+  { id: "breaking-out-of-frame",  label: "Breaking Out of Frame",  description: "Limb extends past canvas border",     promptHint: "the subject's hand or limb extending past the canvas border, breaking the fourth wall and reaching beyond the frame's edge into the viewer's space", term: "out-of-bounds effect, limb past the frame" },
   { id: "pixel-disintegration",   label: "Pixel Disintegration",   description: "Subject dissolving into particles",   promptHint: "the subject pixelating and dissolving into floating geometric particles drifting outward, ordered chaos with crisp pixel-cube fragments scattering away from the silhouette" },
   { id: "smoke-sculpture",        label: "Smoke Sculpture",        description: "Subject formed from swirling smoke",  promptHint: "the subject formed entirely of swirling smoke, ethereal greyscale mass holding human shape with wispy tendrils trailing off and dissolving at the edges" },
   { id: "liquid-sculpture",       label: "Liquid Sculpture",       description: "Subject formed from flowing liquid",  promptHint: "the subject formed entirely of flowing water and liquid, ripples and reflections traveling through the form with droplets suspended around the silhouette" },
   { id: "shattering-glass",       label: "Shattering Glass",       description: "Frozen glass shards mid-flight",      promptHint: "the subject framed behind shattering glass with fragments mid-flight, motion frozen at the moment of impact, splintered cracks radiating outward and shards catching the light" },
-  { id: "emerging-from-background", label: "Emerging From Background", description: "Half-emerging from a textured surface", promptHint: "the subject half-emerging out of a textured background, partially integrated into the surface as if pushing through wet plaster or relief sculpture, body and background sharing material" },
+  { id: "emerging-from-background", label: "Emerging From Background", description: "Half-emerging from a textured surface", promptHint: "the subject half-emerging out of a textured background, partially integrated into the surface as if pushing through wet plaster or relief sculpture, body and background sharing material", term: "subject emerging from a textured surface" },
   { id: "fragmented-mosaic",      label: "Fragmented Mosaic",      description: "Portrait built from mosaic tiles",    promptHint: "the subject's portrait composed of small mosaic tiles, fragmented yet unmistakably recognizable with grout lines between each ceramic-like fragment forming the larger image" },
-  { id: "glitch-distortion",      label: "Glitch Distortion",      description: "RGB-shift digital corruption",        promptHint: "the subject distorted by digital glitch artifacts with RGB channel separation, scanline tearing and datamoshed compression bands cutting horizontally across the figure" },
-  { id: "doubled-mirror",         label: "Doubled Mirror",         description: "Mirror-reflected duplication",        promptHint: "the subject duplicated in mirror reflections, multiplied identity with two or more echoed versions of the figure stitched along an invisible mirror seam" },
-  { id: "floating-fragments",     label: "Floating Fragments",     description: "Body partially drifting away",        promptHint: "the subject's body partially floating away in fragments, broken pieces of the figure detaching and drifting upward like windborne paper, leaving a partially dissolved silhouette" },
-  { id: "silhouette-outline",     label: "Silhouette Outline",     description: "Clean black silhouette on flat BG",   promptHint: "the subject reduced to a clean black silhouette outline against a flat single-color background, no internal detail, pure shape language" },
+  { id: "glitch-distortion",      label: "Glitch Distortion",      description: "RGB-shift digital corruption",        promptHint: "the subject distorted by digital glitch artifacts with RGB channel separation, scanline tearing and datamoshed compression bands cutting horizontally across the figure", term: "rgb-shift glitch distortion, scanline tearing" },
+  { id: "doubled-mirror",         label: "Doubled Mirror",         description: "Mirror-reflected duplication",        promptHint: "the subject duplicated in mirror reflections, multiplied identity with two or more echoed versions of the figure stitched along an invisible mirror seam", term: "mirrored duplication of the subject" },
+  { id: "floating-fragments",     label: "Floating Fragments",     description: "Body partially drifting away",        promptHint: "the subject's body partially floating away in fragments, broken pieces of the figure detaching and drifting upward like windborne paper, leaving a partially dissolved silhouette", term: "body fragmenting into drifting pieces" },
+  { id: "silhouette-outline",     label: "Silhouette Outline",     description: "Clean black silhouette on flat BG",   promptHint: "the subject reduced to a clean black silhouette outline against a flat single-color background, no internal detail, pure shape language", term: "flat black silhouette on a solid background" },
   { id: "exploding-particles",    label: "Exploding Particles",    description: "Outline scattering into particles",   promptHint: "the subject's outline exploding outward into a cloud of fine particles, dust and motes scattering radially around a partially intact core figure" },
   { id: "3x3-grid-collage",       label: "3x3 Grid Collage",       description: "Contact-sheet 9-pose montage",        promptHint: "the subject shown in a 3x3 grid of varied poses and expressions arranged as a contact-sheet collage, nine clean panels with consistent lighting and slight pose variation in each cell" },
   { id: "matte-painting",         label: "Matte Painting",         description: "Composite matte-painted background blended with live action, classic VFX", promptHint: "the subject composited against a matte-painted background blended seamlessly with live action, classic VFX matte-painting integration with hand-painted environment extension behind the figure" },
@@ -64,4 +73,9 @@ export function getCompositionEffectPromptHint(id: string | undefined | null): s
   return getCompositionEffect(id)?.promptHint ?? ""
 }
 
+/** The compact professional term for a composition effect (see `term.ts`). */
+export function getCompositionEffectTerm(id: string | undefined | null): string {
+  return resolveTerm(getCompositionEffect(id))
+}
+
 export const COMPOSITION_EFFECT_IDS: ReadonlyArray<string> = COMPOSITION_EFFECTS.map((c) => c.id)

package/src/era.ts

@@ -17,6 +17,8 @@
  * orchestrator.
  */
 
+import { resolveTerm } from "./term.js"
+
 export type EraCategory = "decade-20c" | "pre-modern" | "speculative"
 
 export interface Era {
@@ -25,6 +27,16 @@ export interface Era {
   readonly category: EraCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * Compact period name for prompt injection, authored only where the
+   * lowercased label is not what a period stylist would write: UI compounds
+   * ("1950s Diner / Pin-up"), annotated labels ("Fin-de-siècle (1895-1905)"),
+   * and decade names whose word order reads as a menu entry rather than an era
+   * ("Atomic Age 50s", "Pre-War Roaring"). Proper era names — medieval,
+   * renaissance, victorian, dieselpunk — need nothing; the label already IS
+   * the term.
+   */
+  readonly term?: string
 }
 
 export const ERAS: ReadonlyArray<Era> = [
@@ -58,6 +70,7 @@ export const ERAS: ReadonlyArray<Era> = [
     label: "1950s Diner / Pin-up",
     category: "decade-20c",
     description: "Chrome diners and bouffant pin-ups",
+    term: "1950s diner pin-up",
     promptHint:
       "set in the 1950s diner pin-up era — full circle skirts, cropped denim, leather jackets and bouffant hair in chrome diners and drive-ins, with saturated Kodachrome reds and turquoise",
   },
@@ -66,6 +79,7 @@ export const ERAS: ReadonlyArray<Era> = [
     label: "Atomic Age 50s",
     category: "decade-20c",
     description: "1950s sci-fi futurism and Cold War anxiety",
+    term: "1950s atomic age",
     promptHint:
       "set in the 1950s atomic-age era — ranch-style suburban homes, atomic starburst ornaments, finned appliances, B-movie sci-fi posters and Cold War civil-defense propaganda, with bright pulpy Technicolor saturation and hard mid-century optimism shot through with quiet nuclear dread",
   },
@@ -98,6 +112,7 @@ export const ERAS: ReadonlyArray<Era> = [
     label: "1990s Mall",
     category: "decade-20c",
     description: "Mall-rat grunge-and-pop nineties",
+    term: "1990s mall culture",
     promptHint:
       "set in the 1990s mall era — denim and crop tops, slip dresses, chokers and platform sneakers under fluorescent food-court lighting, with slight VHS-grain and a warm disposable-camera flash cast",
   },
@@ -106,6 +121,7 @@ export const ERAS: ReadonlyArray<Era> = [
     label: "2000s Tabloid / Y2K",
     category: "decade-20c",
     description: "Paparazzi-flash low-rise tabloid",
+    term: "2000s tabloid y2k",
     promptHint:
       "set in the 2000s tabloid Y2K era — low-rise jeans, butterfly tops, trucker hats and chrome flip phones outside celebrity nightclubs, with harsh paparazzi flash, deep blacks and faint chromatic gloss",
   },
@@ -114,6 +130,7 @@ export const ERAS: ReadonlyArray<Era> = [
     label: "Gen Z 2020s",
     category: "decade-20c",
     description: "Phone-first TikTok-coded current era",
+    term: "2020s gen z",
     promptHint:
       "set in the Gen Z 2020s era — phone-first vertical composition, TikTok-coded styling with baggy denim, Y2K nostalgia revivals, claw clips and oversized headphones, micro-trend churn and the saturated front-camera glow of contemporary social-media aesthetics",
   },
@@ -188,6 +205,7 @@ export const ERAS: ReadonlyArray<Era> = [
     label: "Fin-de-siècle (1895-1905)",
     category: "pre-modern",
     description: "Turn-of-century Belle Epoque elegance",
+    term: "fin-de-siècle 1900s",
     promptHint:
       "set in the fin-de-siècle turn-of-century era — art-nouveau curves, gaslight glow, corseted high-collared gowns, top hats and cane-and-cloak in proto-modern Belle Epoque Paris and Vienna, with warm gas-flame amber color and soft sepia halation",
   },
@@ -196,6 +214,7 @@ export const ERAS: ReadonlyArray<Era> = [
     label: "Pre-War Roaring",
     category: "pre-modern",
     description: "Late-1910s art-nouveau cusp",
+    term: "late-1910s pre-war",
     promptHint:
       "set in the late-1910s pre-war era — art-nouveau drapery, chignon hair, lace collars and cane-and-cloak in gas-lit Paris cafes, with sepia-bronze monochrome and soft halation",
   },
@@ -277,6 +296,11 @@ export function getEraPromptHint(id: string | undefined | null): string {
   return getEra(id)?.promptHint ?? ""
 }
 
+/** Compact counterpart of `getEraPromptHint` — the short period name. */
+export function getEraTerm(id: string | undefined | null): string {
+  return resolveTerm(getEra(id))
+}
+
 export const ERA_IDS: ReadonlyArray<string> = ERAS.map((e) => e.id)
 
 export const ERA_CATEGORY_LABELS: Readonly<Record<EraCategory, string>> = {