@nodaro/prompts 1.7.3 → 1.8.1

package/src/__tests__/prompt-builder.test.ts

@@ -1771,3 +1771,56 @@ describe("buildIdentityDirectives — locationReferencePhotoKind subject-line an
   })
 })
 
+
+describe("the provider reference cap slices by ATTACH priority, not raw order", () => {
+  // Incident 2026-08-25 ("two characters wired, one sent"): the raw candidate
+  // list interleaves each character's canonical with its whole variant array,
+  // and a raw slice at the provider cap (nano-banana-pro = 8) let one
+  // variant-rich character evict the character wired after it ENTIRELY —
+  // even though unmentioned variants never attach and the provider was sent
+  // two URLs total.
+  const characterRefs = (slug: string, name: string, url: string, variantCount: number) => [
+    {
+      id: `${slug}_canonical`, defaultName: name, source: "wired-character" as const, url,
+      characterSlug: slug, variantSlug: undefined, characterCanonicalDescription: `about ${name}`,
+      variantDescription: null, variantDisplayName: "canonical",
+    },
+    ...Array.from({ length: variantCount }, (_, i) => ({
+      id: `${slug}_v${i}`, defaultName: `${name} / v${i}`, source: "wired-character" as const,
+      url: `${url}?v=${i}`, characterSlug: slug, variantSlug: `v${i}`,
+      characterCanonicalDescription: `about ${name}`, variantDescription: null, variantDisplayName: `v${i}`,
+    })),
+  ]
+
+  it("a variant-rich first character no longer evicts the second", () => {
+    const refs = [
+      ...characterRefs("ava", "Ava", "https://cdn.test/ava.png", 9),
+      ...characterRefs("ben", "Ben", "https://cdn.test/ben.png", 0),
+    ]
+    for (const referenceFormat of ["hybrid", "legacy"] as const) {
+      const r = buildImagePrompt({
+        prompt: "two people at the beach.",
+        provider: "nano-banana-pro",
+        referenceFormat,
+        connectedReferences: refs as never,
+      })
+      expect(r.referenceImageUrls, referenceFormat).toEqual(
+        expect.arrayContaining(["https://cdn.test/ava.png", "https://cdn.test/ben.png"]),
+      )
+    }
+  })
+
+  it("the cap itself still holds when canonicals alone exceed it", () => {
+    const refs = Array.from({ length: 10 }, (_, i) =>
+      characterRefs(`c${i}`, `C${i}`, `https://cdn.test/c${i}.png`, 0),
+    ).flat()
+    const r = buildImagePrompt({
+      prompt: "a crowd.",
+      provider: "nano-banana-pro",
+      referenceFormat: "hybrid",
+      connectedReferences: refs as never,
+    })
+    expect((r.referenceImageUrls ?? []).length).toBeLessThanOrEqual(8)
+    expect((r.referenceImageUrls ?? []).length).toBe(8)
+  })
+})

package/src/__tests__/provider-prompt-doctrine.test.ts

@@ -48,4 +48,22 @@ describe("PROVIDER_PROMPT_DOCTRINES", () => {
     // no native negative-prompt param
     expect(d.doctrine).toMatch(/negative/i)
   })
+
+  it("splits the timestamp + multi-view rules by version: 2.0 SKUs no, seedance-2-5 yes (official 2.5 guide)", () => {
+    // Official "Dreamina Seedance 2.5 prompt guide" → Differences from Seedance 2.0:
+    // 2.0 does not respond to timestamps (shot numbers only) and multi-view
+    // subject images are not recommended; 2.5 supports integer-second
+    // timestamps and multi-view references. The doctrine is one group for the
+    // whole family, so BOTH halves must be stated — a rewrite that drops
+    // either side re-applies a 2.0 rule to 2.5 (or vice versa).
+    const d = getPromptDoctrine("seedance-2-5")!
+    expect(d.providers).toContain("seedance-2")
+    expect(d.doctrine).toMatch(/2\.0[^.]*(ignore|do not respond to|respond to shot numbers only)[^.]*timestamps|timestamps[^.]*2\.0/i)
+    expect(d.doctrine).toMatch(/seedance-2-5[^.]*integer-second timestamps|integer-second timestamps[^.]*2\.5/i)
+    expect(d.doctrine).toMatch(/At the 5-second mark/)
+    expect(d.doctrine).toMatch(/2\.5 accepts multi-view|supported on 2\.5/i)
+    const tips = getPromptTips("seedance-2-5").join(" ")
+    expect(tips).toMatch(/2\.0 SKUs ignore timestamps/)
+    expect(tips).toMatch(/seedance-2-5 honours integer-second timestamps/)
+  })
 })

package/src/__tests__/registered-catalogs-funnel.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import {
+  PICKER_CATALOGS, getRegisteredPickerCatalogs, getPickerCatalog, listPickerCatalogs,
+} from "../picker-catalogs.js"
+import { registerCatalogPack, resetCatalogPacks } from "../catalog-packs.js"
+
+beforeEach(() => resetCatalogPacks())
+
+describe("registered read funnel", () => {
+  it("with no packs, registered set equals the frozen base (inert default)", () => {
+    expect(getRegisteredPickerCatalogs()).toEqual(PICKER_CATALOGS)
+    expect(Object.isFrozen(PICKER_CATALOGS)).toBe(true)
+  })
+
+  it("late registration is reflected after the memo invalidates by version", () => {
+    const before = getPickerCatalog("setting")!.options!.map((o) => o.id)
+    registerCatalogPack({ id: "sai/setting-extend", catalogId: "setting", mode: "extend",
+      options: [{ id: "shul-hall", label: "Shul Hall", promptHint: "in a synagogue hall", term: "shul hall" }] })
+    const after = getPickerCatalog("setting")!.options!.map((o) => o.id)
+    expect(after).toEqual([...before, "shul-hall"])
+    // base is untouched
+    expect(PICKER_CATALOGS.find((c) => c.catalogId === "setting")!.options!.some((o) => o.id === "shul-hall")).toBe(false)
+  })
+
+  it("listPickerCatalogs reads the registered set", () => {
+    registerCatalogPack({ id: "sai/deny", catalogId: "setting", mode: "deny", denyIds: ["forest"] })
+    const setting = listPickerCatalogs().find((c) => c.catalogId === "setting")!
+    expect(setting.options!.some((o) => o.id === "forest")).toBe(false)
+  })
+})

package/src/__tests__/registered-catalogs-guard.test.ts

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest"
+import { getRegisteredPickerCatalogs, getPickerCatalog, projectPickerCatalog } from "../picker-catalogs.js"
+
+describe("every registered catalog is resolvable + projectable", () => {
+  it.each(getRegisteredPickerCatalogs().map((c) => [c.catalogId] as const))("%s resolves and projects", (id) => {
+    const c = getPickerCatalog(id)
+    expect(c, `getPickerCatalog("${id}") returned undefined`).toBeTruthy()
+    const projected = projectPickerCatalog(c!, { detail: "compact" })
+    expect(projected.catalogId).toBe(id)
+  })
+})

package/src/__tests__/term.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest"
+import {
+  TERM_MAX_CHARS,
+  deriveTerm,
+  isSuspiciousDerivedTerm,
+  resolveTerm,
+  type TermCarrier,
+} from "../term.js"
+
+const carrier = (over: Partial<TermCarrier> = {}): TermCarrier => ({
+  id: "x",
+  label: "Whip Pan Left",
+  promptHint: "the camera whips left in a single blurred sweep",
+  ...over,
+})
+
+describe("TERM_MAX_CHARS", () => {
+  it("is the documented cap", () => {
+    expect(TERM_MAX_CHARS).toBe(60)
+  })
+})
+
+describe("deriveTerm", () => {
+  it("lowercases the label", () => {
+    expect(deriveTerm("Medium Close-Up")).toBe("medium close-up")
+  })
+
+  it("removes parenthetical segments", () => {
+    expect(deriveTerm("Ultra-wide (14mm)")).toBe("ultra-wide")
+    expect(deriveTerm("ISO 1600 (visible grain)")).toBe("iso 1600")
+    expect(deriveTerm("(only) parenthetical")).toBe("parenthetical")
+  })
+
+  it("collapses whitespace and trims", () => {
+    expect(deriveTerm("  Hard   Cut \n")).toBe("hard cut")
+  })
+
+  it("does NOT split on '/' — ambiguity must surface, not be guessed", () => {
+    expect(deriveTerm("None / Hard Cut")).toBe("none / hard cut")
+    expect(deriveTerm("Fog / Mist")).toBe("fog / mist")
+  })
+
+  it("yields an empty string for an empty or purely parenthetical label", () => {
+    expect(deriveTerm("")).toBe("")
+    expect(deriveTerm("   ")).toBe("")
+    expect(deriveTerm("(auto)")).toBe("")
+  })
+})
+
+describe("isSuspiciousDerivedTerm", () => {
+  it("accepts a clean multi-word label", () => {
+    expect(isSuspiciousDerivedTerm("Whip Pan Left")).toBe(false)
+    expect(isSuspiciousDerivedTerm("Medium Close-Up")).toBe(false)
+  })
+
+  it.each(["None / Hard Cut", "Ultra-wide (14mm)", "Key: Rembrandt", "Black & White", "Start → End", "2× Speed"])(
+    "flags the UI-compound / annotated label %s",
+    (label) => {
+      expect(isSuspiciousDerivedTerm(label)).toBe(true)
+    },
+  )
+
+  it("flags a label that derives to nothing", () => {
+    expect(isSuspiciousDerivedTerm("")).toBe(true)
+    expect(isSuspiciousDerivedTerm("   ")).toBe(true)
+  })
+
+  it("flags a bare word only under bareWordSuspicious", () => {
+    expect(isSuspiciousDerivedTerm("Warm")).toBe(false)
+    expect(isSuspiciousDerivedTerm("Warm", { bareWordSuspicious: true })).toBe(true)
+    expect(isSuspiciousDerivedTerm("Short", { bareWordSuspicious: true })).toBe(true)
+  })
+
+  it("does not flag a multi-word label under bareWordSuspicious", () => {
+    expect(isSuspiciousDerivedTerm("Warm Tungsten", { bareWordSuspicious: true })).toBe(false)
+  })
+})
+
+describe("resolveTerm", () => {
+  it("returns '' for a missing entry", () => {
+    expect(resolveTerm(undefined)).toBe("")
+    expect(resolveTerm(null)).toBe("")
+  })
+
+  it("returns '' for a no-op entry whose promptHint is empty (auto / none)", () => {
+    expect(resolveTerm(carrier({ id: "auto", label: "Auto", promptHint: "" }))).toBe("")
+    // …even when a term was authored on it: an entry that injects nothing has
+    // nothing to inject in compact mode either.
+    expect(resolveTerm(carrier({ id: "auto", label: "Auto", promptHint: "", term: "auto" }))).toBe("")
+  })
+
+  it("prefers an explicit authored term", () => {
+    expect(resolveTerm(carrier({ label: "None / Hard Cut", term: "hard cut" }))).toBe("hard cut")
+  })
+
+  it("falls back to the derived label when no term is authored", () => {
+    expect(resolveTerm(carrier({ label: "Whip Pan Left" }))).toBe("whip pan left")
+    expect(resolveTerm(carrier({ label: "Ultra-wide (14mm)" }))).toBe("ultra-wide")
+  })
+
+  it("treats an empty authored term as authored (does not fall back to the label)", () => {
+    expect(resolveTerm(carrier({ label: "Whip Pan Left", term: "" }))).toBe("")
+  })
+})

package/src/__tests__/transitions.test.ts

@@ -2,9 +2,9 @@ import { describe, expect, it } from "vitest"
 import { TRANSITIONS, TRANSITION_IDS, TRANSITION_CATEGORY_ORDER, TRANSITION_CATEGORY_LABELS, composeTransitionHintFromConnections, getTransition, getTransitionLabel, getTransitionPromptHint } from "../transitions.js"
 
 describe("transitions catalog", () => {
-  it("ships 76 unique entries", () => {
-    expect(TRANSITIONS).toHaveLength(76)
-    expect(new Set(TRANSITION_IDS).size).toBe(76)
+  it("ships 82 unique entries", () => {
+    expect(TRANSITIONS).toHaveLength(82)
+    expect(new Set(TRANSITION_IDS).size).toBe(82)
   })
 
   it("every entry has a non-empty id, label, and description", () => {
@@ -20,9 +20,12 @@ describe("transitions catalog", () => {
     for (const t of TRANSITIONS) {
       counts[t.category] = (counts[t.category] ?? 0) + 1
     }
+    // `snap-to-black` is filed under STANDARD, beside `fade-to-black`: it is a
+    // cut, and the catalog groups by editing technique, not by what the frame
+    // happens to do (which would have put it in LIGHT next to `white-flash`).
     expect(counts).toEqual({
-      standard: 11, time: 8, element: 14, morph: 9,
-      portal: 10, physics: 9, light: 8, glitch: 7,
+      standard: 14, time: 8, element: 14, morph: 9,
+      portal: 12, physics: 10, light: 8, glitch: 7,
     })
   })
 

package/src/__tests__/upstream-immutability.test.ts

@@ -0,0 +1,23 @@
+// The convergence invariant, in-package form: registering a pack NEVER mutates
+// an upstream/base catalog array (curation is additive-by-registration, never
+// an in-place edit of an upstream file's exported data).
+import { describe, it, expect, beforeEach } from "vitest"
+import { PICKER_CATALOGS } from "../picker-catalogs.js"
+import { registerCatalogPack, resetCatalogPacks } from "../catalog-packs.js"
+
+beforeEach(() => resetCatalogPacks())
+
+describe("packs never edit upstream in place", () => {
+  it("base PICKER_CATALOGS is frozen and unchanged after replace/extend/deny", () => {
+    const snapshot = JSON.stringify(PICKER_CATALOGS)
+    expect(Object.isFrozen(PICKER_CATALOGS)).toBe(true)
+    registerCatalogPack({ id: "x", catalogId: "setting", mode: "deny", denyIds: ["forest"] })
+    registerCatalogPack({
+      id: "y",
+      catalogId: "mood",
+      mode: "extend",
+      options: [{ id: "z", label: "Z", promptHint: "z", term: "z" }],
+    })
+    expect(JSON.stringify(PICKER_CATALOGS)).toBe(snapshot)
+  })
+})

package/src/action-fx.ts

@@ -17,6 +17,8 @@
  * frontend DAG executor + backend orchestrator.
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export type ActionFxCategory =
   | "disaster"
   | "fire-blasts"
@@ -31,6 +33,8 @@ export interface ActionFx {
   readonly category: ActionFxCategory
   readonly description: string
   readonly promptHint: string
+  /** Optional authored compact term (see `term.ts` for the convention). */
+  readonly term?: string
 }
 
 export const ACTION_FX_CATEGORY_ORDER: ReadonlyArray<ActionFxCategory> = [
@@ -70,7 +74,8 @@ export const ACTION_FX: ReadonlyArray<ActionFx> = [
   { id: "sandstorm",            category: "disaster", label: "Sandstorm",            description: "Wall of orange dust engulfing scene",
     promptHint: "a towering sandstorm wall of orange-brown dust engulfing the scene, swirling fine particles reducing visibility to feet and burying surfaces under shifting waves of grit" },
   { id: "dust-storm-haboob",    category: "disaster", label: "Dust Storm (Haboob)",  description: "Towering desert dust front",
-    promptHint: "a towering haboob dust storm rolling across the scene, mountainous wall of dense ochre dust front billowing forward and swallowing the horizon in a dramatic monolithic curtain" },
+    promptHint: "a towering haboob dust storm rolling across the scene, mountainous wall of dense ochre dust front billowing forward and swallowing the horizon in a dramatic monolithic curtain",
+    term: "haboob dust storm" },
   { id: "wildfire-distant",     category: "disaster", label: "Distant Wildfire",     description: "Orange glow + smoke on horizon",
     promptHint: "a distant wildfire raging on the horizon, orange-red glow lighting up dark plumes of smoke billowing into a hazy sky with embers visible at the treeline" },
   { id: "wildfire-engulfing",   category: "disaster", label: "Engulfing Wildfire",   description: "Flames closing in, intense heat shimmer",
@@ -80,7 +85,8 @@ export const ACTION_FX: ReadonlyArray<ActionFx> = [
   { id: "lava-flow",            category: "disaster", label: "Lava Flow",            description: "Glowing molten river creeping across ground",
     promptHint: "a glowing molten lava flow creeping across the ground, bright orange-red rivers of fire snaking through cooled black crust with shimmering heat distortion above and wisps of sulfurous smoke" },
   { id: "ash-rain",             category: "disaster", label: "Falling Ash Rain",     description: "Apocalyptic grey ash falling like snow",
-    promptHint: "thick grey volcanic ash falling like dirty snow across the scene, apocalyptic post-eruption atmosphere with fine flakes settling on every surface and a hazy desaturated sky" },
+    promptHint: "thick grey volcanic ash falling like dirty snow across the scene, apocalyptic post-eruption atmosphere with fine flakes settling on every surface and a hazy desaturated sky",
+    term: "falling volcanic ash" },
   { id: "avalanche",            category: "disaster", label: "Avalanche",            description: "Wall of snow tumbling down mountainside",
     promptHint: "a massive avalanche tumbling down a mountainside, wall of churning snow and ice cascading at speed with a billowing powder cloud rolling forward and crushing everything in its path" },
   { id: "hailstorm",            category: "disaster", label: "Hailstorm",            description: "Large hailstones bouncing off surfaces",
@@ -139,15 +145,18 @@ export const ACTION_FX: ReadonlyArray<ActionFx> = [
   { id: "bullet-trail",         category: "combat", label: "Bullet Trail",         description: "Visible bullet streak through air",
     promptHint: "a streaking bullet trail cutting through the air, thin bright tracer line accompanied by faint vapor wake suggesting hypersonic velocity and a sense of forward motion through the frame" },
   { id: "sword-spark",          category: "combat", label: "Sword Spark",          description: "Macro shower of metal-on-metal friction sparks",
-    promptHint: "a macro close-up of bright sparks at the moment of metal-on-metal friction, white-hot incandescent flecks scattering radially with brief streaks of friction-light, captured at extreme close range with no swords or blades visible in the frame" },
+    promptHint: "a macro close-up of bright sparks at the moment of metal-on-metal friction, white-hot incandescent flecks scattering radially with brief streaks of friction-light, captured at extreme close range with no swords or blades visible in the frame",
+    term: "metal-on-metal friction sparks" },
   { id: "blade-clash",          category: "combat", label: "Blade Clash",          description: "Two blades meeting with impact wave",
     promptHint: "two blades clashing together at the moment of impact, sparks flying outward from the contact line and a brief shockwave of displaced air rippling around the steel edges" },
   { id: "ricochet-spark",       category: "combat", label: "Ricochet Spark",       description: "Bullet bouncing off metal with sparks",
     promptHint: "a bullet ricocheting off a metal surface, sharp burst of orange-white sparks at the deflection point with the bullet visibly trailing off at a new angle and a thin streak of vapor in its wake" },
   { id: "debris-field",         category: "combat", label: "Debris Field",         description: "Frozen mid-air shrapnel scattering",
-    promptHint: "a debris field frozen in mid-air, fragments of wood, metal, and concrete scattering outward in a radial pattern from a central impact point with dust and smoke swirling among the larger pieces" },
+    promptHint: "a debris field frozen in mid-air, fragments of wood, metal, and concrete scattering outward in a radial pattern from a central impact point with dust and smoke swirling among the larger pieces",
+    term: "debris frozen in mid-air" },
   { id: "glass-shatter-airborne", category: "combat", label: "Airborne Glass Shatter", description: "Glass exploding outward in mid-air shards",
-    promptHint: "a window or glass surface shattering outward in mid-air, hundreds of jagged crystalline shards exploding into the scene catching the light and tumbling in suspended chaos at the moment of impact" },
+    promptHint: "a window or glass surface shattering outward in mid-air, hundreds of jagged crystalline shards exploding into the scene catching the light and tumbling in suspended chaos at the moment of impact",
+    term: "glass shattering in mid-air" },
   { id: "shockwave-ground",     category: "combat", label: "Ground Shockwave",     description: "Visible expanding ring at ground level",
     promptHint: "a visible shockwave expanding at ground level, dust and small debris pushed outward in a clear radial ring from the impact origin with a momentary distortion in the air above" },
   { id: "sonic-boom",           category: "combat", label: "Sonic Boom",           description: "Cone of compressed air at supersonic speed",
@@ -159,7 +168,8 @@ export const ACTION_FX: ReadonlyArray<ActionFx> = [
   { id: "blood-spray",          category: "combat", label: "Blood Spray",          description: "Cinematic arc of blood droplets",
     promptHint: "a cinematic arc of blood droplets spraying outward in slow-motion, suspended red flecks tracing a curved path through the air with the dramatic stylized aesthetic of action cinema" },
   { id: "arrow-hit-spark",      category: "combat", label: "Arrow Hit Spark",      description: "Arrow striking with small sparks at impact",
-    promptHint: "an arrow striking a surface with a small burst of sparks at the impact point, shaft quivering on contact and tiny incandescent flecks scattering outward from the arrowhead" },
+    promptHint: "an arrow striking a surface with a small burst of sparks at the impact point, shaft quivering on contact and tiny incandescent flecks scattering outward from the arrowhead",
+    term: "arrow impact sparks" },
   // ── Sci-Fi ──
   { id: "laser-blast",          category: "sci-fi", label: "Laser Blast",          description: "Bright coherent beam of energy",
     promptHint: "a bright coherent laser blast cutting through the scene, vivid red or green beam of focused energy with a glowing core and a halo of scattered light along its path" },
@@ -172,9 +182,11 @@ export const ACTION_FX: ReadonlyArray<ActionFx> = [
   { id: "force-field-impact",   category: "sci-fi", label: "Force Field Impact",   description: "Visible ripple where projectile hits shield",
     promptHint: "a force field absorbing an impact, visible ripple spreading outward from the strike point with hexagonal energy panels glowing brightly at the contact site and discharge arcs branching across the surface" },
   { id: "portal-opening",       category: "sci-fi", label: "Portal Opening",       description: "Swirling vortex of energy tearing open in space",
-    promptHint: "a sci-fi portal tearing open in space, swirling vortex of bluish energy with edges flickering between dimensions and a glowing event horizon framing a glimpse of the destination beyond" },
+    promptHint: "a sci-fi portal tearing open in space, swirling vortex of bluish energy with edges flickering between dimensions and a glowing event horizon framing a glimpse of the destination beyond",
+    term: "sci-fi portal opening" },
   { id: "warp-distortion",      category: "sci-fi", label: "Warp Distortion",      description: "Spacetime bending around an object",
-    promptHint: "a spacetime warp distortion bending the air around an object, light streaks curving inward and the background visibly stretched and refracted in the gravitational well of the effect" },
+    promptHint: "a spacetime warp distortion bending the air around an object, light streaks curving inward and the background visibly stretched and refracted in the gravitational well of the effect",
+    term: "spacetime warp distortion" },
   { id: "hologram-flicker",     category: "sci-fi", label: "Hologram Flicker",     description: "Translucent projection glitching",
     promptHint: "a translucent holographic projection flickering and glitching in the scene, scanlines and chromatic noise distorting the cyan-blue figure with brief signal dropouts revealing the air behind it" },
   { id: "ion-storm",            category: "sci-fi", label: "Ion Storm",            description: "Crackling field of charged particles against a cosmic backdrop",
@@ -202,7 +214,8 @@ export const ACTION_FX: ReadonlyArray<ActionFx> = [
   { id: "dark-vortex",          category: "magic", label: "Dark Vortex",          description: "Ominous black-purple swirling void",
     promptHint: "an ominous dark vortex swirling in the scene, churning black-and-purple void with tendrils of shadow energy reaching outward and a sense of consuming power drawing light into its center" },
   { id: "light-explosion",      category: "magic", label: "Light Explosion",      description: "Burst of pure white-gold radiance",
-    promptHint: "a brilliant explosion of pure white-gold radiance, divine burst of light radiating outward with rays of beam-light fanning across the scene and motes of golden particles suspended in the afterglow" },
+    promptHint: "a brilliant explosion of pure white-gold radiance, divine burst of light radiating outward with rays of beam-light fanning across the scene and motes of golden particles suspended in the afterglow",
+    term: "explosion of white-gold light" },
 ] as const
 
 export const ACTION_FX_IDS: ReadonlyArray<string> = ACTION_FX.map((fx) => fx.id)
@@ -226,15 +239,25 @@ export function getActionFxPromptHint(id: string | undefined | null): string {
 }
 
 /**
- * Multi-pick: 1–2 ids → composite FX clause.
+ * Compact professional TERM for an id — the short phrase a VFX supervisor
+ * would write in a prompt ("haboob dust storm", "metal-on-metal friction
+ * sparks"), as opposed to the paragraph-length `promptHint`.
  *
- * Single id → entry's own promptHint as a single-element array.
- * Two ids → emit each independently and let the comma-join compose them.
- * Caps at 2 ids (silently drops the rest); the picker UI also enforces this
- * cap, but the cap here keeps the contract robust against stale workflow
- * data. Duplicate ids are deduplicated before the cap is applied.
+ * Same lookup and same empty-string-on-miss behavior as
+ * `getActionFxPromptHint`, so the two can never disagree about which entry
+ * they describe.
  */
-export function buildActionFxHints(value: unknown): string[] {
+export function getActionFxTerm(id: string | undefined | null): string {
+  return resolveTerm(getActionFx(id))
+}
+
+/**
+ * The multi-pick id list both builders below read: a lone string, or the first
+ * 2 distinct strings of an array (silently dropping the rest). The picker UI
+ * enforces the same cap; keeping it here too holds the contract against stale
+ * workflow data.
+ */
+function pickActionFxIds(value: unknown): string[] {
   const ids: string[] = []
   if (typeof value === "string" && value) {
     ids.push(value)
@@ -246,10 +269,37 @@ export function buildActionFxHints(value: unknown): string[] {
       }
     }
   }
+  return ids
+}
+
+/**
+ * Multi-pick: 1–2 ids → composite FX clause.
+ *
+ * Single id → entry's own promptHint as a single-element array.
+ * Two ids → emit each independently and let the comma-join compose them.
+ * Caps at 2 ids (silently drops the rest); the picker UI also enforces this
+ * cap, but the cap here keeps the contract robust against stale workflow
+ * data. Duplicate ids are deduplicated before the cap is applied.
+ */
+export function buildActionFxHints(value: unknown, mode: PickerHintMode = "full"): string[] {
+  if (mode === "compact") return buildActionFxTerms(value)
   const hints: string[] = []
-  for (const id of ids) {
+  for (const id of pickActionFxIds(value)) {
     const hint = getActionFxPromptHint(id)
     if (hint) hints.push(hint)
   }
   return hints
 }
+
+/**
+ * Compact-mode mirror of `buildActionFxHints`: the same 1–2 ids, resolved to
+ * their short professional terms instead of their paragraph-length hints.
+ */
+export function buildActionFxTerms(value: unknown): string[] {
+  const terms: string[] = []
+  for (const id of pickActionFxIds(value)) {
+    const term = getActionFxTerm(id)
+    if (term) terms.push(term)
+  }
+  return terms
+}

package/src/aesthetic.ts

@@ -19,6 +19,8 @@
  * backend orchestrator.
  */
 
+import { resolveTerm, type PickerHintMode } from "./term.js"
+
 export type AestheticCategory = "mainstream" | "niche" | "era" | "mood"
 
 export interface Aesthetic {
@@ -27,6 +29,13 @@ export interface Aesthetic {
   readonly category: AestheticCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * Compact professional term (see `term.ts`). Authored only where the
+   * lowercased label is not the phrase a stylist would write in a prompt —
+   * UI compounds ("Techwear / Gorpcore") and the fashion-era labels whose
+   * bare nouns name an art movement rather than the look.
+   */
+  readonly term?: string
 }
 
 export const AESTHETICS: ReadonlyArray<Aesthetic> = [
@@ -70,6 +79,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "Tactical urban performance gear",
     promptHint:
       "in the techwear-gorpcore aesthetic — black tactical shells, MOLLE webbing, cargo pants and chunky trail runners in a rain-slick neon city, with cold cyan-magenta color",
+    term: "techwear gorpcore",
   },
   {
     id: "old-money",
@@ -78,6 +88,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "Quiet-luxury heritage prep",
     promptHint:
       "in the old-money preppy aesthetic — cashmere sweaters, polo shirts, pearl strands and tailored linen on yacht decks and clay courts, with crisp, sun-bleached Mediterranean color",
+    term: "old money preppy",
   },
   {
     id: "streetwear",
@@ -280,6 +291,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "Grunge-meets-emo internet alt",
     promptHint:
       "in the alt-girl aesthetic — alternative subculture mix of grunge, scene, emo and e-girl with dyed split hair, layered chains, fishnets, oversized band tees and smudged dark eyeliner, lit with cool moody color",
+    term: "alt-girl",
   },
   {
     id: "blokecore",
@@ -296,6 +308,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "Neon Japanese decora rave kid",
     promptHint:
       "in the Y2K-rave decora club-kid aesthetic — fluorescent layered tops, plastic-charm bracelets, kawaii hair clips, leg warmers and platform sneakers under blacklight and neon strobes, with hyper-saturated electric color",
+    term: "y2k rave decora club-kid",
   },
 
   // -------------------- Fashion eras --------------------
@@ -306,6 +319,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "Pared-down quiet-luxury restraint",
     promptHint:
       "in the minimalist aesthetic — clean monochrome tailoring, structured silhouettes and empty white-stone spaces, with restrained neutral color and even soft light",
+    term: "minimalist fashion",
   },
   {
     id: "maximalism",
@@ -314,6 +328,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "More-is-more clashing pattern",
     promptHint:
       "in the maximalist aesthetic — clashing prints, layered jewelry, velvet, sequins and floral wallpaper in densely styled rooms, with rich saturated color",
+    term: "maximalist fashion",
   },
   {
     id: "avant-garde",
@@ -322,6 +337,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "Conceptual sculptural fashion",
     promptHint:
       "in the avant-garde aesthetic — sculptural deconstructed silhouettes, exaggerated proportions and architectural draping in stark gallery-white spaces, with cold minimal color",
+    term: "avant-garde fashion",
   },
   {
     id: "old-hollywood-glam",
@@ -330,6 +346,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "Silver-screen 1940s glamour",
     promptHint:
       "in the old-Hollywood-glam aesthetic — satin gowns, fur stoles, finger waves and red lipstick under sculpted studio key light, with silvery monochrome and high-contrast tonality",
+    term: "old hollywood glamour",
   },
 
   // -------------------- Mood bundles --------------------
@@ -348,6 +365,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "Gentle, low-effort warm calm",
     promptHint:
       "in a soft easygoing mood — relaxed knits, oversized layers and easy posture in softly lit rooms, with hazy natural light and creamy gentle color",
+    term: "soft easygoing mood",
   },
   {
     id: "casual-lived-in",
@@ -356,6 +374,7 @@ export const AESTHETICS: ReadonlyArray<Aesthetic> = [
     description: "Worn-in, unstyled everyday",
     promptHint:
       "in a casual lived-in mood — worn jeans, faded tees and rumpled hair in everyday domestic settings, with flat naturalistic light and unpolished snapshot color",
+    term: "casual lived-in mood",
   },
   {
     id: "effortless-cool",
@@ -395,12 +414,13 @@ export function getAestheticPromptHint(id: string | undefined | null): string {
   return getAesthetic(id)?.promptHint ?? ""
 }
 
-/**
- * Multi-pick variant: 1-2 aesthetic ids → blended hint. Single → entry's
- * own promptHint. Two → "styled in a {A} + {B} aesthetic blend" with
- * canonical entry labels (Y2K, dark academia, etc. stay as written).
- */
-export function buildAestheticHints(value: unknown): string {
+/** Compact-mode sibling of `getAestheticPromptHint` (see `term.ts`). */
+export function getAestheticTerm(id: string | undefined | null): string {
+  return resolveTerm(getAesthetic(id))
+}
+
+/** The 1-2 distinct ids a multi-pick aesthetic value carries, in order. */
+function aestheticIds(value: unknown): string[] {
   const ids: string[] = []
   if (typeof value === "string" && value) ids.push(value)
   else if (Array.isArray(value)) {
@@ -408,6 +428,17 @@ export function buildAestheticHints(value: unknown): string {
       if (typeof v === "string" && v && !ids.includes(v)) ids.push(v)
     }
   }
+  return ids
+}
+
+/**
+ * Multi-pick variant: 1-2 aesthetic ids → blended hint. Single → entry's
+ * own promptHint. Two → "styled in a {A} + {B} aesthetic blend" with
+ * canonical entry labels (Y2K, dark academia, etc. stay as written).
+ */
+export function buildAestheticHints(value: unknown, mode: PickerHintMode = "full"): string {
+  if (mode === "compact") return buildAestheticTerms(value)
+  const ids = aestheticIds(value)
   if (ids.length === 0) return ""
   if (ids.length === 1) return getAestheticPromptHint(ids[0])
   const labels = ids
@@ -418,6 +449,23 @@ export function buildAestheticHints(value: unknown): string {
   return `styled in a ${labels[0]} + ${labels[1]} aesthetic blend`
 }
 
+/**
+ * Compact-mode sibling of `buildAestheticHints`: same 1-2 id shape, same
+ * blend structure, but composed from the entries' short terms instead of
+ * their paragraph-length hints.
+ */
+export function buildAestheticTerms(value: unknown): string {
+  const ids = aestheticIds(value)
+  if (ids.length === 0) return ""
+  if (ids.length === 1) return getAestheticTerm(ids[0])
+  const terms = ids
+    .slice(0, 2)
+    .map((id) => getAestheticTerm(id))
+    .filter((t) => t.length > 0)
+  if (terms.length < 2) return getAestheticTerm(ids[0])
+  return `${terms[0]} + ${terms[1]} aesthetic blend`
+}
+
 export const AESTHETIC_IDS: ReadonlyArray<string> = AESTHETICS.map((a) => a.id)
 
 export const AESTHETIC_CATEGORY_LABELS: Readonly<Record<AestheticCategory, string>> = {